| 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. |