Date: 64bit UTC date handling.
[Time: 64bit UTC Time handling.]

Detailed Description

All dates in QOF use Universal Coordinated Time, (UTC), wrapped to allow representation of dates before the epoch.

localtime is available via GDate but there are limitations.

  1. The GDate data structure represents a day between January 1, Year 1, and sometime a few thousand years in the future, not the full range of QofTime.
  2. Right now GDate will go to the year 65535 or so, but g_date_set_parse() only parses up to the year 8000 or so - just count on "a few thousand".
  3. g_date_strftime only deals with date related formats, results of using time formats is undefined.

A QofDateEntry is one a collection of formats for handling dates, including common defaults. New entries need to be registered using qof_date_add_format before being used to print or scan strings containing dates.

Todo:
Add support for customised handlers for added formats.
A QofDate is theoretically able to go forward to the year 292,471,206,707 AD and back to the year 292,471,206,708 BC. Whether such dates actually exist is outside the scope of this documentation.

Note:
Time moves at a constant rate, dates do not. Dates are inherently tied to the rotation of the Earth and that rotation is slowing down, causing the need for leapseconds. The incidence of leapseconds cannot be accurately predicted and dates far into the future may be out by a number of seconds. This is important if future dates are based around the start (or end) of a particular day - when those dates come to be viewed as the past, the actual day calculated from the number of seconds may differ to the day originally calculated. When using future dates, avoid using dates at the start or end of a particular day.
Since:
v0.7.0


Files

file  qofdate.h
 64bit Date handling routines

Data Structures

struct  QofDate_s
 Full range replacement for struct tm. More...

QofDateFormat - standardised date formats

To simplify usage of strftime and strptime (especially checking error states), QofDate uses a set of standard date formats. You can also register your own format strings as long as they are strftime compatible.

see also QofDate and locales.

gboolean qof_date_format_add (const gchar *str, QofDateFormat *identifier)
 Add a specific strftime compatible string as a new QofDateFormat.
const gchar * qof_date_format_to_name (QofDateFormat format)
 Retrieve the shorthand name for the selected date format.
QofDateFormat qof_date_format_from_name (const gchar *name)
 Returns the default date format for a known shorthand name.
gboolean qof_date_format_set_name (const gchar *name, QofDateFormat format)
 Set a shorthand name for a custom date format.
QofDateFormat qof_date_format_get_current (void)
 returns the current date format.
gboolean qof_date_format_set_current (QofDateFormat df)
 Selects one registered date format as the current default.
const gchar * qof_date_format_get_format (QofDateFormat df)
 Retrieve the strftime format string for a registered date format.
gchar qof_date_format_get_date_separator (QofDateFormat df)
 Return the field separator for the current date format.
gboolean qof_date_format_set_date_separator (const gchar sep, QofDateFormat df)
 Set a locale-specific separator.

QofDate handlers

QofDate * qof_date_new (void)
QofDate * qof_date_get_current (void)
QofDate * qof_date_new_dmy (gint day, gint month, gint64 year)
void qof_date_free (QofDate *date)
QofTime * qof_date_time_difference (const QofDate *date1, const QofDate *date2)
gboolean qof_date_is_last_mday (const QofDate *qd)
gboolean qof_date_addmonths (QofDate *qd, gint months, gboolean track_last_day)
gboolean qof_date_equal (const QofDate *d1, const QofDate *d2)
gint qof_date_compare (const QofDate *d1, const QofDate *d2)
gboolean qof_date_valid (QofDate *date)
 Validate a QofDate.
guint16 qof_date_get_yday (gint mday, gint month, gint64 year)
guint8 qof_date_get_mday (gint month, gint64 year)

Conversion handlers for QofDate

QofDate * qof_date_from_qtime (const QofTime *qt)
QofTime * qof_date_to_qtime (const QofDate *qd)
QofDate * qof_date_from_struct_tm (const struct tm *stm)
 Convert a struct tm to a QofDate.
gboolean qof_date_to_struct_tm (const QofDate *qt, struct tm *stm, glong *nanosecs)
 Convert a QofDate to a struct tm.
gboolean qof_date_to_gdate (const QofDate *qd, GDate *gd)
 Convert a QofDate to a GDate.
QofDate * qof_date_from_gdate (const GDate *gd)
 Create a QofDate from a GDate.

Manipulate QofTime as a date

Shorthand routines to modify a QofTime using date-type values, instead of having to always use seconds.

gboolean qof_date_adddays (QofDate *qd, gint days)
 Add a number of days to a QofDate and normalise.
gboolean qof_date_set_day_end (QofDate *qd)
gboolean qof_date_set_day_start (QofDate *qd)
gboolean qof_date_set_day_middle (QofDate *qd)

Date Printing/Scanning functions

QofDate supports a wider range of dates than either strftime or GDate and supports all non-locale-specific strftime format specifiers over the full range of QofDate.

Note:
Locale-specific formats cannot be extended to the full range of QofDate dates because the locale data for these formats is only available to the underlying strftime implementation. The formats affected are those involving the E and O modifiers and other format specifiers that use the current locale. e.g. Japanese Emperor reigns, local numeric specifiers, translated days of the week / month etc. If these are used, only dates within the range of the locale-sensitive strftime on that platform can be supported (either inside or outside QofDate).
The full list of affected format specifiers is:

'a', 'A', 'b', 'h', 'B', 'c', 'C', 'x', 'p', 'P', 'r', 'X', 'E', 'O'.

QofDate will attempt to fallback to a usable format if the date is out of range of the underlying strftime. e.g. QOF_DATE_FORMAT_UTC, QOF_DATE_FORMAT_UK, QOF_DATE_FORMAT_US, QOF_DATE_FORMAT_CE or QOF_DATE_FORMAT_ISO.

Note:
It is not particularly sensible to write locale-sensitive date strings to any kind of permanent storage. Locale-specific format specifiers should only be used for displaying dates to the user.
For more information, see QofDate and locales.

  • Scanning: Convert a timestamp into a QofTime*
    1. To scan a string yourself, use qof_date_format_get_format to get the format to pass to strptime or use g_date_set_parse
    2. To scan a stamp created with a registered date format, use qof_date_parse


gchar * qof_date_print (const QofDate *date, QofDateFormat df)
 Convert a QofDate to a timestamp according to the specified date format.
QofDate * qof_date_parse (const gchar *str, QofDateFormat df)
 Convert a timestamp to a QofTime.

Default QofDate formats

#define QOF_DATE_FORMAT_US   1
 Continental US default. "%m/%d/%Y".
#define QOF_DATE_FORMAT_UK   2
 United Kingdom default. "%d/%m/%Y".
#define QOF_DATE_FORMAT_CE   3
 Contintental European default. "%d.%m.%Y".
#define QOF_DATE_FORMAT_ISO   4
 Short ISO form. "%F".
#define QOF_DATE_FORMAT_UTC   5
 QOF UTC format, xsd:date compatible. QOF_UTC_DATE_FORMAT "%Y-%m-%dT%H:%M:%SZ".
#define QOF_DATE_FORMAT_ISO8601   6
#define QOF_DATE_FORMAT_LOCALE   7
 GNU locale default. "%x".
#define QOF_DATE_FORMAT_CUSTOM   8
 Date and time for the current locale "%c".
#define DATE_FORMAT_LAST   QOF_DATE_FORMAT_CUSTOM

Defines

#define MAX_DATE_LENGTH   41
 The maximum length of a string used for or created by dates.
#define MAX_DATE_BUFFER   256
 The maximum length of a QofDate buffer.
#define SECS_PER_DAY   86400
#define SECS_PER_HOUR   3600
#define QOF_MOD_DATE   "qof-dates"
#define qof_date_isleap(year)   ((year) % 4 == 0 && ((year) % 100 != 0 || (year) % 400 == 0))
#define QOF_UTC_DATE_FORMAT   "%Y-%m-%dT%H:%M:%SZ"
 UTC date format string.
#define QOF_HOUR_TO_SEC(x)   (x * SECS_PER_HOUR)
#define QOF_MIN_TO_SEC(x)   (x * 60)
#define QOF_DAYS_TO_SEC(x)   (x * SECS_PER_DAY)

Typedefs

typedef struct QofDate_s QofDate
typedef gint QofDateFormat

Functions

void qof_date_init (void)
 initialise the QofDate tables
void qof_date_close (void)
 close down the QofDate tables

Define Documentation

#define DATE_FORMAT_LAST   QOF_DATE_FORMAT_CUSTOM

New identifiers must be larger than this.

Definition at line 322 of file qofdate.h.

#define MAX_DATE_BUFFER   256

The maximum length of a QofDate buffer.

Todo:
rationalise with MAX_DATE_LENGTH

Definition at line 92 of file qofdate.h.

#define MAX_DATE_LENGTH   41

The maximum length of a string used for or created by dates.

When setting a custom QofDateFormat, neither the format string itself nor any date string created from that format is allowed to exceed this length.

Definition at line 87 of file qofdate.h.

#define QOF_DATE_FORMAT_CE   3

Contintental European default. "%d.%m.%Y".

9th May 2006 == 09.05.2006

Definition at line 263 of file qofdate.h.

#define QOF_DATE_FORMAT_CUSTOM   8

Date and time for the current locale "%c".

QOF_DATE_FORMAT_LOCALE and QOF_DATE_FORMAT_CUSTOM are only suitable for date / time display - storing these values in any kind of file is a recipe for disaster as the exact format can be affected by environment variables and other imponderables.

One example: 9th May 2006 gives Tue 09 May 2006 14:50:10 UTC

Note:
QOF_DATE_FORMAT_CUSTOM includes locale-specific format specifiers and therefore cannot support the full range of QofDate. see QofDate and locales.

Definition at line 319 of file qofdate.h.

#define QOF_DATE_FORMAT_ISO   4

Short ISO form. "%F".

9th May 2006 == 2006-05-09

Definition at line 268 of file qofdate.h.

#define QOF_DATE_FORMAT_ISO8601   6

Date and time with nanoseconds and timezone.

"%Y-%m-%d %H:%M:%S.%N %z"

12th July 2006 gives 2006-07-12 17:08:16.329768000 +0000 in UTC. Timezones can be specified and will then be converted into UTC at validation.

Definition at line 287 of file qofdate.h.

#define QOF_DATE_FORMAT_LOCALE   7

GNU locale default. "%x".

QOF_DATE_FORMAT_LOCALE and QOF_DATE_FORMAT_CUSTOM are only suitable for date / time display - storing these values in any kind of file is a recipe for disaster as the exact format can be affected by environment variables and other imponderables.

One example: 9th May 2006 gives 09/05/06

Note:
QOF_DATE_FORMAT_LOCALE includes locale-specific format specifiers and therefore cannot support the full range of QofDate. see QofDate and locales.

Definition at line 303 of file qofdate.h.

#define QOF_DATE_FORMAT_UK   2

United Kingdom default. "%d/%m/%Y".

9th May 2006 == 09/05/2006

Definition at line 258 of file qofdate.h.

#define QOF_DATE_FORMAT_US   1

Continental US default. "%m/%d/%Y".

9th May 2006 == 05/09/2006

Definition at line 253 of file qofdate.h.

#define QOF_DATE_FORMAT_UTC   5

QOF UTC format, xsd:date compatible. QOF_UTC_DATE_FORMAT "%Y-%m-%dT%H:%M:%SZ".

xsd:date is recommended for any XML data storage of dates and times.

9th May 2006 == 2006-05-09T14:49:04Z

Definition at line 277 of file qofdate.h.

#define qof_date_isleap ( year   )     ((year) % 4 == 0 && ((year) % 100 != 0 || (year) % 400 == 0))

Nonzero if YEAR is a leap year (every 4 years, except every 100th isn't, and every 400th is).

Definition at line 222 of file qofdate.h.

#define QOF_DAYS_TO_SEC ( x   )     (x * SECS_PER_DAY)

convenience macro to turn days into seconds.

Definition at line 331 of file qofdate.h.

#define QOF_HOUR_TO_SEC ( x   )     (x * SECS_PER_HOUR)

convenience macro to turn hours into seconds.

Definition at line 327 of file qofdate.h.

#define QOF_MIN_TO_SEC ( x   )     (x * 60)

convenience macro to turn minutes into seconds.

Definition at line 329 of file qofdate.h.

#define QOF_MOD_DATE   "qof-dates"

QofLogModule name for QofDate

Definition at line 98 of file qofdate.h.

#define QOF_UTC_DATE_FORMAT   "%Y-%m-%dT%H:%M:%SZ"

UTC date format string.

Timezone independent, date and time inclusive, as used in the QSF backend. The T and Z characters are from xsd:dateTime format in coordinated universal time, UTC. You can reproduce the string from the GNU/Linux command line using the date utility: 

$ date -u +%Y-%m-%dT%H:M:SZ 
2004-12-12T23:39:11Z
The datestring must be timezone independent and include all specified fields. Remember to use gmtime() NOT localtime()!

Definition at line 244 of file qofdate.h.

#define SECS_PER_DAY   86400

number of seconds in one whole day.

Definition at line 94 of file qofdate.h.

#define SECS_PER_HOUR   3600

number of seconds in one whole hour.

Definition at line 96 of file qofdate.h.

Typedef Documentation

typedef gint QofDateFormat

Index value of the selected QofDateFormat in the DateFormatTable

Definition at line 335 of file qofdate.h.

Function Documentation

gboolean qof_date_adddays ( QofDate *  qd,
gint  days 
)

Add a number of days to a QofDate and normalise.

Parameters:
qd A valid QofDate.
days Number of days to add - use negative value to subtract.
Returns:
FALSE on error, otherwise TRUE.

Definition at line 966 of file qofdate.c.

00967 {
00968     g_return_val_if_fail (qd, FALSE);
00969     g_return_val_if_fail (qof_date_valid (qd), FALSE);
00970     qd->qd_mday += days;
00971     return qof_date_valid (qd);
00972 }

gboolean qof_date_addmonths ( QofDate *  qd,
gint  months,
gboolean  track_last_day 
)

Add (or subtract) months from a QofDate

Optionally tracks the last day of the month so that if the original QofDate is the last day of the month in the specified year, the updated QofDate will also be the last day of the updated month in the updated year.

Parameters:
qd A QofDate which will be normalised before calculations begin.
months Number of months to add (or subtract if months is negative).
track_last_day Whether to track the last day.
Returns:
FALSE on error, otherwise TRUE.

Definition at line 975 of file qofdate.c.

00977 {
00978     g_return_val_if_fail (qd, FALSE);
00979     g_return_val_if_fail (qof_date_valid (qd), FALSE);
00980     qd->qd_mon += months % 12;
00981     qd->qd_year += months / 12;
00982     g_return_val_if_fail (qof_date_valid (qd), FALSE);
00983     if (track_last_day && qof_date_is_last_mday (qd))
00984     {
00985         qd->qd_mday = qof_date_get_mday (qd->qd_mon,
00986             qd->qd_year);
00987     }
00988     return TRUE;
00989 }

gint qof_date_compare ( const QofDate *  d1,
const QofDate *  d2 
)

Compare two QofDates

Definition at line 637 of file qofdate.c.

00638 {
00639     if ((!d1) && (!d2))
00640         return 0;
00641     if (d1 == d2)
00642         return 0;
00643     if (!d1)
00644         return -1;
00645     if (!d2)
00646         return 1;
00647     if (d1->qd_year < d2->qd_year)
00648         return -1;
00649     if (d1->qd_year > d2->qd_year)
00650         return 1;
00651     if (d1->qd_mon < d2->qd_mon)
00652         return -1;
00653     if (d1->qd_mon > d2->qd_mon)
00654         return 1;
00655     if (d1->qd_mday < d2->qd_mday)
00656         return -1;
00657     if (d1->qd_mday > d2->qd_mday)
00658         return 1;
00659     if (d1->qd_hour < d2->qd_hour)
00660         return -1;
00661     if (d1->qd_hour > d2->qd_hour)
00662         return 1;
00663     if (d1->qd_min < d2->qd_min)
00664         return -1;
00665     if (d1->qd_min > d2->qd_min)
00666         return 1;
00667     if (d1->qd_sec < d2->qd_sec)
00668         return -1;
00669     if (d1->qd_sec > d2->qd_sec)
00670         return 1;
00671     if (d1->qd_nanosecs < d2->qd_nanosecs)
00672         return -1;
00673     if (d1->qd_nanosecs > d2->qd_nanosecs)
00674         return 1;
00675     return 0;
00676 }

gboolean qof_date_equal ( const QofDate *  d1,
const QofDate *  d2 
)

Check two QofDates for equality

Definition at line 629 of file qofdate.c.

00630 {
00631     if (0 == qof_date_compare (d1, d2))
00632         return TRUE;
00633     return FALSE;
00634 }

gboolean qof_date_format_add ( const gchar *  str,
QofDateFormat *  identifier 
)

Add a specific strftime compatible string as a new QofDateFormat.

Unlike GDate, QofDate allows time-related formats.

Parameters:
str A pre-formatted string, suitable to be passed directly to strftime.
identifier integer pointer. Will be set to the positive value to be used to identify this date format later.
Returns:
TRUE on success, otherwise FALSE

Todo:
Move to QofDate and qofgmtime_r

Definition at line 202 of file qofdate.c.

00203 {
00204     struct tm check;
00205     gint len;
00206     time_t now;
00207     gchar test[MAX_DATE_BUFFER];
00208 
00210     g_return_val_if_fail (QofDateInit, FALSE);
00211     g_return_val_if_fail (str, FALSE);
00212     g_return_val_if_fail (strlen (str) != 0, FALSE);
00213     /* prevent really long strings being passed */
00214     ENTER (" str=%s", str);
00215     if (strlen (str) > MAX_DATE_LENGTH)
00216     {
00217         LEAVE (" '%s' is too long! Max=%d str_len=%d",
00218             str, MAX_DATE_LENGTH, (gint) strlen (str));
00219         return FALSE;
00220     }
00221     /* test the incoming string using the current time. */
00222     now = time (NULL);
00223     test[0] = '\1';
00224     check = *gmtime_r (&now, &check);
00225     /* need to allow time related formats - 
00226     don't use g_date_strftime here. */
00227     len = strftime (test, (MAX_DATE_BUFFER - 1), str, &check);
00228     if (len == 0 && test[0] != '\0')
00229     {
00230         LEAVE (" strftime could not understand '%s'", str);
00231         return FALSE;
00232     }
00233     len = strlen (test);
00234     if (len > MAX_DATE_LENGTH)
00235     {
00236         LEAVE (" %s creates a string '%s' that is too long!"
00237             " Max=%d str_len=%d", str, test, MAX_DATE_LENGTH, len);
00238         return FALSE;
00239     }
00240     *identifier = g_hash_table_size (DateFormatTable) + 1;
00241     {
00242         QofDateEntry *d = g_new0 (QofDateEntry, 1);
00243         d->format = str;
00244         d->name = str;
00245         d->separator = locale_separator;
00246         d->df = *identifier;
00247         g_hash_table_insert (DateFormatTable, GINT_TO_POINTER (d->df), d);
00248     }
00249     LEAVE (" successful");
00250     return TRUE;
00251 }

QofDateFormat qof_date_format_from_name ( const gchar *  name  ) 

Returns the default date format for a known shorthand name.

If the selected QofDateFormat is one of the defaults, the shorthand "name" is returned. If format is not a default, returns negative one.

Parameters:
name Shorthand "name" of this format.
Returns:
the QofDateFormat on success, negative one on failure.

Definition at line 385 of file qofdate.c.

00386 {
00387     struct iter i;
00388 
00389     if (!name)
00390         return -1;
00391     if (0 == safe_strcmp (name, "us"))
00392         return QOF_DATE_FORMAT_US;
00393     if (0 == safe_strcmp (name, "uk"))
00394         return QOF_DATE_FORMAT_UK;
00395     if (0 == safe_strcmp (name, "ce"))
00396         return QOF_DATE_FORMAT_CE;
00397     if (0 == safe_strcmp (name, "utc"))
00398         return QOF_DATE_FORMAT_UTC;
00399     if (0 == safe_strcmp (name, "iso"))
00400         return QOF_DATE_FORMAT_ISO;
00401     if (0 == safe_strcmp (name, "locale"))
00402         return QOF_DATE_FORMAT_LOCALE;
00403     if (0 == safe_strcmp (name, "custom"))
00404         return QOF_DATE_FORMAT_CUSTOM;
00405     i.name = name;
00406     i.df = -1;
00407     g_hash_table_foreach (DateFormatTable, lookup_name, &i);
00408     return i.df;
00409 }

gchar qof_date_format_get_date_separator ( QofDateFormat  df  ) 

Return the field separator for the current date format.

Note:
The separator only relates to the date portion of any date format string, i.e. the separator used between day, month and year. Separators used between time fields like hour, minute, second in any date format are not available.
Returns:
date single non-digit character to separate fields within the date section of a date format or a null on error.

Definition at line 325 of file qofdate.c.

00326 {
00327     QofDateEntry *d;
00328 
00329     g_return_val_if_fail (QofDateInit, locale_separator);
00330     d = g_hash_table_lookup (DateFormatTable, GINT_TO_POINTER (df));
00331     if (!d)
00332     {
00333         PERR (" unknown format: '%d'", df);
00334         return locale_separator;
00335     }
00336     return d->separator;
00337 }

const gchar* qof_date_format_get_format ( QofDateFormat  df  ) 

Retrieve the strftime format string for a registered date format.

Parameters:
df The QofDateFormat identifier for the registered date format.
Returns:
The format string for this date format or NULL on error.

Definition at line 310 of file qofdate.c.

00311 {
00312     QofDateEntry *d;
00313 
00314     g_return_val_if_fail (QofDateInit, NULL);
00315     d = g_hash_table_lookup (DateFormatTable, GINT_TO_POINTER (df));
00316     if (!d)
00317     {
00318         PERR (" unknown format: '%d'", df);
00319         return NULL;
00320     }
00321     return d->format;
00322 }

gboolean qof_date_format_set_current ( QofDateFormat  df  ) 

Selects one registered date format as the current default.

Parameters:
df QofDateFormat identifier indicating preferred format.
Returns:
TRUE on success, else FALSE.

Definition at line 294 of file qofdate.c.

00295 {
00296     QofDateEntry *d;
00297 
00298     g_return_val_if_fail (QofDateInit, FALSE);
00299     d = g_hash_table_lookup (DateFormatTable, GINT_TO_POINTER (df));
00300     if (!d)
00301     {
00302         PERR (" unknown format: '%d'", df);
00303         return FALSE;
00304     }
00305     dateFormat = d->df;
00306     return TRUE;
00307 }

gboolean qof_date_format_set_date_separator ( const gchar  sep,
QofDateFormat  df 
)

Set a locale-specific separator.

Sets the date separator for a date format added using qof_date_format_add.

Returns:
FALSE if date format is not one of the QOF defaults or if the character is a digit, TRUE on success.

Definition at line 340 of file qofdate.c.

00341 {
00342     QofDateEntry *d;
00343 
00344     g_return_val_if_fail (QofDateInit, FALSE);
00345     if (df < DATE_FORMAT_LAST)
00346     {
00347         DEBUG (" Prevented attempt to override a default format");
00348         return FALSE;
00349     }
00350     if (g_ascii_isdigit (sep))
00351         return FALSE;
00352     d = g_hash_table_lookup (DateFormatTable, GINT_TO_POINTER (df));
00353     if (!d)
00354     {
00355         PERR (" unknown format: '%d'", df);
00356         return FALSE;
00357     }
00358     d->separator = sep;
00359     g_hash_table_insert (DateFormatTable, GINT_TO_POINTER (df), d);
00360     return TRUE;
00361 }

gboolean qof_date_format_set_name ( const gchar *  name,
QofDateFormat  format 
)

Set a shorthand name for a custom date format.

Used alongside qof_date_format_add to allow any date format to have a shorthand name.

Parameters:
name Shorthand name for a date format added with qof_date_format_add. The string becomes the property of QofDate and should not be freed.
format identifier used previously with qof_date_format_add
Returns:
TRUE if the shorthand name can be set, FALSE on error or if the chosen QofDateFormat is one of the defaults.

Definition at line 269 of file qofdate.c.

00270 {
00271     QofDateEntry *d;
00272 
00273     g_return_val_if_fail (QofDateInit, FALSE);
00274     if (format <= DATE_FORMAT_LAST)
00275         return FALSE;
00276     d = g_hash_table_lookup (DateFormatTable, GINT_TO_POINTER (format));
00277     if (!d)
00278     {
00279         PERR (" unknown format: '%d'", format);
00280         return FALSE;
00281     }
00282     d->name = name;
00283     g_hash_table_insert (DateFormatTable, GINT_TO_POINTER (format), d);
00284     return TRUE;
00285 }

const gchar* qof_date_format_to_name ( QofDateFormat  format  ) 

Retrieve the shorthand name for the selected date format.

If the selected QofDateFormat is one of the defaults, a shorthand "name" is used. If it is a string added using qof_date_add_format, the string itself is returned.

Parameters:
format The QofDateFormat to lookup.
Returns:
FALSE on success and TRUE on failure.

Definition at line 254 of file qofdate.c.

00255 {
00256     QofDateEntry *d;
00257 
00258     g_return_val_if_fail (QofDateInit, NULL);
00259     d = g_hash_table_lookup (DateFormatTable, GINT_TO_POINTER (format));
00260     if (!d)
00261     {
00262         PERR (" unknown format: '%d'", format);
00263         return NULL;
00264     }
00265     return d->name;
00266 }

void qof_date_free ( QofDate *  date  ) 

free a QofDate

Definition at line 608 of file qofdate.c.

00609 {
00610     g_return_if_fail (date);
00611     g_free (date);
00612     date = NULL;
00613 }

QofDate* qof_date_from_gdate ( const GDate *  gd  ) 

Create a QofDate from a GDate.

A GDate is always within the range of a QofDate.

Parameters:
gd A valid GDate.
Returns:
NULL on error, otherwise a newly allocated, valid, QofDate.

Definition at line 750 of file qofdate.c.

00751 {
00752     QofDate * qd;
00753 
00754     g_return_val_if_fail (g_date_valid (date), NULL);
00755     qd = qof_date_new ();
00756     qd->qd_year = g_date_get_year (date);
00757     qd->qd_mon  = g_date_get_month (date);
00758     qd->qd_mday = g_date_get_day (date);
00759     qd = date_normalise (qd);
00760     return qd;
00761 }

QofDate* qof_date_from_qtime ( const QofTime *  qt  ) 

Return a QofDate in UTC from a QofTime.

Definition at line 850 of file qofdate.c.

00851 {
00852     QofDate *qd;
00853     gint leap_extra_secs;
00854 
00855     /* may not want to create a new time or date - it
00856     complicates memory management. */
00857     g_return_val_if_fail (qt, NULL);
00858     g_return_val_if_fail (qof_time_is_valid (qt), NULL);
00859     qd = qof_date_new ();
00860     leap_extra_secs = 0;
00861     setenv ("TZ", "GMT", 1);
00862     tzset();
00863     leap_extra_secs = extract_interval (qt);
00864     qof_date_offset (qt, leap_extra_secs, qd);
00865     qd->qd_nanosecs = qof_time_get_nanosecs (qt);
00866     qd->qd_is_dst = 0;
00867     qd->qd_zone = "GMT";
00868     qd->qd_gmt_off = 0L;
00869     if (!qof_date_valid(qd))
00870         return NULL;
00871     return qd;
00872 }

QofDate* qof_date_from_struct_tm ( const struct tm *  stm  ) 

Convert a struct tm to a QofDate.

Parameters:
stm A pointer to a valid struct tm.
Returns:
Newly allocated QofDate or NULL if tm is NULL.

Definition at line 679 of file qofdate.c.

00680 {
00681     QofDate *d;
00682 
00683     g_return_val_if_fail (stm, NULL);
00684     d = g_new0 (QofDate, 1);
00685     d->qd_sec  = stm->tm_sec;
00686     d->qd_min  = stm->tm_min;
00687     d->qd_hour = stm->tm_hour;
00688     d->qd_mday = stm->tm_mday;
00689     d->qd_mon  = stm->tm_mon + 1;
00690     d->qd_year = stm->tm_year + 1900;
00691     d->qd_wday = stm->tm_wday;
00692     d->qd_yday = stm->tm_yday;
00693     d->qd_is_dst = stm->tm_isdst;
00694     d->qd_gmt_off = stm->tm_gmtoff;
00695     d->qd_zone = stm->tm_zone;
00696     d->qd_valid = TRUE;
00697     d = date_normalise(d);
00698     return d;
00699 }

QofDate* qof_date_get_current ( void   ) 

create a new QofDate for the current date and time.

Definition at line 582 of file qofdate.c.

00583 {
00584     QofTime *qt;
00585     QofDate *qd;
00586 
00587     qt = qof_time_get_current ();
00588     qd = qof_date_from_qtime (qt);
00589     qof_time_free (qt);
00590     return qd;
00591 }

guint8 qof_date_get_mday ( gint  month,
gint64  year 
)

full range version of g_date_get_days_in_month

Parameters:
month Any valid QofDate qd_mon, 1 to 12.
year Any valid QofDate qd_year.
Returns:
0 on error, otherwise the number of days in the specified month, taking leap years into account.

Definition at line 183 of file qofdate.c.

00184 {
00185     g_return_val_if_fail (month !=  0, 0);
00186     g_return_val_if_fail (month <= 12, 0);
00187     g_return_val_if_fail (month >=  1, 0);
00188     g_return_val_if_fail (year  !=  0, 0);
00189     return days_in_months[qof_date_isleap (year)][month];
00190 }

guint16 qof_date_get_yday ( gint  mday,
gint  month,
gint64  year 
)

full range version of g_date_get_day_of_year

Parameters:
mday Any valid QofDate qd_mday, 1 to 31.
month Any valid QofDate qd_mon, 1 to 12.
year Any valid QofDate qd_year.
Returns:
0 if error, otherwise the day of the year, where Jan 1 is 1, the first day of the year.

Definition at line 167 of file qofdate.c.

00168 {
00169     guint8 leap;
00170 
00171     g_return_val_if_fail (mday  != 0, 0);
00172     g_return_val_if_fail (month != 0, 0);
00173     g_return_val_if_fail (month <= 12, 0);
00174     g_return_val_if_fail (month >= 1, 0);
00175     g_return_val_if_fail (year  != 0, 0);
00176     leap = qof_date_isleap (year);
00177     g_return_val_if_fail (mday <= 
00178         qof_date_get_mday (month, year), 0);
00179     return days_in_year[leap][month] + mday;
00180 }

gboolean qof_date_is_last_mday ( const QofDate *  qd  ) 

Checks if QofDate the last day of the month.

Parameters:
qd A valid QofDate.
Returns:
TRUE if qd_mday is the last day of qd_mon in qd_year, otherwise (or on error), FALSE.

Definition at line 193 of file qofdate.c.

00194 {
00195     g_return_val_if_fail (qd, FALSE);
00196     g_return_val_if_fail (qd->qd_valid, FALSE);
00197     return (qd->qd_mday == 
00198         qof_date_get_mday (qd->qd_mon, qd->qd_year));
00199 }

QofDate* qof_date_new ( void   ) 

create a new, empty, QofDate

Definition at line 573 of file qofdate.c.

00574 {
00575     QofDate *d;
00576 
00577     d = g_new0 (QofDate, 1);
00578     return d;
00579 }

QofDate* qof_date_new_dmy ( gint  day,
gint  month,
gint64  year 
)

create a new QofDate from basic calendar data.

Definition at line 594 of file qofdate.c.

00595 {
00596     QofDate *qd;
00597 
00598     qd = g_new0 (QofDate, 1);
00599     qd->qd_mday = day;
00600     qd->qd_mon  = month;
00601     qd->qd_year = year;
00602     if(!qof_date_valid (qd))
00603         return NULL;
00604     return qd;
00605 }

QofDate* qof_date_parse ( const gchar *  str,
QofDateFormat  df 
)

Convert a timestamp to a QofTime.

Safe for all dates within the range of QofDate.

Parameters:
str a timestamp created with one of the registered QofDateFormat formats.
df The registered QofDateFormat that produced the string.
Returns:
a newly allocated, valid, QofDate or NULL on error.

Definition at line 525 of file qofdate.c.

00526 {
00527     const gchar *format;
00528     QofDateError error;
00529     QofDate *date;
00530     gchar *check;
00531 
00532     check = NULL;
00533     error = ERR_NO_ERROR;
00534     date = qof_date_new ();
00535     format = qof_date_format_get_format (df);
00536     check = strptime_internal (str, format, date, &error);
00537     if (error != ERR_NO_ERROR)
00538     {
00539         qof_date_free (date);
00540         return NULL;
00541     }
00542     date = date_normalise (date);
00543     return date;
00544 }

gchar* qof_date_print ( const QofDate *  date,
QofDateFormat  df 
)

Convert a QofDate to a timestamp according to the specified date format.

Unlike qof_time_stamp_now, any supported QofDate can be converted in any registered QofDateFormat.

Parameters:
date A valid QofDate.
df a registered QofDateFormat to use to create the string.
Returns:
NULL on error, otherwise a string which should be freed when no longer needed.

Definition at line 547 of file qofdate.c.

00548 {
00549     size_t result;
00550     gchar temp[MAX_DATE_BUFFER];
00551     QofDateEntry *d;
00552 
00553     g_return_val_if_fail (QofDateInit, NULL);
00554     g_return_val_if_fail (date, NULL);
00555     g_return_val_if_fail (date->qd_valid, NULL);
00556     d = g_hash_table_lookup (DateFormatTable, 
00557         GINT_TO_POINTER (df));
00558     g_return_val_if_fail (d, NULL);
00559     temp[0] = '\1';
00560     result = strftime_case (FALSE, temp, MAX_DATE_BUFFER, 
00561         d->format, date, 1, date->qd_nanosecs);
00562     if (result == 0 && temp[0] != '\0')
00563     {
00564         PERR (" qof extended strftime failed");
00565         return NULL;
00566     }
00567     return g_strndup(temp, result);
00568 }

QofTime* qof_date_time_difference ( const QofDate *  date1,
const QofDate *  date2 
)

Calculate the QofTime between two QofDates

Definition at line 925 of file qofdate.c.

00927 {
00928     gint64 days;
00929     QofTime *secs;
00930 
00931     secs = qof_time_new ();
00932     days = days_between (date1->qd_year, date2->qd_year);
00933     qof_time_add_secs(secs, QOF_DAYS_TO_SEC(days));
00934     if (days >= 0)
00935     {
00936         /* positive value, add date2 secs, subtract date1 */
00937         qof_time_add_secs(secs, -1 *
00938                 (QOF_HOUR_TO_SEC(date1->qd_hour) -
00939                 QOF_MIN_TO_SEC(date1->qd_min) -
00940                 (date1->qd_sec)));
00941         qof_time_add_secs(secs,
00942                 QOF_HOUR_TO_SEC(date2->qd_hour) +
00943                 QOF_MIN_TO_SEC(date2->qd_min) +
00944                 (date2->qd_sec));
00945         qof_time_set_nanosecs(secs, 
00946             (date1->qd_nanosecs - date2->qd_nanosecs));
00947     }
00948     if (days < 0)
00949     {
00950         /* negative value*/
00951         qof_time_add_secs (secs, 
00952                 QOF_HOUR_TO_SEC(date1->qd_hour) -
00953                 QOF_MIN_TO_SEC(date1->qd_min) -
00954                 (date1->qd_sec));
00955         qof_time_add_secs (secs, -1 * 
00956                 (QOF_HOUR_TO_SEC(date2->qd_hour) +
00957                 QOF_MIN_TO_SEC(date2->qd_min) +
00958                 (date2->qd_sec)));
00959         qof_time_set_nanosecs(secs, 
00960             (date2->qd_nanosecs - date1->qd_nanosecs));
00961     }
00962     return secs;
00963 }

gboolean qof_date_to_gdate ( const QofDate *  qd,
GDate *  gd 
)

Convert a QofDate to a GDate.

Parameters:
qd a valid QofDate
gd a new GDate to store the converted value.
Returns:
FALSE on error, if the QofDate is out of range of a GDate or if QofDate is not valid, otherwise TRUE.

Definition at line 730 of file qofdate.c.

00731 {
00732     g_return_val_if_fail (qd, FALSE);
00733     g_return_val_if_fail (gd, FALSE);
00734     g_return_val_if_fail (qd->qd_valid, FALSE);
00735     if (qd->qd_year >= G_MAXUINT16)
00736     {
00737         PERR (" QofDate out of range of GDate");
00738         return FALSE;
00739     }
00740     if (!g_date_valid_dmy (qd->qd_mday, qd->qd_mon, qd->qd_year))
00741     {
00742         PERR (" GDate failed to allow day, month and/or year");
00743         return FALSE;
00744     }
00745     g_date_set_dmy (gd, qd->qd_mday, qd->qd_mon, qd->qd_year);
00746     return TRUE;
00747 }

QofTime* qof_date_to_qtime ( const QofDate *  qd  ) 

Return a valid QofTime from a valid QofDate.

Definition at line 892 of file qofdate.c.

00893 {
00894     QofTime *qt;
00895     QofTimeSecs c;
00896 
00897     g_return_val_if_fail (qd, NULL);
00898     g_return_val_if_fail (qd->qd_valid, NULL);
00899     c = 0;
00900     qt = NULL;
00901     if (qd->qd_year < 1970)
00902     {
00903         c = qd->qd_sec;
00904         c += QOF_MIN_TO_SEC(qd->qd_min);
00905         c += QOF_HOUR_TO_SEC(qd->qd_hour);
00906         c += QOF_DAYS_TO_SEC(qd->qd_yday);
00907         c -= QOF_DAYS_TO_SEC(days_between (1970, qd->qd_year));
00908         c -= qd->qd_gmt_off;
00909         qt = qof_time_set (c, qd->qd_nanosecs);
00910     }
00911     if (qd->qd_year >= 1970)
00912     {
00913         c = qd->qd_sec;
00914         c += QOF_MIN_TO_SEC(qd->qd_min);
00915         c += QOF_HOUR_TO_SEC(qd->qd_hour);
00916         c += QOF_DAYS_TO_SEC(qd->qd_yday);
00917         c += QOF_DAYS_TO_SEC(days_between (1970, qd->qd_year));
00918         c -= qd->qd_gmt_off;
00919         qt = qof_time_set (c, qd->qd_nanosecs);
00920     }
00921     return qt;
00922 }

gboolean qof_date_to_struct_tm ( const QofDate *  qt,
struct tm *  stm,
glong *  nanosecs 
)

Convert a QofDate to a struct tm.

Warning:
Check the return value - a QofDate has a larger range than a struct tm. The struct tm will be unchanged if a conversion would have been out of range.
Parameters:
qt A valid QofDate.
stm Pointer to a struct tm to store the result.
nanosecs Pointer to a glong to store the nanoseconds.
Returns:
FALSE on error or if the QofDate is invalid or out of the range of a struct tm, otherwise TRUE.

Definition at line 702 of file qofdate.c.

00704 {
00705     g_return_val_if_fail (qd, FALSE);
00706     g_return_val_if_fail (stm, FALSE);
00707     g_return_val_if_fail (qd->qd_valid, FALSE);
00708     if ((qd->qd_year > G_MAXINT) || (qd->qd_year < 1900))
00709     {
00710         PERR (" date too large for struct tm");
00711         return FALSE;
00712     }
00713     stm->tm_sec  = qd->qd_sec;
00714     stm->tm_min  = qd->qd_min;
00715     stm->tm_hour = qd->qd_hour;
00716     stm->tm_mday = qd->qd_mday;
00717     stm->tm_mon  = qd->qd_mon - 1;
00718     stm->tm_year = qd->qd_year - 1900;
00719     stm->tm_wday = qd->qd_wday;
00720     stm->tm_yday = qd->qd_yday;
00721     stm->tm_isdst = qd->qd_is_dst;
00722     stm->tm_gmtoff = qd->qd_gmt_off;
00723     stm->tm_zone = qd->qd_zone;
00724     if (nanosecs != NULL)
00725         *nanosecs = qd->qd_nanosecs;
00726     return TRUE;
00727 }

gboolean qof_date_valid ( QofDate *  date  ) 

Validate a QofDate.

If the QofDate is already valid, just returns TRUE. If the QofDate is not valid but can be normalised, the QofDate is normalised and the function returns TRUE. If the QofDate cannot be normalised, returns FALSE.

Year Zero does not exist in the Christian Era, the Gregorian calendar or the Julian calendar. A year zero does exist in ISO 8601:2004 and in the astronomical year numbering with a defined year zero equal to 1 BC, as well as in some Buddhist and Hindu lunar calendars.

In QofDate, 1BC is immediately followed by 1AD and months are numbered from 1 to 12, not from zero.

Normalising a QofDate tries to use sensible defaults:

Definition at line 616 of file qofdate.c.

00617 {
00618     g_return_val_if_fail (date, FALSE);
00619     date = date_normalise (date);
00620     if (date->qd_valid == FALSE)
00621     {
00622         PERR (" unknown QofDate error");
00623         return FALSE;
00624     }
00625     return TRUE;
00626 }

Generated on Thu Jan 31 22:50:27 2008 for QOF by  doxygen 1.5.4