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.
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.
Files | |
file | qoftime.h |
64bit UTC Time handling routines | |
Modules | |
Date: 64bit UTC date handling. | |
Data Structures | |
struct | timespec64 |
QofTime functions. | |
typedef QofTime64 | QofTime |
Use a 64-bit signed int QofTime. | |
typedef gint64 | QofTimeSecs |
Replacement for time_t. | |
void | qof_time_add_secs (QofTime *qt, QofTimeSecs secs) |
Add (or subtract) seconds from a QofTime. | |
QofTime * | qof_time_add_secs_copy (QofTime *qt, QofTimeSecs secs) |
Create a new QofTime, secs different to an original. | |
QofTime * | qof_time_new (void) |
create an empty QofTime | |
QofTime * | qof_time_copy (const QofTime *qt) |
Create a copy of a QofTime. | |
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. | |
void | qof_time_set_nanosecs (QofTime *time, glong nano) |
Set the number of seconds. | |
QofTimeSecs | qof_time_get_secs (const QofTime *time) |
Get the number of seconds. | |
glong | qof_time_get_nanosecs (const QofTime *time) |
Get the number of seconds. | |
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. | |
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. | |
gboolean | qof_time_to_gtimeval (QofTime *qt, GTimeVal *gtv) |
Convert a QofTime to a GTimeVal. | |
void | qof_time_from_gtimeval (QofTime *qt, GTimeVal *gtv) |
Convert a QofTime to a GTimeVal. | |
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. | |
QofTime * | qof_time_from_gdate (GDate *date) |
Convert a GDate to a QofTime. | |
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. | |
gboolean | qof_time_set_day_middle (QofTime *t) |
set the given QofTime to midday on the same day. | |
gboolean | qof_time_set_day_start (QofTime *time) |
set the given QofTime to the first second of that day. | |
gboolean | qof_time_set_day_end (QofTime *time) |
set the given QofTime to the last second of that day. | |
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) |
Defines | |
#define | QOF_MOD_TIME "qof-time" |
#define | QOF_NSECS 1000000000 |
Typedefs | |
typedef timespec64 | Timespec |
#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. |
Definition at line 64 of file qoftime.c.
00065 { 00066 g_return_if_fail (qt); 00067 g_return_if_fail (qt->valid); 00068 qt->qt_sec += secs; 00069 }
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 72 of file qoftime.c.
00073 { 00074 QofTime *copy; 00075 00076 g_return_val_if_fail (qt, NULL); 00077 g_return_val_if_fail (qt->valid, NULL); 00078 copy = qof_time_copy (qt); 00079 copy->qt_sec += secs; 00080 return copy; 00081 }
comparison: if (ta < tb) -1; else if (ta > tb) 1; else 0;
Definition at line 164 of file qoftime.c.
00165 { 00166 g_return_val_if_fail (ta->valid && tb->valid, -1); 00167 if (ta == tb) 00168 return 0; 00169 if (ta->qt_sec < tb->qt_sec) 00170 return -1; 00171 if (ta->qt_sec > tb->qt_sec) 00172 return 1; 00173 if (ta->qt_nsec < tb->qt_nsec) 00174 return -1; 00175 if (ta->qt_nsec > tb->qt_nsec) 00176 return 1; 00177 return 0; 00178 }
Create a copy of a QofTime.
qt | A valid QofTime to copy. |
Definition at line 222 of file qoftime.c.
00223 { 00224 g_return_val_if_fail (qt, NULL); 00225 g_return_val_if_fail (qt->valid, NULL); 00226 return qof_time_set (qt->qt_sec, qt->qt_nsec); 00227 }
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
Definition at line 181 of file qoftime.c.
00182 { 00183 QofTime *retval; 00184 00185 g_return_val_if_fail (ta->valid && tb->valid, NULL); 00186 retval = g_new0 (QofTime, 1); 00187 retval->qt_sec = ta->qt_sec - tb->qt_sec; 00188 retval->qt_nsec = ta->qt_nsec - tb->qt_nsec; 00189 retval->valid = TRUE; 00190 time_normalize (retval); 00191 return retval; 00192 }
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 481 of file qoftime.c.
00482 { 00483 GDate *d; 00484 QofTime *qt; 00485 00486 g_return_val_if_fail (g_date_valid_dmy (day, month, year), NULL); 00487 d = g_date_new_dmy (day, month, year); 00488 qt = qof_time_from_gdate (d); 00489 return qt; 00490 }
strict equality
Definition at line 147 of file qoftime.c.
00148 { 00149 if (ta == tb) 00150 return TRUE; 00151 if (!ta) 00152 return FALSE; 00153 if (!tb) 00154 return FALSE; 00155 g_return_val_if_fail (ta->valid && tb->valid, FALSE); 00156 if (ta->qt_sec != tb->qt_sec) 00157 return FALSE; 00158 if (ta->qt_nsec != tb->qt_nsec) 00159 return FALSE; 00160 return TRUE; 00161 }
QofTime* qof_time_from_gdate | ( | GDate * | date | ) |
Convert a GDate to a QofTime.
date | The GDate to convert |
Definition at line 327 of file qoftime.c.
00328 { 00329 GTimeVal *current, from_date; 00330 GDate *now; 00331 gint days_between; 00332 gint64 secs_between; 00333 QofTime *qt; 00334 00335 g_return_val_if_fail (date, NULL); 00336 current = qof_time_get_current_start (); 00337 now = g_date_new (); 00338 g_date_set_time_val (now, current); 00339 /* if date is in the future, days_between is negative */ 00340 days_between = g_date_days_between (date, now); 00341 qt = qof_time_new (); 00342 qof_time_from_gtimeval (qt, &from_date); 00343 secs_between = days_between * SECS_PER_DAY; 00344 qof_time_set_secs (qt, current->tv_sec - secs_between); 00345 qof_time_set_nanosecs (qt, 0); 00346 return qt; 00347 }
void qof_time_from_gtimeval | ( | QofTime * | qt, | |
GTimeVal * | gtv | |||
) |
Convert a QofTime to a GTimeVal.
Safe for all dates supported by a valid GTimeVal.
qt | QofTime to set. | |
gtv | GTimeVal to convert |
Definition at line 289 of file qoftime.c.
00290 { 00291 qt->qt_sec = (QofTimeSecs) gtv->tv_sec; 00292 qt->qt_nsec = gtv->tv_usec * 1000; 00293 qt->valid = TRUE; 00294 time_normalize (qt); 00295 }
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 230 of file qoftime.c.
00231 { 00232 return qof_time_set (t, nanosecs); 00233 }
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 257 of file qoftime.c.
00258 { 00259 QofDate *qd; 00260 QofTime *qt; 00261 00262 /* avoids use of gmtime_r and therefore time_t */ 00263 qd = qof_date_from_struct_tm (qtm); 00264 qd->qd_nanosecs = nanosecs; 00265 qt = qof_date_to_qtime (qd); 00266 qof_date_free (qd); 00267 return qt; 00268 }
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 385 of file qoftime.c.
00386 { 00387 QofTime *now; 00388 GTimeVal gnow; 00389 00390 now = qof_time_new (); 00391 g_get_current_time (&gnow); 00392 qof_time_from_gtimeval (now, &gnow); 00393 return now; 00394 }
GTimeVal* qof_time_get_current_start | ( | void | ) |
Definition at line 368 of file qoftime.c.
00369 { 00370 GTimeVal *current; 00371 struct tm tm; 00372 00374 current = g_new0 (GTimeVal, 1); 00375 g_get_current_time (current); 00376 /* OK to use time_t for current time. */ 00377 tm = *gmtime_r (¤t->tv_sec, &tm); 00378 current->tv_sec -= tm.tm_sec; 00379 current->tv_sec -= tm.tm_min * 60; 00380 current->tv_sec -= tm.tm_hour * 60 * 60; 00381 return current; 00382 }
glong qof_time_get_nanosecs | ( | const QofTime * | time | ) |
Get the number of seconds.
time | pointer to a QofTime time, created with qof_time_new(); |
Definition at line 140 of file qoftime.c.
QofTimeSecs qof_time_get_secs | ( | const QofTime * | time | ) |
Get the number of seconds.
time | pointer to a QofTime time, created with qof_time_new(); |
Definition at line 132 of file qoftime.c.
00133 { 00134 g_return_val_if_fail (qt, 0); 00135 g_return_val_if_fail (qt->valid == TRUE, 0); 00136 return qt->qt_sec; 00137 }
QofTime* qof_time_get_today_end | ( | void | ) |
returns a QofTime of the last second of today.
Definition at line 437 of file qoftime.c.
00438 { 00439 QofTime *qt; 00440 00441 qt = qof_time_get_today_start (); 00442 qt->qt_sec += SECS_PER_DAY - 1; 00443 return qt; 00444 }
QofTime* qof_time_get_today_start | ( | void | ) |
return a QofTime of the first second of today.
Definition at line 422 of file qoftime.c.
00423 { 00424 QofTime *qt; 00425 GDate *d; 00426 GTimeVal val; 00427 00428 qt = qof_time_new (); 00429 g_get_current_time (&val); 00430 d = g_date_new (); 00431 g_date_set_time_val (d, &val); 00432 qt = qof_time_from_gdate (d); 00433 return qt; 00434 }
guint8 qof_time_last_mday | ( | QofTime * | ts | ) |
Return the number of the last day of the month for the value contained in the QofTime.
Definition at line 447 of file qoftime.c.
00448 { 00449 GDate *d; 00450 GDateMonth m; 00451 GDateYear y; 00452 00453 g_return_val_if_fail (qt, 0); 00454 d = qof_time_to_gdate (qt); 00455 if (!d) 00456 return 0; 00457 m = g_date_get_month (d); 00458 y = g_date_get_year (d); 00459 return g_date_get_days_in_month (m, y); 00460 }
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 209 of file qoftime.c.
00210 { 00211 QofTime *qt; 00212 00213 qt = qof_time_new (); 00214 qt->qt_sec = t; 00215 qt->qt_nsec = nanosecs; 00216 qt->valid = TRUE; 00217 time_normalize (qt); 00218 return qt; 00219 }
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 350 of file qoftime.c.
00351 { 00352 if (!qof_time_set_day_start (qt)) 00353 return FALSE; 00354 qt->qt_sec += (SECS_PER_DAY - 1); 00355 return TRUE; 00356 }
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 359 of file qoftime.c.
00360 { 00361 if (!qof_time_set_day_start (qt)) 00362 return FALSE; 00363 qt->qt_sec += (SECS_PER_DAY / 2); 00364 return TRUE; 00365 }
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 397 of file qoftime.c.
00398 { 00399 GDate *d, *now; 00400 GTimeVal *current, from_date; 00401 gint days_between; 00402 00404 g_return_val_if_fail (qt, FALSE); 00405 d = qof_time_to_gdate (qt); 00406 if (!d) 00407 return FALSE; 00408 now = g_date_new (); 00409 current = qof_time_get_current_start (); 00410 g_date_set_time_val (now, current); 00411 /* if date is in the future, days_between is negative */ 00412 days_between = g_date_days_between (d, now); 00413 from_date.tv_sec = current->tv_sec - (days_between * SECS_PER_DAY); 00414 from_date.tv_usec = 0; 00415 qof_time_from_gtimeval (qt, &from_date); 00416 g_date_free (d); 00417 g_free (current); 00418 return TRUE; 00419 }
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. |
Definition at line 124 of file qoftime.c.
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. |
Definition at line 116 of file qoftime.c.
gchar* qof_time_stamp_now | ( | void | ) |
Return the current time in UTC textual format.
Definition at line 493 of file qoftime.c.
00494 { 00495 gint len; 00496 struct tm qtm; 00497 time_t t; 00498 gchar test[MAX_DATE_LENGTH]; 00499 const gchar *fmt; 00500 00501 ENTER (" "); 00502 t = time (NULL); 00503 qtm = *gmtime_r (&t, &qtm); 00504 fmt = qof_date_format_get_format (QOF_DATE_FORMAT_UTC); 00505 len = strftime (test, MAX_DATE_LENGTH, fmt, &qtm); 00506 if (len == 0 && test[0] != '\0') 00507 { 00508 LEAVE (" strftime failed."); 00509 return NULL; 00510 } 00511 LEAVE (" "); 00512 return g_strdup (test); 00513 }
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 463 of file qoftime.c.
00465 { 00466 GDate *d; 00467 00468 d = qof_time_to_gdate (qt); 00469 if (!d) 00470 return FALSE; 00471 if (day) 00472 *day = g_date_get_day (d); 00473 if (month) 00474 *month = g_date_get_month (d); 00475 if (year) 00476 *year = g_date_get_year (d); 00477 return TRUE; 00478 }
GDate* qof_time_to_gdate | ( | QofTime * | time | ) |
Convert QofTime to GDate.
time | The QofTime to convert |
Definition at line 298 of file qoftime.c.
00299 { 00300 GDate *d; 00301 time_t t; 00302 glong nsecs; 00303 gboolean success; 00304 struct tm utc; 00305 00315 success = qof_time_to_time_t (qt, &t, &nsecs); 00316 if (!success) 00317 return NULL; 00318 utc = *gmtime_r (&t, &utc); 00319 d = g_date_new_dmy (utc.tm_mday, utc.tm_mon + 1, 00320 utc.tm_year + 1900); 00321 if (g_date_valid (d)) 00322 return d; 00323 return NULL; 00324 }
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.
qt | QofTime to convert | |
gtv | GTimeVal to set, left unchanged if an error occurs. |
Definition at line 271 of file qoftime.c.
00272 { 00273 if (!qt->valid) 00274 { 00275 PERR (" invalid QofTime passed"); 00276 return FALSE; 00277 } 00278 if (qt->qt_sec > G_MAXLONG) 00279 { 00280 PERR (" QofTime out of range for GTimeVal"); 00281 return FALSE; 00282 } 00283 gtv->tv_sec = (glong) qt->qt_sec; 00284 gtv->tv_usec = qt->qt_nsec; 00285 return TRUE; 00286 }
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 236 of file qoftime.c.
00237 { 00238 if (!qt->valid) 00239 return FALSE; 00240 if (qt->qt_sec < 0) 00241 return FALSE; 00242 if (qt->qt_nsec > 0) 00243 { 00244 *nanosecs = qt->qt_nsec; 00245 } 00246 if ((sizeof (qt->qt_sec) > sizeof (time_t)) 00247 && (qt->qt_sec > G_MAXINT32)) 00248 { 00249 PERR (" QofTime too large for time_t on this platform."); 00250 return FALSE; 00251 } 00252 *t = qt->qt_sec; 00253 return TRUE; 00254 }