1 /* 2 3 -Procedure tparse_c ( Parse a UTC time string ) 4 5 -Abstract 6 7 Parse a time string and return seconds past the J2000 epoch 8 on a formal calendar. 9 10 -Disclaimer 11 12 THIS SOFTWARE AND ANY RELATED MATERIALS WERE CREATED BY THE 13 CALIFORNIA INSTITUTE OF TECHNOLOGY (CALTECH) UNDER A U.S. 14 GOVERNMENT CONTRACT WITH THE NATIONAL AERONAUTICS AND SPACE 15 ADMINISTRATION (NASA). THE SOFTWARE IS TECHNOLOGY AND SOFTWARE 16 PUBLICLY AVAILABLE UNDER U.S. EXPORT LAWS AND IS PROVIDED "AS-IS" 17 TO THE RECIPIENT WITHOUT WARRANTY OF ANY KIND, INCLUDING ANY 18 WARRANTIES OF PERFORMANCE OR MERCHANTABILITY OR FITNESS FOR A 19 PARTICULAR USE OR PURPOSE (AS SET FORTH IN UNITED STATES UCC 20 SECTIONS 2312-2313) OR FOR ANY PURPOSE WHATSOEVER, FOR THE 21 SOFTWARE AND RELATED MATERIALS, HOWEVER USED. 22 23 IN NO EVENT SHALL CALTECH, ITS JET PROPULSION LABORATORY, OR NASA 24 BE LIABLE FOR ANY DAMAGES AND/OR COSTS, INCLUDING, BUT NOT 25 LIMITED TO, INCIDENTAL OR CONSEQUENTIAL DAMAGES OF ANY KIND, 26 INCLUDING ECONOMIC DAMAGE OR INJURY TO PROPERTY AND LOST PROFITS, 27 REGARDLESS OF WHETHER CALTECH, JPL, OR NASA BE ADVISED, HAVE 28 REASON TO KNOW, OR, IN FACT, SHALL KNOW OF THE POSSIBILITY. 29 30 RECIPIENT BEARS ALL RISK RELATING TO QUALITY AND PERFORMANCE OF 31 THE SOFTWARE AND ANY RELATED MATERIALS, AND AGREES TO INDEMNIFY 32 CALTECH AND NASA FOR ALL THIRD-PARTY CLAIMS RESULTING FROM THE 33 ACTIONS OF RECIPIENT IN THE USE OF THE SOFTWARE. 34 35 -Required_Reading 36 37 None. 38 39 -Keywords 40 41 PARSING, TIME 42 43 */ 44 45 #include "SpiceUsr.h" 46 #include "SpiceZfc.h" 47 #include "SpiceZst.h" 48 #include "SpiceZmc.h" 49 50 tparse_c(ConstSpiceChar * string,SpiceInt lenout,SpiceDouble * sp2000,SpiceChar * errmsg)51 void tparse_c ( ConstSpiceChar * string, 52 SpiceInt lenout, 53 SpiceDouble * sp2000, 54 SpiceChar * errmsg ) 55 /* 56 57 -Brief_I/O 58 59 VARIABLE I/O DESCRIPTION 60 -------- --- -------------------------------------------------- 61 string I Input time string, UTC. 62 lenout I Available space in output error message string. 63 sp2000 O Equivalent UTC seconds past J2000. 64 errmsg O Descriptive error message. 65 66 -Detailed_Input 67 68 string is an input time string, containing a Calendar or 69 Julian Date. It may be in several different formats 70 and can make use of abbreviations. Several example 71 strings and the times that they translate to are listed 72 below. 73 74 lenout is the maximum number of characters, including the 75 terminating null, that may be written to the output 76 error message string. 77 78 -Detailed_Output 79 80 sp2000 is the equivalent of UTC, expressed in UTC 81 seconds past J2000. If an error occurs, or if 82 the input time string is ambiguous, sp2000 is not 83 changed. 84 85 errmsg is a descriptive error message, which is empty when 86 no error occurs. 87 88 -Parameters 89 90 None. 91 92 -Exceptions 93 94 Error free. 95 96 This routine returns information about parse errors in the output 97 string `errmsg'. 98 99 -Files 100 101 None. 102 103 -Particulars 104 105 The input string is examined and the various components of a date 106 are identified: julian date, year, month, day of year, day of month, 107 hour, minutes, seconds. These items are assumed to be components on 108 a calendar that contains no leapseconds (i.e. every day is assumed 109 to have exactly 86400 seconds). 110 111 tparse_c recognizes a wide range of standard time formats. The 112 examples section contains a list of several common strings that are 113 recognized and their interpretation. tparse_c relies on the lower 114 lever routine TPARTV to interpret the input string. 115 116 Here is a brief summary of some of the basic rules used in the 117 interpretation of strings. 118 119 1) Unless the substring JD or jd is present the string is assumed to 120 be a calendar format (day-month-year or year and day of year). 121 If the substring JD or jd is present, the string is assumed to 122 represent a julian date. 123 124 2) If the julian date specifier is not present, any integer greater 125 than 999 is regarded as being a year specification. 126 127 3) A dash '-' can represent a minus sign only if it is precedes the 128 first digit in the string and the string contains the julian 129 date specifier (JD). (No negative years, months, days, etc are 130 allowed). 131 132 4) Numeric components of a time string must be separated 133 by a character that is not a digit or decimal point. 134 Only one decimal component is allowed. For example 135 1994219.12819 is sometimes interpreted as the 136 219th day of 1994 + 0.12819 days. tparse_c does not 137 support such strings. 138 139 No exponential components are allowed. For example you 140 can't input 1993 Jun 23 23:00:01.202E-4 you have 141 to explicitly list all zeros that follow the decimal 142 point: i.e. 1993 Jun 23 23:00:00.0001202 143 144 5) The single colon (:) when used to separate numeric 145 components of a string is interpreted as separating 146 Hours, Minutes, and Seconds of time. 147 148 6) If a double slash (//) or double colon (::) follows 149 a pair of integers, those integers are assumed to 150 represent the year and day of year. 151 152 7) A quote followed by an integer less than 100 is regarded 153 as an abbreviated year. For example: '93 would be regarded 154 as the 93rd year of the reference century. See TEXPYR 155 for further discussion of abbreviated years. 156 157 8) An integer followed by "B.C." or "A.D." is regarded as 158 a year in the era associated with that abbreviation. 159 160 9) All dates are regarded as belonging to the extended 161 Gregorian Calendar (the Gregorian calendar is the calendar 162 currently used by western society). See the routine JUL2GR 163 for converting from Julian Calendar to the 164 Gregorian Calendar. 165 western society). 166 167 10) When the size of the integer components does not clearly 168 specify a year the following patterns are assumed 169 170 Calendar Format 171 172 Year Month Day 173 Month Day Year 174 Year Day Month 175 176 Where Month is the name of a month, not its numeric 177 value. 178 179 When integer components are separated by slashes (/) 180 as in 3/4/5. Month, Day, Year is assumed (2005 March 4) 181 182 Day of Year Format. 183 184 If a day of year marker is present (// or ::) the 185 pattern 186 187 I-I// or I-I:: (where I stands for and integer) 188 is interpreted as Year Day-of-Year. However, I-I/ is 189 regarded as ambiguous. 190 191 To understand the complete list of strings that can be understood 192 by tparse_c you need to examine TPARTV and read the appendix to 193 the TIME required reading entitled "Parsing Time Strings" 194 195 tparse_c does not support the specification of time system 196 such as TDT or TDB; AM/PM specifications of time; or time 197 zones (such as PDT, UTC+7:20, etc.). 198 199 If some part of the time string is not recognized or if 200 the meaning of the components are not clear, an error string 201 is constructed that explains the problem with the string. 202 203 Since the routine is works by breaking the input string into 204 a sequence of tokens whose meanings are determined by position 205 and magnitude, you can supply strings such as 1993 FEB 35 and 206 have this correctly interpreted as March 7, 1993. However, 207 this default action can be modified so that only "proper" 208 calendar dates and times are recognized. To do this call 209 the routine TPARCH as shown below: 210 211 TPARCH ( "YES" ) 212 213 This will cause the routine to treat dates and times with 214 components outside the normal range as errors. 215 216 To return to the default behavior 217 218 TPARCH ( "NO" ) 219 220 -Examples 221 222 The following are examples of valid inputs to TPARSE: 223 224 225 226 ISO (T) Formats. 227 228 String Year Mon DOY DOM HR Min Sec 229 ---------------------------- ---- --- --- --- -- --- ------ 230 1996-12-18T12:28:28 1996 Dec na 18 12 28 28 231 1986-01-18T12 1986 Jan na 18 12 00 00 232 1986-01-18T12:19 1986 Jan na 18 12 19 00 233 1986-01-18T12:19:52.18 1986 Jan na 18 12 19 52.18 234 1995-08T18:28:12 1995 na 008 na 18 28 12 235 1995-18T 1995 na 018 na 00 00 00 236 237 238 Calendar Formats. 239 240 String Year Mon DOM HR Min Sec 241 ---------------------------- ---- --- --- -- --- ------ 242 Tue Aug 6 11:10:57 1996 1996 Aug 06 11 10 57 243 1 DEC 1997 12:28:29.192 1997 Dec 01 12 28 29.192 244 2/3/1996 17:18:12.002 1996 Feb 03 17 18 12.002 245 Mar 2 12:18:17.287 1993 1993 Mar 02 12 18 17.287 246 1992 11:18:28 3 Jul 1992 Jul 03 11 18 28 247 June 12, 1989 01:21 1989 Jun 12 01 21 00 248 1978/3/12 23:28:59.29 1978 Mar 12 23 28 59.29 249 17JUN1982 18:28:28 1982 Jun 17 18 28 28 250 13:28:28.128 1992 27 Jun 1992 Jun 27 13 28 28.128 251 1972 27 jun 12:29 1972 Jun 27 12 29 00 252 '93 Jan 23 12:29:47.289 1993* Jan 23 12 29 47.289 253 27 Jan 3, 19:12:28.182 2027* Jan 03 19 12 28.182 254 23 A.D. APR 4, 18:28:29.29 0023** Apr 04 18 28 29.29 255 18 B.C. Jun 3, 12:29:28.291 -017** Jun 03 12 29 28.291 256 29 Jun 30 12:29:29.298 2029+ Jun 30 12 29 29.298 257 29 Jun '30 12:29:29.298 2030* Jun 29 12 29 29.298 258 259 Day of Year Formats 260 261 String Year DOY HR Min Sec 262 ---------------------------- ---- --- -- --- ------ 263 1997-162::12:18:28.827 1997 162 12 18 28.827 264 162-1996/12:28:28.287 1996 162 12 28 28.287 265 1993-321/12:28:28.287 1993 231 12 28 28.287 266 1992 183// 12 18 19 1992 183 12 18 19 267 17:28:01.287 1992-272// 1992 272 17 28 01.287 268 17:28:01.282 272-1994// 1994 272 17 28 01.282 269 '92-271/ 12:28:30.291 1992* 271 12 28 30.291 270 92-182/ 18:28:28.281 1992* 182 18 28 28.281 271 182-92/ 12:29:29.192 0182+ 092 12 29 29.192 272 182-'92/ 12:28:29.182 1992 182 12 28 29.182 273 274 275 Julian Date Strings 276 277 jd 28272.291 Julian Date 28272.291 278 2451515.2981 (JD) Julian Date 2451515.2981 279 2451515.2981 JD Julian Date 2451515.2981 280 281 Abbreviations Used in Tables 282 283 na --- Not Applicable 284 Mon --- Month 285 DOY --- Day of Year 286 DOM --- Day of Month 287 Wkday --- Weekday 288 Hr --- Hour 289 Min --- Minutes 290 Sec --- Sec 291 292 * The default interpretation of a year that has been abbreviated 293 with a leading quote as in 'xy (such as '92) is to treat 294 the year as 19xy if xy > 68 and to treat it is 20xy otherwise. 295 Thus '70 is interpreted as 1970 and '67 is treated as 2067. 296 However, you may change the "split point" and centuries through 297 use of the SPICE routine tsetyr_c which is an entry point in 298 the SPICE module TEXPYR. See that routine for a discussion of 299 how you may reset the split point. 300 301 ** All epochs are regarded as belonging to the Gregorian 302 calendar. We formally extend the Gregorian calendar backward 303 and forward in time for all epochs. If you have epochs belonging 304 to the Julian Calendar, consult the routines TPARTV and JUL2GR 305 for a discussion concerning conversions to the Gregorian 306 calendar and ET. 307 308 + When a day of year format or calendar format string is 309 input and neither of integer components of the date 310 is greater than 1000, the first integer 311 is regarded as being the year. 312 313 Any integer greater than 1000 314 is regarded as a year specification. Thus 1001-1821//12:28:28 315 is interpreted as specifying two years and will be rejected 316 as ambiguous. 317 318 -Restrictions 319 320 None. 321 322 -Literature_References 323 324 None. 325 326 -Author_and_Institution 327 328 N.J. Bachman (JPL) 329 J.M. Lynch (JPL) 330 W.M. Owen (JPL) 331 M.J. Spencer (JPL) 332 I.M. Underwood (JPL) 333 W.L. Taber (JPL) 334 335 -Version 336 337 -CSPICE Version 1.0.1, 23-JUL-2015 (NJB) 338 339 Filled in Exceptions section of header. 340 341 -CSPICE Version 1.0.0, 5-JUN-1999 (NJB)(JML)(WMO)(MJS)(IMU)(WLT) 342 343 -Index_Entries 344 345 parse a utc time string 346 347 -& 348 */ 349 350 { /* Begin tparse_c */ 351 352 353 354 /* 355 Use discovery check-in. 356 */ 357 358 359 /* 360 Check the input time string to make sure the pointer is non-null and 361 the string length is non-zero. 362 */ 363 CHKFSTR ( CHK_DISCOVER, "tparse_c", string ); 364 365 366 /* 367 Check the output error message string to make sure the pointer is 368 non-null and the string length is at least 2. 369 */ 370 CHKOSTR ( CHK_DISCOVER, "tparse_c", errmsg, lenout ); 371 372 373 /* 374 Call the f2c'd routine. 375 */ 376 377 tparse_ ( ( char * ) string, 378 ( doublereal * ) sp2000, 379 ( char * ) errmsg, 380 ( ftnlen ) strlen(string), 381 ( ftnlen ) lenout-1 ); 382 383 /* 384 Convert the error message from Fortran to C style. 385 */ 386 F2C_ConvertStr ( lenout, errmsg ); 387 388 389 } /* End tparse_c */ 390 391