QOF
0.7.5
|
Files | |
file | qofdate.h |
64bit Date handling routines | |
Data Structures | |
struct | QofDate_s |
Full range replacement for struct tm. More... | |
Macros | |
#define | MAX_DATE_LENGTH 41 |
The maximum length of a string used for or created by dates. More... | |
#define | MAX_DATE_BUFFER 256 |
The maximum length of a QofDate buffer. More... | |
#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. More... | |
#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 |
Full range replacement for struct tm. More... | |
typedef gint | QofDateFormat |
Functions | |
void | qof_date_init (void) |
initialise the QofDate tables | |
void | qof_date_close (void) |
close down the QofDate tables | |
Default QofDate formats | |
#define | QOF_DATE_FORMAT_US 1 |
Continental US default. "%m/%d/%Y". More... | |
#define | QOF_DATE_FORMAT_UK 2 |
United Kingdom default. "%d/%m/%Y". More... | |
#define | QOF_DATE_FORMAT_CE 3 |
Contintental European default. "%d.%m.%Y". More... | |
#define | QOF_DATE_FORMAT_ISO 4 |
Short ISO form. "%F". More... | |
#define | QOF_DATE_FORMAT_UTC 5 |
QOF UTC format, xsd:date compatible. QOF_UTC_DATE_FORMAT "%Y-%m-%dT%H:%M:%SZ". More... | |
#define | QOF_DATE_FORMAT_ISO8601 6 |
#define | QOF_DATE_FORMAT_LOCALE 7 |
GNU locale default. "%x". More... | |
#define | QOF_DATE_FORMAT_CUSTOM 8 |
Date and time for the current locale "%c". More... | |
#define | DATE_FORMAT_LAST QOF_DATE_FORMAT_CUSTOM |
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. More... | |
const gchar * | qof_date_format_to_name (QofDateFormat format) |
Retrieve the shorthand name for the selected date format. More... | |
QofDateFormat | qof_date_format_from_name (const gchar *name) |
Returns the default date format for a known shorthand name. More... | |
gboolean | qof_date_format_set_name (const gchar *name, QofDateFormat format) |
Set a shorthand name for a custom date format. More... | |
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. More... | |
const gchar * | qof_date_format_get_format (QofDateFormat df) |
Retrieve the strftime format string for a registered date format. More... | |
gchar | qof_date_format_get_date_separator (QofDateFormat df) |
Return the field separator for the current date format. More... | |
gboolean | qof_date_format_set_date_separator (const gchar sep, QofDateFormat df) |
Set a locale-specific separator. More... | |
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. More... | |
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. More... | |
gboolean | qof_date_to_struct_tm (const QofDate *qt, struct tm *stm, glong *nanosecs) |
Convert a QofDate to a struct tm. More... | |
gboolean | qof_date_to_gdate (const QofDate *qd, GDate *gd) |
Convert a QofDate to a GDate. More... | |
QofDate * | qof_date_from_gdate (const GDate *gd) |
Create a QofDate from a GDate. More... | |
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. More... | |
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.
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.
For more information, see QofDate and locales.
| |
gchar * | qof_date_print (const QofDate *date, QofDateFormat df) |
Convert a QofDate to a timestamp according to the specified date format. More... | |
QofDate * | qof_date_parse (const gchar *str, QofDateFormat df) |
Convert a timestamp to a QofTime. More... | |
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.
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.
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.
#define DATE_FORMAT_LAST QOF_DATE_FORMAT_CUSTOM |
#define MAX_DATE_BUFFER 256 |
#define MAX_DATE_LENGTH 41 |
#define QOF_DATE_FORMAT_CE 3 |
#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
#define QOF_DATE_FORMAT_ISO 4 |
#define QOF_DATE_FORMAT_ISO8601 6 |
#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
#define QOF_DATE_FORMAT_UK 2 |
#define QOF_DATE_FORMAT_US 1 |
#define QOF_DATE_FORMAT_UTC 5 |
#define qof_date_isleap | ( | year | ) | ((year) % 4 == 0 && ((year) % 100 != 0 || (year) % 400 == 0)) |
#define QOF_DAYS_TO_SEC | ( | x | ) | (x * SECS_PER_DAY) |
#define QOF_HOUR_TO_SEC | ( | x | ) | (x * SECS_PER_HOUR) |
#define QOF_MIN_TO_SEC | ( | x | ) | (x * 60) |
#define QOF_MOD_DATE "qof-dates" |
#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()!
#define SECS_PER_DAY 86400 |
#define SECS_PER_HOUR 3600 |
Full range replacement for struct tm.
Based on struct tm but using signed integers. The year value uses a signed 64bit value to prevent overflows. (A glong is insufficient by two orders of magnitude.) To retain precision, a QofDate includes a nanoseconds value that can be used with a QofTime and a 64bit value for seconds.
Why is this a date? Because it represents a date, broken down into the component variables. A QofTime always (and only) relates to seconds, a QofDate always relates to how that number of seconds can be represented as a sequence of days, months, years etc.
typedef gint QofDateFormat |
gboolean qof_date_adddays | ( | QofDate * | qd, |
gint | days | ||
) |
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.
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. |
Definition at line 975 of file qofdate.c.
Check two QofDates for equality
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.
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. |
Definition at line 202 of file qofdate.c.
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.
name | Shorthand "name" of this format. |
Definition at line 385 of file qofdate.c.
gchar qof_date_format_get_date_separator | ( | QofDateFormat | df | ) |
Return the field separator for the current date format.
Definition at line 325 of file qofdate.c.
const gchar* qof_date_format_get_format | ( | QofDateFormat | df | ) |
gboolean qof_date_format_set_current | ( | QofDateFormat | df | ) |
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.
Definition at line 340 of file qofdate.c.
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.
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 |
Definition at line 269 of file qofdate.c.
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.
format | The QofDateFormat to lookup. |
Definition at line 254 of file qofdate.c.
void qof_date_free | ( | QofDate * | date | ) |
QofDate* qof_date_from_gdate | ( | const GDate * | gd | ) |
QofDate* qof_date_from_struct_tm | ( | const struct tm * | stm | ) |
QofDate* qof_date_get_current | ( | void | ) |
guint8 qof_date_get_mday | ( | gint | month, |
gint64 | year | ||
) |
guint16 qof_date_get_yday | ( | gint | mday, |
gint | month, | ||
gint64 | year | ||
) |
full range version of g_date_get_day_of_year
mday | Any valid QofDate qd_mday, 1 to 31. |
month | Any valid QofDate qd_mon, 1 to 12. |
year | Any valid QofDate qd_year. |
Definition at line 167 of file qofdate.c.
gboolean qof_date_is_last_mday | ( | const QofDate * | qd | ) |
QofDate* qof_date_new | ( | void | ) |
QofDate* qof_date_new_dmy | ( | gint | day, |
gint | month, | ||
gint64 | year | ||
) |
QofDate* qof_date_parse | ( | const gchar * | str, |
QofDateFormat | df | ||
) |
Convert a timestamp to a QofTime.
Safe for all dates within the range of QofDate.
str | a timestamp created with one of the registered QofDateFormat formats. |
df | The registered QofDateFormat that produced the string. |
Definition at line 525 of file qofdate.c.
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.
date | A valid QofDate. |
df | a registered QofDateFormat to use to create the string. |
Definition at line 547 of file qofdate.c.
gboolean qof_date_to_gdate | ( | const QofDate * | qd, |
GDate * | gd | ||
) |
gboolean qof_date_to_struct_tm | ( | const QofDate * | qt, |
struct tm * | stm, | ||
glong * | nanosecs | ||
) |
Convert a QofDate to a struct tm.
qt | A valid QofDate. |
stm | Pointer to a struct tm to store the result. |
nanosecs | Pointer to a glong to store the nanoseconds. |
Definition at line 702 of file qofdate.c.
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: