| tparse_c |
|
Table of contents
Procedure
tparse_c ( Parse a UTC time string )
void tparse_c ( ConstSpiceChar * string,
SpiceInt errmln,
SpiceDouble * sp2000,
SpiceChar * errmsg )
AbstractParse a time string and return seconds past the J2000 epoch on a formal calendar. Required_ReadingTIME KeywordsPARSING TIME Brief_I/OVARIABLE 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.
ParametersNone. 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.
FilesNone. 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.
RestrictionsNone. Literature_ReferencesNone. Author_and_InstitutionN.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_Entriesparse a utc time string |
Fri Dec 31 18:41:14 2021