1 /******************************************************************** 2 * qofdate.h - QofDate, 64bit UTC date handling. 3 * Rewritten from scratch for QOF 0.7.0 4 * 5 * Fri May 5 15:05:24 2006 6 * Copyright (C) 2006 Free Software Foundation, Inc. 7 ********************************************************************/ 8 /* 9 * This program is free software; you can redistribute it and/or modify 10 * it under the terms of the GNU General Public License as published by 11 * the Free Software Foundation; either version 2 of the License, or 12 * (at your option) any later version. 13 * 14 * This program is distributed in the hope that it will be useful, 15 * but WITHOUT ANY WARRANTY; without even the implied warranty of 16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 17 * GNU General Public License for more details. 18 * 19 * You should have received a copy of the GNU General Public License 20 * along with this program; if not, write to the Free Software 21 * Foundation, Inc., 51 Franklin Street, Fifth Floor Boston, MA 02110-1301, USA 22 */ 23 /** @addtogroup QOFTIME 24 @{ 25 */ 26 /** @addtogroup Date Date: 64bit UTC date handling. 27 28 All dates in QOF use Universal Coordinated Time, (UTC), 29 wrapped to allow representation of dates before the epoch. 30 31 localtime is available via GDate but there are limitations. 32 33 -# The GDate data structure represents a day between 34 January 1, Year 1, and sometime a few thousand years in the 35 future, not the full range of QofTime. 36 -# Right now GDate will go to the year 65535 or so, but 37 g_date_set_parse() only parses up to the year 8000 or so - 38 just count on "a few thousand". 39 -# g_date_strftime only deals with date related formats, 40 results of using time formats is undefined. 41 42 A QofDateEntry is one a collection of formats for handling 43 dates, including common defaults. New entries need to be 44 registered using qof_date_add_format before being used to print 45 or scan strings containing dates. 46 47 \todo Add support for customised handlers for added formats. 48 49 A QofDate is theoretically able to go forward to the year 50 292,471,206,707 AD and back to the year 292,471,206,708 BC. 51 Whether such dates actually exist is outside the scope of 52 this documentation. 53 54 \note Time moves at a constant rate, dates do not. Dates are 55 inherently tied to the rotation of the Earth and that rotation 56 is slowing down, causing the need for leapseconds. The incidence 57 of leapseconds cannot be accurately predicted and dates far 58 into the future may be out by a number of seconds. This is 59 important if future dates are based around the start (or end) 60 of a particular day - when those dates come to be viewed as 61 the past, the actual day calculated from the number of seconds 62 may differ to the day originally calculated. When using future 63 dates, avoid using dates at the start or end of a particular day. 64 65 \since v0.7.0 66 67 @{ 68 */ 69 /** 70 @file qofdate.h 71 @brief 64bit Date handling routines 72 @author Copyright 2006 Neil Williams <linux@codehelp.co.uk> 73 */ 74 75 #ifndef QOFDATE_H 76 #define QOFDATE_H 77 78 #include "qoftime.h" 79 80 /** \brief The maximum length of a string used for or created 81 by dates. 82 83 When setting a custom QofDateFormat, neither the format string 84 itself nor any date string created from that format is allowed 85 to exceed this length. 86 */ 87 #define MAX_DATE_LENGTH 41 88 /** \brief The maximum length of a QofDate buffer 89 90 \todo rationalise with MAX_DATE_LENGTH 91 */ 92 #define MAX_DATE_BUFFER 256 93 /** number of seconds in one whole day. */ 94 #define SECS_PER_DAY 86400 95 /** number of seconds in one whole hour. */ 96 #define SECS_PER_HOUR 3600 97 /** QofLogModule name for QofDate */ 98 #define QOF_MOD_DATE "qof-dates" 99 100 /** \brief Full range replacement for struct tm. 101 102 Based on struct tm but using signed integers. The year value 103 uses a signed 64bit value to prevent overflows. (A glong 104 is insufficient by two orders of magnitude.) To retain precision, 105 a QofDate includes a nanoseconds value that can be used 106 with a QofTime and a 64bit value for seconds. 107 108 \note All QofDate values can be negative. 109 The normalising cascade handles rollovers. 110 e.g. If a QofDate qd_min value is 5 111 initially, setting qd_sec to 68 causes qd_sec to actually 112 hold the value 8 and qd_min to hold the value 6. Alternatively, 113 setting qd_sec to -64 with qd_min set to 5 causes qd_sec to hold 114 the value 56 and qd_min to hold the value 3. 115 116 \todo check - years work like this, days don't!! 117 Only qd_year retains a negative value once set. Adding 118 one year to a negative QofDate causes the QofDate to be set to 119 one year further into the past. This follows the same pattern 120 as typical BC dates: the 1st of May 501BC is further into the 121 past than the 5th of May 500BC. 122 123 Why is this a date? Because it represents a date, 124 broken down into the component variables. A QofTime 125 always (and only) relates to seconds, a QofDate always 126 relates to how that number of seconds can be represented 127 as a sequence of days, months, years etc. 128 129 \note Although values can be set directly, 130 ::qof_date_valid should be called before attempting to 131 manipulate a QofDate. 132 133 \todo Reorganise the qof_time_* functions to reflect this 134 statement. qof_time_set_day_end should be qof_date_set_day_end 135 and the various qof_date_time functions need to be reviewed. 136 137 */ 138 typedef struct QofDate_s 139 { 140 /** From QofTime */ 141 glong qd_nanosecs; 142 /** Enlarged replacement of struct tm.tm_sec */ 143 gint64 qd_sec; 144 /** \brief Signed replacement of struct tm.tm_min. 145 146 Setting qd_min to a negative value adjusts the other date 147 values when the QofDate is validated and normalised to 148 create an earlier time. 149 */ 150 glong qd_min; 151 /** \brief Signed replacement of struct tm.tm_hour. 152 153 Setting qd_hour to a negative value adjusts the other date 154 values when the QofDate is validated and normalised to 155 create an earlier time. 156 */ 157 glong qd_hour; 158 /** \brief Signed replacement of struct tm.tm_mday. 159 160 Setting qd_mday to a negative value adjusts the other date 161 values when the QofDate is validated and normalised to 162 create an earlier time. 163 */ 164 glong qd_mday; 165 /** \brief Signed replacement of struct tm.tm_mon. 166 167 Setting qd_mon to a negative value adjusts the other date 168 values when the QofDate is validated and normalised to 169 create an earlier time. 170 */ 171 glong qd_mon; 172 /** \brief Extended version to cope with full range of dates. 173 174 \warning QofDate does not use 1900 or 1970 as a base, all 175 years in QofDate are true values. qd_year == 0 is the only 176 invalid value (validation converts 0 to 1BC). A value of 177 qd_year == 106 means 106AD, not 2006: A value of qd_year 178 == 2006 means 2006, not 3906. Use negative values for dates 179 in 1BC or earlier: qd_year == -43 means 43BC. 180 */ 181 gint64 qd_year; 182 /** Signed replacement of struct tm.tm_wday. 183 qd_wday is a calculated value and will be overridden when 184 the QofDate is validated. */ 185 gshort qd_wday; 186 /** Signed replacement of struct tm.tm_yday. 187 qd_yday is a calculated value and will be overridden when 188 the QofDate is validated. */ 189 gshort qd_yday; 190 /** Signed replacement of struct tm.tm_isdst. 191 qd_is_dst is a calculated value and will be set to UTC when 192 the QofDate is validated. */ 193 gshort qd_is_dst; 194 /** \brief Calculated value based on struct tm.tm_gmtoff. 195 196 \note qd_gmt_off \b WILL be overridden to UTC when the QofDate 197 is validated. This can be used to convert a localtime to UTC - 198 set the value from struct tm.tm_gmtoff for the localtime and 199 validate the QofDate to get UTC. 200 */ 201 glong qd_gmt_off; 202 /** \brief Calculated value based on struct tm.tm_zone. 203 204 \note qd_zone \b WILL be overridden to "GMT" when the QofDate 205 is validated. This can be used to convert a localtime to UTC - 206 set the value from struct tm.tm_zone for the localtime and 207 validate the QofDate to get UTC. */ 208 const gchar *qd_zone; 209 /** \brief If the QofDate is valid or merely initialised. 210 211 Some QofDate values are invalid when initialised 212 to zero (e.g. qm_mday). Avoid setting this value manually 213 (just because it can be done, does not mean doing it is a 214 good idea). Use ::qof_date_valid to ensure that values like 215 qd_wday, qd_yday, qd_gmt_off and qd_is_dst are set correctly. 216 */ 217 gboolean qd_valid; 218 } QofDate; 219 220 /** Nonzero if YEAR is a leap year (every 4 years, 221 except every 100th isn't, and every 400th is). */ 222 # define qof_date_isleap(year) \ 223 ((year) % 4 == 0 && ((year) % 100 != 0 || (year) % 400 == 0)) 224 225 /** \brief initialise the QofDate tables */ 226 void qof_date_init (void); 227 228 /** \brief close down the QofDate tables */ 229 void qof_date_close (void); 230 231 /** \brief UTC date format string. 232 233 Timezone independent, date and time inclusive, as used in the 234 QSF backend. The T and Z characters are from xsd:dateTime format 235 in coordinated universal time, UTC. You can reproduce the string 236 from the GNU/Linux command line using the date utility: 237 \verbatim 238 $ date -u +%Y-%m-%dT%H:M:SZ 239 2004-12-12T23:39:11Z 240 \endverbatim 241 The datestring must be timezone independent and include all 242 specified fields. Remember to use gmtime() NOT localtime()! 243 */ 244 #define QOF_UTC_DATE_FORMAT "%Y-%m-%dT%H:%M:%SZ" 245 246 /** \name Default QofDate formats 247 @{ 248 */ 249 /** \brief Continental US default. "%m/%d/%Y" 250 251 9th May 2006 == 05/09/2006 252 */ 253 #define QOF_DATE_FORMAT_US 1 254 /** \brief United Kingdom default. "%d/%m/%Y" 255 256 9th May 2006 == 09/05/2006 257 */ 258 #define QOF_DATE_FORMAT_UK 2 259 /** \brief Contintental European default. "%d.%m.%Y" 260 261 9th May 2006 == 09.05.2006 262 */ 263 #define QOF_DATE_FORMAT_CE 3 264 /** \brief Short ISO form. "%F" 265 266 9th May 2006 == 2006-05-09 267 */ 268 #define QOF_DATE_FORMAT_ISO 4 269 /** \brief QOF UTC format, xsd:date compatible. 270 QOF_UTC_DATE_FORMAT "%Y-%m-%dT%H:%M:%SZ" 271 272 xsd:date is recommended for any XML data storage of dates and 273 times. 274 275 9th May 2006 == 2006-05-09T14:49:04Z 276 */ 277 #define QOF_DATE_FORMAT_UTC 5 278 279 /** Date and time with nanoseconds and timezone. 280 281 "%Y-%m-%d %H:%M:%S.%N %z" 282 283 12th July 2006 gives 2006-07-12 17:08:16.329768000 +0000 284 in UTC. Timezones can be specified and will then be 285 converted into UTC at validation. 286 */ 287 #define QOF_DATE_FORMAT_ISO8601 6 288 289 /** \brief GNU locale default. "%x" 290 291 QOF_DATE_FORMAT_LOCALE and QOF_DATE_FORMAT_CUSTOM are only 292 suitable for date / time display - storing these values 293 in any kind of file is a recipe for disaster as the exact 294 format can be affected by environment variables and other 295 imponderables. 296 297 One example: 9th May 2006 gives 09/05/06 298 299 \note QOF_DATE_FORMAT_LOCALE includes locale-specific format 300 specifiers and therefore cannot support the full range of 301 QofDate. see \ref datelocales 302 */ 303 #define QOF_DATE_FORMAT_LOCALE 7 304 305 /** \brief Date and time for the current locale "%c" 306 307 QOF_DATE_FORMAT_LOCALE and QOF_DATE_FORMAT_CUSTOM are only 308 suitable for date / time display - storing these values in 309 any kind of file is a recipe for disaster as the exact 310 format can be affected by environment variables and other 311 imponderables. 312 313 One example: 9th May 2006 gives Tue 09 May 2006 14:50:10 UTC 314 315 \note QOF_DATE_FORMAT_CUSTOM includes locale-specific format 316 specifiers and therefore cannot support the full range of 317 QofDate. see \ref datelocales 318 */ 319 #define QOF_DATE_FORMAT_CUSTOM 8 320 321 /** New identifiers must be larger than this. */ 322 #define DATE_FORMAT_LAST QOF_DATE_FORMAT_CUSTOM 323 324 /** @} */ 325 326 /** convenience macro to turn hours into seconds. */ 327 #define QOF_HOUR_TO_SEC(x) (x * SECS_PER_HOUR) 328 /** convenience macro to turn minutes into seconds. */ 329 #define QOF_MIN_TO_SEC(x) (x * 60) 330 /** convenience macro to turn days into seconds. */ 331 #define QOF_DAYS_TO_SEC(x) (x * SECS_PER_DAY) 332 333 /** Index value of the selected QofDateFormat in the 334 DateFormatTable */ 335 typedef gint QofDateFormat; 336 337 /** \name QofDateFormat - standardised date formats 338 339 To simplify usage of strftime and strptime (especially 340 checking error states), QofDate uses a set of standard 341 date formats. You can also register your own format 342 strings as long as they are strftime compatible. 343 344 see also \ref datelocales 345 @{ 346 */ 347 /** \brief Add a specific strftime compatible string as a new 348 QofDateFormat 349 350 Unlike GDate, QofDate allows time-related formats. 351 352 \param str A pre-formatted string, suitable to be passed 353 directly to strftime. 354 \param identifier integer pointer. Will be set to the 355 positive value to be used to identify this date format later. 356 \return TRUE on success, otherwise FALSE 357 */ 358 gboolean 359 qof_date_format_add (const gchar * str, QofDateFormat *identifier); 360 361 /** \brief Retrieve the shorthand name for the selected date 362 format. 363 364 If the selected QofDateFormat is one of the defaults, a shorthand 365 "name" is used. If it is a string added using 366 qof_date_add_format, the string itself is returned. 367 368 \param format The QofDateFormat to lookup. 369 \return FALSE on success and TRUE on failure. 370 */ 371 const gchar * 372 qof_date_format_to_name (QofDateFormat format); 373 374 /** \brief Returns the default date format for a known shorthand 375 name. 376 377 If the selected QofDateFormat is one of the defaults, the 378 shorthand "name" is returned. If format is not a default, 379 returns negative one. 380 381 \param name Shorthand "name" of this format. 382 \return the QofDateFormat on success, negative one on failure. 383 */ 384 QofDateFormat 385 qof_date_format_from_name (const gchar * name); 386 387 /** \brief Set a shorthand name for a custom date format. 388 389 Used alongside ::qof_date_format_add to allow any date format 390 to have a shorthand name. 391 392 \param name Shorthand name for a date format added with 393 qof_date_format_add. The string becomes the property of QofDate 394 and should not be freed. 395 \param format identifier used previously with 396 qof_date_format_add 397 \return TRUE if the shorthand name can be set, FALSE on error or 398 if the chosen QofDateFormat is one of the defaults. 399 */ 400 gboolean 401 qof_date_format_set_name (const gchar * name, QofDateFormat format); 402 403 /** \brief returns the current date format. */ 404 QofDateFormat 405 qof_date_format_get_current (void); 406 407 /** \brief Selects one registered date format as the current 408 default. 409 410 \param df QofDateFormat identifier indicating preferred format. 411 \return TRUE on success, else FALSE. 412 */ 413 gboolean 414 qof_date_format_set_current (QofDateFormat df); 415 416 /** \brief Retrieve the strftime format string for a registered 417 date format. 418 @param df The QofDateFormat identifier for the registered date 419 format. 420 421 @return The format string for this date format or NULL on error. 422 */ 423 const gchar * 424 qof_date_format_get_format (QofDateFormat df); 425 426 /** \brief Return the field separator for the current date format 427 428 \note The separator only relates to the date portion of any 429 date format string, i.e. the separator used between day, month 430 and year. Separators used between time fields like hour, minute, 431 second in any date format are not available. 432 433 \return date single non-digit character to separate fields 434 within the date section of a date format or a null on error. 435 */ 436 gchar 437 qof_date_format_get_date_separator (QofDateFormat df); 438 439 /** \brief Set a locale-specific separator. 440 441 Sets the date separator for a date format added using 442 ::qof_date_format_add. 443 444 \return FALSE if date format is not one of the QOF defaults 445 or if the character is a digit, TRUE on success. 446 */ 447 gboolean 448 qof_date_format_set_date_separator (const gchar sep, QofDateFormat df); 449 /** @} */ 450 451 /** \name QofDate handlers 452 @{ 453 */ 454 /** create a new, empty, QofDate */ 455 QofDate * 456 qof_date_new (void); 457 458 /** create a new QofDate for the current date and time. */ 459 QofDate * 460 qof_date_get_current (void); 461 462 /** create a new QofDate from basic calendar data. */ 463 QofDate * 464 qof_date_new_dmy (gint day, gint month, gint64 year); 465 466 /** free a QofDate */ 467 void 468 qof_date_free (QofDate * date); 469 470 /** Calculate the QofTime between two QofDates */ 471 QofTime* 472 qof_date_time_difference (const QofDate * date1, const QofDate * date2); 473 474 /** Checks if QofDate the last day of the month. 475 476 \param qd A \b valid QofDate. 477 478 \return TRUE if qd_mday is the last day of qd_mon in qd_year, 479 otherwise (or on error), FALSE. 480 */ 481 gboolean 482 qof_date_is_last_mday (const QofDate *qd); 483 484 /** Add (or subtract) months from a QofDate 485 486 Optionally tracks the last day of the month so that 487 if the original QofDate is the last day of the month in 488 the specified year, the updated QofDate will also be the 489 last day of the updated month in the updated year. 490 491 \param qd A QofDate which will be normalised before 492 calculations begin. 493 \param months Number of months to add (or subtract if 494 months is negative). 495 \param track_last_day Whether to track the last day. 496 497 \return FALSE on error, otherwise TRUE. 498 */ 499 gboolean 500 qof_date_addmonths (QofDate * qd, gint months, 501 gboolean track_last_day); 502 503 /** Check two QofDates for equality */ 504 gboolean 505 qof_date_equal (const QofDate *d1, const QofDate *d2); 506 507 /** Compare two QofDates */ 508 gint 509 qof_date_compare (const QofDate * d1, const QofDate * d2); 510 511 /** \brief Validate a QofDate 512 513 If the QofDate is already valid, just returns TRUE. 514 If the QofDate is not valid but can be normalised, the QofDate 515 is normalised and the function returns TRUE. 516 If the QofDate cannot be normalised, returns FALSE. 517 518 Year Zero does not exist in the Christian Era, the Gregorian 519 calendar or the Julian calendar. A year zero does exist in 520 ISO 8601:2004 and in the astronomical year numbering with a 521 defined year zero equal to 1 BC, as well as in some Buddhist 522 and Hindu lunar calendars. 523 524 In QofDate, 1BC is immediately followed by 1AD 525 and months are numbered from 1 to 12, not from zero. 526 527 Normalising a QofDate tries to use sensible defaults: 528 - if qd_mon == 0, validating sets qd_mon to 1 (January) 529 - if qd_year == 0, validating sets qd_year to -1 (1BC). 530 - if qd_mday == 0, validating sets qd_mday to 1. 531 */ 532 gboolean 533 qof_date_valid (QofDate *date); 534 535 /** full range version of g_date_get_day_of_year 536 537 \param mday Any valid QofDate qd_mday, 1 to 31. 538 \param month Any valid QofDate qd_mon, 1 to 12. 539 \param year Any valid QofDate qd_year. 540 541 \return 0 if error, otherwise the day of the year, 542 where Jan 1 is 1, the first day of the year. 543 */ 544 guint16 545 qof_date_get_yday (gint mday, gint month, gint64 year); 546 547 /** full range version of g_date_get_days_in_month 548 549 \param month Any valid QofDate qd_mon, 1 to 12. 550 \param year Any valid QofDate qd_year. 551 552 \return 0 on error, otherwise the number of days in the 553 specified month, taking leap years into account. 554 */ 555 guint8 556 qof_date_get_mday (gint month, gint64 year); 557 558 /** @} */ 559 560 /** \name Conversion handlers for QofDate 561 @{ 562 */ 563 /** Return a QofDate in UTC from a QofTime. */ 564 QofDate * 565 qof_date_from_qtime (const QofTime *qt); 566 567 /** Return a valid QofTime from a valid QofDate. */ 568 QofTime * 569 qof_date_to_qtime (const QofDate *qd); 570 571 /** \brief Convert a struct tm to a QofDate. 572 573 \param stm A pointer to a valid struct tm. 574 \return Newly allocated QofDate or NULL if tm is NULL. 575 */ 576 QofDate * 577 qof_date_from_struct_tm (const struct tm *stm); 578 579 /** \brief Convert a QofDate to a struct tm 580 581 \warning Check the return value - a QofDate has 582 a larger range than a struct tm. The struct tm 583 will be unchanged if a conversion would have been 584 out of range. 585 586 \param qt A valid QofDate. 587 \param stm Pointer to a struct tm to store the result. 588 \param nanosecs Pointer to a glong to store the nanoseconds. 589 590 \return FALSE on error or if the QofDate is invalid or out of 591 the range of a struct tm, otherwise TRUE. 592 */ 593 gboolean 594 qof_date_to_struct_tm (const QofDate * qt, struct tm *stm, glong * nanosecs); 595 596 /** \brief Convert a QofDate to a GDate 597 598 \param qd a valid QofDate 599 \param gd a new GDate to store the converted value. 600 601 \return FALSE on error, if the QofDate is out 602 of range of a GDate or if QofDate is not valid, 603 otherwise TRUE. 604 */ 605 gboolean 606 qof_date_to_gdate (const QofDate *qd, GDate *gd); 607 608 /** \brief Create a QofDate from a GDate. 609 610 A GDate is always within the range of a QofDate. 611 612 \param gd A valid GDate. 613 614 \return NULL on error, otherwise a newly allocated, 615 valid, QofDate. 616 */ 617 QofDate * 618 qof_date_from_gdate (const GDate *gd); 619 620 /** @} */ 621 /** \name Manipulate QofTime as a date 622 623 Shorthand routines to modify a QofTime using date-type values, 624 instead of having to always use seconds. 625 @{ 626 */ 627 /** \brief Add a number of days to a QofDate and normalise. 628 629 \param qd A valid QofDate. 630 \param days Number of days to add - use negative value to 631 subtract. 632 633 \return FALSE on error, otherwise TRUE. 634 */ 635 gboolean 636 qof_date_adddays (QofDate * qd, gint days); 637 638 gboolean 639 qof_date_set_day_end (QofDate * qd); 640 641 gboolean 642 qof_date_set_day_start (QofDate * qd); 643 644 gboolean 645 qof_date_set_day_middle (QofDate * qd); 646 647 /**@} */ 648 649 /** \name Date Printing/Scanning functions 650 651 QofDate supports a wider range of dates than either strftime or 652 GDate and supports all non-locale-specific strftime format 653 specifiers over the full range of QofDate. 654 655 \note Locale-specific formats cannot be extended to the full 656 range of QofDate dates because the locale data for these 657 formats is only available to the underlying strftime 658 implementation. The formats affected are those involving 659 the %E and %O modifiers and other format specifiers that use 660 the current locale. e.g. Japanese Emperor reigns, local 661 numeric specifiers, translated days of the week / month etc. 662 If these are used, only dates within the range of the 663 locale-sensitive strftime on that platform can be 664 supported (either inside or outside QofDate). 665 666 The full list of affected format specifiers is: 667 668 \verbatim 669 'a', 'A', 'b', 'h', 'B', 'c', 'C', 'x', 'p', 'P', 'r', 'X', 'E', 'O'. 670 \endverbatim 671 672 QofDate will attempt to fallback to a usable format 673 if the date is out of range of the underlying strftime. 674 e.g. QOF_DATE_FORMAT_UTC, QOF_DATE_FORMAT_UK, 675 QOF_DATE_FORMAT_US, QOF_DATE_FORMAT_CE or QOF_DATE_FORMAT_ISO. 676 677 \note It is not particularly sensible to write locale-sensitive 678 date strings to any kind of permanent storage. Locale-specific 679 format specifiers should only be used for displaying dates to 680 the user. 681 682 For more information, see \ref datelocales 683 684 - Printing: Convert a QofTime* into a timestamp. 685 -# To print a string yourself, use 686 ::qof_date_format_get_format to get the format to pass to 687 strftime or g_date_strftime. 688 -# To use a registered date format, use 689 ::qof_date_format_set_current and ::qof_date_print. 690 691 - Scanning: Convert a timestamp into a QofTime* 692 -# To scan a string yourself, use ::qof_date_format_get_format 693 to get the format to pass to strptime or use g_date_set_parse 694 -# To scan a stamp created with a registered date format, use 695 ::qof_date_parse 696 @{ 697 */ 698 699 /** \brief Convert a QofDate to a timestamp according to the 700 specified date format. 701 702 Unlike qof_time_stamp_now, any supported QofDate can be converted 703 in any registered QofDateFormat. 704 705 \param date A valid QofDate. 706 \param df a registered QofDateFormat to use to create 707 the string. 708 709 \return NULL on error, otherwise a string which should be freed 710 when no longer needed. 711 */ 712 gchar * 713 qof_date_print (const QofDate * date, QofDateFormat df); 714 715 /** \brief Convert a timestamp to a QofTime 716 717 Safe for all dates within the range of QofDate. 718 719 \param str a timestamp created with one of the registered 720 QofDateFormat formats. 721 \param df The registered QofDateFormat that produced the 722 string. 723 \return a newly allocated, valid, QofDate or NULL on error. 724 */ 725 QofDate * 726 qof_date_parse (const gchar * str, QofDateFormat df); 727 728 /** @} */ 729 /** @} */ 730 /** @} */ 731 732 #endif /* QOFDATE_H */ 733