Debian Codegraph @

lib/datetime/README

raw
1 /****************************************************************************
2 *
3 * MODULE: datetime
4 * AUTHOR(S): Bill Brown <brown gis.uiuc.edu> and Michael Shapiro (CERL)
5 * (original contributors, 1995)
6 * Brad Douglas <rez touchofmadness.com>,
7 * Markus Neteler <neteler itc.it>,
8 * Bernhard Reiter <bernhard intevation.de>,
9 * Radim Blazek <radim.blazek gmail.com>
10 * Glynn Clements <glynn gclements.plus.com>,
11 * PURPOSE: library for date time structure
12 * COPYRIGHT: (C) 2002-2007 by the GRASS Development Team
13 *
14 * This program is free software under the GNU General Public
15 * License (>=v2). Read the file COPYING that comes with GRASS
16 * for details.
17 *
18 *****************************************************************************/
19
20 Note: The timestamp routines
21 G_read_grid3_timestamp +
22 G_remove_grid3_timestamp +
23 G_write_grid3_timestamp
24 are stored in src/libes/gis/timestamp.c
25 (added 3/2001)
26 ---------------------------------------------------------------------------
27
28 This is the DateTime structure
29
30 typedef struct {
31 int mode; /* absolute or relative */
32 int from, to; /* range of values */
33 int positive; /* positive/negative datetime */
34 int year, month, day;
35 int hour, minute;
36 double second;
37 int fracsec; /* #decimal place in printed seconds */
38 int tz; /* timezone - minutes from UTC */
39 } DateTime;
40
41 DateTimes have a 3-part type consisting of
42 'mode' and
43 range qualifiers 'from' and 'to'
44
45 mode: one of
46
47 #define DATETIME_TYPE_ABSOLUTE 1
48 #define DATETIME_TYPE_RELATIVE 2
49
50 from, to: one of
51
52 #define DATETIME_YEAR 1
53 #define DATETIME_MONTH 2
54 #define DATETIME_DAY 3
55 #define DATETIME_HOUR 4
56 #define DATETIME_MINUTE 5
57 #define DATETIME_SECOND 6
58
59 The values for the from/to #defines must increase from YEAR to SECOND
60 In other words YEAR < MONTH < DAY < HOUR < MINUTE < SECOND. The idea
61 is that the higher elements represent higher precision for a date/time.
62 For example, having seconds in the time is more precise than if seconds
63 are not present.
64
65 There are some restrictions on legal values for from/to.
66 1. from <= to
67 2. if the 'mode' is ABSOLUTE, then 'from' must be YEAR
68 3. if the 'mode' is RELATIVE, then
69 'from' and 'to' in {YEAR,MONTH}
70 or in
71 'from' and 'to' in {DAY,HOUR,MINUTE,SECOND}
72
73 year,month,day
74 hour,minute,second:
75 These are non-negative values.
76
77 For ABSOLUTE types, these must be valid date/time values
78 year a complete year, all the digits (not just the last 2 digits)
79 must be positive (since 0 isn't a legal year).
80 month [1,12]
81 day [1,n] where n depends on the year/month.
82 hour [0,23]
83 minute [0,59]
84 second [0.0,<60.0]
85
86 For RELATIVE types, the value corresponding to 'from' is
87 unrestricted (except that it can't be negative). The other values
88 are restricted as follows:
89 if from==YEAR, month is [0,11]
90 if from==DAY, hour is [0,23], min is [0,59], sec is [0.0,<60.0]
91 if from==HOUR, min is [0,59], sec is [0.0,<60.0]
92 if from==MINUTE, sec is [0.0,<60.0]
93
94
95 fracsec:
96 This controls the number of decimal places to print after the seconds.
97 It is only used if the 'to' element is SECOND. It must be non-neagtive.
98
99 tz:
100 The time (hour/minute) in ABSOLUTE types is in local time.
101 The specification of a timezone (tz) is an (subtractive)
102 offset to convert from local time to UTC.
103 To get UTC from localtime: LT - TZ
104
105 tz is expressed in minutes from -720 to 780
106 (720 == 12 hours, 780 minutes == 13 hours).
107 [See ANSI X3.51-1975, section 2.2.3]
108
109 For a timezone to be allowed, the 'to' field must be one of
110 {MINUTE, SECOND}
111
112 positive:
113 this indicates if the datetime value is to considered
114 "positive" (!=0) or "negative" (==0)
115
116 For mode ABSOLUTE, positive==0 means BC
117
118 ----------------------------------------------------
119 API
120
121 (*) Error messages
122 Guidelines:
123 All functions that return int status codes should return
124 0 (or positive) if OK;
125 a negative integer if not;
126 and register the error with a call to datetime_error()
127
128 applications can test for error by
129
130 if (datetime_function() < 0) {process the error}
131
132 int
133 :+ datetime_error (int code, char *msg)
134 record 'code' and 'msg' as error code/msg (in static variables)
135 code==0 will clear the error (ie set msg=NULL)
136
137 returns 'code' so that it can be used like:
138
139 return datetime_error (-1, "bad date");
140
141 char *
142 :+ datetime_get_error_msg()
143 returns pointer to static error msg (which is NULL if no error)
144
145 int
146 :+ datetime_get_error_code()
147 returns error code
148
149 void
150 :+ datetime_clear_error()
151 clears error code and message
152
153 (*) Type:
154
155 int
156 :+ datetime_set_type (DateTime *dt; int mode, from, to, fracsec)
157
158 This routine must be called before any use of dt can be made
159 with other datetime functions
160
161 initialize all the elements in dt.
162 Set all values to zero except
163 tz (set to illegal value - 99*24)
164 positive (set to 1 for positive)
165
166 Set the type info in dt: mode, from, to, fracsec
167 validate the mode/from/to/fracsec (according to the rules for the mode)
168 ie. return the return value from datetime_check_type(dt)
169
170
171 void
172 :+ datetime_get_type (DateTime *dt; int *mode, *from, *to, *fracsec)
173
174 extract the mode, from, to, and fracsec out of dt.
175
176 int
177 :+ datetime_check_type (DateTime *dt)
178
179 checks the mode/from/to/fracsec in dt.
180 returns:
181 0: OK
182 -1: mode is invalid - not one of {ABSOLUTE,RELATIVE}
183 -2: from is invalid - not one of {YEAR,MONTH,DAY,HOUR,MINUTE,SECOND}
184 -3: to is invalid - not one of {YEAR,MONTH,DAY,HOUR,MINUTE,SECOND}
185 -4: from/to are reversed (from>to is illegal)
186 -5: invalid from/to combination for RELATIVE mode
187 from in {YEAR,MONTH} but to is not, or
188 from in {DAY,HOUR,MINUTE,SECOND} but to is not
189 -6: from is invalid for ABSOLUTE mode (from != YEAR is illegal)
190 -7: fracsec is negative (only if to==SECOND)
191
192 int
193 :+ datetime_is_valid_type (DateTime *dt)
194
195 returns 1 if datetime_check_type() returns 0
196 0 if not.
197
198 int
199 :+ datetime_change_from_to (DateTime *dt; int from, to; int round)
200
201 change the from/to of the type for dt.
202
203 'dt' must be legal
204 The 'from/to' must be legal values for the mode of dt;
205 (if they are not legal, then the original values are preserved,
206 dt is not changed).
207
208 returns 0 OK, -1 invalid 'dt', -2 invalid 'from/to'
209
210 round = negative implies floor() [decrease magnitude]
211 0 implies normal rounding, [incr/decr magnitude]
212 positive implies ceil() [increase magnitude]
213
214 Rounding up should be implemented using datetime_increment().
215
216 If dt.mode is ABSOLUTE, then 'from' must be YEAR.
217
218 If dt.from < 'from' (losing "lower" elements), convert the
219 "lost" values to the equivalent value for the new 'from'
220 Lost elements are then set to zero.
221 (This case can only occur for dt.mode relative):
222
223 months += lost years * 12 ; years = 0
224 hours += lost days * 24 ; days = 0
225 minutes += lost hours * 60 ; hours = 0
226 seconds += lost minutes * 60.0 ; minutes = 0
227
228 If dt.from > 'from' (adding "lower" elements), the new elements
229 are set to zero.
230
231 If dt.to < 'to' (adding "higher" elements), the new elements
232 are set to zero.
233
234 If dt.to > 'to' (losing "higher" elements), the
235 the new 'to' is adjusted according to the value for 'round'
236 After rounding the "lost" elements are set to zero.
237
238 if 'round' < 0, then no change is made to the lower elements
239 if 'round' > 0 and if the higher elements are not all zero then
240 the new 'to' element is incremented by by creating a
241 relative DateTime 'incr' with from='to' and to='to'
242 and value 1 then calling datetime_increment(dt,incr)
243
244 if round == 0, then if the doubling all higher elements
245 would cause a carry to occur, then the new 'to'
246 element is incremented, as follows
247 create a DateTime will all higher elements
248 equal to their corresponding elements in 'dt'
249 and then calling datetime_increment(dt,incr)
250
251 int
252 :+ datetime_is_absolute (DateTime *dt)
253 Returns
254 1 if dt.mode is absolute
255 0 if not (even if dt.mode is not defined)
256
257 int
258 :+ datetime_is_relative (DateTime *dt)
259 Returns
260 1 if dt.mode is relative
261 0 if not (even if dt.mode is not defined)
262
263 (*) Copy
264
265 void
266 :+ datetime_copy (DateTime *dst, *src)
267
268 This function copies the 'src' to the 'dst' by
269 dst "=" src :
270
271 dst.from = src.from
272 dst.to = src.to
273 ...
274
275 (*) Same
276
277 int
278 :+ datetime_is_same (DateTime *dt1, *dt2)
279
280 Returns
281 1 if dt1 is exactly the same as dt2
282 0 if they differ
283
284 (*) Ascii
285 The ascii representation of DateTime is
286
287 ABSOLUTE: 15 Jan 1994 [bc] 10:35:23.456 -0500
288 RELATIVE: [-] 2 years 5 months
289 [-] 100 days 15 hours 25 minutes 35.34 seconds
290 The parts can be missing.
291 ABSOLUTE: 1994 [bc]
292 Jan 1994 [bc]
293 15 jan 1000 [bc]
294 15 jan 1994 [bc] 10 [+0000]
295 15 jan 1994 [bc] 10:00 [+0100]
296 15 jan 1994 [bc] 10:00:23.34 [-0500]
297 RELATIVE: [-] 2 years
298 [-] 5 months
299 [-] 2 years 5 months
300 [-] 100 days
301 [-] 15 hours 25 minutes 35.34 seconds
302 [-] 100 days 25 minutes
303 [-] 1000 hours 35.34 seconds
304 etc.
305 NOTE: values missing between the from/to are assumed to be zero;
306 when scanning, they can be missing; when formatting they will
307 appear as 0 (to preserve the from/to):
308
309 1000 hours 0 minutes 35.34 seconds
310 0 days 10 hours 0 minutes
311
312 NOTE: when scanning the from/to are determined by the fields
313 present. Compare:
314 10 hours 0 minutes 35.34 seconds [from=HOUR,to=SECOND]
315 and
316 0 days 10 hours 0 minutes 35.34 seconds [from=DAY,to=SECOND]
317
318 int
319 :+ datetime_scan (DateTime *dt, char *string)
320
321 Convert the ascii string into a DateTime
322 This determines the mode/from/to based on the string,
323 inits 'dt' and then sets values in 'dt' based on the
324 'string'
325
326 Returns 0 if 'string' is legal, -1 if not.
327
328
329 void
330 :+ datetime_format (DateTime *dt, char *string)
331
332 Convert 'dt' to a printable string. 'string' should
333 be large enough to hold the result, perhaps 80 bytes?
334
335 (*) Values
336
337 These routines get/set elements of 'dt'. They return
338 0 if OK
339 -1 if the value being gotten or set is not a legal value
340 -2 if the from/to for 'dt' doesn't include this value
341 Values don't get set if they are invalid.
342
343 int
344 :+ datetime_check_year (DateTime *dt, int year)
345 Returns
346 0 is legal year for dt
347 -1 illegal year for this dt
348 -2 dt has no year component
349
350 int
351 :+ datetime_set_year (DateTime *dt, int year)
352 if dt.mode = ABSOLUTE, this also sets dt.day = 0
353
354 int
355 :+ datetime_get_year (DateTime *dt, int *year)
356
357
358 int
359 :+ datetime_check_month (DateTime *dt, int month)
360 Returns
361 0 is legal month for dt
362 -1 illegal month for this dt
363 -2 dt has no month component
364
365 int
366 :+ datetime_set_month (DateTime *dt, int month)
367 if dt.mode = ABSOLUTE, this also sets dt.day = 0
368
369 int
370 :+ datetime_get_month (DateTime *dt, int *month)
371
372 int
373 :+ datetime_check_day (DateTime *dt, int day)
374 Returns
375 0 is legal day for dt
376 -1 illegal day for this dt
377 -2 dt has no day component
378 Note: if dt.mode is ABSOLUTE, then dt.year and dt.month
379 must also be legal, since the 'day' must be a legal
380 value for the dt.year/dt.month
381
382 int
383 :+ datetime_set_day (DateTime *dt, int day)
384
385 if dt.mode = ABSOLUTE, then
386 'day' must be less than or equal to the number of days in
387 the dt.year,dt.month:
388
389 if (day > datetime_days_in_month (dt.year, dt.month))
390 {error}
391
392 This implies that year/month must be set before days for
393 ABSOLUTE datetimes.
394
395 int
396 :+ datetime_get_day (DateTime *dt, int *day)
397
398 int
399 :+ datetime_check_hour (DateTime *dt, int hour)
400
401 int
402 :+ datetime_set_hour (DateTime *dt, int hour)
403
404 int
405 :+ datetime_get_hour (DateTime *dt, int *hour)
406
407 int
408 :+ datetime_check_minute (DateTime *dt, int minute)
409
410 int
411 :+ datetime_set_minute (DateTime *dt, int minute)
412
413 int
414 :+ datetime_get_minute (DateTime *dt, int *minute)
415
416 int
417 :+ datetime_check_second (DateTime *dt, double second)
418
419 int
420 :+ datetime_set_second (DateTime *dt, double second)
421
422 int
423 :+ datetime_get_second (DateTime *dt, double *second)
424
425 int
426 :+ datetime_check_fracsec (DateTime *dt, int fracsec)
427
428 int
429 :+ datetime_set_fracsec (DateTime *dt, int fracsec)
430
431 int
432 :+ datetime_get_fracsec (DateTime *dt, int *fracsec)
433
434 (*) Arithmetic
435 These functions perform addition/subtraction on datetimes.
436
437 int
438 : datetime_increment (DateTime *src, *incr)
439
440 this function changes the 'src' date/time data based on the 'incr'
441 The type (mode/from/to) of the 'src' can be anything.
442 The mode of the 'incr' must be RELATIVE,
443 and the type (mode/from/to) for 'incr' must be a valid increment
444 for 'src'. See datetime_is_valid_increment(), datetime_check_increment()
445
446 returns
447 0: OK
448 -1: 'incr' is invalid increment for 'src'
449 -2: 'src' is ABSOLUTE, 'incr' is a {DAY-SECOND} interval
450 and 'src' is a date for which this function
451 has not been implemented. NOTE: this should only happen
452 if the total number of days in the 'src' would exceed 28
453 since this would then cause date arithmetic to kick in
454 to figure out if these are too many days for the month.
455 ## BROWN - identify which dates you know how to handle, and which you do not.
456
457 For src.mode ABSOLUTE,
458 positive 'incr' moves into the future,
459 negative 'incr' moves into the past.
460
461 BC implies the year is negative, but all else is positive.
462 Suppose the date is 10jan100bc.
463 To add 1 year would decrease the year to 99 (10jan99bc).
464 To increase the day by 1 would set the day to 11 (11jan100bc).
465 To increase the month by 1 would change the month from 1 (jan)
466 to 2 (feb) (10feb100bc)
467 Also, year==0 is illegal: adding 1 year to 1[bc] gives 1[ad]
468
469 For src.mode RELATIVE
470 Incrementing or decrementing must consider the 'src' and 'incr'
471 as single values (+ or -) and work with this value.
472 For example, suppose
473 A = -4 days, 5 hours, 15 minutes
474 B = 25 hours
475 then
476 A = -(4*24*60 +5*60+15) = -6075
477 B = (25*60) = 1500
478 A + B = -4575 = -(3*24*60 + 4*60 + 15)
479 A = -3 days, 4 hours, 15 minutes
480
481
482
483 The 'fracsec' in 'src' is preserved.
484
485 The 'from/to' of the 'src' is preserved.
486
487 A timezone in 'src' is allowed - it's presence is ignored.
488
489 NOTE: There is no datetime_decrement()
490 To decrement, set the 'incr' negative.
491
492 void
493 :+ datetime_set_positive (DateTime *dt)
494
495 void
496 :+ datetime_set_negative (DateTime *dt)
497
498 void
499 :+ datetime_invert_sign (DateTime *dt)
500
501 int
502 :+ datetime_is_positive (DateTime *dt)
503 these control the "sign" of the datetime value.
504
505 int
506 : datetime_difference (DateTime *a, *b, *result)
507
508 This performs the formula: result = a - b;
509
510 both a and b must be absolute.
511 result will be relative
512 If a is "earlier" than b, then result should be set negative.
513
514 b must be no more "precise" than a.
515 (a copy of b is "extended" to the precision of a)
516
517 datetime_copy (tb, b)
518 datetime_reset_from_to (tb, b.from, a.to, a.fracsec))
519
520
521 If result.to == SECOND, then result.fracsec is a.fracsec
522
523 result will have the following from/to based on a.to:
524
525 result
526 a.to from to
527 YEAR YEAR YEAR
528 MONTH YEAR MONTH
529 DAY DAY DAY
530 HOUR DAY HOUR
531 MINUTE DAY MINUTE
532 SECOND DAY SECOND
533
534 If either 'a' or 'b' has a timezone, both must have a timezone.
535 The difference will account for the differences in the time zones.
536
537
538 int
539 :+ datetime_is_valid_increment (DateTime *src, *incr)
540 Returns
541 datetime_check_increment(src, incr) == 0
542
543 int
544 :+ datetime_check_increment (DateTime *src, *incr)
545
546 This checks if the type of 'incr' is valid for
547 incrementing/decrementing 'src'.
548
549 Returns:
550 1 src is not a legal DateTime, error code/msg
551 are those set by datetime_is_valid_type()
552 2 incr is not a legal DateTime, error code/msg
553 are those set by datetime_is_valid_type()
554 -1 incr.mode not relative
555 -2 incr more precise that src
556 -3 illegal incr, must be YEAR-MONTH
557 -4 illegal incr, must be DAY-SECOND
558
559 The type (mode/from/to) of the 'src' can be anything.
560 The incr.mode must be RELATIVE
561 (return -1 if not)
562
563 incr.to is restricted based on the src.to:
564
565 incr.to <= src.to (incr not more precise than src)
566 (return -2 if not)
567
568 if src.to is in {YEAR,MONTH} then
569 incr.to must be in {YEAR,MONTH}
570 (return -3 if not)
571 if src.to is in {DAY,HOUR,MINUTE,SECOND} then
572 incr.to must be in {DAY,HOUR,MINUTE,SECOND}
573 (return -4 if not)
574
575 note: it is ok for incr.from > src.from
576 (which can only happen for src.mode RELATIVE).
577
578 A timezone in 'src' is allowed - it's presence is ignored.
579
580 To aid in setting the 'incr' type, the following routine can be used
581
582 int
583 :+ datetime_get_increment_type (DateTime *src; int *mode, *from, *to, *fracsec)
584
585 this returns the components of a type (mode/from/to/fracsec) that
586 can be used to construct a DateTime object that can be used
587 to increment the 'src'. See datetime_set_increment_type().
588
589 returns 0 dt is legal
590 !=0 why dt is illegal
591
592 Implemented as follows:
593
594 *mode = RELATIVE
595 *to = src.to
596 *fracsec = src.fracsec
597
598 if src.mode is ABSOLUTE
599 if src.to is in {YEAR,MONTH} then
600 *from = YEAR
601 if src.to is in {DAY,HOUR,MINUTE,SECOND} then
602 *from = DAY
603
604 if src.mode is RELATIVE, then
605 *from = src.from
606
607
608 int
609 :+ datetime_set_increment_type (DateTime *src, *incr)
610
611 src must be legal
612 This is a convenience routine which is implemented as follows:
613
614 int mode, from ,to;
615 int fracsec;
616
617 if(datetime_get_increment_type (src, &mode, &from, &to, &fracsec))
618 return datetime_error_cde();
619 return datetime_set_type (incr, mode, from, to, fracsec);
620
621 (*) Misc
622
623 int
624 :+ datetime_days_in_month (int month, year)
625
626 int
627 :+ datetime_is_leap_year (int year)
628
629 int
630 :+ datetime_days_in_year (int year)
631
632 (*) Timezone
633
634 int
635 :+ datetime_is_valid_timezone (int minutes)
636 returns:
637 1 OK: -720 <= minutes <= 780 (720 = 12 hours; 780 = 13 hours)
638 0 NOT OK
639
640 int
641 :+ datetime_check_timezone (DateTime *dt, int minutes)
642
643 'dt' must be mode ABSOLUTE and dt.to must be one of {MINUTE,SECOND}
644 minutes must be a valid timezone offset: ie in the range [-720,+780]
645
646 return
647 0: OK
648 -1: mode not ABSOLUTE
649 -2: dt.to not in {MINUTE,SECOND}
650 -3: minutes not valid - not in the range [-720,+780]
651
652 int
653 :+ datetime_set_timezone (DateTime *dt, int minutes)
654
655 if (datetime_check_timezone(dt,minutes)==0)
656 set dt.tz=minutes
657
658 'dt' must be mode ABSOLUTE and dt.to must be one of {MINUTE,SECOND}
659 minutes must be a valid timezone offset: ie in the range [-720,+780]
660
661 return
662 0: OK
663 -1: mode not ABSOLUTE
664 -2: dt.to not in {MINUTE,SECOND}
665 -3: minutes not valid - not in the range [-720,+780]
666
667 int
668 :+ datetime_get_timezone (DateTime *dt, int *minutes)
669
670 return
671 0: OK - if 'dt' has a timezone and sets 'minutes'
672 -1: mode not ABSOLUTE
673 -2: dt.to not in {MINUTE,SECOND}
674 -3: minutes not valid - not in the range [-720,+780]
675
676
677 void
678 :+ datetime_unset_timezone (DateTime *dt)
679 Remove timezone from 'dt'
680 dt.tz = 99*60 (some illegal value)
681
682 int
683 :+ datetime_change_timezone (DateTime *dt; int minutes)
684 if dt has a timezone,
685 increment dt by minutes-dt.tz MINUTES
686 set dt.tz = minutes
687
688 returns 0 OK, datetime_check_timezone(dt) if not,
689 or -4 if minues invalid
690
691 int
692 :+ datetime_change_to_utc (DateTime *dt)
693 return datetime_change_timezone (dt, 0);
694
695 void
696 :+ datetime_decompose_timezone (int tz, int *hour, int *minute)
697 tz = abs(tz)
698 *hour = tz/60
699 *minute = tz%60
700
701 note: hour,minute are non-negative. Must look at sign of tz
702 itself to see if the tz is negative offset or not. This routine
703 would be used to format tz for output. For example if tz=-350
704 this would be hour=5 minute=50, but negative. Output might econde
705 this as -0550: printf ("%s%02d%02d", tz<0?"-":"", hour, minute)
706
707 (*) A function that returns the timezone for the local system??
708
709 int
710 :+ datetime_get_local_timezone (int *minutes)
711
712 returns 0 OK, -1 local timezone info not available
713
714 (*) Local time
715
716 void
717 :+ datetime_get_local_time (DateTime *dt)
718
719 set mode/from/to ABSOLUTE/YEAR/SECOND
720 set the local time into 'dt'
721
722 does not set timezone.
723
724 (*) GRASS will probably have to have a function that returns the
725 timezone of the database:
726
727 ### BROWN
728 ## so a database only has one timezone? Or can each map have its own?
729 ### SHAPIRO
730 ## good question. A location may span more than one time zone. Also timezones
731 ## are not nice shapes. We probably need a function that returns a timezone
732 ## for a specified latlon/longitude and/or for a region. How would this
733 ## function deal with daylight savings time?
734 ## The timezone(s) might have to be represented as a vector map
735 ## I suggest we hold off on this and add it later.
736
737 G_get_database_timezone (int *tz)
738 tz in minutes as defined for datetime library
739 returns
740 0 database has no timezone
741 1 database has a timezone - returned in tz
742 -1 error reading timezone file.