GnuCash  4.8a-176-g88ecf8dd1
Files | Data Structures | Macros | Typedefs | Enumerations | Functions | Variables
Date: Date and Time Printing, Parsing and Manipulation

Utility functions to handle date and time (adjusting, getting the current date, printing the date and time, etc.) More...

Files

file  gnc-date.h
 Date and Time handling routines.
 

Data Structures

struct  Time64
 

Macros

#define MAX_DATE_LENGTH   34
 The maximum length of a string created by the date printers.
 
#define QOF_UTC_DATE_FORMAT   "%Y-%m-%dT%H:%M:%SZ"
 Constants. More...
 
#define DATE_FORMAT_FIRST   QOF_DATE_FORMAT_US
 
#define DATE_FORMAT_LAST   QOF_DATE_FORMAT_UTC
 
#define qof_date_format_get_format   qof_date_text_format_get_string
 

Typedefs

typedef gint64 time64
 Many systems, including Microsoft Windows and BSD-derived Unixes like Darwin, are retaining the int-32 typedef for time_t. More...
 

Enumerations

enum  QofDateFormat {
  QOF_DATE_FORMAT_US, QOF_DATE_FORMAT_UK, QOF_DATE_FORMAT_CE, QOF_DATE_FORMAT_ISO,
  QOF_DATE_FORMAT_LOCALE, QOF_DATE_FORMAT_UTC, QOF_DATE_FORMAT_CUSTOM, QOF_DATE_FORMAT_UNSET
}
 Enum for determining a date format. More...
 
enum  QofDateCompletion { QOF_DATE_COMPLETION_THISYEAR, QOF_DATE_COMPLETION_SLIDING }
 Enum for date completion modes (for dates entered without year) More...
 
enum  GNCDateMonthFormat { GNCDATE_MONTH_NUMBER, GNCDATE_MONTH_ABBREV, GNCDATE_MONTH_NAME }
 This is how to format the month, as a number, an abbreviated string, or the full name.
 

Functions

struct tm * gnc_localtime (const time64 *secs)
 fill out a time struct from a 64-bit time value. More...
 
struct tm * gnc_localtime_r (const time64 *secs, struct tm *time)
 fill out a time struct from a 64-bit time value adjusted for the current time zone. More...
 
struct tm * gnc_gmtime (const time64 *secs)
 fill out a time struct from a 64-bit time value More...
 
gint gnc_start_of_week (void)
 returns an integer corresponding to locale start of week More...
 
time64 gnc_mktime (struct tm *time)
 calculate seconds from the epoch given a time struct More...
 
time64 gnc_timegm (struct tm *time)
 calculate seconds from the epoch given a time struct More...
 
gchar * gnc_ctime (const time64 *secs)
 Return a string representation of a date from a 64-bit time value. More...
 
time64 gnc_time (time64 *tbuf)
 get the current local time More...
 
gdouble gnc_difftime (const time64 secs1, const time64 secs2)
 Find the difference in seconds between two time values. More...
 
void gnc_tm_free (struct tm *time)
 free a struct tm* created with gnc_localtime() or gnc_gmtime() More...
 
time64 time64CanonicalDayTime (time64 t)
 convert a time64 on a certain day (localtime) to the time64 representing midday on that day. More...
 
time64 gdate_to_time64 (GDate d)
 Turns a GDate into a time64, returning the first second of the day.
 
time64 gnc_dmy2time64 (gint day, gint month, gint year)
 Convert a day, month, and year to a time64, returning the first second of the day.
 
time64 gnc_dmy2time64_neutral (gint day, gint month, gint year)
 Converts a day, month, and year to a time64 representing 11:00:00 UTC 11:00:00 UTC falls on the same time in almost all timezones, the exceptions being the +13, +14, and -12 timezones used by countries along the International Date Line. More...
 
time64 gnc_dmy2time64_end (gint day, gint month, gint year)
 Same as gnc_dmy2time64, but last second of the day.
 
time64 gnc_iso8601_to_time64_gmt (const gchar *)
 The gnc_iso8601_to_time64_gmt() routine converts an ISO-8601 style date/time string to time64. More...
 
gchar * gnc_time64_to_iso8601_buff (time64, char *buff)
 The gnc_time64_to_iso8601_buff() routine takes the input UTC time64 value and prints it as an ISO-8601 style string. More...
 

Variables

const char * gnc_default_strftime_date_format
 The default date format for use with strftime. More...
 

GValue

GType time64_get_type (void)
 
#define GNC_TYPE_TIME64   (time64_get_type ())
 

String / DateFormat conversion.

const gchar * gnc_date_dateformat_to_string (QofDateFormat format)
 The string->value versions return FALSE on success and TRUE on failure.
 
gboolean gnc_date_string_to_dateformat (const gchar *format_string, QofDateFormat *format)
 Converts the date format to a printable string. More...
 
const gchar * gnc_date_monthformat_to_string (GNCDateMonthFormat format)
 
gboolean gnc_date_string_to_monthformat (const gchar *format_string, GNCDateMonthFormat *format)
 Converts the month format to a printable string. More...
 
char * gnc_print_time64 (time64 time, const char *format)
 print a time64 as a date string per format More...
 

GDate time64 setters

GDate * gnc_g_date_new_today (void)
 Returns a newly allocated date of the current clock time, taken from time(2). More...
 
void gnc_gdate_set_today (GDate *gd)
 Set a GDate to the current day. More...
 
void gnc_gdate_set_time64 (GDate *gd, time64 time)
 Set a GDate to a time64. More...
 

Detailed Description

Utility functions to handle date and time (adjusting, getting the current date, printing the date and time, etc.)

Overall, this file is quite a mess. Note, however, that other applications, besides just GnuCash, use this file. In particular, GnoTime (gttr.sourcefore.net) uses this file, and this file is formally a part of QOF (qof.sourceforge.net).

An important note about time-keeping: The general goal of any program that works with numeric time values SHOULD BE to always stores and use UNIVERSAL TIME internally. 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). If one wants to display the local time, then the display-print routine should make all final tweaks to print the local time. The local time must not be kept as a numeric value anywhere in the program. If one wants to parse a user's input string as if it were local time, then the output of the parse routine MUST BE universal time. A sane program must never ever store (to file or db) a time that is not Universal Time. Break these rules, and you will rue the day...

Warning
HACK ALERT – the scan and print routines should probably be moved to somewhere else. The engine really isn't involved with things like printing formats. This is needed mostly by the GUI and so on. If a file-io backend needs date handling, it should do it itself, instead of depending on the routines here.

(to be renamed qofdate.h in libqof2.)

Author
Copyright (C) 1997 Robin D. Clark rclar.nosp@m.k@cs.nosp@m..hmc..nosp@m.edu
Copyright (C) 1998-2001,2003 Linas Vepstas linas.nosp@m.@lin.nosp@m.as.or.nosp@m.g

Macro Definition Documentation

◆ qof_date_format_get_format

#define qof_date_format_get_format   qof_date_text_format_get_string
Deprecated:
qof_date_format_get_format has been replaced by qof_date_text_format_get_string

Definition at line 152 of file gnc-date.h.

◆ QOF_UTC_DATE_FORMAT

#define QOF_UTC_DATE_FORMAT   "%Y-%m-%dT%H:%M:%SZ"

Constants.

UTC date format string.

Time zone independent, date and time inclusive, as used in the QSF backend. The T and Z characters are from xsd:dateTime format in coordinated universal time, UTC. You can reproduce the string from the GNU/Linux command line using the date utility: date -u +Y-m-dTH:M:SZ = 2004-12-12T23:39:11Z The datestring must be time zone independent and include all specified fields. Remember to use gmtime() NOT localtime()!

Definition at line 125 of file gnc-date.h.

Typedef Documentation

◆ time64

typedef gint64 time64

Many systems, including Microsoft Windows and BSD-derived Unixes like Darwin, are retaining the int-32 typedef for time_t.

Since this stops working in 2038, we define our own:

Definition at line 93 of file gnc-date.h.

Enumeration Type Documentation

◆ QofDateCompletion

Enum for date completion modes (for dates entered without year)

Enumerator
QOF_DATE_COMPLETION_THISYEAR 

use current year

QOF_DATE_COMPLETION_SLIDING 

use sliding 12-month window

Definition at line 144 of file gnc-date.h.

145 {
QofDateCompletion
Enum for date completion modes (for dates entered without year)
Definition: gnc-date.h:144
use sliding 12-month window
Definition: gnc-date.h:147
use current year
Definition: gnc-date.h:146

◆ QofDateFormat

Enum for determining a date format.

Enumerator
QOF_DATE_FORMAT_US 

United states: mm/dd/yyyy.

QOF_DATE_FORMAT_UK 

Britain: dd/mm/yyyy.

QOF_DATE_FORMAT_CE 

Continental Europe: dd.mm.yyyy.

QOF_DATE_FORMAT_ISO 

ISO: yyyy-mm-dd.

QOF_DATE_FORMAT_LOCALE 

Take from locale information.

QOF_DATE_FORMAT_UTC 

UTC: 2004-12-12T23:39:11Z.

QOF_DATE_FORMAT_CUSTOM 

Used by the check printing code.

QOF_DATE_FORMAT_UNSET 

No Fancy Date Format, use Global.

Definition at line 128 of file gnc-date.h.

129 {
138 } QofDateFormat;
ISO: yyyy-mm-dd.
Definition: gnc-date.h:133
Used by the check printing code.
Definition: gnc-date.h:136
Continental Europe: dd.mm.yyyy.
Definition: gnc-date.h:132
No Fancy Date Format, use Global.
Definition: gnc-date.h:137
UTC: 2004-12-12T23:39:11Z.
Definition: gnc-date.h:135
Take from locale information.
Definition: gnc-date.h:134
Britain: dd/mm/yyyy.
Definition: gnc-date.h:131
QofDateFormat
Enum for determining a date format.
Definition: gnc-date.h:128
United states: mm/dd/yyyy.
Definition: gnc-date.h:130

Function Documentation

◆ gnc_ctime()

gchar* gnc_ctime ( const time64 secs)

Return a string representation of a date from a 64-bit time value.

Parameters
secsSeconds since 00:00:01 UTC 01 January 1970 (negative values are seconds before that moment)
Returns
A string, which must be freed with g_free(), representing the date in the following format: Thu Nov 24 18:22:48 1986
\0 This is equivalent to the strftime format a b H:M:S Y.

Definition at line 267 of file gnc-date.cpp.

268 {
269  return gnc_print_time64(*secs, "%a %b %d %H:%M:%S %Y");
270 }
char * gnc_print_time64(time64 time, const char *format)
print a time64 as a date string per format
Definition: gnc-date.cpp:379

◆ gnc_date_string_to_dateformat()

gboolean gnc_date_string_to_dateformat ( const gchar *  format_string,
QofDateFormat format 
)

Converts the date format to a printable string.

Note the reversed return values!

Returns
FALSE on success, TRUE on failure.

◆ gnc_date_string_to_monthformat()

gboolean gnc_date_string_to_monthformat ( const gchar *  format_string,
GNCDateMonthFormat format 
)

Converts the month format to a printable string.

Note the reversed return values!

Returns
FALSE on success, TRUE on failure.

◆ gnc_difftime()

gdouble gnc_difftime ( const time64  secs1,
const time64  secs2 
)

Find the difference in seconds between two time values.

Parameters
secs1The first time value, in Seconds since 00:00:01 UTC 01 January 1970 (negative values are seconds before that moment)
secs2The second time value, in Seconds since 00:00:01 UTC 01 January 1970 (negative values are seconds before that moment)
Returns
The difference in seconds between secs1 and secs2. If secs2 is later than secs1 the value will be negative.

Definition at line 283 of file gnc-date.cpp.

284 {
285  return (double)secs1 - (double)secs2;
286 }

◆ gnc_dmy2time64_neutral()

time64 gnc_dmy2time64_neutral ( gint  day,
gint  month,
gint  year 
)

Converts a day, month, and year to a time64 representing 11:00:00 UTC 11:00:00 UTC falls on the same time in almost all timezones, the exceptions being the +13, +14, and -12 timezones used by countries along the International Date Line.

Since users in those timezones would see dates immediately change by one day, the function checks the current timezone for those changes and adjusts the UTC time so that the date will be consistent.

◆ gnc_g_date_new_today()

GDate* gnc_g_date_new_today ( void  )

Returns a newly allocated date of the current clock time, taken from time(2).

The caller must g_date_free() the object afterwards.

Definition at line 1229 of file gnc-date.cpp.

1230 {
1231  GncDate gncd;
1232  auto ymd = gncd.year_month_day();
1233  auto month = static_cast<GDateMonth>(ymd.month);
1234  auto result = g_date_new_dmy (ymd.day, month, ymd.year);
1235  g_assert(g_date_valid (result));
1236  return result;
1237 }void
ymd year_month_day() const
Get the year, month, and day from the date as a ymd.
GnuCash Date class.

◆ gnc_gdate_set_time64()

void gnc_gdate_set_time64 ( GDate *  gd,
time64  time 
)

Set a GDate to a time64.

Parameters
gdthe date to act on
timethe time to set it to.

Definition at line 1247 of file gnc-date.cpp.

1248 {
1249  struct tm tm;
1250  gnc_localtime_r(&time, &tm);
1251  g_date_set_dmy (gd, tm.tm_mday,
1252  static_cast<GDateMonth>(tm.tm_mon + 1),
1253  tm.tm_year + 1900);
1254 }
struct tm * gnc_localtime_r(const time64 *secs, struct tm *time)
fill out a time struct from a 64-bit time value adjusted for the current time zone.
Definition: gnc-date.cpp:117

◆ gnc_gdate_set_today()

void gnc_gdate_set_today ( GDate *  gd)

Set a GDate to the current day.

Parameters
gdThe date to act on

Definition at line 1239 of file gnc-date.cpp.

1240 {
1241  GDate *today = gnc_g_date_new_today ();
1242  g_date_set_julian (gd, g_date_get_julian (today));
1243  g_date_free (today);
1244 }
GDate * gnc_g_date_new_today()
Returns a newly allocated date of the current clock time, taken from time(2).
Definition: gnc-date.cpp:1229

◆ gnc_gmtime()

struct tm* gnc_gmtime ( const time64 secs)

fill out a time struct from a 64-bit time value

Parameters
secsSeconds since 00:00:01 UTC 01 January 1970 (negative values are seconds before that moment)
Returns
A struct tm*, allocated on the heap. Must be freed with gnc_tm_free() The time is UTC.

Definition at line 189 of file gnc-date.cpp.

190 {
191  try
192  {
193  auto time = static_cast<struct tm*>(calloc(1, sizeof(struct tm)));
194  GncDateTime gncdt(*secs);
195  *time = gncdt.utc_tm();
196  return time;
197  }
198  catch(std::invalid_argument&)
199  {
200  return NULL;
201  }
202 
203 }
GnuCash DateTime class.

◆ gnc_iso8601_to_time64_gmt()

time64 gnc_iso8601_to_time64_gmt ( const gchar *  )

The gnc_iso8601_to_time64_gmt() routine converts an ISO-8601 style date/time string to time64.

Please note that ISO-8601 strings are a representation of Universal Time (UTC), and as such, they 'store' UTC. To make them human readable, they show time zone information along with a local-time string. But fundamentally, they are UTC. Thus, this routine takes a UTC input, and returns a UTC output.

For example: 1998-07-17 11:00:00.68-0500 is 680 milliseconds after 11 o'clock, central daylight time It is also 680 milliseconds after 16:00:00 hours UTC.

Returns
The universal time.

XXX Caution: this routine does not handle strings that specify times before January 1 1970.

◆ gnc_localtime()

struct tm* gnc_localtime ( const time64 secs)

fill out a time struct from a 64-bit time value.

Parameters
secsSeconds since 00:00:01 UTC 01 January 1970 (negative values are seconds before that moment).
Returns
A struct tm*, allocated on the heap. Must be freed with gnc_tm_free(). The time is adjusted for the current local time zone.

Definition at line 105 of file gnc-date.cpp.

106 {
107  auto time = static_cast<struct tm*>(calloc(1, sizeof(struct tm)));
108  if (gnc_localtime_r (secs, time) == NULL)
109  {
110  gnc_tm_free (time);
111  return NULL;
112  }
113  return time;
114 }
struct tm * gnc_localtime_r(const time64 *secs, struct tm *time)
fill out a time struct from a 64-bit time value adjusted for the current time zone.
Definition: gnc-date.cpp:117
void gnc_tm_free(struct tm *time)
free a struct tm* created with gnc_localtime() or gnc_gmtime()
Definition: gnc-date.cpp:99

◆ gnc_localtime_r()

struct tm* gnc_localtime_r ( const time64 secs,
struct tm *  time 
)

fill out a time struct from a 64-bit time value adjusted for the current time zone.

Parameters
secsSeconds since 00:00:01 UTC 01 January 1970 (negative values are seconds before that moment)
timeA struct tm* for the function to fill. The time is adjusted for the current local time zone.

Definition at line 117 of file gnc-date.cpp.

118 {
119  try
120  {
121  *time = static_cast<struct tm>(GncDateTime(*secs));
122  return time;
123  }
124  catch(std::invalid_argument&)
125  {
126  return NULL;
127  }
128 }
GnuCash DateTime class.

◆ gnc_mktime()

time64 gnc_mktime ( struct tm *  time)

calculate seconds from the epoch given a time struct

Parameters
timeA struct tm* containing the date-time information. The time is understood to be in the current local time zone.
Returns
Seconds since 00:00:01 UTC 01 January 1970 (negative values are seconds before that moment).

Definition at line 230 of file gnc-date.cpp.

231 {
232  try
233  {
234  normalize_struct_tm (time);
235  GncDateTime gncdt(*time);
236  *time = static_cast<struct tm>(gncdt);
237  return static_cast<time64>(gncdt);
238  }
239  catch(std::invalid_argument&)
240  {
241  return 0;
242  }
243 }
GnuCash DateTime class.
gint64 time64
Many systems, including Microsoft Windows and BSD-derived Unixes like Darwin, are retaining the int-3...
Definition: gnc-date.h:93

◆ gnc_print_time64()

char* gnc_print_time64 ( time64  time,
const char *  format 
)

print a time64 as a date string per format

Parameters
timeThe time64 to print
formatA date format conforming to the strftime format rules.
Returns
a raw heap-allocated char* which must be freed.

Definition at line 379 of file gnc-date.cpp.

380 {
381  try
382  {
383  GncDateTime gncdt(time);
384  auto sstr = gncdt.format(format);
385  //ugly C allocation so that the ptr can be freed at the other end
386  char* cstr = static_cast<char*>(malloc(sstr.length() + 1));
387  memset(cstr, 0, sstr.length() + 1);
388  strncpy(cstr, sstr.c_str(), sstr.length());
389  return cstr;
390  }
391  catch(std::runtime_error& err)
392  {
393  PWARN("Error processing time64 %" PRId64 ": %s", time, err.what());
394  return nullptr;
395  }
396  catch(std::logic_error& err)
397  {
398  PWARN("Error processing time64 %" PRId64 ": %s", time, err.what());
399  return nullptr;
400  }
401 }
GnuCash DateTime class.
#define PWARN(format, args...)
Log a warning.
Definition: qoflog.h:250

◆ gnc_start_of_week()

gint gnc_start_of_week ( void  )

returns an integer corresponding to locale start of week

Returns
An integer 1=Sunday, 2=Monday etc. If error, return 0.

Definition at line 206 of file gnc-date.cpp.

207 {
208  /* icu's day of week is 1 based. Using 0 here to mean unset or error while setting */
209  static int cached_result = 0;
210 
211  if (!cached_result)
212  {
213  UErrorCode err = U_ZERO_ERROR;
214  auto cal = icu::Calendar::createInstance (err);
215  if (!cal)
216  {
217  PERR("ICU error: %s\n", u_errorName (err));
218  return 0;
219  }
220 
221  /* 1 for sunday, 2 for monday, etc. */
222  cached_result = cal->getFirstDayOfWeek (err);
223  delete cal;
224  }
225 
226  return cached_result;
227 }
#define PERR(format, args...)
Log a serious error.
Definition: qoflog.h:244

◆ gnc_time()

time64 gnc_time ( time64 tbuf)

get the current local time

Parameters
Atime64* which, if not NULL, will be filled in with the same value as is returned.
Returns
Seconds since 00:00:01 UTC 01 January 1970 (negative values are seconds before that moment)

Definition at line 273 of file gnc-date.cpp.

274 {
275  GncDateTime gncdt;
276  auto time = static_cast<time64>(gncdt);
277  if (tbuf != NULL)
278  *tbuf = time;
279  return time;
280 }
GnuCash DateTime class.
gint64 time64
Many systems, including Microsoft Windows and BSD-derived Unixes like Darwin, are retaining the int-3...
Definition: gnc-date.h:93

◆ gnc_time64_to_iso8601_buff()

gchar* gnc_time64_to_iso8601_buff ( time64  ,
char *  buff 
)

The gnc_time64_to_iso8601_buff() routine takes the input UTC time64 value and prints it as an ISO-8601 style string.

The buffer must be long enough to contain the NULL-terminated string (32 characters + NUL). This routine returns a pointer to the null terminator (and can thus be used in the 'stpcpy' metaphor of string concatenation).

Please note that ISO-8601 strings are a representation of Universal Time (UTC), and as such, they 'store' UTC. To make them human readable, they show time zone information along with a local-time string. But fundamentally, they are UTC. Thus, this routine takes a UTC input, and returns a UTC output.

The string generated by this routine uses the local time zone on the machine on which it is executing to create the time string.

Definition at line 1142 of file gnc-date.cpp.

1143 {
1144  constexpr size_t max_iso_date_length = 32;
1145 
1146  if (! buff) return NULL;
1147  try
1148  {
1149  GncDateTime gncdt(time);
1150  auto sstr = gncdt.format_iso8601();
1151 
1152  memset(buff, 0, sstr.length() + 1);
1153  strncpy(buff, sstr.c_str(), sstr.length());
1154  return buff + sstr.length();
1155  }
1156  catch(std::logic_error& err)
1157  {
1158  PWARN("Error processing time64 %" PRId64 ": %s", time, err.what());
1159  return buff;
1160  }
1161  catch(std::runtime_error& err)
1162  {
1163  PWARN("Error processing time64 %" PRId64 ": %s", time, err.what());
1164  return buff;
1165  }
1166 }
GnuCash DateTime class.
#define PWARN(format, args...)
Log a warning.
Definition: qoflog.h:250

◆ gnc_timegm()

time64 gnc_timegm ( struct tm *  time)

calculate seconds from the epoch given a time struct

Parameters
timeA struct tm* containing the date-time information The time is understood to be utc.
Returns
Seconds since 00:00:01 UTC 01 January 1970 (negative values are seconds before that moment).

Definition at line 246 of file gnc-date.cpp.

247 {
248  try
249  {
250  normalize_struct_tm(time);
251  GncDateTime gncdt(*time);
252  *time = static_cast<struct tm>(gncdt);
253  time->tm_sec -= gncdt.offset();
254  normalize_struct_tm(time);
255 #ifdef HAVE_STRUcT_TM_GMTOFF
256  time->tm_gmtoff = 0;
257 #endif
258  return static_cast<time64>(gncdt) - gncdt.offset();
259  }
260  catch(std::invalid_argument&)
261  {
262  return 0;
263  }
264 }
GnuCash DateTime class.
gint64 time64
Many systems, including Microsoft Windows and BSD-derived Unixes like Darwin, are retaining the int-3...
Definition: gnc-date.h:93

◆ gnc_tm_free()

void gnc_tm_free ( struct tm *  time)

free a struct tm* created with gnc_localtime() or gnc_gmtime()

Parameters
timeThe struct tm* to be freed.

Definition at line 99 of file gnc-date.cpp.

100 {
101  free(time);
102 }

◆ time64CanonicalDayTime()

time64 time64CanonicalDayTime ( time64  t)

convert a time64 on a certain day (localtime) to the time64 representing midday on that day.

Watch out - this is not the first second of the day, which is returned by various other functions returning a time64.

Definition at line 413 of file gnc-date.cpp.

414 {
415  struct tm tm;
416  gnc_localtime_r(&t, &tm);
417  gnc_tm_set_day_middle(&tm);
418  return gnc_mktime (&tm);
419 }
struct tm * gnc_localtime_r(const time64 *secs, struct tm *time)
fill out a time struct from a 64-bit time value adjusted for the current time zone.
Definition: gnc-date.cpp:117
time64 gnc_mktime(struct tm *time)
calculate seconds from the epoch given a time struct
Definition: gnc-date.cpp:230

Variable Documentation

◆ gnc_default_strftime_date_format

const char* gnc_default_strftime_date_format

The default date format for use with strftime.

Definition at line 76 of file gnc-date.cpp.