QOF  0.7.5
QofDate_s Struct Reference

Full range replacement for struct tm. More...

#include <qofdate.h>

Data Fields

glong qd_nanosecs
gint64 qd_sec
glong qd_min
 Signed replacement of struct tm.tm_min.
glong qd_hour
 Signed replacement of struct tm.tm_hour.
glong qd_mday
 Signed replacement of struct tm.tm_mday.
glong qd_mon
 Signed replacement of struct tm.tm_mon.
gint64 qd_year
 Extended version to cope with full range of dates.
gshort qd_wday
gshort qd_yday
gshort qd_is_dst
glong qd_gmt_off
 Calculated value based on struct tm.tm_gmtoff.
const gchar * qd_zone
 Calculated value based on struct tm.tm_zone.
gboolean qd_valid
 If the QofDate is valid or merely initialised.

Detailed Description

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.

Note:
All QofDate values can be negative. The normalising cascade handles rollovers. e.g. If a QofDate qd_min value is 5 initially, setting qd_sec to 68 causes qd_sec to actually hold the value 8 and qd_min to hold the value 6. Alternatively, setting qd_sec to -64 with qd_min set to 5 causes qd_sec to hold the value 56 and qd_min to hold the value 3.
Todo:
check - years work like this, days don't!! Only qd_year retains a negative value once set. Adding one year to a negative QofDate causes the QofDate to be set to one year further into the past. This follows the same pattern as typical BC dates: the 1st of May 501BC is further into the past than the 5th of May 500BC.

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.

Note:
Although values can be set directly, qof_date_valid should be called before attempting to manipulate a QofDate.
Todo:
Reorganise the qof_time_* functions to reflect this statement. qof_time_set_day_end should be qof_date_set_day_end and the various qof_date_time functions need to be reviewed.

Definition at line 138 of file qofdate.h.


Field Documentation

Calculated value based on struct tm.tm_gmtoff.

Note:
qd_gmt_off WILL be overridden to UTC when the QofDate is validated. This can be used to convert a localtime to UTC - set the value from struct tm.tm_gmtoff for the localtime and validate the QofDate to get UTC.

Definition at line 201 of file qofdate.h.

Signed replacement of struct tm.tm_hour.

Setting qd_hour to a negative value adjusts the other date values when the QofDate is validated and normalised to create an earlier time.

Definition at line 157 of file qofdate.h.

Signed replacement of struct tm.tm_isdst. qd_is_dst is a calculated value and will be set to UTC when the QofDate is validated.

Definition at line 193 of file qofdate.h.

Signed replacement of struct tm.tm_mday.

Setting qd_mday to a negative value adjusts the other date values when the QofDate is validated and normalised to create an earlier time.

Definition at line 164 of file qofdate.h.

Signed replacement of struct tm.tm_min.

Setting qd_min to a negative value adjusts the other date values when the QofDate is validated and normalised to create an earlier time.

Definition at line 150 of file qofdate.h.

Signed replacement of struct tm.tm_mon.

Setting qd_mon to a negative value adjusts the other date values when the QofDate is validated and normalised to create an earlier time.

Definition at line 171 of file qofdate.h.

From QofTime

Definition at line 141 of file qofdate.h.

Enlarged replacement of struct tm.tm_sec

Definition at line 143 of file qofdate.h.

If the QofDate is valid or merely initialised.

Some QofDate values are invalid when initialised to zero (e.g. qm_mday). Avoid setting this value manually (just because it can be done, does not mean doing it is a good idea). Use qof_date_valid to ensure that values like qd_wday, qd_yday, qd_gmt_off and qd_is_dst are set correctly.

Definition at line 217 of file qofdate.h.

Signed replacement of struct tm.tm_wday. qd_wday is a calculated value and will be overridden when the QofDate is validated.

Definition at line 185 of file qofdate.h.

Signed replacement of struct tm.tm_yday. qd_yday is a calculated value and will be overridden when the QofDate is validated.

Definition at line 189 of file qofdate.h.

Extended version to cope with full range of dates.

Warning:
QofDate does not use 1900 or 1970 as a base, all years in QofDate are true values. qd_year == 0 is the only invalid value (validation converts 0 to 1BC). A value of qd_year == 106 means 106AD, not 2006: A value of qd_year == 2006 means 2006, not 3906. Use negative values for dates in 1BC or earlier: qd_year == -43 means 43BC.

Definition at line 181 of file qofdate.h.

const gchar* QofDate_s::qd_zone

Calculated value based on struct tm.tm_zone.

Note:
qd_zone WILL be overridden to "GMT" when the QofDate is validated. This can be used to convert a localtime to UTC - set the value from struct tm.tm_zone for the localtime and validate the QofDate to get UTC.

Definition at line 208 of file qofdate.h.


The documentation for this struct was generated from the following file: