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 tparch_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

       tparch_c ( Parse check---check format of strings )

       void tparch_c ( ConstSpiceChar    * type )

#### Abstract

       Restrict the set of strings that are recognized by SPICE time
       parsing routines to those that have standard values for all time
       components.

#### Required_Reading

       TIME

#### Keywords

       PARSING
       TIME

#### Brief_I/O

       VARIABLE  I/O  DESCRIPTION
       --------  ---  --------------------------------------------------
       type       I   String: Use "YES" to restrict time inputs.

#### Detailed_Input

       type        is a character string that is used to adjust the set of
                   strings that will be regarded as valid time strings by
                   SPICE time parsing routines.

                   The default behavior of SPICE time software is to allow
                   an extended range of values for the various components
                   (tokens) of a time string. For example, using its default
                   behavior, tparse_c would regard 1993 JAN 367 as a valid
                   time string and return the UTC seconds past the J2000
                   epoch value that corresponds to Jan 2, 1994.

                   While this is a "reasonable" interpretation of such a
                   string, there may be occasions when such a string should
                   be regarded as an error.

                   By calling tparch_c with a value of "YES", the action of
                   the time software will be modified. Strings that have
                   components that are out of the range of values used in
                   most English discourse will be regarded as errors. Thus
                   the numeric values of MONTH, DAY, HOUR, MINUTE, and
                   SECOND must satisfy the following conditions to be
                   regarded as legitimate calendar time strings.

                      ITEM     Valid Range
                      ------   -----------------------------------------
                      MONTH    1 to 13
                      DAY      1 to 365 (366 for leap years) when
                               DAY is interpreted as the day of year
                               i.e. the month token is empty.
                               1 to 31  if month is January
                               1 to 28  (29 in leap years) if month is
                                        February
                               1 to 31  if month is March
                               1 to 30  if month is April
                               1 to 31  if month is May
                               1 to 31  if month is June
                               1 to 30  if month is July
                               1 to 31  if month is August
                               1 to 30  if month is September
                               1 to 31  if month is October
                               1 to 30  if month is November
                               1 to 31  if month is December
                      HOUR     0 to 23
                      MINUTE   0 to 59
                      SECOND   0 up to but not including 60 on days that
                               can not have a leapsecond.
                               0 up to but not including 61 for times
                               that are the last second of June or
                               December. In other words,
                                    JUN 30, 23:59:60.xxxxxx...x
                               and  DEC 31, 23:59:60.xxxxxx...x

                   To reset the action of time software to the default
                   action, set `type' to a value that is not equivalent to
                   "YES" when case and spaces are ignored.

#### Detailed_Output

       None.

#### Parameters

       None.

#### Exceptions

       1)  If the `type' input string pointer is null, the error
           SPICE(NULLPOINTER) is signaled.

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

#### Files

       None.

#### Particulars

       This routine is used to alter the collections of strings
       that SPICE software regards as legitimate calendar strings. The
       default behavior of SPICE software is to accept strings such
       as FEB 34, 1993 and to interpret these in a "natural way"
       (FEB 34, 1993 is regarded as MARCH 6, 1993.) This behavior
       is sometimes useful for "private" programs that you write.
       However, such a string may be a typo (a finger accidentally hit
       two keys for the day instead of one). Given that this string
       does not appear in common usage, you may want to consider
       that it is more likely the result of erroneous input. You
       can alter the behavior of SPICE software so that it will
       treat such a string as an error. To do this call this entry
       point with `type' having the value "YES".

          tparch_c ( "YES" );

       Until the behavior is reset by calling tparch_c with a value
       other than "YES" (such as "NO"), SPICE software will treat all
       out-of-bound components of time strings as errors.

       If you are happy with the SPICE default interpretation of
       strings, you do not need to make any calls to tparch_c.

       All time parsing routines --including the top-level APIs tparse_c
       and utc2et_c-- respect the setting assigned by tparch_c, except the
       CSPICE routine str2et_c.

#### Examples

       The numerical results shown for this example 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) When accepting times as input interactively, you usually
          read a string typed at a keyboard and then pass that string
          to the SPICE time system to convert it to an ephemeris time.
          The default behavior of SPICE software is to accept strings
          such as FEB 34, 1993 and to interpret these in a "natural way"
          (FEB 34, 1993 is regarded as MARCH 6, 1993.) The following
          example code demonstrates how to modify this behavior.

          Example code begins here.

          /.
             Program tparch_ex1
          ./
          #include <stdio.h>
          #include <string.h>
          #include "SpiceUsr.h"

          int main( )
          {

             /.
             Local parameters.
             ./
             #define TIMSTR       "FEB 34, 1993"
             #define ERRMLN       1001

             /.
             Local variables.
             ./
             SpiceChar            errmsg [ERRMLN];

             SpiceDouble          sp2000;

             /.
             First, demonstrate the default behavior of SPICE.
             Let's get the number of UTC seconds past J2000 epoch.
             ./
             tparse_c ( TIMSTR, ERRMLN, &sp2000, errmsg );

             if ( !strncmp( errmsg, "", 1 ) )
             {
                printf( "UTC (s):  %17.6f\n", sp2000 );
             }
             else
             {
                printf( "Error  : %s\n", errmsg );
             }

             /.
             Now, turn error checking on and parse the time string
             again.
             ./
             tparch_c ( "YES" );
             tparse_c ( TIMSTR, ERRMLN, &sp2000, errmsg );

             if ( !strncmp( errmsg, "", 1 ) )
             {
                printf( "UTC (s):  %17.6f\n", sp2000 );
             }
             else
             {
                printf( "Error  : %s\n", errmsg );
             }

             return ( 0 );
          }

          When this program was executed on a Mac/Intel/cc/64-bit
          platform, the output was:

          UTC (s):  -215352000.000000
          Error  : The day of the month specified for the month of February was ***

          Warning: incomplete output. 1 line extended past the right
          margin of the header and has been truncated. This line is
          marked by "***" at the end of the line.

#### Restrictions

       None.

#### Literature_References

       None.

#### Author_and_Institution

       J. Diaz del Rio     (ODC Space)

#### Version

       -CSPICE Version 1.0.0, 01-NOV-2021 (JDR)

#### Index_Entries

       Restrict time strings to proper form

#### Link to routine tparch_c source file tparch_c.c

    Fri Dec 31 18:41:14 2021