| SPICE Time Subsystem |
Table of ContentsSPICE Time Subsystem Abstract References Introduction Intended Audience Overview SPICE Time Representations Coordinated Universal Time (UTC) International Atomic Time (TAI) Naming the seconds of TAI --- UTC Tying UTC to the Earth's Rotation Leapseconds The Leapseconds Kernel (LSK) Barycentric Dynamic Time (TDB) The J2000 Epoch Barycentric Dynamical Time (TDB) Terrestrial Time (TT) The Relationship between TT and TDB In the Toolkit ET Means TDB Naming the Seconds of TDB Leapseconds Computing UTC from TDB Problems With the Formulation of DeltaET Spacecraft Clock (SCLK) Julian Date The abbreviation JD Time Subsystem Functions Function to load needed kernels Function to convert a time string to TDB (ET) Function to convert UTC to TDB (ET) Function to convert a spacecraft clock time string to TDB (ET) Function to convert a TDB (ET) to a time string based on a format template Function to convert a TDB (ET) to UTC Function to convert a TDB (ET) to Spacecraft Clock time string Function to convert a TDB (ET) to Calendar format TDB Function to convert a TDB (ET) to Local True Solar Time Function to convert a TDB (ET) to planetocentric longitude of the sun Function to convert between uniform time scales Function to compute the difference between TDB (ET) and UTC Function to create a time string format picture Functions returning time constants Foundation Routines and Utilities Parse a time string to a time vector Convert between different parsed representations of time Time utility functions Input String Conversion Parsing Time Strings Labels (A.M. and P.M.) Labels (Time Zones) Labels ( TDB, TT, and UTC ) Changing Default Behavior Abbreviated Years Range of Time String Components Default Time Systems, Time Zone, and Calendar Changing the Time System Time Zones Calendars Usage example Appendix A. Summary of Time Subsystem Functions Appendix B. Non-native text files Appendix C. Parsing Time Strings An Outline of the Parser Tokenizing the Input String Combining and Removing Tokens Initial Token Processing Julian Dates Calendar Dates ISO Formats Other Calendar Formats Built in Representations Last Resort Production Rules Conclusion Appendix D: Document Revision History 2021 SEP 10 by E. D. Wright and M. Costa Sitja 2017 MAR 06 by E. D. Wright. 2015 SEP 09 by N. J. Bachman. 2012 JUN 14 by E. D. Wright. 2009 APR 09 2009 by E. D. Wright, B. V. Semenov. 2004 DEC 23 by NAIF. 2004 FEB 02 by NAIF. 1997 NOV 18 by E. D. Wright. CSPICE naming conventions 1997 JUL 22 by NAIF. 1996 OCT 15 by NAIF. 1994 JUN 30 by NAIF. 1992 APR 13 by NAIF. SPICE Time Subsystem
Abstract
References
[1] Moyer, T.D., "Transformation from Proper Time on Earth to
Coordinate Time in Solar System Barycentric Space-Time Frame
of Reference, Parts 1 and 2," Celestial Mechanics 23 (1981),
33-56 and 57-68.
[2] Moyer, T.D., Effects of Conversion to the J2000 Astronomical
Reference System on Algorithms for Computing Time Differences
and Clock Rates, JPL IOM 314.5--942, 1 October 1985.
[3] The Explanatory Supplement to the Astronomical Almanac (1992)
Edited by P. Kenneth Seidelmann, University Science Books,
Mill Valley, California 94941.
[4] SCLK Required Reading (sclk.req)
[5] Kernel Required Reading (kernel.req)
[6] James Jespersen and Jane Fitz-Randolph ``From Sundials to
Atomic Clocks---Understanding Time and Frequency''
(Dover Publications, Inc. 1977) ISBN 0-486-24265-X.
[7] Standish, E. M., Astron. Astrophys., "Time Scales in the JPL
and CfA Ephemerides", 336, 381-384 (1998).
[8] SPICE Time Subsystem Tutorial,
(https://naif.jpl.nasa.gov/naif/tutorials.html).
[9] Most Used SPICE APIs document (mostused.html).
The variable names used are consistent with notations used in the
Astronomical Almanac.
Introduction
The Toolkit also supports conversion between spacecraft clock (SCLK) and Barycentric Dynamical Time (TDB). CSPICE functions dealing with spacecraft clock are discussed in SCLK Required Reading (sclk.req). Intended Audience
Overview
SPICE Time Representations
The Toolkit supports these time systems
Coordinated Universal Time (UTC)International Atomic Time (TAI)
Naming the seconds of TAI --- UTC
00:00:00is midnight and is the first instant of the calendar day specified by the first three components of the UTC time. In the SPICE system UTC times are represented by character strings. These strings contain: year, month, day, hour, minute and second separated by delimiters (spaces or punctuation marks). The various delimiters and substrings between the delimiters are called the tokens of the string. A typical time string looks like
5 OCTOBER 1986 7:20:16.122 (UTC)The tokens of the string and the associated UTC time components are
5 --- day OCTOBER --- month 1986 --- year 7 --- hours 20 --- minutes 16.122 --- secondsThe link between any token and its corresponding UTC component is determined by examining the values of the tokens and comparing them to the other tokens. The precise rules used are spelled out in great detail in Appendix C. For now, simply be assured that the following five strings all mean the same thing and are interpreted in the same way by SPICE.
5 OCTOBER 1986 1986 OCTOBER 5 1986 5 OCTOBER 1986 10 5 10 5 1986 Tying UTC to the Earth's Rotation
Leapseconds
... DECEMBER 31 23:59:57 ... DECEMBER 31 23:59:58 ... DECEMBER 31 23:59:59 ... DECEMBER 31 23:59:60 ... JANUARY 1 00:00:00instead of the usual progression
... DECEMBER 31 23:59:57 ... DECEMBER 31 23:59:58 ... DECEMBER 31 23:59:59 ... JANUARY 1 00:00:00Should Greenwich UT1 midnight run ahead of UTC midnight by more than 0.9 seconds the IERS will announce a negative leap second. In this case one of the usual UTC hours-minutes-seconds triples will be missing from the list of UTC names. In this case the progression will be:
... DECEMBER 31 23:59:57 ... DECEMBER 31 23:59:58 ... JANUARY 1 00:00:00Since 1972 when leap seconds and the UTC system were introduced, a negative leap second has not occurred. Leapseconds occur at the same time in all time zones. In other words, the seconds component of a time string is the same for any time zone as is the seconds component of UTC. The following are all legitimate ways to represent an epoch of some event that occurred in the leapsecond
1995 December 31 23:59:60.5 (UTC) 1996 January 1, 05:29:60.5 (UTC+5:30 --- Calcutta Time) 1995 December 31, 20:29:60.5 (UTC-3:30 --- Newfoundland) 1995 December 31 18:59:60.5 (EST) 1995 December 31 17:59:60.5 (CST) 1995 December 31 16:59:60.5 (MST) 1995 December 31 15:59:60.5 (PST) The Leapseconds Kernel (LSK)
LSK files conform to a flexible format called ``NAIF text kernel'' format. The SPICE file identification word provided by itself on the first line of an LSK file is ``KPL/LSK''. Both the NAIF text kernel format and SPICE file identification word are described in detail in the Kernel Required Reading document, kernel.req. When the IERS announces a new leapsecond will be declared in the future, NAIF makes available an updated Leapseconds Lernel several months prior to the new leapsecond taking effect and announces its availability to the SPICE user community. Barycentric Dynamic Time (TDB)
The J2000 Epoch
(As we've seen, ``J2000'' is used to name the fundamental inertial frame as well as a particular epoch. This can sometimes be confusing if you are not careful to distinguish the context in which the term ``J2000'' is used.) Barycentric Dynamical Time (TDB)
Terrestrial Time (TT)
The Relationship between TT and TDB
At some times in the year the TT clock appears to run fast when compared to the TDB clock, at other times of the year it appears to run slow. Let TDB0 be some fixed epoch on the TDB clock and TT0 be a fixed epoch on the TT clock (TDB0 and TT0 do not necessarily have to be the same epoch). Any epoch, EPOCH, can be represented in the following ways: as the number of seconds TDB(EPOCH), that have elapsed since TDB0 on the TDB clock; or as the number of seconds, TT(EPOCH), that have elapsed since TT0 on the TT clock. If we plot the differences TDB(EPOCH) - TT(EPOCH) against TDB(EPOCH) over all epochs, we will find that the graph is very close to a periodic function. In SPICE the difference between TT and TDB is computed as follows:
TDB - TT = K * sin (E) (1)
where K is a constant, and E is the eccentric anomaly of the
heliocentric orbit of the Earth-Moon barycenter. This difference, which
ignores small-period fluctuations, is accurate to about 0.000030
seconds. To five decimal places the difference between TT and TDB is a
periodic function with magnitude approximately 0.001658 seconds and
period equal to one sidereal year.
The eccentric anomaly E is given by
E = M + EB sin (M) (2)
where EB and M are the eccentricity and mean anomaly of the heliocentric
orbit of the Earth-Moon barycenter. The mean anomaly is in turn given by
M = M0 + M1*t (3)
where t is the epoch TDB expressed in barycentric dynamical seconds past
the epoch of J2000.
The values K, EB, M0, and M1 are retrieved from the kernel pool. These are part of the Leapseconds Kernel. They correspond to the ``kernel pool variables'' DELTET/K, DELTET/EB, and DELTET/M. The nominal values are:
DELTET/K = 1.657D-3 DELTET/EB = 1.671D-2 DELTET/M = ( 6.239996D0 1.99096871D-7 ) In the Toolkit ET Means TDB
Ephemeris time is given in terms of seconds past a reference epoch. The reference epoch used throughout the Toolkit is the epoch J2000 (roughly noon on January 1, 2000). Using the Toolkit software, you can find out how many seconds the J2000 epoch is from right now. SPICE uses a double precision value for TDB in all Toolkits. Naming the Seconds of TDB
However, ephemeris time is described as a count of ephemeris seconds past the ephemeris reference epoch (J2000). For most of us the expression
-312819349 seconds past the ephemeris epoch J2000bears little relationship to the time system we use to organize our lives. For this reason, it is common to give names to the various ephemeris seconds in a manner analogous to the UTC naming of the seconds of TAI---as a calendar date and time of day. The above string corresponds to
1990 FEB 1 21:44:11 (TDB)There is an important distinction between the names given to ephemeris seconds and the names used by the UTC system. The names assigned to ephemeris times never have leap seconds. The `seconds' component of the name is restricted to and includes all values from 0 to 59.999... . Thus the time string above does not represent the same moment in time as does ``1990 FEB 1 21:44:11 (UTC)'' There are two reasons. First, ephemeris time is ahead of atomic time by 32.184 seconds. Second, when a leap second occurs, UTC strings fit an extra name into the sequence of valid UTC names. Thus it appears that UTC names fall behind TDB names by a second after each leapsecond. For instance, as of 2020 DEC 01 UTC time strings appear to be 69.184 seconds behind TDB time strings. This difference is due to the fact that the two naming conventions are not the same; they simply have a lot of names in common. It is both fortunate and unfortunate that there is a huge set of common names between calendar dates TDB and calendar dates UTC. Since there are relatively few leapseconds, a time given by an TDB name is always close to the time in the UTC system having the same name. Thus for planning whether or not you are likely to need a coat and how to arrange your daily activities around the observation. But for precise work you must pay attention to the difference between the two time systems. If in planning the observation of a stellar occultation by an asteroid the difference between the two naming systems is neglected, it is likely that the observation will be missed. Leapseconds
Any given Leapseconds Kernel will eventually become obsolete. Sometime after the creation of any Leapseconds Kernel there will be a new leapsecond that must be accounted for. When future leapseconds occur the old Leapseconds Kernel will no longer correctly describe the relationship between UTC, TT and TDB for epochs that follow the new leapsecond. However, for epochs prior to the new leapsecond, the old kernel will always correctly describe the relationship between UTC, TT and TDB. NAIF announces the addition, or not, of a new leapsecond declared by the IERS several months in advance of it taking place. Simultaneously NAIF prepares and announces a new Leapseconds Kernel if one is needed. Computing UTC from TDB
1996, Oct 11, 12:01:02.1840 (TT) 1996, Oct 11, 12:00:00.0000 (UTC) 1996, Oct 12, 12:01:02.1840 (TT) 1996, Oct 12, 12:00:00.0000 (UTC) 1996, Oct 13, 12:01:02.1840 (TT) 1996, Oct 13, 12:00:00.0000 (UTC) 1996, Oct 14, 12:01:02.1840 (TT) 1996, Oct 14, 12:00:00.0000 (UTC) 1996, Oct 15, 12:01:02.1840 (TT) 1996, Oct 15, 12:00:00.0000 (UTC)At least in October 1996, it's clear that if you have either TT or UTC you can construct the corresponding representation for the same epoch in the UTC or TT system by simply subtracting or adding 62.184 seconds. If you don't worry about what happens during a leapsecond you can express the above idea as:
DeltaTT = TT - UTC (4)
For all epochs except during UTC leapseconds the above expression makes
sense. DeltaTT is simply a step function, increasing by one after each
leapsecond. Thus DeltaTT can be viewed as a step function of either UTC
or TT.
If you rearrange this expression, you can get
UTC = TT - DeltaTT (5)
Since, TT can be expressed as seconds past J2000 (TT), the above
expression indicates that UTC can be expressed as some count of seconds.
This representation is referred to by the dubious name of ``UTC seconds
past J2000.'' If you write down the UTC calendar time string
corresponding to an epoch and count the number of seconds between that
calendar expression and the UTC calendar expression ``January 1, 2000
12:00:00'' and ignore leapseconds, you get the value of UTC in the
expression above.
In practice this expression is broken down as follows:
UTC = TT - DeltaTA - DeltaAT (6)
where
DeltaTA = (TT - TAI)
and
DeltaAT = DeltaTT - DeltaTA
The value DeltaTA is a constant, its value is nominally 32.184 seconds.
DeltaTA is a step function. These two variables appear in the
Leapseconds Kernel.
If we combine equation (6) above with equation (1) from the section ``The Relationship between TT and TDB'' we get the following expression
TDB - UTC = DeltaTA + DeltaAT + K*sin(E) (7)
This last value is called DeltaET and is computed by the CSPICE function
deltet_c. The various values that are used in the computation of DeltaET
are contained in the Leapseconds Kernel. Below we show the principal
contents of a sample Leapseconds kernel.
\begindata
DELTET/DELTA_T_A = 32.184
DELTET/K = 1.657D-3
DELTET/EB = 1.671D-2
DELTET/M = ( 6.239996D0 1.99096871D-7 )
DELTET/DELTA_AT = ( 10, @1972-JAN-1
11, @1972-JUL-1
12, @1973-JAN-1
13, @1974-JAN-1
14, @1975-JAN-1
15, @1976-JAN-1
16, @1977-JAN-1
17, @1978-JAN-1
18, @1979-JAN-1
19, @1980-JAN-1
20, @1981-JUL-1
21, @1982-JUL-1
22, @1983-JUL-1
23, @1985-JUL-1
24, @1988-JAN-1 )
\begintext
DELTET/DELTA_T_A corresponds to DeltaTA in equation (7).
DELTET/K corresponds to K in equation (7).
DELTET/EB corresponds to EB in equation (2).
DELTET/M corresponds to M0 and M1 of equation (3).
DELTET/DELTA_AT corresponds to DeltaAT of equation (7).
Note that this expression gives the
points on the UTC scale at which
DeltaAT changes.
Problems With the Formulation of DeltaET
1996 Jan 01, 00:01:01.6840 (TT) 1996 Dec 31, 23:59:60.5000 (UTC)Given these two epochs, it is no longer clear what we should assign to the value TT - UTC. Thus, although equation (7) above provides a simple expression for computing the ``difference between UTC and TDB'', the expression fails to tell us how to convert between TDB (or TT) and UTC during leapseconds. For this reason the SPICE system does not use DeltaET when converting between TDB (or TT) and UTC. Instead, the table of offsets corresponding to DeltaAT in the Leapseconds Kernel is converted to an equivalent table as shown below.
Day Number of 1971-DEC-31 TAI seconds past 2000 at
beginning of 1971-DEC-31
Day Number of 1972-JAN-01 TAI seconds past 2000 at
beginning of 1972-JAN-01
Day Number of 1972-JUN-30 TAI seconds past 2000 at
beginning of 1972-JUN-30
Day Number of 1972-JUL-01 TAI seconds past 2000 at
beginning of 1972-JUL-01
Day Number of 1972-DEC-31 TAI seconds past 2000 at
beginning of 1972-DEC-31
Day Number of 1973-JAN-01 TAI seconds past 2000 at
beginning of 1973-JAN-01
Day Number of 1973-DEC-31 TAI seconds past 2000 at
beginning of 1973-DEC-31
. .
. .
. .
where the day number associated with a particular calendar date is the
integer number of days that have passed since Jan 01, 0001 A.D. (on the
extended Gregorian Calendar).
Given an epoch to be converted between UTC and some other time system (call this other system `S'), we decompose the conversion problem into two parts:
Having settled the problem of converting between TAI and UTC, the conversion between TAI and system S is carried out using the analytic expressions (equations (1), (2) and (3)) given above. Spacecraft Clock (SCLK)
Each spacecraft clock can be constructed differently. For Galileo the SPICE spacecraft clock times looks like
p/rrrrrrrr:mm:t:e p - partition number r - rim counts m - minor frame t - real time interrupt e - mod eight countWhen asking for the matrix which describes the pointing for some structure or instrument used to perform an observation, you will usually request this information by supplying the spacecraft clock string that was used to tag the observation. This string must usually be related to UTC or TDB. Consequently it is necessary to load a file of ``spacecraft clock coefficients'' that enables SPICE to transform the spacecraft clock string into one of the other time systems. This file of spacecraft clock coefficients is loaded with the function furnsh_c. A more detailed discussion of Spacecraft Clock is contained in the Required Reading file sclk.req that is included with the CSPICE Toolkit. Julian Date
Julian Ephemeris Date is computed directly from TDB via the formula
JED = J2000 + TDB/SPDwhere J2000 is the Julian Ephemeris Date of the reference epoch for TDB, and SPD is the number or seconds per day. Julian Date UTC has an integer value (value, not integer type) whenever the corresponding UTC time is noon. We recommend against using the JDUTC system as it provides no mechanism for talking about events that might occur during a leapsecond. All of the other time systems discussed can be used to refer to events occurring during a leap second. The abbreviation JD
Consequently, for high accuracy work, you must be sure of the context when using strings labeled in this way. Unless context is clear, it's usually safer to label Julian Date strings with one of the unambiguous labels: JDUTC, JDTDB, or JDTDT. SPICE does not accommodate use of Modified Julian Date (MJD), because this term has multiple definitions. Time Subsystem FunctionsFunction to load needed kernels
The Leapseconds Kernel is a text kernel loaded using the furnsh_c function:
furnsh_c ( lsk );Load the Leapseconds Kernel only once per program run. The precise contents of the Leapseconds Kernel are discussed in the section ``Leapseconds.'' Text kernels and the furnsh_c function are discussed in more detail in KERNEL Required Reading, kernel.req. Function to convert a time string to TDB (ET)
str2et_c ( string, &et );This function requires the LSK data. The default interpretation of `string' is to regard the time of day to be a time on a 24-hour clock in the UTC time system. The date is a date on the Gregorian Calendar (this is the calendar used in nearly all Western societies). The function computes the ephemeris epoch corresponding to the input string. The ephemeris epoch is represented as seconds past the J2000 epoch. The variety of ways people have developed for representing times is enormous. It is unlikely that any single function can accommodate all of the custom time formats that have arisen in various computing contexts. However, we believe that str2et_c correctly interprets most time formats used throughout the planetary science community. For example str2et_c supports ISO time formats, UNIX `date` output formats, VMS time formats, MS-DOS formats, epochs in both the A.D. and B.C. eras, time zones, etc. Function to convert UTC to TDB (ET)
utc2et_c ( utcstr, et );This function requires the LSK data. This function converts strings in the UTC system to TDB seconds past the J2000 epoch. Unlike str2et_c it does not support other time systems or time zones. In addition, the function does not recognize times on a 12-hour clock. Strings such as
1983 June 13, 9:00:00 A.M.are treated as erroneous. Function to convert a spacecraft clock time string to TDB (ET)
scs2e_c ( sc, sclkch, et )This function requires the appropriate SCLK and LSK data. Function to convert a TDB (ET) to a time string based on a format template
timout_c ( et, pictur, lenout, output );This function requires the LSK data. Consider the following example time string:
04:29:29.292 Jan 13, 1996The value for `pictur' to create time strings similar in appearance to the example string is:
SpiceChar * pictur = "HR:MN:SC.### Mon DD, YYYY ::RND";Note, `pictur' could describe a time string format the SPICE time subsystem parsing functions cannot recognize. Most of the components in `pictur' are fairly obvious. The exception is the substring
::RNDThis substring tells the formatting logic to round the seconds portion of the output string instead of simply truncating. (Note that the case of the letters is significant in `pictur'.) timout_c can produce strings representing epochs in the time systems (UTC, TDB, TT) or any time zone, and on the Julian Calendar, Gregorian Calendar or Mixed Calendar. You may round or truncate numeric components. Function to convert a TDB (ET) to UTC
et2utc_c ( et, format, prec, lenout, utcstr );This function requires the LSK data. This function is not as flexible as timout_c. All outputs are UTC outputs, and only a limited set of formats are supported.
Format String Name Example String ------------- ----------- -------------------------- C Calendar 1979 JUL 04 14:19:57.184 D Day of Year 1979-114 // 14:19:57.184 J Julian Date JD 2433282.529 ISOC ISO Calendar 1987-04-12T16:31:12.814 ISOD ISO Day of Year 1987-102T16:31:12.814You may specify the number of decimal places in the fractional part of the seconds token or the Julian Date (three are used in the examples above). Note that Julian Dates are prefaced with the character string `JD' (and are UTC Julian Dates). et2utc_c has one advantage over timout_c: it is can output years with more than four digits which timout_c cannot do. Function to convert a TDB (ET) to Spacecraft Clock time string
sce2s_c ( sc, et, lenout, sclkch );This function requires the appropriate SCLK and the LSK data. Function to convert a TDB (ET) to Calendar format TDB
etcal_c ( et, lenout, string );This function requires no kernel data. Function to convert a TDB (ET) to Local True Solar Time
Formally, the local solar time at a site on a body is the difference between the planetocentric longitude of the site and the planetocentric longitude of the Sun as seen from the center of the body. The angular difference in these two longitudes is measured in hours, minutes, and seconds in the same sense that hours, minutes and seconds are used to measure right ascension--- 24 hours in 360 degrees; 60 minutes in an hour; 60 seconds in a minute. When the sun is on the zenith meridian (directly overhead), the hour is defined to be 12. Finally, the hours increase from sunrise to sunset. Because of these conventions, an hour of local solar time will not be of the same duration as a UTC hour. In the case of a site on Mars, a solar hour will be approximately 62 UTC minutes. Local solar time for a specific site can be computed using the function:
et2lst_c ( et, body, lon, type, timlen, ampmlen, hr, mn, sc, time, ampm );This function requires appropriate SPK and PCK data. This function converts ephemeris time (TDB) to the local solar time for a point at a user specified longitude on the surface of a body. This computation is performed using the bodyfixed location of the sun. Consequently, you must first load SPK and PCK files that contain sufficient position and orientation data for the computation of the bodyfixed location of the sun. Load SPK and PCKs (text and binary) using furnsh_c. As with the Leapseconds Kernel, SPKs and PCKs need to be loaded just once per program run---usually at program initialization. Please refer to kernel.req for further information concerning kernels [5]. Function to convert a TDB (ET) to planetocentric longitude of the sun
ls = lspcn_c ( body, et, abcorr );This function requires the appropriate SPK and PCK data. Function to convert between uniform time scales
A numeric time system is additive if given the representations E1 and E2 of any pair of successive epochs, the time elapsed between the epochs is given by the difference E2 - E1. Convert between uniform time scales using the appropriate function:
double = unitim_c ( epoch, insys, outsys );This function requires no kernel data. The uniform time scales that are supported by this function are:
String ID Time system --------- -------------------------- TAI International Atomic Time TDB Barycentric Dynamical Time TT Terrestrial Time TDT Terrestrial Dynamical Time (TT) ET Ephemeris time, alias for TDB JDTDB Julian Date relative to TDB JDTDT Julian Date relative to TDT (TT) JED Julian Ephemeris date (synonym to JDTDB) GPS Global Positioning System Time Function to compute the difference between TDB (ET) and UTC
deltet_c( epoch, eptype, delta )This function requires the LSK data. Function to create a time string format picture
tpictr_c ( exampl, lenout, lenerr, pictur, ok, errmsg );This function requires no kernel data. The arguments `ok' and `errmsg' exist because some `exampl' strings are not recognized as time strings. tpictr_c recognizes the same set of time strings as the primary time string parsing function tparse_c. Please refer to the time string examples shown in the ``Input String Conversion'' section of this document. If you want your output string to be in a system other than UTC you must supply the label for that system in your example string. tpictr_c can construct format pictures for strings that are not accepted by the string conversion functions. For example, if you would like to suppress the year in a calendar output format, you could use the following example string:
SpiceChar * exampl = "Jan 12, 02:28:29.### A.M. (PDT)";Even though this string is ambiguous as an epoch (there's no year specified), it is sufficient for determining a picture that describes its format. If you decide to use tpictr_c with inputs like this, be sure to check the output flag `ok'; even though you know what is intended, tpictr_c may have problems with some ambiguous time strings. Functions returning time constants
b1900_c()The Julian ephemeris date (TDB) of the epoch of the Besselian date 1950:
b1950_c()The Julian Date of 1899 DEC 31 12:00:00 (TDB):
j1900_c()The Julian ephemeris date of the epoch 1 Jan 1950 00:00:00 (TDB):
j1950_c()The Julian ephemeris date of the epoch 1 Jan 2000 12:00:00 (TDB):
j2000_c()The Julian ephemeris date of the epoch 1 Jan 2100 12:00:00:
j2100_c()The number of seconds in a Julian year (365.25 Julian days):
jyear_c()The number of TDB seconds in a Julian day TDB (86400 seconds):
spd_c()The number of seconds in a tropical year (approximately the number of seconds from one spring equinox to the next):
tyear_c() Foundation Routines and Utilities
These and other utility functions lack wrapper interfaces in CSPICE but can be used in their f2c'd form (see cspice.req included in the CSPICE toolkit for details). Parse a time string to a time vector
tpartv_ ( string, tvec, ntvec, typ, modify,
mods, yabbrv, succes, pictur, error,
string_len, typ_len, modify_len,
pictur_len, error_len);
Convert between different parsed representations of time
ttrans_ ( from, to, tvec, from_len, to_len); Time utility functions
Convert two-digit abbreviated years to full years. You set the lower bound of the 100 year mapping interval via the function tsetyr_c discussed earlier in this document.
texpyr_ ( year );Take a numeric vector representing the components of a calendar time to check that all components are within the normal range used in conversation. Note that TCHECK performs no action until you call TPARCH with an argument of "YES".
tcheck_ ( tvec, typ, mods, modify, ok, error,
typ_len, modify_len, error_len);
Determine if component checking has been enabled in TCHECK via a call to
TPARCH.
tchckd_ ( yesno, yesno_len );Convert the year, month, and day of an epoch on the Julian Calendar to the corresponding year, month, day and day-of-year on the Gregorian calendar.
jul2gr_ ( year, month, day, doy );Convert the year, month, and day of an epoch on the Gregorian Calendar to the corresponding year, month, day and day-of-year on the Julian calendar.
gr2jul_ ( year, month, day, doy ); Input String Conversion
SpiceChar * string = "Oct 1, 1996 09:12:32";However, arithmetic is most easily performed with numeric representations of time. In SPICE we represent epochs as some number of double precision seconds past the J2000 epoch. The analyzing the input string and assigning meaning to its various components, a.k.a. parsing, is performed by lower level time system functions. Below are a number of examples of strings and the interpretation assigned to the various components. 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 00Calendar 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.298Day 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.182Julian Date Strings.
jd 28272.291 Julian Date 28272.291 2451515.2981 (JD) Julian Date 2451515.2981 2451515.2981 JD Julian Date 2451515.2981Abbreviations Used in Tables
na --- Not Applicable Mon --- Month DOY --- Day of Year DOM --- Day of Month Wkday --- Weekday Hr --- Hour Min --- Minutes Sec --- Seconds
Parsing Time Strings
The following substrings are immediately recognizable.
The case of the letters in these substrings does not matter. For example all of the various ways of writing ``TDB'' ( ``TDB'', ``tDB'', ... ``tdb'') are recognized as ``TDB''. It is not necessary to leave space between the various substrings. For example ``JDTDT'' and ``JDUTC'' are recognized as ``JD'' followed by ``TDT'' and ``JD'' followed by ``UTC'' respectively. To determine the meaning of the numeric tokens in the input string, a set of transformation rules are applied to the full set of tokens in the string. These transformations are repeated until the meaning of every token has been determined or until further transformations yield no new clues into the meaning of the numeric tokens. Here is an overview of the rules that are applied to the various tokens in the string.
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.
Once the various tokens have been determined and a meaning attached to
them, the Time subsystem uses the tokens to construct the double
precision number giving the number of seconds past J2000 that
corresponds to input string. However, not all tokens or token
combinations are allowed by the functions.
Labels (A.M. and P.M.)
1988 June 13, 3:29:48 P.M.is still regarded as a UTC epoch. However, with the addition of the ``P.M.'' label it is now interpreted as the same epoch as the unlabeled epoch 1988 June 13, 15:29:48. Similarly
1988 June 13, 12:29:48 A.M.is interpreted as
1988 June 13, 00:29:48on the 24-hour clock. 12:00 A.M. corresponds to Midnight (00:00 on the 24-hour clock). 12:00 P.M. corresponds to Noon (12:00 on the 24-hour clock). Labels (Time Zones)
1988 June 13, 3:29:48 P.M. PSTis interpreted as an epoch in the Pacific Standard Time system. This is equivalent to
1988 June 13, 23:29:48 UTCAll of the standard abbreviations for U.S. time zones are recognized by the time parser.
EST --- Eastern Standard Time ( UTC-5:00 ) CST --- Central Standard Time ( UTC-6:00 ) MST --- Mountain Standard Time ( UTC-7:00 ) PST --- Pacific Standard Time ( UTC-8:00 ) EDT --- Eastern Daylight Time ( UTC-4:00 ) CDT --- Central Daylight Time ( UTC-5:00 ) MDT --- Mountain Daylight Time ( UTC-6:00 ) PDT --- Pacific Daylight Time ( UTC-7:00 )In addition, any other time zone may be specified by representing its offset from UTC. To specify an offset from UTC you need to create an offset label. The label starts with the letters `UTC' followed by a `+' for time zones east of Greenwich and `-' for time zones west of Greenwich. This is followed by the number of hours to add or subtract from UTC. This is optionally followed by a colon `:' and the number of minutes to add or subtract to get the local time zone. Thus to specify the time zone of Calcutta (which is 5 and 1/2 hours ahead of UTC) you would specify the time zone to be UTC+5:30. To specify the time zone of Newfoundland (which is 3 and 1/2 hours behind UTC) use the offset notation UTC-3:30. Labels ( TDB, TT, and UTC )
In these systems there are no leapseconds; every day has exactly 86400 seconds. TDB times are written as
1988 June 13, 12:29:48 TDBTT times are written as:
1988 June 13, 12:29:48 TTTo add clarity or to override any changes you happen to make to the default behavior of ET2STR (see below) you may add the label ``UTC'' to any time string.
1998 Jun 13, 12:29:48 UTCNote that the system label may be placed anywhere in the time string. All of the following will be understood by the time parsing software:
TDB 1988 June 13, 12:29:48 1988 June 13, 12:29:48 TDB 1988 June 13, TDB 12:29:48 Changing Default Behavior
Abbreviated Years
E.g., set the default range to be from 1972 to 2071:
tsetyr_c ( 1972 );Note that this change affects the behavior of all string conversion functions. Range of Time String Components
1985 FEB 43 27:65:25 (equivalent to 1985 MAR 16 04:05:25)will be accepted as input. You might wish to restrict the range of input strings so that this behavior is not allowed. The SPICELIB routine TPARCH exists for this purpose. This routine lacks a wrapper interface in CSPICE but can be used in its f2c'd form (see cspice.req included in the CSPICE toolkit for details). Example:
TPARCH ( 'YES' )Call the function early in your program, prior to any calls to functions tparse_c and utc2et_c. Then the components of calendar strings will be restricted so that all calendar components will be in the ``expected'' range. Please refer to the header of tparse_c or SPICELIB routine TPARCH for information describing the exact ranges for the components. str2et_c does not accept time strings whose components are outside the normal range used in conversation. You cannot alter this behavior without re-coding str2et_c. Default Time Systems, Time Zone, and Calendar
timdef_c ( "SET", item, lenout, value );
``item'' ``value''
--------- --------------
CALENDAR GREGORIAN
JULIAN
MIXED
SYSTEM TDB
TT
TDT
UTC
ZONE EST
EDT
CST
CDT
MST
MDT
PST
PDT
UTC+HR
UTC-HR ( 0 <= HR < 13 )
UTC+HR:MN ( 0 <= MN < 60 )
UTC-HR:MN
The case of item is not significant.
Keep in mind that if you specify a time zone or time system label in the input time string the default time zone or system is not used. The label in the string is used to determine the time zone or time system. Changing the Time System
timdef_c ( "SET", "SYSTEM", lenout, "UTC" ); timdef_c ( "SET", "SYSTEM", lenout, "TDB" ); timdef_c ( "SET", "SYSTEM", lenout, "TDT" ); timdef_c ( "SET", "SYSTEM", lenout, "TT" );Note that setting a time system turns off any default time zone you may have `SET' using timdef_c. Time Zones
timdef_c ( "SET", "ZONE", lenout, "PST" );Note that setting a time zone turns off any default time system you may have `SET' via timdef_c. Calendars
Both the Gregorian and Julian calendars can be extended forward and backward in time indefinitely. The default behavior uses the Gregorian calendar for all epochs. However, using the timdef_c function `SET' capability, you can set the default calendar to one of three: GREGORIAN, JULIAN, or MIXED:
timdef_c ( "SET", "CALENDAR", lenout, "GREGORIAN" ); timdef_c ( "SET", "CALENDAR", lenout, "JULIAN" ); timdef_c ( "SET", "CALENDAR", lenout, "MIXED" );The ``MIXED'' calendar assumes that calendar strings for epochs prior to October 5, 1582 belong to the Julian Calendar; strings for later epochs are assumed to belong to the Gregorian Calendar. The specification of a calendar does not affect a previous setting of a time system or time zone. Usage example
Note that the data necessary to convert between UTC and TDB are loaded into the kernel pool just once, typically during program initialization.
/*
Convert between UTC and TDB interactively, and convert TDB
back to UTC in calendar format, DOY format, and as a
Julian date.
Requires a Leapseconds Kernel.
*/
#include <stdio.h>
#include "SpiceUsr.h"
#define UTCLEN 34
void main ()
{
SpiceDouble et;
SpiceChar utcstr[UTCLEN];
SpiceChar dutcstr[UTCLEN];
SpiceChar jutcstr[UTCLEN];
SpiceChar * leap;
SpiceChar * response;
SpiceInt response_len = 50;
/* Get the name of the kernel file. */
leap = prompt_c ( "Name of leapsecond kernel? " );
/* Load the kernel pool.*/
furnsh_c ( leap );
response = "Y";
/* Compute result for each new time epoch. */
do
{
response = prompt_c ( "Enter time string: " );
str2et_c ( response, &et );
printf( "Time converts to TDB (sec past J2000) %f\n\n",
et );
/* Convert from et to string */
et2utc_c ( et , "C", 3, UTCLEN, utcstr );
et2utc_c ( et , "D", 3, UTCLEN, dutcstr );
et2utc_c ( et , "J", 3, UTCLEN, jutcstr );
printf( "ET converts to %s, %s, %s\n\n", utcstr,
dutcstr,
jutcstr );
response = prompt_c ( "Continue? (Y/N)" );
}
while ( *response == 'Y' || *response == 'y' );
}
Appendix A. Summary of Time Subsystem Functions
b1900_c() Constant b1950_c() Constant j1900_c() Constant j1950_c() Constant j2000_c() Constant j2100_c() Constant jyear_c() Constant spd_c() Constant tyear_c() Constant deltet_c Delta TDB, TDB - UTC et2lst_c TDB to Local Solar Time et2utc_c TDB to UTC etcal_c Convert TDB to Calendar format lspcn_c Longitude of the sun, planetocentric str2et_c String to TDB timdef_c Set/get time software defaults timout_c TDB to string time Output tparse_c Parse a UTC time string tpictr_c Create a Time Format Picture tsetyr_c Set year expansion boundaries unitim_c Uniform time scale transformation utc2et_c UTC to TDB Appendix B. Non-native text files
All other SPICE Toolkit language implementations can read non-native text files. Appendix C. Parsing Time Strings
This appendix is not for everyone. Unless you need to understand in great detail how parsing of strings is performed, you can safely skip this appendix. The discussion below is quite technical and mirrors very closely the code in TPARTV that handles the parsing of time strings. An Outline of the Parser
Having identified the components in the string as integers, months, weekdays, time systems, etc. an internal representation of the string is constructed. This representation is simply a list of the identified substrings in the order they are encountered. Each item in the list is called a token. Working with the list of tokens, various rules are applied to remove some tokens and combine others into new tokens. The process of combination and removal of tokens continues until all tokens belong to a special set of ``meaningful'' tokens or until no further combinations and removals can be performed. If processing stops before all tokens are meaningful, a diagnostic message is created and the string is regarded as un-parsable. If all of the tokens are meaningful, a compatibility check is performed on the tokens to make sure that they unambiguously specify an epoch. Once it is clear that an unambiguous epoch has been specified, the substrings corresponding to the meaningful tokens are converted into numeric representations or are noted so that the time conversion software can properly interpret the numeric components. Almost all of the work of manipulating tokens is carried out by SPICE private routines. These routines are not considered part of the SPICE public interface. Feel free to read and copy these routines. However, we strongly recommend that you not call these routines in your own code since we do not guarantee backward compatibility of these routines in future releases of the Toolkit. Tokenizing the Input String
Starting with the next unexamined character (on the first pass this is the first character in the string), scan from left to right looking for one of the following classes of substrings:
The steps above are then repeated until the entire substring has been tokenized or a failure to recognize some substring occurs. If a failure occurs the location in the string is noted and a diagnostic message is created indicating the failure in the attempt to parse the string. When the tokenization is finished, there will be a list of tokens from which a string can be constructed that lists the class of each token. Each class of token is represented by a single character. By placing these characters in a string a simple list of token classes is maintained. The characters used for the remainder of this discussion are listed below.
Q stands for the quote character [ stands for the left parenthesis character ] stands for the right parenthesis character , stands for the comma character - stands for the dash character . stands for the decimal point character / stands for the slash character : stands for the colon character N stands for one of the symbols A.M. or P.M. O stands for the symbol UTC+ Z stands for a time zone such as PDT, PSD, CDT, b stands for a block of white space (spaces or tabs) d stands for the day of year marker (// or ::) e stands for the era (B.C. or A.D.) j stands for Julian date m stands for a month o stands for the symbol UTC- s stands for a time system (UTC, TT, TDT, TDB) t stands the ISO date-T-time separator w stands for the day of the week i stands for a sequence of digits x stands for a character to ignoreThus the list of token classifications corresponding to
1995 Jan 12 12:28:28
will be
ibmbibi:i:i
Combining and Removing Tokens
There are 3 basic operations that can be performed on the tokenized representation:
Initial Token Processing
Julian Dates
Calendar Dates
Any integer class tokens (`i') whose corresponding substrings represent integers greater than or equal to 1000 are reclassified as years (`Y'). ISO Formats
Token list Transformation
----------- --------------
Y-i-iT YmD
Y-i-iTi YmDH
Y-i-iTi:i YmDHM
Y-i-iTi:i:i YmDHMS
Y-i-iTi:i:n YmDHMS
Y-i-iTi:n YmDHM
Y-i-iTn YmDH
Y-iT Yy
Y-iTi YyH
Y-iTi:i YyHM
Y-iTi:i:i YyHMS
Y-iTi:i:n YyHMS
Y-iTi:n YyHM
Y-iTn YyH
i-i-iT YmD
i-i-iTi YmDH
i-i-iTi:i YmDHM
i-i-iTi:i:i YmDHMS
i-i-iTi:i:n YmDHMS
i-i-iTi:n YmDHM
i-i-iTn YmDH
i-iT Yy
i-iTi YyH
i-iTi:i YyHM
i-iTi:i:i YyHMS
i-iTi:i:n YyHMS
i-iTi:n YyHM
i-iTn YyH
Y --- Year
m --- Month
D --- Day of Month
y --- Day of Year
H --- Hour
M --- Minute
S --- Second
If the token list contains the ISO separator (`T') but the list does not
match one of the patters shown above, the input string is regarded as
erroneous.
Other Calendar Formats
[e] ---> *e* (parenthesized era to era) [w] ---> *w* (parenthesized weekday to weekday) [N] ---> *N* (parenthesized AM/PM to AM/PM) [Z] ---> *Z* (parenthesized time zone to time zone) [s] ---> *s* (parenthesized time system to time system) ie, ---> Ye (integer-era to Year-era)
Built in Representations
Token list Transformation ----------- -------------- Y-i-it YmD Y-i-iti YmDH Y-i-iti:i YmDHM Y-i-iti:i:i YmDHMS Y-i-iti:i:n YmDHMS Y-i-iti:n YmDHM Y-i-itn YmDH Y-i/ Yy Y-i/i:i YyHM Y-i/i:i:i YyHMS Y-i/i:i:n YyHMS Y-i/i:n YyHM Y-id Yy Y-idi:i YyHM Y-idi:i:i YyHMS Y-idi:i:n YyHMS Y-idi:n YyHM Y-it Yy Y-iti YyH Y-iti:i YyHM Y-iti:i:i YyHMS Y-iti:i:n YyHMS Y-iti:n YyHM Y-itn YyH Yid Yy Yidi:i YyHM Yidi:i:i YyHMS Yidi:i:n YyHMS Yidi:n YyHM Yii YmD Yiii YmDH Yiii:i YmDHM Yiii:i:i YmDHMS Yiii:i:n YmDHMS Yiii:n YmDHM Yiiii YmDHM Yiiiii YmDHMS Yiiiin YmDHMS Yiiin YmDHM Yiin YmDH Yim YDm Yimi YDmH Yimi:i YDmHM Yimi:i:i YDmHMS Yimi:i:n YDmHMS Yimi:n YDmHM Yimn YDmH Yin YmD Ymi YmD Ymii YmDH Ymii:i YmDHM Ymii:i:i YmDHMS Ymii:i:n YmDHMS Ymii:n YmDHM Ymin YmDH Ymn YmD Ynm YDm i-Y/ yY i-Y/i:i yYHM i-Y/i:i:i yYHMS i-Y/i:i:n yYHMS i-Y/i:n yYHM i-Yd yY i-Ydi:i yYHM i-Ydi:i:i yYHMS i-Ydi:i:n yYHMS i-Ydi:n yYHM i-i-Y mDY i-i-Yi:i mDYHM i-i-Yi:i:i mDYHMS i-i-Yi:i:n mDYHMS i-i-Yi:n mDYHM i-i-it YmD i-i-iti YmDH i-i-iti:i YmDHM i-i-iti:i:i YmDHMS i-i-iti:i:n YmDHMS i-i-iti:n YmDHM i-i-itn YmDH i-i/i:i YyHM i-i/i:i:i YyHMS i-i/i:i:n YyHMS i-i/i:n YyHM i-idi:i YyHM i-idi:i:i YyHMS i-idi:i:n YyHMS i-idi:n YyHM i-it Yy i-iti YyH i-iti:i YyHM i-iti:i:i YyHMS i-iti:i:n YyHMS i-iti:n YyHM i-itn YyH i/i/Y mDY i/i/Y/i:n mDYHM i/i/Yi:i mDYHM i/i/Yi:i:i mDYHMS i/i/Yi:i:n mDYHMS i/i/i mDY i/i/ii:i mDYHM i/i/ii:i:i mDYHMS i/i/ii:i:n mDYHMS i/i/ii:n mDYHM i/i/ii:n mDYHM i:i:ii-i-Y HMSmDY i:i:ii/i/Y HMSmDY i:i:ii/i/i HMSmDY i:i:iimY HMSDmY i:i:imiY HMSmDY i:i:ni-i-Y HMSmDY i:i:ni/i/Y HMSmDY i:i:ni/i/i HMSmDY i:i:nimY HMSDmY i:i:nmiY HMSmDY i:ii-i-Y HMmDY i:ii/i/Y HMmDY i:ii/i/i HMmDY i:iimY HMDmY i:imiY HMmDY i:ni-i-Y HMmDY i:ni/i/Y HMmDY i:ni/i/i HMmDY i:nimY HMDmY i:nmiY HMmDY iYd yY iYdi:i yYHM iYdi:i:i yYHMS iYdi:i:n yYHMS iYdi:n yYHM iiY mDY iiYi mDYH iiYi:i mDYHM iiYi:i:i mDYHMS iiYi:i:n mDYHMS iiYi:n mDYHM iiYn mDYH iid Yy iidi:i YyHM iidi:i:i YyHMS iidi:i:n YyHMS iidi:n YyHM iim YDm iimi YDmH iimi:i YDmHM iimi:i:i YDmHMS iimi:i:n YDmHMS iimi:n YDmHM iimii YDmHM iimiii YDmHMS iimiin YDmHMS iimin YDmHM iimn YDmH imY DmY imYi DmYH imYi:i DmYHM imYi:i:i DmYHMS imYi:i:n DmYHMS imYi:n DmYHM imYn DmYH imi YmD imi:i:iY DmHMSY imi:i:nY DmHMSY imi:iY DmHMY imi:nY DmHMY imii YmDH imii:i YmDHM imii:i:i YmDHMS imii:i:n YmDHMS imii:n YmDHM imiii YmDHM imiiii YmDHMS imiiin YmDHMS imiin YmDHM imin YmDH imn YmD inY mDY inm YDm miY mDY miYi mDYH miYi:i mDYHM miYi:i:i mDYHMS miYi:i:n mDYHMS miYi:n mDYHM miYn mDYH mii mDY mii:i:iY mDHMSY mii:i:nY mDHMSY mii:iY mDHMY mii:nY mDHMY miii mDYH miii:i mDYHM miii:i:i mDYHMS miii:i:n mDYHMS miii:n mDYHM miiii mDYHM miiiii mDYHMS miiiin mDYHMS miiin mDYHM miin mDYH mnY mDY mni mDY nmY DmYIf the token list agrees with one of the items in the above list, the double precision value corresponding to each token is computed and the parsing process halts with success. Last Resort Production Rules
Assuming that the error checks just discussed do not produce an error diagnosis, the string is processed according to the following rules:
i:i:i:n ---> D*H*M*S (days, hours, minutes, seconds) i:i:i:i ---> D*H*M*S (days, hours, minutes, seconds) i:i:n ---> H*M*S (hours, minutes, seconds) i:i:i ---> H*M*S (hours, minutes, seconds) i:n ---> H*M (hours, minutes) i:i ---> H*M (hours, minutes)
<miiH ---> mDY (month, day, year) <mi ---> mD (month, day) Siim> ---> SYDm (seconds, year, day, month) im> ---> Dm (day, month) miY> ---> mDY (month, day, year) Ymi ---> YmD (year, month, day) Smi ---> SmD (seconds, month, day) Mmi ---> MmD (minutes, month, day) imY ---> DmY (day, month, year) imH ---> DmH (day, month, hour) Yid ---> Yy* (year, day-of-year) iYd ---> yY* (day-of-year, year) Ydi ---> Y*y (year, day-of-year)
Conclusion
Appendix D: Document Revision History2021 SEP 10 by E. D. Wright and M. Costa Sitja
Updates corresponding to additional interfaces from J. Diaz del Rio. Description edited to use "TT" rather than "TDT", "TDB" rather than "ET". Edits to ISO time string format description. 2017 MAR 06 by E. D. Wright.
Edited ``Document Revision History'' chapter to show a consistent format. 2015 SEP 09 by N. J. Bachman.
Corrected typo in the start date for the applicable period of the Gregorian calendar when the MIXED calendar option is selected. The date was changed to October 5, 1582. Corrected formatting of the Utility Routines section: the ASCII versions of this document for Mice and Icy displayed function names truncated to 8 characters (the problem did not occur in the HTML versions). 2012 JUN 14 by E. D. Wright.
2009 APR 09 2009 by E. D. Wright, B. V. Semenov.
Added a note about the SPICE file identification word for LSK files. 2004 DEC 23 by NAIF.
2004 FEB 02 by NAIF.
1997 NOV 18 by E. D. Wright.
CSPICE naming conventions
1997 JUL 22 by NAIF.
In addition to the new routine et2lst_c, we document a slight extension of the set of time strings that are recognized by the SPICE time software. This extension is documented in Appendix B. 1996 OCT 15 by NAIF.
The following routines are new as of version N0046.
str2et_c tsetyr_c ttrans_ jul2gr_ timout_c timdef_c tpartv_ gr2jul_ tpictr_c tchckd_ tcheck_ texpyr_ 1994 JUN 30 by NAIF.
1992 APR 13 by NAIF.
|