Changeset 1534

Timestamp:

Aug 13, 2004, 2:30:36 PM (22 years ago)

Author:

jhoblitt

Message:

ruff draft of the date and time handling API.

File:

• trunk/doc/pslib/psLibSDRS.tex (modified) (2 diffs)

trunk/doc/pslib/psLibSDRS.tex

@@ -1 @@
-%%% $Id: psLibSDRS.tex,v 1.67 2004-08-13 20:50:59 price Exp $
+%%% $Id: psLibSDRS.tex,v 1.68 2004-08-14 00:30:36 jhoblitt Exp $
 \documentclass[panstarrs,spec]{panstarrs}
 
@@ -3017 +3017 @@
 \subsection{Dates and times}
 
-We require a collection of functions to manipulate time data.  These
-operations primarily consist of conversions between specific time
-formats.  PSLib currently uses the UNIX \code{timeval} structure
-representation of time as the native time format.
-\begin{verbatim}
+We require a collection of functions to manipulate time data.  These operations
+primarily consist of conversions between specific time formats.  Internally,
+PSLib handles times as struct similar to the POSIX \code{struct timeval} which
+has been extended to track the time system being represented.
+
+\begin{verbatim}
+typedef enum {
+    PS_TIME_TAI,                    /* seconds since 1970-01-01T00:00:00Z (Gregorian) */
+    PS_TIME_UTC,                    /* seconds since 1970-01-01T00:00:00Z (Gregorian) */
+    PS_TIME_UT1,                    /* seconds since 1970-01-01T00:00:00Z (Gregorian) */
+    PS_TIME_LST,                    /* seconds since 1970-01-01T00:00:00Z (Gregorian) */
+} psTimeType;
+
 typedef struct {
-  time_t         tv_sec;   /* seconds */
-  suseconds_t    tv_usec;  /* microseconds */
+    psU64            sec;           /* seconds */
+    psU32            nsec;          /* nanoseconds */
+    psTimeType       type;          /* type of time */ 
 } psTime;
 \end{verbatim}
 
+A number of functions are provided to get the current time in a particular time
+system.
+
+\begin{verbatim}
+psTime *psGetTAI(void);
+psTime *psGetUTC(void);
+psTime *psGetUT1(void);
+psTime *psGetLST(psF64 longitude);
+psF64 *psGetJD(void);
+psF64 *psGetMJD(void);
+\end{verbatim}
+
+When converting to a time system the source time system is automaticaly
+converted to TAI and then from TAI to the destination type.
+
+\begin{verbatim}
+bool psTimeToTAI(psTimeType type, psTime *time);
+bool psTimeToUTC(psTimeType type, psTime *time);
+bool psTimeToUT1(psTimeType type, psTime *time);
+bool psTimeToLST(psTimeType type, psTime *time);
+psF64 psTimeToJD(psTime *time);
+psF64 psTimeToMJD(psTime *time);
+\end{verbatim}
+
+A collection of functions convert from the \code{psTime} types to various
+external formats.  Note that ISO8601 format is "YYYY-MM-DDThh:mm:ss,sZ"
+
+\begin{verbatim}
+char *psFormatISO8601(psTime *time);
+struct timeval *psFormatTimeval(psTime *time);
+\end{verbatim}
+
+A related collection of functions convert from external formats to a
+\code{psTime} type.
+
+\begin{verbatim}
+psTime *psParseISO8601(psTimeType type, char *input);
+psTime *psParseTimeval(psTimeType type, struct timeval *input);
+\end{verbatim}
+
+All \code{psTime} types must be able to be converted to to the TAI type.
+Conversion from one \code{psTime} type to another is achieved by first
+converting to TAI and then to the target type.
+
+\begin{verbatim}
+psTime *psTAIToUTC(psTime *time);
+psTime *psUTCToTAI(psTime *time);
+\end{verbatim}
+
 A utility function provides the current time from the system clock, in correct TAI units:
 \begin{verbatim}
-psTime psTimeGetTime (void);
-\end{verbatim}
-
-A collection of functions convert from the native \code{psTime} format
-to various external formats.  Note that ISO Time is represented by
-YYYY/MM/DD,HH:MM:SS.SSS.  
-\begin{verbatim}
-char *psTimeToISOTime (psTime time);
-double psTimeToUTC (psTime time);
-double psTimeToMJD (psTime time);
-double psTimeToJD (psTime time);
-struct timeval *psTimeToTimeval (psTime time);
-struct tm *psTimeToTm (psTime time);
-\end{verbatim}
-
-A matching set of functions convert from the external formats to the
-native \code{psTime}:
-\begin{verbatim}
-psTime *psISOTimeToTime (char *input);
-psTime *psUTCToTime (double input);
-psTime *psMJDToTime (double input);
-psTime *psJDToTime (double input);
-psTime *psTimevalToTime (struct timeval *input);
-psTime *psTMtoTime (struct tm *input);
+psTime *psTAIToUT1(psTime *time);
+psTime *psUT1ToTAI(psTime *time);
+\end{verbatim}
+
+\begin{verbatim}
+psTime *psTAIToLST(psTime *time, double longitude);
+psTime *psLSTToTAI(psTime *time, double longitude);
+\end{verbatim}
+
+A number of utility functions is needed for type conversion.
+
+\begin{verbatim}
+psTime *psUT1ToGMST00(psTime *time);
+psTime *psGMST00ToUT1(psTime *time);
+\end{verbatim}
+
+\begin{verbatim}
+psTime *psGMST00ToLST(psTime *time, double longitude);
+psTime *psLSTToGMST00(psTime *time, double longitude);
+\end{verbatim}
+
+Conversions to/from Julian Centuries.
+
+\begin{verbatim}
+psF64 psJDToJC(psF64 time);
+psF64 psJCToJD(psF64 time);
+\end{verbatim}
+
+\begin{verbatim}
+psF64 psMJDToJC(psF64 time);
+psF64 psJCToMJD(psF64 time);
+\end{verbatim}
+
+\begin{verbatim}
+unsigned int psGetLeapSeconds(psTime *utc);
+\end{verbatim}
+
+\begin{verbatim}
+double psGetUT1Delta(psTime *tai);
+\end{verbatim}
+
+Time math is only done on the \code{psTime} TAI type.
+
+\begin{verbatim}
+psTime *psTAIAdd(psTime *tai1, psTime *tai2);
+psTime *psTAISub(psTime *tai1, psTime *tai2);
+psTime *psTAIDelta(psTime *tai1, psTime *tai2);
 \end{verbatim}