tparse_c

Index Page tparse_c
A B C D E F G H I J K L M N O P Q R S T U V W X
Procedure Abstract Required_Reading Keywords Brief_I/O Detailed_Input | Detailed_Output Parameters Exceptions Files Particulars Examples | Restrictions Literature_References Author_and_Institution Version Index_Entries
#### Procedure
       void tparse_c ( ConstSpiceChar  * string,
                       SpiceInt          lenout,
                       SpiceDouble     * sp2000,
                       SpiceChar       * errmsg  )
#### Abstract
       Parse a time string and return seconds past the J2000 epoch
       on a formal calendar.
#### Required_Reading
       None.
#### Keywords
       PARSING, TIME
#### Brief_I/O
       VARIABLE  I/O  DESCRIPTION
       --------  ---  --------------------------------------------------
       string     I   Input time string, UTC.
       lenout     I   Available space in output error message string.
       sp2000     O   Equivalent UTC seconds past J2000.
       errmsg     O   Descriptive error message.
#### Detailed_Input
       string      is an input time string, containing a Calendar or
                   Julian Date.  It may be in several different formats
                   and can make use of abbreviations. Several example
                   strings and the times that they translate to are listed
                   below.

       lenout      is the maximum number of characters, including the
                   terminating null, that may be written to the output
                   error message string.
#### Detailed_Output
       sp2000      is the equivalent of UTC, expressed in UTC
                   seconds past J2000. If an error occurs, or if
                   the input time string is ambiguous, sp2000 is not
                   changed.

       errmsg      is a descriptive error message, which is empty when
                   no error occurs.
#### Parameters
       None.
#### Exceptions
       1)
#### Files
       None.
#### Particulars
       The input string is examined and the various components of a date
       are identified: julian date, year, month, day of year, day of month,
       hour, minutes, seconds.  These items are assumed to be components on
       a calendar that contains no leapseconds (i.e. every day is assumed
       to have exactly 86400 seconds).

       tparse_c recognizes a wide range of standard time formats. The
       examples section contains a list of several common strings that are
       recognized and their interpretation. tparse_c relies on the lower
       lever routine TPARTV to interpret the input string.

       Here is a brief summary of some of the basic rules used in the
       interpretation of strings.

       1)  Unless the substring JD or jd is present the string is assumed to
           be a calendar format (day-month-year or year and day of year).
           If the substring JD or jd is present, the string is assumed to
           represent a julian date.

       2)  If the julian date specifier is not present, any integer greater
           than 999 is regarded as being a year specification.

       3)  A dash '-' can represent a minus sign only if it is precedes the
           first digit in the string and the string contains the julian
           date specifier (JD).  (No negative years, months, days, etc are
           allowed).

       4)  Numeric components of a time string must be separated
           by a character that is not a digit or decimal point.
           Only one decimal component is allowed.  For example
           1994219.12819 is sometimes interpreted as the
           219th day of 1994 + 0.12819 days.  tparse_c does not
           support such strings.

           No exponential components are allowed.  For example you
           can't input 1993 Jun 23 23:00:01.202E-4 you have
           to explicitly list all zeros that follow the decimal
           point: i.e.  1993 Jun 23 23:00:00.0001202

       5)  The single colon (:) when used to separate numeric
           components of a string is interpreted as separating
           Hours, Minutes, and Seconds of time.

       6)  If a double slash (//) or double colon (::) follows
           a pair of integers, those integers are assumed  to
           represent the year and day of year.

       7)  A quote followed by an integer less than 100 is regarded
           as an abbreviated year.  For example: '93 would be regarded
           as the 93rd year of the reference century.  See TEXPYR
           for further discussion of abbreviated years.

        8) An integer followed by "B.C." or "A.D." is regarded as
           a year in the era associated with that abbreviation.

        9) All dates are regarded as belonging to the extended
           Gregorian Calendar (the Gregorian calendar is the calendar
           currently used by western society).  See the routine JUL2GR
           for  converting from Julian Calendar to the
           Gregorian Calendar.
           western society).

       10) When the size of the integer components does not clearly
           specify a year the following patterns are assumed

           Calendar Format

               Year Month Day
               Month Day Year
               Year Day Month

               Where Month is the name of a month, not its numeric
               value.

               When integer components are separated by slashes (/)
               as in 3/4/5.  Month, Day, Year is assumed (2005 March 4)

            Day of Year Format.

               If a day of year marker is present (// or ::) the
               pattern

               I-I// or I-I:: (where I stands for and integer)
               is interpreted as Year Day-of-Year. However, I-I/ is
               regarded as ambiguous.

       To understand the complete list of strings that can be understood
       by tparse_c you need to examine TPARTV and read the appendix to
       the TIME required reading entitled "Parsing Time Strings"

       tparse_c does not support the specification of time system
       such as TDT or TDB; AM/PM specifications of time; or time
       zones (such as PDT, UTC+7:20, etc.).

       If some part of the time string is not recognized or if
       the meaning of the components are not clear, an error string
       is constructed that explains the problem with the string.

       Since the routine is works by breaking the input string into
       a sequence of tokens whose meanings are determined by position
       and magnitude, you can supply strings such as 1993 FEB 35 and
       have this correctly interpreted as March 7, 1993.  However,
       this default action can be modified so that only "proper"
       calendar dates and times are recognized.  To do this call
       the routine TPARCH as shown below:

          TPARCH ( "YES" )

       This will cause the routine to treat dates and times with
       components outside the normal range as errors.

       To return to the default behavior

          TPARCH ( "NO" )
#### Examples
       The following are examples of valid inputs to TPARSE:

       ISO (T) Formats.

       String                        Year Mon  DOY DOM  HR Min Sec
       ----------------------------  ---- ---  --- ---  -- --- ------
       1996-12-18T12:28:28           1996 Dec   na  18  12  28 28
       1986-01-18T12                 1986 Jan   na  18  12  00 00
       1986-01-18T12:19              1986 Jan   na  18  12  19 00
       1986-01-18T12:19:52.18        1986 Jan   na  18  12  19 52.18
       1995-08T18:28:12              1995  na  008  na  18  28 12
       1995-18T                      1995  na  018  na  00  00 00

       Calendar Formats.

       String                        Year   Mon DOM  HR Min  Sec
       ----------------------------  ----   --- ---  -- ---  ------
       Tue Aug  6 11:10:57  1996     1996   Aug  06  11  10  57
       1 DEC 1997 12:28:29.192       1997   Dec  01  12  28  29.192
       2/3/1996 17:18:12.002         1996   Feb  03  17  18  12.002
       Mar 2 12:18:17.287 1993       1993   Mar  02  12  18  17.287
       1992 11:18:28  3 Jul          1992   Jul  03  11  18  28
       June 12, 1989 01:21           1989   Jun  12  01  21  00
       1978/3/12 23:28:59.29         1978   Mar  12  23  28  59.29
       17JUN1982 18:28:28            1982   Jun  17  18  28  28
       13:28:28.128 1992 27 Jun      1992   Jun  27  13  28  28.128
       1972 27 jun 12:29             1972   Jun  27  12  29  00
       '93 Jan 23 12:29:47.289       1993*  Jan  23  12  29  47.289
       27 Jan 3, 19:12:28.182        2027*  Jan  03  19  12  28.182
       23 A.D. APR 4, 18:28:29.29    0023** Apr  04  18  28  29.29
       18 B.C. Jun 3, 12:29:28.291   -017** Jun  03  12  29  28.291
       29 Jun  30 12:29:29.298       2029+  Jun  30  12  29  29.298
       29 Jun '30 12:29:29.298       2030*  Jun  29  12  29  29.298

       Day of Year Formats

       String                        Year  DOY HR Min Sec
       ----------------------------  ----  --- -- --- ------
       1997-162::12:18:28.827        1997  162 12  18 28.827
       162-1996/12:28:28.287         1996  162 12  28 28.287
       1993-321/12:28:28.287         1993  231 12  28 28.287
       1992 183// 12 18 19           1992  183 12  18 19
       17:28:01.287 1992-272//       1992  272 17  28 01.287
       17:28:01.282 272-1994//       1994  272 17  28 01.282
       '92-271/ 12:28:30.291         1992* 271 12  28 30.291
       92-182/ 18:28:28.281          1992* 182 18  28 28.281
       182-92/ 12:29:29.192          0182+ 092 12  29 29.192
       182-'92/ 12:28:29.182         1992  182 12  28 29.182

       Julian Date Strings

       jd 28272.291                  Julian Date   28272.291
       2451515.2981 (JD)             Julian Date 2451515.2981
       2451515.2981 JD               Julian Date 2451515.2981

                                    Abbreviations Used in Tables

                                       na    --- Not Applicable
                                       Mon   --- Month
                                       DOY   --- Day of Year
                                       DOM   --- Day of Month
                                       Wkday --- Weekday
                                       Hr    --- Hour
                                       Min   --- Minutes
                                       Sec   --- Sec

       * The default interpretation of a year that has been abbreviated
       with a leading quote as in 'xy (such as '92) is to treat
       the year as 19xy if xy > 68 and to treat it is 20xy otherwise.
       Thus '70 is interpreted as 1970 and '67 is treated as 2067.
       However, you may change the "split point" and centuries through
       use of the SPICE routine tsetyr_c which is an entry point in
       the SPICE module TEXPYR.  See that routine for a discussion of
       how you may reset the split point.

       ** All epochs are regarded as belonging to the Gregorian
       calendar.  We formally extend the Gregorian calendar backward
       and forward in time for all epochs.  If you have epochs belonging
       to the Julian Calendar, consult the routines TPARTV and JUL2GR
       for a discussion concerning conversions to the Gregorian
       calendar and ET.

       +  When a day of year format or calendar format string is
       input and neither of integer components of the date
       is greater than 1000, the first integer
       is regarded as being the year.

       Any integer greater than 1000
       is regarded as a year specification. Thus 1001-1821//12:28:28
       is interpreted as specifying two years and will be rejected
       as ambiguous.
#### Restrictions
       None.
#### Literature_References
       None.
#### Author_and_Institution
       N.J. Bachman    (JPL)
       J.M. Lynch      (JPL)
       W.M. Owen       (JPL)
       M.J. Spencer    (JPL)
       I.M. Underwood  (JPL)
       W.L. Taber      (JPL)
#### Version
       -CSPICE Version 1.0.0, 5-JUN-1999 (NJB)(JML)(WMO)(MJS)(IMU)(WLT)
#### Index_Entries
       parse a utc time string
#### Link to routine tparse_c source file tparse_c.c

    Thu Apr 16 08:59:23 2009