|
file | qoftime.h |
| 64bit UTC Time handling routines
|
|
|
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...
|
|
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.
- Note
- GTime is defined to always be a 32bit integer, unlike time_t which may be 64bit on some systems. Therefore, GTime will overflow in the year 2038. (A 32bit time_t will overflow at 2038-01-19T03:14:07Z to be precise, at which point it will likely wrap around to 20:45:52 UTC on December 13, 1901.)
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.
- Note
- Most conversions of QofTime can cause a loss of data. GDate contains no time data, time_t varies between platforms and struct tm does not include fractions of a second. Avoid converting back and forth between time formats. All conversions between QofTime and time_t, struct tm or other 32bit time implementations must check the return value of QofTime functions to ensure the QofTime was within the range supported by the 32bit type.
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.
- Since
- v0.7.0
#define QOF_MOD_TIME "qof-time" |
log module name
Definition at line 94 of file qoftime.h.
#define QOF_NSECS 1000000000 |
number of nanoseconds per second. 10^9
Definition at line 105 of file qoftime.h.
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.
Definition at line 120 of file qoftime.h.
Replacement for time_t.
Prevents overflows by making all values 64bit on all platforms.
(time_t will overflow on 32bit systems in 2038)
Definition at line 129 of file qoftime.h.
Normalise a QofTime to an absolute value.
- Parameters
-
t | the QofTime to normalise. |
- Returns
- the normalised QofTime t.
Definition at line 196 of file qoftime.c.
198 g_return_val_if_fail (qt, NULL);
199 return time_normalize (qt);
Add (or subtract) seconds from a QofTime.
- Parameters
-
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
Definition at line 65 of file qoftime.c.
67 g_return_if_fail (qt);
68 g_return_if_fail (qt->valid);
Create a new QofTime, secs different to an original.
- Parameters
-
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. |
- Returns
- a new, valid, QofTime that is secs different to the original.
Definition at line 73 of file qoftime.c.
77 g_return_val_if_fail (qt, NULL);
78 g_return_val_if_fail (qt->valid, NULL);
comparison: if (ta < tb) -1; else if (ta > tb) 1; else 0;
Definition at line 165 of file qoftime.c.
167 g_return_val_if_fail (ta->valid && tb->valid, -1);
170 if (ta->qt_sec < tb->qt_sec)
172 if (ta->qt_sec > tb->qt_sec)
174 if (ta->qt_nsec < tb->qt_nsec)
176 if (ta->qt_nsec > tb->qt_nsec)
Create a copy of a QofTime.
- Parameters
-
qt | A valid QofTime to copy. |
- Returns
- NULL on error, otherwise a new, valid and normalised QofTime set to the same time as the original.
Definition at line 223 of file qoftime.c.
225 g_return_val_if_fail (qt, NULL);
226 g_return_val_if_fail (qt->valid, NULL);
difference between two QofTimes.
Results are normalised ie qt_sec and qt_nsec of the result have the same size abs(result.qt_nsec) <= 1000000000
- Returns
- a new QofTime of the difference. The caller must free the difference QofTime when done.
Definition at line 182 of file qoftime.c.
186 g_return_val_if_fail (ta->valid && tb->valid, NULL);
188 retval->qt_sec = ta->qt_sec - tb->qt_sec;
189 retval->qt_nsec = ta->qt_nsec - tb->qt_nsec;
190 retval->valid = TRUE;
191 time_normalize (retval);
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.
- Parameters
-
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. |
- Returns
- NULL on error, otherwise the converted QofTime.
Definition at line 457 of file qoftime.c.
462 g_return_val_if_fail (g_date_valid_dmy (day, month, year), NULL);
463 d = g_date_new_dmy (day, month, year);
strict equality
Definition at line 148 of file qoftime.c.
156 g_return_val_if_fail (ta->valid && tb->valid, FALSE);
157 if (ta->qt_sec != tb->qt_sec)
159 if (ta->qt_nsec != tb->qt_nsec)
QofTime* qof_time_from_gdate |
( |
GDate * |
date | ) |
|
Convert a GDate to a QofTime.
- Warning
- the QofTime is set to the first second of the particular day, UTC.
- Parameters
-
- Returns
- a valid QofTime or NULL on error.
Definition at line 312 of file qoftime.c.
318 g_return_val_if_fail (date, NULL);
319 g_date_to_struct_tm (date, >m);
void qof_time_from_gtimeval |
( |
QofTime * |
qt, |
|
|
GTimeVal * |
gtv |
|
) |
| |
Convert a QofTime to a GTimeVal.
Safe for all dates supported by a valid GTimeVal.
- Parameters
-
qt | QofTime to set. |
gtv | GTimeVal to convert |
Definition at line 290 of file qoftime.c.
293 qt->qt_nsec = gtv->tv_usec * 1000;
QofTime* qof_time_from_time_t |
( |
time_t |
t, |
|
|
glong |
nanosecs |
|
) |
| |
Turns a time_t into a QofTime
- Note
- On some platforms, time_t is only 32bit. Use QofTimeSecs instead.
- Parameters
-
t | integer seconds since the epoch. |
nanosecs | number of nanoseconds |
- Returns
- pointer to a newly allocated QofTime.
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.
- Parameters
-
tm | broken-down time structure. |
nanosecs | Fractions of a second. |
- Returns
- a newly allocated QofTime or NULL on error.
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).
- Returns
- a newly allocated, valid, QofTime of the current time.
- Todo:
- use to replace qof_time_get_current_start
Definition at line 362 of file qoftime.c.
368 g_get_current_time (&gnow);
GTimeVal* qof_time_get_current_start |
( |
void |
| ) |
|
- Todo:
- move to a private header; used by qofdate.c and test-date.c
- Todo:
- replace with QofDate
Definition at line 345 of file qoftime.c.
351 current = g_new0 (GTimeVal, 1);
352 g_get_current_time (current);
354 tm = *gmtime_r (¤t->tv_sec, &tm);
355 current->tv_sec -= tm.tm_sec;
356 current->tv_sec -= tm.tm_min * 60;
357 current->tv_sec -= tm.tm_hour * 60 * 60;
glong qof_time_get_nanosecs |
( |
const QofTime * |
time | ) |
|
Get the number of seconds.
- Parameters
-
- Returns
- long int number of nanoseconds.
Definition at line 141 of file qoftime.c.
143 g_return_val_if_fail (qt->valid == TRUE, 0);
Get the number of seconds.
- Parameters
-
- Returns
- Signed 64bit number of seconds.
Definition at line 133 of file qoftime.c.
135 g_return_val_if_fail (qt, 0);
136 g_return_val_if_fail (qt->valid == TRUE, 0);
QofTime* qof_time_get_today_end |
( |
void |
| ) |
|
returns a QofTime of the last second of today.
Definition at line 413 of file qoftime.c.
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.
- Todo:
- remove GDate limits.
Only usable within the range of dates supported by GDate.
- Returns
- zero on error.
Definition at line 423 of file qoftime.c.
429 g_return_val_if_fail (qt, 0);
433 m = g_date_get_month (d);
434 y = g_date_get_year (d);
435 return g_date_get_days_in_month (m, y);
create an empty QofTime
The QofTime becomes the property of the caller and needs to be freed with qof_time_free when no longer required.
Definition at line 46 of file qoftime.c.
Turns a QofTimeSecs into a QofTime
An alternative call that combines qof_time_set_secs and qof_time_set_nanosecs.
- Parameters
-
t | 64bit integer number of seconds (t == 0 at the epoch, use negative values for previous times.) |
nanosecs | number of nanoseconds |
- Returns
- pointer to a newly allocated (and validated) QofTime.
Definition at line 210 of file qoftime.c.
216 qt->qt_nsec = nanosecs;
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.
- Todo:
- remove GDate limits.
- Returns
- FALSE on error, otherwise TRUE.
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.
- Todo:
- remove GDate limits.
- Returns
- FALSE on error, otherwise TRUE
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.
- Todo:
- remove GDate limits.
- Returns
- FALSE on error, otherwise TRUE.
Definition at line 374 of file qoftime.c.
379 g_return_val_if_fail (qt, FALSE);
void qof_time_set_nanosecs |
( |
QofTime * |
time, |
|
|
glong |
nano |
|
) |
| |
Set the number of seconds.
- Parameters
-
time | pointer to a QofTime time, created with qof_time_new(); |
nano | long int number of nanoseconds. |
Definition at line 125 of file qoftime.c.
Set the number of seconds.
- Parameters
-
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. |
Definition at line 117 of file qoftime.c.
gchar* qof_time_stamp_now |
( |
void |
| ) |
|
Return the current time in UTC textual format.
- Returns
- A pointer to the generated string.
- Note
- The caller owns this buffer and must free it when done.
Definition at line 469 of file qoftime.c.
479 qtm = *gmtime_r (&t, &qtm);
482 if (len == 0 && test[0] !=
'\0')
484 LEAVE (
" strftime failed.");
488 return g_strdup (test);
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.
- Todo:
- Remove GDate limits and use QofDate.
- Parameters
-
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. |
- Returns
- FALSE if the time cannot be converted, otherwise TRUE.
Definition at line 439 of file qoftime.c.
448 *day = g_date_get_day (d);
450 *month = g_date_get_month (d);
452 *year = g_date_get_year (d);
GDate* qof_time_to_gdate |
( |
QofTime * |
time | ) |
|
Convert QofTime to GDate.
- Warning
- The GDate will lose time-related data within the QofTime. i.e. converting a QofTime to a GDate and back to a QofTime causes the final QofTime to be set to the start of the particular day, UTC.
- Parameters
-
time | The QofTime to convert |
- Returns
- a valid GDate or NULL on error.
Definition at line 299 of file qoftime.c.
306 if (g_date_valid (d))
gboolean qof_time_to_gtimeval |
( |
QofTime * |
qt, |
|
|
GTimeVal * |
gtv |
|
) |
| |
Convert a QofTime to a GTimeVal.
Safe for dates between 1st January Year 1 and 31st December 2037.
- Parameters
-
qt | QofTime to convert |
gtv | GTimeVal to set, left unchanged if an error occurs. |
- Returns
- TRUE on success, FALSE on error.
Definition at line 272 of file qoftime.c.
276 PERR (
" invalid QofTime passed");
279 if (qt->qt_sec > G_MAXLONG)
281 PERR (
" QofTime out of range for GTimeVal");
284 gtv->tv_sec = (glong) qt->qt_sec;
285 gtv->tv_usec = qt->qt_nsec;
gboolean qof_time_to_time_t |
( |
QofTime * |
ts, |
|
|
time_t * |
t, |
|
|
glong * |
nanosecs |
|
) |
| |
Tries to turn a QofTime into a time_t
- Note
- CARE: QofTime is 64bit, time_t might be 32bit. GDate has a wider range. time_t may be defined as an integer on some platforms, causing data loss.
- Parameters
-
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. |
- Returns
- FALSE on error or if the QofTime is before the epoch or outside the range of time_t, otherwise TRUE.
Definition at line 237 of file qoftime.c.
245 *nanosecs = qt->qt_nsec;
247 if ((
sizeof (qt->qt_sec) > sizeof (time_t))
248 && (qt->qt_sec > G_MAXINT32))
250 PERR (
" QofTime too large for time_t on this platform.");