1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html><head><meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1">
<title>CODA Time</title>
<link href="../css/codadoc.css" rel="stylesheet" type="text/css">
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
</head>
<body>
<div class="wide">
<center>
<a class="qindex" href="index.html">Main Page</a>
<a class="qindex" href="modules.html">Modules</a>
</center>
<hr>
<!-- Generated by Doxygen 1.9.3 -->
</div><!-- top -->
<div class="header">
<div class="summary">
<a href="#func-members">Functions</a> </div>
<div class="headertitle"><div class="title">CODA Time</div></div>
</div><!--header-->
<div class="contents">
<table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a id="func-members" name="func-members"></a>
Functions</h2></td></tr>
<tr class="memitem:gac7e53fbe8303cf09da1100ec1f351502"><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__coda__time.html#gac7e53fbe8303cf09da1100ec1f351502">coda_time_double_to_parts</a> (double datetime, int *year, int *month, int *day, int *hour, int *minute, int *second, int *musec)</td></tr>
<tr class="separator:gac7e53fbe8303cf09da1100ec1f351502"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:ga33d83c499e47ab2f3336d15cefd41d01"><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__coda__time.html#ga33d83c499e47ab2f3336d15cefd41d01">coda_time_double_to_parts_utc</a> (double datetime, int *year, int *month, int *day, int *hour, int *minute, int *second, int *musec)</td></tr>
<tr class="separator:ga33d83c499e47ab2f3336d15cefd41d01"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:ga68a5cc3bafba6aa1c229b2a99832476d"><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__coda__time.html#ga68a5cc3bafba6aa1c229b2a99832476d">coda_time_parts_to_double</a> (int year, int month, int day, int hour, int minute, int second, int musec, double *datetime)</td></tr>
<tr class="separator:ga68a5cc3bafba6aa1c229b2a99832476d"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:gaf7c1a9e246a7ead184e273c2f989f753"><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__coda__time.html#gaf7c1a9e246a7ead184e273c2f989f753">coda_time_parts_to_double_utc</a> (int year, int month, int day, int hour, int minute, int second, int musec, double *datetime)</td></tr>
<tr class="separator:gaf7c1a9e246a7ead184e273c2f989f753"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:ga10db4874ac23454c2eab401641b92d8d"><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__coda__time.html#ga10db4874ac23454c2eab401641b92d8d">coda_time_parts_to_string</a> (int year, int month, int day, int hour, int minute, int second, int musec, const char *format, char *str)</td></tr>
<tr class="separator:ga10db4874ac23454c2eab401641b92d8d"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:gae49096a0cf25e2040330f58b066d2a32"><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__coda__time.html#gae49096a0cf25e2040330f58b066d2a32">coda_time_string_to_parts</a> (const char *format, const char *str, int *year, int *month, int *day, int *hour, int *minute, int *second, int *musec)</td></tr>
<tr class="separator:gae49096a0cf25e2040330f58b066d2a32"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:ga007c704f3d0fb4d3a85844f8f1a6b4a5"><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__coda__time.html#ga007c704f3d0fb4d3a85844f8f1a6b4a5">coda_time_double_to_string</a> (double datetime, const char *format, char *str)</td></tr>
<tr class="separator:ga007c704f3d0fb4d3a85844f8f1a6b4a5"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:gab1d84e5940f179417ea0ea0b6b108e4f"><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__coda__time.html#gab1d84e5940f179417ea0ea0b6b108e4f">coda_time_double_to_string_utc</a> (double datetime, const char *format, char *str)</td></tr>
<tr class="separator:gab1d84e5940f179417ea0ea0b6b108e4f"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:gafffc74f0ed6fa1013d45e390aa0aac9e"><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__coda__time.html#gafffc74f0ed6fa1013d45e390aa0aac9e">coda_time_string_to_double</a> (const char *format, const char *str, double *datetime)</td></tr>
<tr class="separator:gafffc74f0ed6fa1013d45e390aa0aac9e"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:ga790783facbde8372839ba2acc93d03fa"><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__coda__time.html#ga790783facbde8372839ba2acc93d03fa">coda_time_string_to_double_utc</a> (const char *format, const char *str, double *datetime)</td></tr>
<tr class="separator:ga790783facbde8372839ba2acc93d03fa"><td class="memSeparator" colspan="2"> </td></tr>
</table>
<a name="details" id="details"></a><h2 class="groupheader">Detailed Description</h2>
<p >The CODA Time module contains all functions and procedures related to time handling.</p>
<p >Most of the time functions assume that you stay within the same time system. In CODA a single time value can be represented in three different forms and CODA provides functions to convert between them:</p><ul>
<li>as a floating point value indicating the amount of seconds since 2000-01-01 00:00:00.00000 (this Jan 1st 2000 is an 'epoch' in the same time system as your time value is in)</li>
<li>as a decomposition of individual year, month, day, hour, minute, second, and microsecond values.</li>
<li>as a string (e.g. "2005-04-03 02:01:00.00000").</li>
</ul>
<p >The problem is that most time values are provided using the UTC time system. However, because of leap seconds, the only valid representations for a UTC time value are the last two. The problem with the floating point representation is that there is no unique definition of the Jan 1st 2000 epoch. Whenever a leap second is introduced this also shifts the epoch by one second. For instance, you cannot calculate the difference in seconds between UTC 2006-01-02 00:00:00 and UTC 2005-12-30 00:00:00 by just subtracting the two floating point representations of those times because of the leap second at 2005-12-31 23:59:60. If you would just subtract the values you would get 172800 seconds, but the actual answer should be 172801 seconds. If you want to calculate leap-second-accurate time differences the only solution is to convert your UTC time values to a time system that is based on actual clock ticks such as TAI or GPS.</p>
<p >In CODA this problem is solved by introducing special UTC leap-second-aware functions for converting from a floating point value to a string or datetime decomposition (and vice versa). The floating point value is in TAI whereas the string and datetime decomposition values represent the time value in UTC (be aware that the value for 'amount of seconds in a minute' can range from 0 to 60 inclusive for UTC!)</p>
<p >For each public time function there are thus two variants. One that treats all days as having 86400 seconds (and where both the input(s) and output(s) are of the same time system) and one that is able to deal with leap seconds. The functions that deal with leap seconds have 'utc' in the name and assume that the number of seconds since 2000-01-01 is a value in the TAI time system whereas the datetime decomposition (or string value) is using the UTC time system.</p>
<p >Note that TAI does not really have a fixed epoch relative to which to provide a number of seconds. TAI is only represented in how it deviates from UTC. In CODA, the choice was made to base the offset for the TAI floating point values on the convention that 2000-01-01T00:00:00 UTC has an offset of 0 (in UTC). Since at that time TAI was 32 seconds ahead of UTC, coda_utcdatetime_to_double() (which converts UTC to TAI) will thus return the value 32 for 2000-01-01T00:00:00.</p>
<p >If you don't want to use an actual TAI floating point value, but just an amount of seconds since 2000-01-01T00:00:00 UTC (i.e. such that a leap-second aware coversion of 2000-01-01T00:00:00 to a floating point value will actually result in 0), the best approach is to just subtract the result of coda_utcdatetime_to_double(2000,1,1,0,0,0,0,...) from your other result of coda_utcdatetime_to_double(). Note that this is more robust than assuming the epoch difference is always 32 and it is also an approach that can be applied more generally to retrieve a number of seconds relative to any other UTC date.</p>
<p >Below is an overview of time systems that are commonly used:</p><ul>
<li>TAI: International Atomic Time scale International Atomic Time (TAI) represents the mean of readings of several atomic clocks, and its fundamental unit is exactly one SI second at mean sea level and is, therefore, constant and continuous. d TAI = TAI - UTC is the increment to be applied to UTC to give TAI.</li>
<li>UTC: Coordinated Universal Time The time system generally used is the Coordinated Universal Time (UTC), previously called Greenwich Mean Time. The UTC is piece wise uniform and continuous, i.e. the time difference between UTC and TAI is equal to an integer number of seconds and is constant except for occasional jumps from inserted integer leap seconds. The leap seconds are inserted to cause UTC to follow the rotation of the Earth, which is expressed by means of the non uniform time reference Universal Time UT1. If UT1 is predicted to lag behind UTC by more than 0.9 seconds, a leap second is inserted. CODA has a built-in table of leap seconds up to 2012-07-01. You can use a more recent table by downloading the recent list of leap seconds from <a href="ftp://maia.usno.navy.mil/ser7/tai-utc.dat">ftp://maia.usno.navy.mil/ser7/tai-utc.dat</a> and set the environment variable CODA_LEAP_SECOND_TABLE with a full path to this file.</li>
<li>UT1: Universal Time Universal Time (UT1) is a time reference that conforms, within a close approximation, to the mean diurnal motion of the Earth. It is determined from observations of the diurnal motions of the stars, and then corrected for the shift in the longitude of the observing stations caused by the polar motion.</li>
<li>GPS: GPS Time GPS Time is an atomic clock time similar to but not the same as UTC time. It is synchronised to UTC but the main difference relies in the fact that GPS time does not introduce any leap second. Thus, the introduction of UTC leap second causes the GPS time and UTC time to differ by a known integer number of cumulative leap seconds; i.e. the leap seconds that have been accumulated since GPS epoch in midnight January 5, 1980. d GPS = TAI - GPS is the increment to be applied to GPS to give TAI, being a constant value of 19 seconds. </li>
</ul>
<h2 class="groupheader">Function Documentation</h2>
<a id="gac7e53fbe8303cf09da1100ec1f351502" name="gac7e53fbe8303cf09da1100ec1f351502"></a>
<h2 class="memtitle"><span class="permalink"><a href="#gac7e53fbe8303cf09da1100ec1f351502">◆ </a></span>coda_time_double_to_parts()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int coda_time_double_to_parts </td>
<td>(</td>
<td class="paramtype">double </td>
<td class="paramname"><em>datetime</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int * </td>
<td class="paramname"><em>year</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int * </td>
<td class="paramname"><em>month</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int * </td>
<td class="paramname"><em>day</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int * </td>
<td class="paramname"><em>hour</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int * </td>
<td class="paramname"><em>minute</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int * </td>
<td class="paramname"><em>second</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int * </td>
<td class="paramname"><em>musec</em> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p >Retrieve the decomposed date corresponding with the given amount of seconds since Jan 1st 2000. </p><dl class="section warning"><dt>Warning</dt><dd>This function does <em>not</em> perform any leap second correction. The returned value is just a straightforward conversion using 86400 seconds per day. </dd></dl>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">datetime</td><td>The amount of seconds since Jan 1st 2000. </td></tr>
<tr><td class="paramname">year</td><td>Pointer to the variable where the year will be stored. </td></tr>
<tr><td class="paramname">month</td><td>Pointer to the variable where the month of the year (1 - 12) will be stored. </td></tr>
<tr><td class="paramname">day</td><td>Pointer to the variable where the day of the month (1 - 31) will be stored. </td></tr>
<tr><td class="paramname">hour</td><td>Pointer to the variable where the hour of the day (0 - 23) will be stored. </td></tr>
<tr><td class="paramname">minute</td><td>Pointer to the variable where the minute of the hour (0 - 59) will be stored. </td></tr>
<tr><td class="paramname">second</td><td>Pointer to the variable where the second of the minute (0 - 59) will be stored. </td></tr>
<tr><td class="paramname">musec</td><td>Pointer to the variable where the microseconds of the second (0 - 999999) will be stored. </td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd><ul>
<li><code>0</code>, Success. </li>
<li><code>-1</code>, Error occurred (check <a class="el" href="group__coda__error.html#gafcb445c7fcab2d4d0af01f0e1c2dc866">coda_errno</a>). </li>
</ul>
</dd></dl>
</div>
</div>
<a id="ga33d83c499e47ab2f3336d15cefd41d01" name="ga33d83c499e47ab2f3336d15cefd41d01"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ga33d83c499e47ab2f3336d15cefd41d01">◆ </a></span>coda_time_double_to_parts_utc()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int coda_time_double_to_parts_utc </td>
<td>(</td>
<td class="paramtype">double </td>
<td class="paramname"><em>datetime</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int * </td>
<td class="paramname"><em>year</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int * </td>
<td class="paramname"><em>month</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int * </td>
<td class="paramname"><em>day</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int * </td>
<td class="paramname"><em>hour</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int * </td>
<td class="paramname"><em>minute</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int * </td>
<td class="paramname"><em>second</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int * </td>
<td class="paramname"><em>musec</em> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p >Retrieve the decomposed UTC date corresponding with the given amount of TAI seconds since Jan 1st 2000. This function assumes the input to by the number of seconds since 2000-01-01 in the TAI system. The returned date/time components will be the corresponding UTC datetime (using proper leap second handling for the TAI to UTC conversion). For example: -88361290 will be 1972-01-01 00:00:00 UTC 0 will be 1999-31-12 23:59:28 UTC 284083232 will be 2008-12-31 23:59:59 UTC 284083233 will be 2008-12-31 23:59:60 UTC 284083234 will be 2009-01-01 00:00:00 UTC </p><dl class="section warning"><dt>Warning</dt><dd>For dates before 1972-01-01 UTC a fixed leap second offset of 10 is used. </dd></dl>
<dl class="section note"><dt>Note</dt><dd>CODA has a built in table of leap seconds. To use a more recent leap second table, download the most recent file from <a href="ftp://maia.usno.navy.mil/ser7/tai-utc.dat">ftp://maia.usno.navy.mil/ser7/tai-utc.dat</a> and set the environment variable CODA_LEAP_SECOND_TABLE with a full path to this file. </dd></dl>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">datetime</td><td>The amount of seconds since Jan 1st 2000. </td></tr>
<tr><td class="paramname">year</td><td>Pointer to the variable where the year will be stored. </td></tr>
<tr><td class="paramname">month</td><td>Pointer to the variable where the month of the year (1 - 12) will be stored. </td></tr>
<tr><td class="paramname">day</td><td>Pointer to the variable where the day of the month (1 - 31) will be stored. </td></tr>
<tr><td class="paramname">hour</td><td>Pointer to the variable where the hour of the day (0 - 23) will be stored. </td></tr>
<tr><td class="paramname">minute</td><td>Pointer to the variable where the minute of the hour (0 - 59) will be stored. </td></tr>
<tr><td class="paramname">second</td><td>Pointer to the variable where the second of the minute (0 - 60) will be stored. </td></tr>
<tr><td class="paramname">musec</td><td>Pointer to the variable where the microseconds of the second (0 - 999999) will be stored. </td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd><ul>
<li><code>0</code>, Success. </li>
<li><code>-1</code>, Error occurred (check <a class="el" href="group__coda__error.html#gafcb445c7fcab2d4d0af01f0e1c2dc866">coda_errno</a>). </li>
</ul>
</dd></dl>
</div>
</div>
<a id="ga007c704f3d0fb4d3a85844f8f1a6b4a5" name="ga007c704f3d0fb4d3a85844f8f1a6b4a5"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ga007c704f3d0fb4d3a85844f8f1a6b4a5">◆ </a></span>coda_time_double_to_string()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int coda_time_double_to_string </td>
<td>(</td>
<td class="paramtype">double </td>
<td class="paramname"><em>datetime</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const char * </td>
<td class="paramname"><em>format</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">char * </td>
<td class="paramname"><em>str</em> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p >Convert a floating point time value to a string using a specified format. The string will be formatted using the format that is provided as second parameter. The time string will be stored in the <em>str</em> parameter. This parameter should be allocated by the user and should be long enough to hold the formatted time string and a 0 termination character.</p>
<p >The specification for the time format parameter is the same as the <a href="../codadef/codadef-expressions.html#timeformat">date/time format patterns in coda expressions</a>.</p>
<dl class="section warning"><dt>Warning</dt><dd>This function does not perform any leap second correction. </dd></dl>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">datetime</td><td>Floating point value representing the number of seconds since January 1st, 2000 00:00:00.000000. </td></tr>
<tr><td class="paramname">format</td><td>Date/time format to use for the string representation of the datetime value. </td></tr>
<tr><td class="paramname">str</td><td>String representation of the floating point time value. </td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd><ul>
<li><code>0</code>, Success. </li>
<li><code>-1</code>, Error occurred (check <a class="el" href="group__coda__error.html#gafcb445c7fcab2d4d0af01f0e1c2dc866">coda_errno</a>). </li>
</ul>
</dd></dl>
</div>
</div>
<a id="gab1d84e5940f179417ea0ea0b6b108e4f" name="gab1d84e5940f179417ea0ea0b6b108e4f"></a>
<h2 class="memtitle"><span class="permalink"><a href="#gab1d84e5940f179417ea0ea0b6b108e4f">◆ </a></span>coda_time_double_to_string_utc()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int coda_time_double_to_string_utc </td>
<td>(</td>
<td class="paramtype">double </td>
<td class="paramname"><em>datetime</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const char * </td>
<td class="paramname"><em>format</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">char * </td>
<td class="paramname"><em>str</em> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p >Convert a floating point TAI time value to a UTC string. The string will be formatted using the format that is provided as second parameter. The time string will be stored in the <em>str</em> parameter. This parameter should be allocated by the user and should be long enough to hold the formatted time string and a 0 termination character.</p>
<p >The specification for the time format parameter is the same as the <a href="../codadef/codadef-expressions.html#timeformat">date/time format patterns in coda expressions</a>.</p>
<p >This function performs proper leap second correction in the conversion from TAI to UTC (see also <em><a class="el" href="group__coda__time.html#ga33d83c499e47ab2f3336d15cefd41d01">coda_time_double_to_parts_utc()</a></em>).</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">datetime</td><td>Floating point value representing the number of seconds since January 1st, 2000 00:00:00.000000. </td></tr>
<tr><td class="paramname">format</td><td>Date/time format to use for the string representation of the datetime value. </td></tr>
<tr><td class="paramname">str</td><td>String representation of the floating point time value. </td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd><ul>
<li><code>0</code>, Success. </li>
<li><code>-1</code>, Error occurred (check <a class="el" href="group__coda__error.html#gafcb445c7fcab2d4d0af01f0e1c2dc866">coda_errno</a>). </li>
</ul>
</dd></dl>
</div>
</div>
<a id="ga68a5cc3bafba6aa1c229b2a99832476d" name="ga68a5cc3bafba6aa1c229b2a99832476d"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ga68a5cc3bafba6aa1c229b2a99832476d">◆ </a></span>coda_time_parts_to_double()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int coda_time_parts_to_double </td>
<td>(</td>
<td class="paramtype">int </td>
<td class="paramname"><em>year</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int </td>
<td class="paramname"><em>month</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int </td>
<td class="paramname"><em>day</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int </td>
<td class="paramname"><em>hour</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int </td>
<td class="paramname"><em>minute</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int </td>
<td class="paramname"><em>second</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int </td>
<td class="paramname"><em>musec</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">double * </td>
<td class="paramname"><em>datetime</em> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p >Retrieve the number of seconds since Jan 1st 2000 for a certain date and time. </p><dl class="section warning"><dt>Warning</dt><dd>This function does <em>not</em> perform any leap second correction. The returned value is just a straightforward conversion using 86400 seconds per day. </dd></dl>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">year</td><td>The year. </td></tr>
<tr><td class="paramname">month</td><td>The month of the year (1 - 12). </td></tr>
<tr><td class="paramname">day</td><td>The day of the month (1 - 31). </td></tr>
<tr><td class="paramname">hour</td><td>The hour of the day (0 - 23). </td></tr>
<tr><td class="paramname">minute</td><td>The minute of the hour (0 - 59). </td></tr>
<tr><td class="paramname">second</td><td>The second of the minute (0 - 59). </td></tr>
<tr><td class="paramname">musec</td><td>The microseconds of the second (0 - 999999). </td></tr>
<tr><td class="paramname">datetime</td><td>Pointer to the variable where the amount of seconds since Jan 1st 2000 will be stored. </td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd><ul>
<li><code>0</code>, Success. </li>
<li><code>-1</code>, Error occurred (check <a class="el" href="group__coda__error.html#gafcb445c7fcab2d4d0af01f0e1c2dc866">coda_errno</a>). </li>
</ul>
</dd></dl>
</div>
</div>
<a id="gaf7c1a9e246a7ead184e273c2f989f753" name="gaf7c1a9e246a7ead184e273c2f989f753"></a>
<h2 class="memtitle"><span class="permalink"><a href="#gaf7c1a9e246a7ead184e273c2f989f753">◆ </a></span>coda_time_parts_to_double_utc()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int coda_time_parts_to_double_utc </td>
<td>(</td>
<td class="paramtype">int </td>
<td class="paramname"><em>year</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int </td>
<td class="paramname"><em>month</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int </td>
<td class="paramname"><em>day</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int </td>
<td class="paramname"><em>hour</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int </td>
<td class="paramname"><em>minute</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int </td>
<td class="paramname"><em>second</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int </td>
<td class="paramname"><em>musec</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">double * </td>
<td class="paramname"><em>datetime</em> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p >Retrieve the number of TAI seconds since Jan 1st 2000 for a certain UTC date and time using leap second correction. This function assumes the input to be an UTC datetime. The returned value will be the seconds since 2000-01-01 in the TAI time system (using proper leap second handling for the UTC to TAI conversion). For example: 1972-01-01 00:00:00 UTC will be -883612790 2000-01-01 00:00:00 UTC will be 32 2008-12-31 23:59:59 UTC will be 284083232 2008-12-31 23:59:60 UTC will be 284083233 2009-01-01 00:00:00 UTC will be 284083234 </p><dl class="section warning"><dt>Warning</dt><dd>For dates before 1972-01-01 UTC a fixed leap second offset of 10 is used. </dd></dl>
<dl class="section note"><dt>Note</dt><dd>CODA has a built in table of leap seconds. To use a more recent leap second table, download the most recent file from <a href="ftp://maia.usno.navy.mil/ser7/tai-utc.dat">ftp://maia.usno.navy.mil/ser7/tai-utc.dat</a> and set the environment variable CODA_LEAP_SECOND_TABLE with a full path to this file. </dd></dl>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">year</td><td>The year. </td></tr>
<tr><td class="paramname">month</td><td>The month of the year (1 - 12). </td></tr>
<tr><td class="paramname">day</td><td>The day of the month (1 - 31). </td></tr>
<tr><td class="paramname">hour</td><td>The hour of the day (0 - 23). </td></tr>
<tr><td class="paramname">minute</td><td>The minute of the hour (0 - 59). </td></tr>
<tr><td class="paramname">second</td><td>The second of the minute (0 - 60). </td></tr>
<tr><td class="paramname">musec</td><td>The microseconds of the second (0 - 999999). </td></tr>
<tr><td class="paramname">datetime</td><td>Pointer to the variable where the amount of seconds since Jan 1st 2000 will be stored. </td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd><ul>
<li><code>0</code>, Success. </li>
<li><code>-1</code>, Error occurred (check <a class="el" href="group__coda__error.html#gafcb445c7fcab2d4d0af01f0e1c2dc866">coda_errno</a>). </li>
</ul>
</dd></dl>
</div>
</div>
<a id="ga10db4874ac23454c2eab401641b92d8d" name="ga10db4874ac23454c2eab401641b92d8d"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ga10db4874ac23454c2eab401641b92d8d">◆ </a></span>coda_time_parts_to_string()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int coda_time_parts_to_string </td>
<td>(</td>
<td class="paramtype">int </td>
<td class="paramname"><em>year</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int </td>
<td class="paramname"><em>month</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int </td>
<td class="paramname"><em>day</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int </td>
<td class="paramname"><em>hour</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int </td>
<td class="paramname"><em>minute</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int </td>
<td class="paramname"><em>second</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int </td>
<td class="paramname"><em>musec</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const char * </td>
<td class="paramname"><em>format</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">char * </td>
<td class="paramname"><em>str</em> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p >Create a string representation for a specific data and time. The string will be formatted using the format that is provided as first parameter. The time string will be stored in the <em>str</em> parameter. This parameter should be allocated by the user and should be long enough to hold the formatted time string and a 0 termination character.</p>
<p >The specification for the time format parameter is the same as the <a href="../codadef/codadef-expressions.html#timeformat">date/time format patterns in coda expressions</a>.</p>
<dl class="section warning"><dt>Warning</dt><dd>This function does not perform any leap second correction. </dd></dl>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">year</td><td>The year. </td></tr>
<tr><td class="paramname">month</td><td>The month of the year (1 - 12). </td></tr>
<tr><td class="paramname">day</td><td>The day of the month (1 - 31). </td></tr>
<tr><td class="paramname">hour</td><td>The hour of the day (0 - 23). </td></tr>
<tr><td class="paramname">minute</td><td>The minute of the hour (0 - 59). </td></tr>
<tr><td class="paramname">second</td><td>The second of the minute (0 - 60). </td></tr>
<tr><td class="paramname">musec</td><td>The microseconds of the second (0 - 999999). </td></tr>
<tr><td class="paramname">format</td><td>Date/time format to use for the string representation of the datetime value. </td></tr>
<tr><td class="paramname">str</td><td>String representation of the given date and time. </td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd><ul>
<li><code>0</code>, Success. </li>
<li><code>-1</code>, Error occurred (check <a class="el" href="group__coda__error.html#gafcb445c7fcab2d4d0af01f0e1c2dc866">coda_errno</a>). </li>
</ul>
</dd></dl>
</div>
</div>
<a id="gafffc74f0ed6fa1013d45e390aa0aac9e" name="gafffc74f0ed6fa1013d45e390aa0aac9e"></a>
<h2 class="memtitle"><span class="permalink"><a href="#gafffc74f0ed6fa1013d45e390aa0aac9e">◆ </a></span>coda_time_string_to_double()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int coda_time_string_to_double </td>
<td>(</td>
<td class="paramtype">const char * </td>
<td class="paramname"><em>format</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const char * </td>
<td class="paramname"><em>str</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">double * </td>
<td class="paramname"><em>datetime</em> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p >Convert a time string to a floating point time value. The string will be parsed using the format that is provided as first parameter. This can be a '|' separated list of formats that will be tried in sequence until one succeeds.</p>
<p >The specification for the time format parameter is the same as the <a href="../codadef/codadef-expressions.html#timeformat">date/time format patterns in coda expressions</a>.</p>
<dl class="section warning"><dt>Warning</dt><dd>This function does not perform any leap second correction. </dd></dl>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">format</td><td>String containing the datetime format(s) to use for parsing the datetime value. </td></tr>
<tr><td class="paramname">str</td><td>String containing the time in one of the supported formats. </td></tr>
<tr><td class="paramname">datetime</td><td>Floating point value representing the number of seconds since January 1st, 2000 00:00:00.000000. </td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd><ul>
<li><code>0</code>, Success. </li>
<li><code>-1</code>, Error occurred (check <a class="el" href="group__coda__error.html#gafcb445c7fcab2d4d0af01f0e1c2dc866">coda_errno</a>). </li>
</ul>
</dd></dl>
</div>
</div>
<a id="ga790783facbde8372839ba2acc93d03fa" name="ga790783facbde8372839ba2acc93d03fa"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ga790783facbde8372839ba2acc93d03fa">◆ </a></span>coda_time_string_to_double_utc()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int coda_time_string_to_double_utc </td>
<td>(</td>
<td class="paramtype">const char * </td>
<td class="paramname"><em>format</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const char * </td>
<td class="paramname"><em>str</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">double * </td>
<td class="paramname"><em>datetime</em> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p >Convert a UTC time string to a TAI floating point time value. The string will be parsed using the format that is provided as first parameter. This can be a '|' separated list of formats that will be tried in sequence until one succeeds.</p>
<p >The specification for the time format parameter is the same as the <a href="../codadef/codadef-expressions.html#timeformat">date/time format patterns in coda expressions</a>.</p>
<p >This function performs proper leap second correction in the conversion from UTC to TAI (see also <em><a class="el" href="group__coda__time.html#gaf7c1a9e246a7ead184e273c2f989f753">coda_time_parts_to_double_utc()</a></em>).</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">format</td><td>String containing the datetime format(s) to use for parsing the datetime value. </td></tr>
<tr><td class="paramname">str</td><td>String containing the time in one of the supported formats. </td></tr>
<tr><td class="paramname">datetime</td><td>Floating point value representing the number of seconds since January 1st, 2000 00:00:00.000000. </td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd><ul>
<li><code>0</code>, Success. </li>
<li><code>-1</code>, Error occurred (check <a class="el" href="group__coda__error.html#gafcb445c7fcab2d4d0af01f0e1c2dc866">coda_errno</a>). </li>
</ul>
</dd></dl>
</div>
</div>
<a id="gae49096a0cf25e2040330f58b066d2a32" name="gae49096a0cf25e2040330f58b066d2a32"></a>
<h2 class="memtitle"><span class="permalink"><a href="#gae49096a0cf25e2040330f58b066d2a32">◆ </a></span>coda_time_string_to_parts()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int coda_time_string_to_parts </td>
<td>(</td>
<td class="paramtype">const char * </td>
<td class="paramname"><em>format</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const char * </td>
<td class="paramname"><em>str</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int * </td>
<td class="paramname"><em>year</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int * </td>
<td class="paramname"><em>month</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int * </td>
<td class="paramname"><em>day</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int * </td>
<td class="paramname"><em>hour</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int * </td>
<td class="paramname"><em>minute</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int * </td>
<td class="paramname"><em>second</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int * </td>
<td class="paramname"><em>musec</em> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p >Convert a time string to a date and time using a specified format. The string will be parsed using the format that is provided as first parameter. This can be a '|' separated list of formats that will be tried in sequence until one succeeds.</p>
<p >The specification for the time format parameter is the same as the <a href="../codadef/codadef-expressions.html#timeformat">date/time format patterns in coda expressions</a>.</p>
<dl class="section warning"><dt>Warning</dt><dd>This function does not perform any leap second correction. </dd></dl>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">format</td><td>String containing the datetime format(s) to use for parsing the datetime value. </td></tr>
<tr><td class="paramname">str</td><td>String containing the time in one of the supported formats. </td></tr>
<tr><td class="paramname">year</td><td>Pointer to the variable where the year will be stored. </td></tr>
<tr><td class="paramname">month</td><td>Pointer to the variable where the month of the year (1 - 12) will be stored. </td></tr>
<tr><td class="paramname">day</td><td>Pointer to the variable where the day of the month (1 - 31) will be stored. </td></tr>
<tr><td class="paramname">hour</td><td>Pointer to the variable where the hour of the day (0 - 23) will be stored. </td></tr>
<tr><td class="paramname">minute</td><td>Pointer to the variable where the minute of the hour (0 - 59) will be stored. </td></tr>
<tr><td class="paramname">second</td><td>Pointer to the variable where the second of the minute (0 - 59) will be stored. </td></tr>
<tr><td class="paramname">musec</td><td>Pointer to the variable where the microseconds of the second (0 - 999999) will be stored. </td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd><ul>
<li><code>0</code>, Success. </li>
<li><code>-1</code>, Error occurred (check <a class="el" href="group__coda__error.html#gafcb445c7fcab2d4d0af01f0e1c2dc866">coda_errno</a>). </li>
</ul>
</dd></dl>
</div>
</div>
</div><!-- contents -->
<div class="footer">
<hr><p>Copyright © 2007-2022 <b>s<span class="soft-red">[</span>&<span class="soft-red">]</span>t</b>, The Netherlands.
</p>
</div>
</div>
</body>
</html>
|
