/*

-Procedure tparse_c ( Parse a UTC time string )

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

   THIS SOFTWARE AND ANY RELATED MATERIALS WERE CREATED BY THE
   CALIFORNIA INSTITUTE OF TECHNOLOGY (CALTECH) UNDER A U.S.
   GOVERNMENT CONTRACT WITH THE NATIONAL AERONAUTICS AND SPACE
   ADMINISTRATION (NASA). THE SOFTWARE IS TECHNOLOGY AND SOFTWARE
   PUBLICLY AVAILABLE UNDER U.S. EXPORT LAWS AND IS PROVIDED "AS-IS"
   TO THE RECIPIENT WITHOUT WARRANTY OF ANY KIND, INCLUDING ANY
   WARRANTIES OF PERFORMANCE OR MERCHANTABILITY OR FITNESS FOR A
   PARTICULAR USE OR PURPOSE (AS SET FORTH IN UNITED STATES UCC
   SECTIONS 2312-2313) OR FOR ANY PURPOSE WHATSOEVER, FOR THE
   SOFTWARE AND RELATED MATERIALS, HOWEVER USED.

   IN NO EVENT SHALL CALTECH, ITS JET PROPULSION LABORATORY, OR NASA
   BE LIABLE FOR ANY DAMAGES AND/OR COSTS, INCLUDING, BUT NOT
   LIMITED TO, INCIDENTAL OR CONSEQUENTIAL DAMAGES OF ANY KIND,
   INCLUDING ECONOMIC DAMAGE OR INJURY TO PROPERTY AND LOST PROFITS,
   REGARDLESS OF WHETHER CALTECH, JPL, OR NASA BE ADVISED, HAVE
   REASON TO KNOW, OR, IN FACT, SHALL KNOW OF THE POSSIBILITY.

   RECIPIENT BEARS ALL RISK RELATING TO QUALITY AND PERFORMANCE OF
   THE SOFTWARE AND ANY RELATED MATERIALS, AND AGREES TO INDEMNIFY
   CALTECH AND NASA FOR ALL THIRD-PARTY CLAIMS RESULTING FROM THE
   ACTIONS OF RECIPIENT IN THE USE OF THE SOFTWARE.

-Required_Reading
 
   None. 
 
-Keywords
 
   PARSING, TIME 
 
*/

   #include "SpiceUsr.h"
   #include "SpiceZfc.h"
   #include "SpiceZst.h"
   #include "SpiceZmc.h"
   

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

-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
 
   Error free. 

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

-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.1, 23-JUL-2015 (NJB)

       Filled in Exceptions section of header.

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

-Index_Entries
 
   parse a utc time string 
 
-&
*/

{ /* Begin tparse_c */



   /*
   Use discovery check-in.
   */


   /*
   Check the input time string to make sure the pointer is non-null and
   the string length is non-zero.
   */
   CHKFSTR ( CHK_DISCOVER, "tparse_c", string );


   /*
   Check the output error message string to make sure the pointer is 
   non-null and the string length is at least 2.
   */
   CHKOSTR ( CHK_DISCOVER, "tparse_c", errmsg, lenout );


   /*
   Call the f2c'd routine.
   */ 

   tparse_ (  ( char        * ) string,
              ( doublereal  * ) sp2000,
              ( char        * ) errmsg,
              ( ftnlen        ) strlen(string),
              ( ftnlen        ) lenout-1        );

   /*
   Convert the error message from Fortran to C style.
   */
   F2C_ConvertStr ( lenout, errmsg );
   
   
} /* End tparse_c */

