QOF
0.8.7
|
Modules | |
Date: 64bit UTC date handling. | |
Files | |
file | qoftime.h |
64bit UTC Time handling routines | |
Macros | |
#define | QOF_MOD_TIME "qof-time" |
#define | QOF_NSECS 1000000000 |
QofTime functions. | |
typedef struct QofTime64 | QofTime |
Use a 64-bit signed int QofTime. More... | |
typedef gint64 | QofTimeSecs |
Replacement for time_t. More... | |
void | qof_time_add_secs (QofTime *qt, QofTimeSecs secs) |
Add (or subtract) seconds from a QofTime. More... | |
QofTime * | qof_time_add_secs_copy (QofTime *qt, QofTimeSecs secs) |
Create a new QofTime, secs different to an original. More... | |
QofTime * | qof_time_new (void) |
create an empty QofTime More... | |
QofTime * | qof_time_copy (const QofTime *qt) |
Create a copy of a QofTime. More... | |
void | qof_time_free (QofTime *qt) |
Free a QofTime when no longer required. | |
void | qof_time_set_secs (QofTime *time, QofTimeSecs secs) |
Set the number of seconds. More... | |
void | qof_time_set_nanosecs (QofTime *time, glong nano) |
Set the number of seconds. More... | |
QofTimeSecs | qof_time_get_secs (const QofTime *time) |
Get the number of seconds. More... | |
glong | qof_time_get_nanosecs (const QofTime *time) |
Get the number of seconds. More... | |
QofTime manipulation | |
gboolean | qof_time_equal (const QofTime *ta, const QofTime *tb) |
gint | qof_time_cmp (const QofTime *ta, const QofTime *tb) |
QofTime * | qof_time_diff (const QofTime *ta, const QofTime *tb) |
difference between two QofTimes. More... | |
QofTime * | qof_time_abs (QofTime *t) |
gboolean | qof_time_is_valid (const QofTime *qt) |
QofTime * | qof_time_from_time_t (time_t t, glong nanosecs) |
QofTime * | qof_time_set (QofTimeSecs t, glong nanosecs) |
gboolean | qof_time_to_time_t (QofTime *ts, time_t *t, glong *nanosecs) |
QofTime * | qof_time_from_tm (struct tm *tm, glong nanosecs) |
Convert a broken-down into a QofTime. More... | |
gboolean | qof_time_to_gtimeval (QofTime *qt, GTimeVal *gtv) |
Convert a QofTime to a GTimeVal. More... | |
void | qof_time_from_gtimeval (QofTime *qt, GTimeVal *gtv) |
Convert a QofTime to a GTimeVal. More... | |
QofTime * | qof_time_dmy_to_time (guint8 day, guint8 month, guint16 year) |
gboolean | qof_time_to_dmy (QofTime *t, guint8 *day, guint8 *month, guint16 *year) |
GDate * | qof_time_to_gdate (QofTime *time) |
Convert QofTime to GDate. More... | |
QofTime * | qof_time_from_gdate (GDate *date) |
Convert a GDate to a QofTime. More... | |
Time Start/End Adjustment routines | |
Given a time value, adjust it to be the beginning or end of that day. | |
GTimeVal * | qof_time_get_current_start (void) |
QofTime * | qof_time_get_current (void) |
Get the current QofTime. More... | |
gboolean | qof_time_set_day_middle (QofTime *t) |
set the given QofTime to midday on the same day. More... | |
gboolean | qof_time_set_day_start (QofTime *time) |
set the given QofTime to the first second of that day. More... | |
gboolean | qof_time_set_day_end (QofTime *time) |
set the given QofTime to the last second of that day. More... | |
guint8 | qof_time_last_mday (QofTime *ts) |
Today's Date | |
QofTime * | qof_time_get_today_start (void) |
QofTime * | qof_time_get_today_end (void) |
gchar * | qof_time_stamp_now (void) |
Universal time is the 'one true time' that is independent of one's location on planet Earth. It is measured in seconds from midnight January 1, 1970 in localtime-Greenwich (GMT).
QofTime uses a signed 64bit integer to count the seconds, which differs from GTimeVal (32bit) and most other time handling routines (which only count from the epoch).
A QofTime where qt_sec == +1 therefore represents one second after midnight on 1st January 1970 - the epoch. Negative values of QofTime->qt_sec represent times before one second before midnight on 31st December 1969. Support for times before 1st Jan Year 1 are included.
QofTime is defined as 64bit on all systems and will not overflow until the year 292,471,208,679 (not counting leap years). i.e. approx. 9223372036854775808 / (60*60*24*365). This also means that some values of QofTime cannot be converted to a time_t on systems where time_t is defined as 32bit.
QofTime is not directly equivalent to GTimeVal - a QofTime can go further into the future. However, within the range supported by GTimeVal and GTime (a 32bit integer), the value of QofTime->qt_sec is always identical to GTimeVal->tv_sec.
The use of signed values and the handling of times prior to the epoch means that a QofTime with zero values can no longer be assumed to be invalid or used alone to denote an init value. QofTime is therefore an opaque type. QofTime and QofDate functions set and check QofTime validity as needed.
QofTime is always and only concerned with seconds. All date or calendar handling is performed using QofDate.
#define QOF_NSECS 1000000000 |
typedef struct QofTime64 QofTime |
Use a 64-bit signed int QofTime.
QofTime is a lot like the unix 'struct timespec' except that it uses a 64-bit signed int to store the seconds. This should adequately cover dates in the distant future as well as the distant past, as long as these are not more than a couple of dozen times the age of the universe. Values of this type can range from -9,223,372,036,854,775,808 to 9,223,372,036,854,775,807.
typedef gint64 QofTimeSecs |
void qof_time_add_secs | ( | QofTime * | qt, |
QofTimeSecs | secs | ||
) |
Add (or subtract) seconds from a QofTime.
qt | A valid QofTime. |
secs | A 64bit number of seconds to add (or subtract if secs is negative) from the QofTime. |
The QofTime is altered in place. To assign the new value to a new QofTime, use qof_time_add_secs_copy
QofTime* qof_time_add_secs_copy | ( | QofTime * | qt, |
QofTimeSecs | secs | ||
) |
Create a new QofTime, secs different to an original.
qt | a valid QofTime to use as the base. |
secs | a 64bit number of seconds to add (or subtract if secs is negative) from the original to create the copy. |
Definition at line 73 of file qoftime.c.
QofTime* qof_time_dmy_to_time | ( | guint8 | day, |
guint8 | month, | ||
guint16 | year | ||
) |
Convert a day, month, and year to a QofTime.
Limited to the range of a GDate.
day | day of month, 1 to 31. |
month | Decimal number of month, 1 to 12. |
year | signed short containing the year. This value is safe for all dates within the range of a GDate. |
Definition at line 457 of file qoftime.c.
strict equality
QofTime* qof_time_from_gdate | ( | GDate * | date | ) |
Convert a GDate to a QofTime.
date | The GDate to convert |
Definition at line 312 of file qoftime.c.
void qof_time_from_gtimeval | ( | QofTime * | qt, |
GTimeVal * | gtv | ||
) |
QofTime* qof_time_from_time_t | ( | time_t | t, |
glong | nanosecs | ||
) |
Turns a time_t into a QofTime
t | integer seconds since the epoch. |
nanosecs | number of nanoseconds |
Definition at line 231 of file qoftime.c.
QofTime* qof_time_from_tm | ( | struct tm * | tm, |
glong | nanosecs | ||
) |
Convert a broken-down into a QofTime.
struct tm broken-down time does not support fractions of a second.
Conversion of a QofTime to a struct tm is not supported because of the inherent data loss.
tm | broken-down time structure. |
nanosecs | Fractions of a second. |
Definition at line 258 of file qoftime.c.
QofTime* qof_time_get_current | ( | void | ) |
Get the current QofTime.
Current implementations can only provide a long number of seconds (max: 2,147,483,647) and the number of microseconds (10^-6) not nanoseconds (10^-9).
Definition at line 362 of file qoftime.c.
GTimeVal* qof_time_get_current_start | ( | void | ) |
glong qof_time_get_nanosecs | ( | const QofTime * | time | ) |
Get the number of seconds.
time | pointer to a QofTime time, created with qof_time_new(); |
QofTimeSecs qof_time_get_secs | ( | const QofTime * | time | ) |
Get the number of seconds.
time | pointer to a QofTime time, created with qof_time_new(); |
QofTime* qof_time_get_today_end | ( | void | ) |
QofTime* qof_time_get_today_start | ( | void | ) |
return a QofTime of the first second of today.
Definition at line 402 of file qoftime.c.
guint8 qof_time_last_mday | ( | QofTime * | ts | ) |
Return the number of the last day of the month for the value contained in the QofTime.
Only usable within the range of dates supported by GDate.
Definition at line 423 of file qoftime.c.
QofTime* qof_time_new | ( | void | ) |
QofTime* qof_time_set | ( | QofTimeSecs | t, |
glong | nanosecs | ||
) |
Turns a QofTimeSecs into a QofTime
An alternative call that combines qof_time_set_secs and qof_time_set_nanosecs.
t | 64bit integer number of seconds (t == 0 at the epoch, use negative values for previous times.) |
nanosecs | number of nanoseconds |
Definition at line 210 of file qoftime.c.
gboolean qof_time_set_day_end | ( | QofTime * | time | ) |
set the given QofTime to the last second of that day.
This routine is limited to dates supported by GDate.
Definition at line 327 of file qoftime.c.
gboolean qof_time_set_day_middle | ( | QofTime * | t | ) |
set the given QofTime to midday on the same day.
This routine is limited to dates supported by GDate.
Definition at line 336 of file qoftime.c.
gboolean qof_time_set_day_start | ( | QofTime * | time | ) |
set the given QofTime to the first second of that day.
This routine is limited to dates supported by GDate.
Definition at line 374 of file qoftime.c.
void qof_time_set_nanosecs | ( | QofTime * | time, |
glong | nano | ||
) |
Set the number of seconds.
time | pointer to a QofTime time, created with qof_time_new(); |
nano | long int number of nanoseconds. |
void qof_time_set_secs | ( | QofTime * | time, |
QofTimeSecs | secs | ||
) |
Set the number of seconds.
time | pointer to a QofTime time, created with qof_time_new(); |
secs | Signed 64bit number of seconds where zero represents midnight at the epoch: 00:00:00 01/01/1970. |
gchar* qof_time_stamp_now | ( | void | ) |
Return the current time in UTC textual format.
Definition at line 469 of file qoftime.c.
gboolean qof_time_to_dmy | ( | QofTime * | t, |
guint8 * | day, | ||
guint8 * | month, | ||
guint16 * | year | ||
) |
Convert a QofTime to day, month and year.
Usable for all QofTime values within the range of GDate.
t | The QofTime to use. |
day | Pointer to a integer to hold day of month, 1 to 31. |
month | Decimal number of month, 1 to 12. |
year | signed short containing the year. This value is safe for all dates within the range of a GDate. |
Definition at line 439 of file qoftime.c.
GDate* qof_time_to_gdate | ( | QofTime * | time | ) |
Convert QofTime to GDate.
time | The QofTime to convert |
Definition at line 299 of file qoftime.c.
gboolean qof_time_to_gtimeval | ( | QofTime * | qt, |
GTimeVal * | gtv | ||
) |
gboolean qof_time_to_time_t | ( | QofTime * | ts, |
time_t * | t, | ||
glong * | nanosecs | ||
) |
Tries to turn a QofTime into a time_t
ts | A 64bit QofTime. |
t | pointer to a time_t to store result. |
nanosecs | pointer to a variable to store the nanoseconds, if any, from the QofTime conversion. |
Definition at line 237 of file qoftime.c.