Index of Functions: A  B  C  D  E  F  G  H  I  J  K  L  M  N  O  P  Q  R  S  T  U  V  W  X 
Index Page
tparse_c

Table of contents
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

   tparse_c ( Parse a UTC time string ) 

   void tparse_c ( ConstSpiceChar  * string,
                   SpiceInt          errmln,
                   SpiceDouble     * sp2000,
                   SpiceChar       * errmsg  )

Abstract

   Parse a time string and return seconds past the J2000 epoch
   on a formal calendar.

Required_Reading

   TIME

Keywords

   PARSING
   TIME


Brief_I/O

   VARIABLE  I/O  DESCRIPTION
   --------  ---  --------------------------------------------------
   string     I   Input time string, UTC.
   errmln     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 in the
               -Examples section.

   errmln      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)  If the `string' input string pointer is null, the error
       SPICE(NULLPOINTER) is signaled.

   2)  If the `string' input string has zero length, the error
       SPICE(EMPTYSTRING) is signaled.

   3)  If the `errmsg' output string pointer is null, the error
       SPICE(NULLPOINTER) is signaled.

   4)  If the `errmsg' output string has length less than two
       characters, the error SPICE(STRINGTOOSHORT) is signaled, since
       the output string is too short to contain one character of
       output data plus a null terminator.

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 level SPICELIB 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 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.

   5)  No exponential components are allowed. For example you
       can't specify the Julian date of J2000 as 2.451545E6.
       You also can't input 1993 Jun 23 23:00:01.202E-4 and have
       to explicitly list all zeros that follow the decimal
       point: i.e. 1993 Jun 23 23:00:00.0001202.

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

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

   8)  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 the SPICELIB
       routine TEXPYR for further discussion of abbreviated years.

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

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

   11) If the ISO date-time separator (T) is present in the string
       ISO allowed token patterns are examined for a match
       with the current token list. If no match is found the
       search is abandoned and appropriate diagnostic messages
       are generated. Historically the interpretation of ISO 
       formatted time strings deviates from the ISO standard in 
       allowing two digit years and expanding years in the 0 to 99 
       range the same way as is done for non ISO formatted strings. 
       Due to this interpretation it is impossible to specify 
       times in years in the 0 A.D. to 99 A.D. range using ISO 
       formatted strings on the input.

   12) If two delimiters are found in succession in the time
       string, the time string is diagnosed as an erroneous string.
       (Delimiters are comma, white space, dash, slash, period, or
       day of year mark. The day of year mark is a pair of forward
       slashes or a pair of colons.)

       Note the delimiters do not have to be the same. The pair
       of characters ",-" counts as two successive delimiters.

   13) White space and commas serve only to delimit tokens in the
       input string. They do not affect the meaning of any
       of the tokens.

   14) If an integer is greater than 1000 (and the "JD" label
       is not present, the integer is regarded as a year.

   15) 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 an 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 the SPICELIB routine 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 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_c as shown below:

      tparch_c ( "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_c ( "NO" );

   This routine returns information about parse errors in the output
   string `errmsg'.

Examples

   The numerical results shown for these examples may differ across
   platforms. The results depend on the SPICE kernels used as
   input, the compiler and supporting libraries, and the machine
   specific arithmetic implementation.

   1) Parse a series of time strings representing calendar dates and
      output number of seconds past J2000 epoch that corresponds to
      each of them. Some of the input strings have an invalid format
      which is reflected in their output.


      Example code begins here.


      /.
         Program tparse_ex1
      ./
      #include <stdio.h>
      #include "SpiceUsr.h"

      int main( )
      {
         /.
         Local constants
         ./
         #define ERRMLN          37

         /.
         Local variables.
         ./
         SpiceChar               errmsg [ ERRMLN ];
         SpiceDouble             sp2000;
         SpiceInt                i;

         /.
         Assign an array of calendar dates. Not all of them are
         valid.
         ./
         SpiceChar             * date[] =  { "1986-01-18T12:19:52.18",
                                             "17JUN1982 18:28:28",
                                             "182-'92/ 12:28:29.182",
                                             "'67-271/ 12:28:30.291",
                                             "-467-14-25 26:00:75",
                                             "1993 FEB 35",
                                             "1993 MAR 7"            };

         /.
         Loop over the `date' array, call tparse_c for each element.
         ./
         printf( "    Input string        UTC sec past J2000\n" );
         printf( "----------------------  ------------------\n" );

         for (i = 0; i < 7; i++ )
         {
            tparse_c ( date[i], ERRMLN, &sp2000, errmsg );

            if ( iswhsp_c(errmsg) )
            {
               printf ( "%-22s  %18.6f\n", date[i], sp2000 );
            }
            else
            {
               printf ( "%-22s  %s\n", date[i], errmsg );
            }
         }

         return ( 0 );
      }


      When this program was executed on a PC/Linux/gcc/64-bit
      platform, the output was:


          Input string        UTC sec past J2000
      ----------------------  ------------------
      1986-01-18T12:19:52.18   -440293207.820000
      17JUN1982 18:28:28       -553541492.000000
      182-'92/ 12:28:29.182    -236820690.818000
      '67-271/ 12:28:30.291    2137710510.291000
      -467-14-25 26:00:75     An unexpected delimiter ('-') was en
      1993 FEB 35              -215265600.000000
      1993 MAR 7               -215265600.000000


      Note that the "1993 FEB 35" string in converted to UTC seconds
      past J2000, interpreted as "1993 MAR 7". Also note that the
      error message resulting from parsing "-467-14-25 26:00:75"
      is truncated to the provided ERRMLN length.


   2) Below is a sampling of some of the time formats that are
      acceptable as inputs to tparse_c. A complete discussion of
      permissible formats is given in the reference document
      time.req.


      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
      1986-01-18T12:19:52.18Z       1986 Jan   na  18  12  19 52.18
      1995-08T18:28:12              1995  na  008  na  18  28 12
      1995-08T18:28:12Z             1995  na  008  na  18  28 12
      1995-18T                      1995  na  018  na  00  00 00
      0000-01-01T                   1 BC Jan   na  01  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 to two digits with or without a leading quote
         as in 'xy or xy (such as '92 or 92) is to treat the year as
         19xy if xy > 68 and to treat it as 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 CSPICE routine tsetyr_c. 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 SPICELIB
         routines TPARTV and JUL2GR for a discussion concerning
         conversions to the Gregorian calendar and ET. The routines
         timdef_c and str2et_c, used together, also support conversions
         from Julian Calendar epochs to ET.

      +  When a day of year format or calendar format string is
         input and neither of the 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)
   M. Costa Sitja      (JPL)
   J. Diaz del Rio     (ODC Space)
   J.M. Lynch          (JPL)
   W.M. Owen           (JPL)
   M.J. Spencer        (JPL)
   W.L. Taber          (JPL)
   I.M. Underwood      (JPL)

Version

   -CSPICE Version 1.1.0, 23-DEC-2021 (JDR) (MCS)

       Changed the input argument name "lenout" to "errmln" for
       consistency with other routines.

       Edited the header to comply with NAIF standard. Added complete
       code example.

       Updated the -Exceptions and -Particulars sections.

       Added TIME to -Required_Reading list.

   -CSPICE Version 1.0.1, 23-JUL-2015 (NJB)

       Filled in -Exceptions section of header.

   -CSPICE Version 1.0.0, 05-JUN-1999 (NJB) (JML) (WMO) (MJS) (IMU) (WLT)

Index_Entries

   parse a utc time string
Fri Dec 31 18:41:14 2021