QOF: Time: 64bit UTC Time handling.

QOF 0.7.5

Modules | Files | Data Structures | Macros | Typedefs
Time: 64bit UTC Time handling.
Query Object Framework

## Modules
| Date: 64bit UTC date handling.

## Files
file | qoftime.h
| 64bit UTC Time handling routines

## Data Structures
struct | timespec64

## Macros
#define | QOF_MOD_TIME "qof-time"
#define | QOF_NSECS 1000000000

## Typedefs
typedef struct timespec64 | Timespec

## 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)

## Detailed Description

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

## Macro Definition Documentation

## ◆ QOF_MOD_TIME

#define QOF_MOD_TIME "qof-time"

log module name

Definition at line 94 of file qoftime.h.

## ◆ QOF_NSECS

#define QOF_NSECS 1000000000

number of nanoseconds per second. 10^9

Definition at line 105 of file qoftime.h.

## Typedef Documentation

## ◆ QofTime

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.

Definition at line 120 of file qoftime.h.

## ◆ QofTimeSecs

typedef gint64 QofTimeSecs

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.

## ◆ Timespec

typedef struct timespec64 Timespec

Deprecated:
  use QofTime.

## Function Documentation

## ◆ qof_time_abs()

QofTime* qof_time_abs | ( | QofTime * | t | ) |

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.

197 {
198 g_return_val_if_fail (qt, NULL);
199 return time_normalize (qt);
200 }

## ◆ qof_time_add_secs()

void qof_time_add_secs | ( | QofTime * | qt,
|  | QofTimeSecs | secs
| ) |  |

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.

66 {
67 g_return_if_fail (qt);
68 g_return_if_fail (qt->valid);
69 qt->qt_sec += secs;
70 }

## ◆ qof_time_add_secs_copy()

QofTime* qof_time_add_secs_copy | ( | QofTime * | qt,
|  | QofTimeSecs | secs
| ) |  |

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.

74 {
75 QofTime *copy;
76
77 g_return_val_if_fail (qt, NULL);
78 g_return_val_if_fail (qt->valid, NULL);
79 copy = qof_time_copy (qt);
80 copy->qt_sec += secs;
81 return copy;
82 }
qof_time_copy
QofTime * qof_time_copy(const QofTime *qt)
Create a copy of a QofTime.
Definition: qoftime.c:223
QofTime
struct QofTime64 QofTime
Use a 64-bit signed int QofTime.
Definition: qoftime.h:120

## ◆ qof_time_cmp()

gint qof_time_cmp | ( | const QofTime * | ta,
|  | const QofTime * | tb
| ) |  |

comparison: if (ta < tb) -1; else if (ta > tb) 1; else 0;

Definition at line 165 of file qoftime.c.

166 {
167 g_return_val_if_fail (ta->valid && tb->valid, -1);
168 if (ta == tb)
169 return 0;
170 if (ta->qt_sec < tb->qt_sec)
171 return -1;
172 if (ta->qt_sec > tb->qt_sec)
173 return 1;
174 if (ta->qt_nsec < tb->qt_nsec)
175 return -1;
176 if (ta->qt_nsec > tb->qt_nsec)
177 return 1;
178 return 0;
179 }

## ◆ qof_time_copy()

QofTime* qof_time_copy | ( | const QofTime * | qt | ) |

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.

224 {
225 g_return_val_if_fail (qt, NULL);
226 g_return_val_if_fail (qt->valid, NULL);
227 return qof_time_set (qt->qt_sec, qt->qt_nsec);
228 }
qof_time_set
QofTime * qof_time_set(QofTimeSecs t, glong nanosecs)
Definition: qoftime.c:210

## ◆ qof_time_diff()

QofTime* qof_time_diff | ( | const QofTime * | ta,
|  | const QofTime * | tb
| ) |  |

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.

183 {
184 QofTime *retval;
185
186 g_return_val_if_fail (ta->valid && tb->valid, NULL);
187 retval = g_new0 (QofTime, 1);
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);
192 return retval;
193 }
QofTime
struct QofTime64 QofTime
Use a 64-bit signed int QofTime.
Definition: qoftime.h:120

## ◆ qof_time_dmy_to_time()

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.

458 {
459 GDate *d;
460 QofTime *qt;
461
462 g_return_val_if_fail (g_date_valid_dmy (day, month, year), NULL);
463 d = g_date_new_dmy (day, month, year);
464 qt = qof_time_from_gdate (d);
465 return qt;
466 }
qof_time_from_gdate
QofTime * qof_time_from_gdate(GDate *date)
Convert a GDate to a QofTime.
Definition: qoftime.c:312
QofTime
struct QofTime64 QofTime
Use a 64-bit signed int QofTime.
Definition: qoftime.h:120

## ◆ qof_time_equal()

gboolean qof_time_equal | ( | const QofTime * | ta,
|  | const QofTime * | tb
| ) |  |

strict equality

Definition at line 148 of file qoftime.c.

149 {
150 if (ta == tb)
151 return TRUE;
152 if (!ta)
153 return FALSE;
154 if (!tb)
155 return FALSE;
156 g_return_val_if_fail (ta->valid && tb->valid, FALSE);
157 if (ta->qt_sec != tb->qt_sec)
158 return FALSE;
159 if (ta->qt_nsec != tb->qt_nsec)
160 return FALSE;
161 return TRUE;
162 }

## ◆ qof_time_from_gdate()

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

  date | The GDate to convert

Returns
  a valid QofTime or NULL on error.

Definition at line 312 of file qoftime.c.

313 {
314 struct tm gtm;
315 QofTime *qt;
316 QofDate *qd;
317
318 g_return_val_if_fail (date, NULL);
319 g_date_to_struct_tm (date, &gtm);
320 qd = qof_date_from_struct_tm (&gtm);
321 qt = qof_date_to_qtime (qd);
322 qof_date_free (qd);
323 return qt;
324 }
qof_date_free
void qof_date_free(QofDate *date)
Definition: qofdate.c:608
qof_date_to_qtime
QofTime * qof_date_to_qtime(const QofDate *qd)
Definition: qofdate.c:892
QofDate_s
Full range replacement for struct tm.
Definition: qofdate.h:138
QofTime
struct QofTime64 QofTime
Use a 64-bit signed int QofTime.
Definition: qoftime.h:120
qof_date_from_struct_tm
QofDate * qof_date_from_struct_tm(const struct tm *stm)
Convert a struct tm to a QofDate.
Definition: qofdate.c:679

## ◆ qof_time_from_gtimeval()

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.

291 {
292 qt->qt_sec = (QofTimeSecs) gtv->tv_sec;
293 qt->qt_nsec = gtv->tv_usec * 1000;
294 qt->valid = TRUE;
295 time_normalize (qt);
296 }
QofTimeSecs
gint64 QofTimeSecs
Replacement for time_t.
Definition: qoftime.h:129

## ◆ qof_time_from_time_t()

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.

232 {
233 return qof_time_set (t, nanosecs);
234 }
qof_time_set
QofTime * qof_time_set(QofTimeSecs t, glong nanosecs)
Definition: qoftime.c:210

## ◆ qof_time_from_tm()

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.

259 {
260 QofDate *qd;
261 QofTime *qt;
262
263 /* avoids use of gmtime_r and therefore time_t */
264 qd = qof_date_from_struct_tm (qtm);
265 qd->qd_nanosecs = nanosecs;
266 qt = qof_date_to_qtime (qd);
267 qof_date_free (qd);
268 return qt;
269 }
qof_date_free
void qof_date_free(QofDate *date)
Definition: qofdate.c:608
qof_date_to_qtime
QofTime * qof_date_to_qtime(const QofDate *qd)
Definition: qofdate.c:892
QofDate_s
Full range replacement for struct tm.
Definition: qofdate.h:138
QofDate_s::qd_nanosecs
glong qd_nanosecs
Definition: qofdate.h:141
QofTime
struct QofTime64 QofTime
Use a 64-bit signed int QofTime.
Definition: qoftime.h:120
qof_date_from_struct_tm
QofDate * qof_date_from_struct_tm(const struct tm *stm)
Convert a struct tm to a QofDate.
Definition: qofdate.c:679

## ◆ qof_time_get_current()

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.

363 {
364 QofTime *now;
365 GTimeVal gnow;
366
367 now = qof_time_new ();
368 g_get_current_time (&gnow);
369 qof_time_from_gtimeval (now, &gnow);
370 return now;
371 }
qof_time_new
QofTime * qof_time_new(void)
create an empty QofTime
Definition: qoftime.c:46
QofTime
struct QofTime64 QofTime
Use a 64-bit signed int QofTime.
Definition: qoftime.h:120
qof_time_from_gtimeval
void qof_time_from_gtimeval(QofTime *qt, GTimeVal *gtv)
Convert a QofTime to a GTimeVal.
Definition: qoftime.c:290

## ◆ qof_time_get_current_start()

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.

346 {
347 GTimeVal *current;
348 struct tm tm;
349
351 current = g_new0 (GTimeVal, 1);
352 g_get_current_time (current);
353 /* OK to use time_t for current time. */
354 tm = *gmtime_r (&current->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;
358 return current;
359 }

## ◆ qof_time_get_nanosecs()

glong qof_time_get_nanosecs | ( | const QofTime * | time | ) |

Get the number of seconds.

Parameters

  time | pointer to a QofTime time, created with qof_time_new();

Returns
  long int number of nanoseconds.

Definition at line 141 of file qoftime.c.

142 {
143 g_return_val_if_fail (qt->valid == TRUE, 0);
144 return qt->qt_nsec;
145 }

## ◆ qof_time_get_secs()

QofTimeSecs qof_time_get_secs | ( | const QofTime * | time | ) |

Get the number of seconds.

Parameters

  time | pointer to a QofTime time, created with qof_time_new();

Returns
  Signed 64bit number of seconds.

Definition at line 133 of file qoftime.c.

134 {
135 g_return_val_if_fail (qt, 0);
136 g_return_val_if_fail (qt->valid == TRUE, 0);
137 return qt->qt_sec;
138 }

## ◆ qof_time_get_today_end()

QofTime* qof_time_get_today_end | ( | void |  | ) |

returns a QofTime of the last second of today.

Definition at line 413 of file qoftime.c.

414 {
415 QofTime *qt;
416
417 qt = qof_time_get_today_start ();
418 qt->qt_sec += SECS_PER_DAY - 1;
419 return qt;
420 }
qof_time_get_today_start
QofTime * qof_time_get_today_start(void)
Definition: qoftime.c:402
SECS_PER_DAY
#define SECS_PER_DAY
Definition: qofdate.h:94
QofTime
struct QofTime64 QofTime
Use a 64-bit signed int QofTime.
Definition: qoftime.h:120

## ◆ qof_time_get_today_start()

QofTime* qof_time_get_today_start | ( | void |  | ) |

return a QofTime of the first second of today.

Definition at line 402 of file qoftime.c.

403 {
404 QofTime *qt;
405
406 qt = qof_time_get_current ();
407 if (!qof_time_set_day_start (qt))
408 return NULL;
409 return qt;
410 }
qof_time_set_day_start
gboolean qof_time_set_day_start(QofTime *qt)
set the given QofTime to the first second of that day.
Definition: qoftime.c:374
qof_time_get_current
QofTime * qof_time_get_current(void)
Get the current QofTime.
Definition: qoftime.c:362
QofTime
struct QofTime64 QofTime
Use a 64-bit signed int QofTime.
Definition: qoftime.h:120

## ◆ qof_time_last_mday()

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.

424 {
425 GDate *d;
426 GDateMonth m;
427 GDateYear y;
428
429 g_return_val_if_fail (qt, 0);
430 d = qof_time_to_gdate (qt);
431 if (!d)
432 return 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);
436 }
qof_time_to_gdate
GDate * qof_time_to_gdate(QofTime *qt)
Convert QofTime to GDate.
Definition: qoftime.c:299

## ◆ qof_time_new()

QofTime* qof_time_new | ( | void |  | ) |

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.

47 {
48 QofTime *qt;
49
50 qt = g_new0 (QofTime, 1);
51 qt->valid = FALSE;
52 return qt;
53 }
QofTime
struct QofTime64 QofTime
Use a 64-bit signed int QofTime.
Definition: qoftime.h:120

## ◆ qof_time_set()

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.

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.

211 {
212 QofTime *qt;
213
214 qt = qof_time_new ();
215 qt->qt_sec = t;
216 qt->qt_nsec = nanosecs;
217 qt->valid = TRUE;
218 time_normalize (qt);
219 return qt;
220 }
qof_time_new
QofTime * qof_time_new(void)
create an empty QofTime
Definition: qoftime.c:46
QofTime
struct QofTime64 QofTime
Use a 64-bit signed int QofTime.
Definition: qoftime.h:120

## ◆ qof_time_set_day_end()

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.

328 {
329 if (!qof_time_set_day_start (qt))
330 return FALSE;
331 qt->qt_sec += (SECS_PER_DAY - 1);
332 return TRUE;
333 }
qof_time_set_day_start
gboolean qof_time_set_day_start(QofTime *qt)
set the given QofTime to the first second of that day.
Definition: qoftime.c:374
SECS_PER_DAY
#define SECS_PER_DAY
Definition: qofdate.h:94

## ◆ qof_time_set_day_middle()

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.

337 {
338 if (!qof_time_set_day_start (qt))
339 return FALSE;
340 qt->qt_sec += (SECS_PER_DAY / 2);
341 return TRUE;
342 }
qof_time_set_day_start
gboolean qof_time_set_day_start(QofTime *qt)
set the given QofTime to the first second of that day.
Definition: qoftime.c:374
SECS_PER_DAY
#define SECS_PER_DAY
Definition: qofdate.h:94

## ◆ qof_time_set_day_start()

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.

375 {
376 QofDate *qd;
377 QofTimeSecs c;
378
379 g_return_val_if_fail (qt, FALSE);
380 qd = qof_date_from_qtime (qt);
381 if (qd->qd_year < 1970)
382 {
383 c = QOF_DAYS_TO_SEC(qd->qd_yday);
384 c -= QOF_DAYS_TO_SEC(days_between (1970, qd->qd_year));
385 c -= qd->qd_gmt_off;
386 qt->qt_sec = c;
387 qt->qt_nsec = 0;
388 }
389 if (qd->qd_year >= 1970)
390 {
391 c = QOF_DAYS_TO_SEC(qd->qd_yday);
392 c += QOF_DAYS_TO_SEC(days_between (1970, qd->qd_year));
393 c -= qd->qd_gmt_off;
394 qt->qt_sec = c;
395 qt->qt_nsec = 0;
396 }
397 qof_date_free (qd);
398 return TRUE;
399 }
QofDate_s::qd_yday
gshort qd_yday
Definition: qofdate.h:189
QofDate_s::qd_year
gint64 qd_year
Extended version to cope with full range of dates.
Definition: qofdate.h:181
qof_date_free
void qof_date_free(QofDate *date)
Definition: qofdate.c:608
qof_date_from_qtime
QofDate * qof_date_from_qtime(const QofTime *qt)
Definition: qofdate.c:850
QofDate_s
Full range replacement for struct tm.
Definition: qofdate.h:138
QofDate_s::qd_gmt_off
glong qd_gmt_off
Calculated value based on struct tm.tm_gmtoff.
Definition: qofdate.h:201
QofTimeSecs
gint64 QofTimeSecs
Replacement for time_t.
Definition: qoftime.h:129
QOF_DAYS_TO_SEC
#define QOF_DAYS_TO_SEC(x)
Definition: qofdate.h:331

## ◆ qof_time_set_nanosecs()

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.

126 {
127 qt->qt_nsec = nano;
128 qt->valid = TRUE;
129 time_normalize (qt);
130 }

## ◆ qof_time_set_secs()

void qof_time_set_secs | ( | QofTime * | time,
|  | QofTimeSecs | secs
| ) |  |

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.

118 {
119 qt->qt_sec = secs;
120 qt->valid = TRUE;
121 time_normalize (qt);
122 }

## ◆ qof_time_stamp_now()

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.

470 {
471 gint len;
472 struct tm qtm;
473 time_t t;
474 gchar test[MAX_DATE_LENGTH];
475 const gchar *fmt;
476
477 ENTER (" ");
478 t = time (NULL);
479 qtm = *gmtime_r (&t, &qtm);
480 fmt = qof_date_format_get_format (QOF_DATE_FORMAT_UTC);
481 len = strftime (test, MAX_DATE_LENGTH, fmt, &qtm);
482 if (len == 0 && test[0] != '\0')
483 {
484 LEAVE (" strftime failed.");
485 return NULL;
486 }
487 LEAVE (" ");
488 return g_strdup (test);
489 }
QOF_DATE_FORMAT_UTC
#define QOF_DATE_FORMAT_UTC
QOF UTC format, xsd:date compatible. QOF_UTC_DATE_FORMAT "%Y-%m-%dT%H:%M:%SZ".
Definition: qofdate.h:277
qof_date_format_get_format
const gchar * qof_date_format_get_format(QofDateFormat df)
Retrieve the strftime format string for a registered date format.
Definition: qofdate.c:310
LEAVE
#define LEAVE(format, args...)
Definition: qoflog.h:227
MAX_DATE_LENGTH
#define MAX_DATE_LENGTH
The maximum length of a string used for or created by dates.
Definition: qofdate.h:87
ENTER
#define ENTER(format, args...)
Definition: qoflog.h:217

## ◆ qof_time_to_dmy()

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.

441 {
442 GDate *d;
443
444 d = qof_time_to_gdate (qt);
445 if (!d)
446 return FALSE;
447 if (day)
448 *day = g_date_get_day (d);
449 if (month)
450 *month = g_date_get_month (d);
451 if (year)
452 *year = g_date_get_year (d);
453 return TRUE;
454 }
qof_time_to_gdate
GDate * qof_time_to_gdate(QofTime *qt)
Convert QofTime to GDate.
Definition: qoftime.c:299

## ◆ qof_time_to_gdate()

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.

300 {
301 QofDate *qd;
302 GDate *d;
303
304 qd = qof_date_from_qtime (qt);
305 d = g_date_new_dmy (qd->qd_mday, qd->qd_mon, qd->qd_year);
306 if (g_date_valid (d))
307 return d;
308 return NULL;
309 }
QofDate_s::qd_year
gint64 qd_year
Extended version to cope with full range of dates.
Definition: qofdate.h:181
qof_date_from_qtime
QofDate * qof_date_from_qtime(const QofTime *qt)
Definition: qofdate.c:850
QofDate_s
Full range replacement for struct tm.
Definition: qofdate.h:138
QofDate_s::qd_mon
glong qd_mon
Signed replacement of struct tm.tm_mon.
Definition: qofdate.h:171
QofDate_s::qd_mday
glong qd_mday
Signed replacement of struct tm.tm_mday.
Definition: qofdate.h:164

## ◆ qof_time_to_gtimeval()

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.

273 {
274 if (!qt->valid)
275 {
276 PERR (" invalid QofTime passed");
277 return FALSE;
278 }
279 if (qt->qt_sec > G_MAXLONG)
280 {
281 PERR (" QofTime out of range for GTimeVal");
282 return FALSE;
283 }
284 gtv->tv_sec = (glong) qt->qt_sec;
285 gtv->tv_usec = qt->qt_nsec;
286 return TRUE;
287 }
PERR
#define PERR(format, args...)
Definition: qoflog.h:183

## ◆ qof_time_to_time_t()

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.

238 {
239 if (!qt->valid)
240 return FALSE;
241 if (qt->qt_sec < 0)
242 return FALSE;
243 if (qt->qt_nsec > 0)
244 {
245 *nanosecs = qt->qt_nsec;
246 }
247 if ((sizeof (qt->qt_sec) > sizeof (time_t))
248 && (qt->qt_sec > G_MAXINT32))
249 {
250 PERR (" QofTime too large for time_t on this platform.");
251 return FALSE;
252 }
253 *t = qt->qt_sec;
254 return TRUE;
255 }
PERR
#define PERR(format, args...)
Definition: qoflog.h:183