qofdate.h File Reference

Detailed Description

64bit Date handling routines

Copyright 2006 Neil Williams <linux@codehelp.co.uk>

Definition in file qofdate.h.

#include "qoftime.h"

Go to the source code of this file.

Data Structures

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


#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)
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".
 Short ISO form. "%F".
 QOF UTC format, xsd:date compatible. QOF_UTC_DATE_FORMAT "%Y-%m-%dT%H:%M:%SZ".
#define QOF_DATE_FORMAT_ISO8601   6
 GNU locale default. "%x".
 Date and time for the current locale "%c".


typedef struct QofDate_s QofDate
typedef gint QofDateFormat


void qof_date_init (void)
 initialise the QofDate tables
void qof_date_close (void)
 close down the QofDate tables
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
QofDateqof_date_new (void)
QofDateqof_date_get_current (void)
QofDateqof_date_new_dmy (gint day, gint month, gint64 year)
void qof_date_free (QofDate *date)
QofTimeqof_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
QofDateqof_date_from_qtime (const QofTime *qt)
QofTimeqof_date_to_qtime (const QofDate *qd)
QofDateqof_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.
QofDateqof_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.

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.

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.
QofDateqof_date_parse (const gchar *str, QofDateFormat df)
 Convert a timestamp to a QofTime.

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