Index: trunk/psLib/src/astronomy/psTime.h =================================================================== --- trunk/psLib/src/astronomy/psTime.h (revision 3713) +++ trunk/psLib/src/astronomy/psTime.h (revision 4051) @@ -1,19 +1,19 @@ /** @file psTime.h * - * @brief Definitions for time, time utilities, and conversion functions for use with psLib astronomy - * functions. - * - * A collection of functions are required by psLib to manipulate time data. These functions primarily consist - * of conversions between specific time formats. They use the UNIX timeval time system as the - * base upon which International Atomic Time (TAI) and Universal Time Coordinated (UTC) are calculated. + * @brief Definitions for time, time utilities, and conversion functions for use + * with psLib astronomy functions. + * + * A collection of functions are required by psLib to manipulate time data. These + * functions primarily consist of conversions between specific time formats. They + * use the UNIX timeval time system as the base upon which International Atomic + * Time (TAI) and Universal Time Coordinated (UTC) are calculated. * * @author Ross Harman, MHPCC * - * @version $Revision: 1.28 $ $Name: not supported by cvs2svn $ - * @date $Date: 2005-04-19 02:44:12 $ + * @version $Revision: 1.29 $ $Name: not supported by cvs2svn $ + * @date $Date: 2005-05-31 21:47:46 $ * * Copyright 2004-2005 Maui High Performance Computing Center, University of Hawaii */ - #ifndef PSTIME_H @@ -88,6 +88,7 @@ /** Allocate time struct. * - * Allocates an empty time struct. User must specify the psTimeType (PS_TIME_TAI or PS_TIME_UTC) in the argument. - * The seconds and microseconds members of the struct are set to zero. + * Allocates an empty time struct. User must specify the psTimeType + * (PS_TIME_TAI or PS_TIME_UTC) in the argument. The seconds and microseconds members + * of the struct are set to zero. * * @return psTime*: Struct with empty time. @@ -99,6 +100,6 @@ /** Get current time. * - * Gets current time from the system clock. User must specify the psTimeType (PS_TIME_TAI or PS_TIME_UTC) in - * the argument. + * Gets current time from the system clock. User must specify the psTimeType + * (PS_TIME_TAI or PS_TIME_UTC) in the argument. * * @return psTime*: Struct with current time. @@ -121,12 +122,12 @@ /** Convert psTime to Local Mean Sidereal Time (LMST). * - * Converts psTime at the given longitude to LMST time. If the input time is not in UTC format, then it is - * converted. - * - * @return double: LST Time. - */ -double psTimeToLMST( + * Converts psTime at the given longitude to LMST time. If the input time is not + * in UTC format, then it is converted. + * + * @return psF64: LST Time. + */ +psF64 psTimeToLMST( psTime *time, ///< psTime to be converted. - double longitude ///< Longitude. + psF64 longitude ///< Longitude. ); @@ -135,20 +136,21 @@ * This function is necessary to for various SLALIB functions. * - * @return double: Time difference. - */ -double psTimeGetUT1Delta( + * @return psF64: Time difference. + */ +psF64 psTimeGetUT1Delta( + const psTime *time, ///< psTime to be looked up. + psTimeBulletin bulletin ///< IERS bulletin to use +); + +/** Determine TAI - UTC from table lookup. + * + * This function is necessary to for various psTime functions. + * + * @return psF64: Time difference. + */ +psF64 p_psTimeGetTAIDelta( const psTime *time ///< psTime to be looked up. ); -/** Determine TAI - UTC from table lookup. - * - * This function is necessary to for various psTime functions. - * - * @return double: Time difference. - */ -double psTimeGetTAIDelta( - const psTime *time ///< psTime to be looked up. -); - /** Determine polar coordinates at a given time. * @@ -157,6 +159,6 @@ * @return psSphere*: Spherical coordinates of Earth's polar axias. */ -struct psSphere* psTimeGetPoleCoords( - const psTime *time ///< psTime determine polar orientation. +struct psSphere* p_psTimeGetPoleCoords( + const psTime *time ///< psTime determine polar orientation. ); @@ -172,20 +174,32 @@ ); +/** Determine if UTC time is a leapsecond. + * + * Determines if the specified UTC time is a valid leapsecond. + * + * @return psBool: valid leap second + */ +psBool psTimeIsLeapSecond( + const psTime* utc ///< UTC to verify if leap second +); + /** Convert psTime to Julian date time. * - * Converts psTime to Julian date (JD) time. This function does not add or subtract leapseconds. - * - * @return double: Julian Date (JD) time. - */ -double psTimeToJD( + * Converts psTime to Julian date (JD) time. This function does not add or + * subtract leapseconds. + * + * @return psF64: Julian Date (JD) time. + */ +psF64 psTimeToJD( const psTime* time ///< Input time to be converted. ); /** Convert psTime to modified Julian date time. * - * Converts psTime to modified Julian date (MJD) time. This function does not add or subtract leapseconds. - * - * @return double: Modified Julian Days (MJD) time. - */ -double psTimeToMJD( + * Converts psTime to modified Julian date (MJD) time. This function does not + * add or subtract leapseconds. + * + * @return psF64: Modified Julian Days (MJD) time. + */ +psF64 psTimeToMJD( const psTime* time ///< Input time to be converted. ); @@ -193,6 +207,6 @@ /** Convert psTime to ISO8601 formatted string. * - * Converts psTime to a null terminated string in the form of YYYY-MM-DDThh:mm:ss.sss. This function does not - * add or subtract leapseconds. + * Converts psTime to a null terminated string in the form of YYYY-MM-DDThh:mm:ss.sss. + * This function does not add or subtract leapseconds. * * @return char*: Pointer null terminated array of chars in ISO time. @@ -206,21 +220,23 @@ * Converts psTime to timeval time. This function does not add or subtract leapseconds. * - * @return timeval: timeval struct time. - */ -struct timeval psTimeToTimeval( - const psTime* time ///< Input time to be converted. + * @return timeval*: timeval struct time. + */ +struct timeval* psTimeToTimeval( + const psTime* time ///< Input time to be converted. ); -/** Convert psTime to tm time. - * - * Converts psTime to tm time. This function is based on a Perl algorithm availble in the Pan-STARRS Image - * processing Algorithm Design Description (ADD). This function does not add or subtract leapseconds. +/* + * Convert psTime to tm time. + * + * Converts psTime to tm time. This function is based on a Perl algorithm availble + * in the Pan-STARRS Image processing Algorithm Design Description (ADD). This function + * does not add or subtract leapseconds. * * @return tm: tm struct time. - */ -struct tm* psTimeToTM( - const psTime *time ///< Input time to be converted. + * +struct tm* p_psTimeToTM( + const psTime *time ///< Input time to be converted. ); - +*/ /** Convert JD to psTime. * @@ -230,5 +246,5 @@ */ psTime* psTimeFromJD( - double time ///< Input time to be converted. + psF64 time ///< Input time to be converted. ); @@ -240,5 +256,5 @@ */ psTime* psTimeFromMJD( - double time ///< Input time to be converted. + psF64 time ///< Input time to be converted. ); @@ -250,5 +266,5 @@ */ psTime* psTimeFromISO( - const char* time ///< Input time to be converted. + const char* time ///< Input time to be converted. ); @@ -260,16 +276,40 @@ */ psTime* psTimeFromTimeval( - const struct timeval *time ///< Input time to be converted. + const struct timeval *time ///< Input time to be converted. +); + +/** Convert Terrestrial Time to psTime + * + * Converts Terrestial Time to psTime. This function assumes resultant time is of type TT. + * + * @return psTime*: time (TT) + */ +psTime* psTimeFromTT( + psS64 sec, ///< Input terrestrial time in seconds + psU32 nsec ///< Input terrestrial time fraction of seconds (nanoseconds) +); + +/** Convert UTC time to psTime + * + * Converts UTC time to psTime. It will verify if time specified is a leapsecond. + * + * @return psTime*: time (UTC) + */ +psTime* psTimeFromUTC( + psS64 sec, ///< Input time in seconds + psU32 nsec, ///< Input time fraction of seconds (nanoseconds) + psBool leapsecond ///< Input time is a leapsecond ); /** Convert tm time to psTime. * - * Converts tm time to psTime. This function is based on a Perl algorithm availble in the Pan-STARRS Image - * processing Algorithm Design Description (ADD). This function does not add or subtract leapseconds. + * Converts tm time to psTime. This function is based on a Perl algorithm availble + * in the Pan-STARRS Image processing Algorithm Design Description (ADD). This function + * does not add or subtract leapseconds. * * @return psTime*: time. */ -psTime* psTimeFromTM( - const struct tm *time ///< Input time to be converted. +psTime* p_psTimeFromTM( + const struct tm *time ///< Input time to be converted. ); @@ -281,6 +321,6 @@ */ psTime* psTimeMath( - const psTime *time, ///< Time. - psF64 delta ///< Time delta. + const psTime *time, ///< Time. + psF64 delta ///< Time delta. ); @@ -292,6 +332,6 @@ */ psF64 psTimeDelta( - const psTime *time1, ///< First time. - const psTime *time2 ///< Second time. + const psTime *time1, ///< First time. + const psTime *time2 ///< Second time. );