GnuCash  2.6.99
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  Timespec
 Use a 64-bit unsigned int timespec. More...
 

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...
 
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...
 
void qof_date_completion_set (QofDateCompletion dc, int backmonths)
 The qof_date_completion_set() routing sets the date completion method to one of QOF_DATE_COMPLETION_THISYEAR (for completing the year to the current calendar year) or QOF_DATE_COMPLETION_SLIDING (for using a sliding 12-month window). More...
 
gchar dateSeparator (void)
 dateSeparator Return the field separator for the current date format More...
 

Variables

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

GValue

GType timespec_get_type (void)
 
#define GNC_TYPE_TIMESPEC   (timespec_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 * gnc_g_date_new_today (void)
 Returns a newly allocated date of the current clock time, taken from time(2). More...
 

Timespec functions

gboolean timespec_equal (const Timespec *ta, const Timespec *tb)
 strict equality
 
gint timespec_cmp (const Timespec *ta, const Timespec *tb)
 comparison: if (ta < tb) -1; else if (ta > tb) 1; else 0;
 
Timespec timespec_diff (const Timespec *ta, const Timespec *tb)
 difference between ta and tb, results are normalized ie tv_sec and tv_nsec of the result have the same size abs(result.tv_nsec) <= 1000000000
 
Timespec timespec_abs (const Timespec *t)
 absolute value, also normalized
 
Timespec timespecCanonicalDayTime (Timespec t)
 convert a timepair on a certain day (localtime) to the timepair representing midday on that day. More...
 
Timespec timespec_now (void)
 Returns the current clock time as a Timespec, taken from time(2). More...
 
void timespecFromTime64 (Timespec *ts, time64 t)
 Turns a time64 into a Timespec.
 
time64 timespecToTime64 (Timespec ts)
 Turns a Timespec into a time64.
 
GDate timespec_to_gdate (Timespec ts)
 Turns a Timespec into a GDate.
 
Timespec gdate_to_timespec (GDate d)
 Turns a GDate into a Timespec, returning the first second of the day.
 
Timespec gnc_dmy2timespec (gint day, gint month, gint year)
 Convert a day, month, and year to a Timespec, returning the first second of the day.
 
Timespec gnc_dmy2timespec_end (gint day, gint month, gint year)
 Same as gnc_dmy2timespec, but last second of the day.
 
Timespec gnc_dmy2timespec_neutral (gint day, gint month, gint year)
 Converts a day, month, and year to a Timespec 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...
 
Timespec gnc_iso8601_to_timespec_gmt (const gchar *)
 The gnc_iso8601_to_timespec_gmt() routine converts an ISO-8601 style date/time string to Timespec. More...
 
gchar * gnc_timespec_to_iso8601_buff (Timespec ts, gchar *buff)
 The gnc_timespec_to_iso8601_buff() routine takes the input UTC Timespec value and prints it as an ISO-8601 style string. More...
 
void gnc_timespec2dmy (Timespec ts, gint *day, gint *month, gint *year)
 Set the proleptic Gregorian day, month, and year from a Timespec. More...
 

QofDateFormat functions

QofDateFormat qof_date_format_get (void)
 The qof_date_format_get routine returns the date format that the date printing will use when printing a date, and the scanning routines will assume when parsing a date. More...
 
void qof_date_format_set (QofDateFormat df)
 The qof_date_format_set() routine sets date format to one of US, UK, CE, OR ISO. More...
 
const gchar * qof_date_format_get_string (QofDateFormat df)
 This function returns a strftime formatting string for printing an all numeric date (e.g. More...
 
const gchar * qof_date_text_format_get_string (QofDateFormat df)
 This function returns a strftime formatting string for printing a date using words and numbers (e.g. More...
 

Date Printing/Scanning functions

gsize qof_strftime (gchar *buf, gsize max, const gchar *format, const struct tm *tm)
 qof_strftime calls qof_format_time to print a given time and afterwards tries to put the result into a buffer of fixed size. More...
 
size_t qof_print_date_dmy_buff (gchar *buff, size_t buflen, int day, int month, int year)
 qof_print_date_dmy_buff Convert a date as day / month / year integers into a localized string representation More...
 
size_t qof_print_date_buff (char *buff, size_t buflen, time64 secs)
 Convenience: calls through to qof_print_date_dmy_buff(). More...
 
size_t qof_print_gdate (char *buf, size_t bufflen, const GDate *gd)
 Convenience; calls through to qof_print_date_dmy_buff(). More...
 
char * qof_print_date (time64 secs)
 Convenience; calls through to qof_print_date_dmy_buff(). More...
 
const char * gnc_print_date (Timespec ts)
 Convenience; calls through to qof_print_date_dmy_buff(). More...
 
size_t qof_print_date_time_buff (char *buff, size_t len, time64 secs)
 Returns the number of bytes printed.
 
gboolean qof_scan_date (const char *buff, int *day, int *month, int *year)
 qof_scan_date Convert a string into day / month / year integers according to the current dateFormat value. More...
 

Date Start/End Adjustment routines

Given a time value, adjust it to be the beginning or end of that day.

time64 gnc_time64_get_day_start (time64 time_val)
 The gnc_time64_get_day_start() routine will take the given time in seconds and adjust it to the last second of that day. More...
 
time64 gnc_time64_get_day_end (time64 time_val)
 The gnc_time64_get_day_end() routine will take the given time in seconds and adjust it to the last second of that day. More...
 
int gnc_date_get_last_mday (int month, int year)
 Get the numerical last date of the month. More...
 

Today's Date

void gnc_tm_get_today_start (struct tm *tm)
 The gnc_tm_get_today_start() routine takes a pointer to a struct tm and fills it in with the first second of the today. More...
 
void gnc_tm_get_today_end (struct tm *tm)
 The gnc_tm_get_today_end() routine takes a pointer to a struct tm and fills it in with the last second of the today. More...
 
time64 gnc_time64_get_today_start (void)
 The gnc_time64_get_today_start() routine returns a time64 value corresponding to the first second of today. More...
 
time64 gnc_time64_get_today_end (void)
 The gnc_time64_get_today_end() routine returns a time64 value corresponding to the last second of today. More...
 
char * gnc_date_timestamp (void)
 Make a timestamp in YYYYMMDDHHMMSS format. More...
 
void gnc_dow_abbrev (gchar *buf, int buf_len, int dow)
 Localized DOW abbreviation. More...
 
#define MIN_BUF_LEN   10
 

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 145 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 118 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 83 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 137 of file gnc-date.h.

138 {
QofDateCompletion
Enum for date completion modes (for dates entered without year)
Definition: gnc-date.h:137
use sliding 12-month window
Definition: gnc-date.h:140
use current year
Definition: gnc-date.h:139

◆ 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 121 of file gnc-date.h.

122 {
131 } QofDateFormat;
ISO: yyyy-mm-dd.
Definition: gnc-date.h:126
Used by the check printing code.
Definition: gnc-date.h:129
Continental Europe: dd.mm.yyyy.
Definition: gnc-date.h:125
No Fancy Date Format, use Global.
Definition: gnc-date.h:130
UTC: 2004-12-12T23:39:11Z.
Definition: gnc-date.h:128
Take from locale information.
Definition: gnc-date.h:127
Britain: dd/mm/yyyy.
Definition: gnc-date.h:124
QofDateFormat
Enum for determining a date format.
Definition: gnc-date.h:121
United states: mm/dd/yyyy.
Definition: gnc-date.h:123

Function Documentation

◆ dateSeparator()

gchar dateSeparator ( void  )

dateSeparator Return the field separator for the current date format

Args: none

Return: date character

Globals: global dateFormat value

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

1002 {
1003  static char locale_separator = '\0';
1004 
1005  switch (dateFormat)
1006  {
1007  case QOF_DATE_FORMAT_CE:
1008  return '.';
1009  case QOF_DATE_FORMAT_ISO:
1010  case QOF_DATE_FORMAT_UTC:
1011  return '-';
1012  case QOF_DATE_FORMAT_US:
1013  case QOF_DATE_FORMAT_UK:
1014  default:
1015  return '/';
1017  if (locale_separator != '\0')
1018  return locale_separator;
1019  else
1020  {
1021  /* Make a guess */
1022  gchar string[256];
1023  struct tm tm;
1024  time64 secs;
1025  gchar *s;
1026 
1027  secs = gnc_time (NULL);
1028  gnc_localtime_r(&secs, &tm);
1029  qof_strftime(string, sizeof(string), GNC_D_FMT, &tm);
1030 
1031  for (s = string; *s != '\0'; s++)
1032  if (!isdigit(*s))
1033  return (locale_separator = *s);
1034  }
1035  break;
1036  }
1037 
1038  return '\0';
1039 }
ISO: yyyy-mm-dd.
Definition: gnc-date.h:126
Continental Europe: dd.mm.yyyy.
Definition: gnc-date.h:125
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:115
UTC: 2004-12-12T23:39:11Z.
Definition: gnc-date.h:128
gsize qof_strftime(gchar *buf, gsize max, const gchar *format, const struct tm *tm)
qof_strftime calls qof_format_time to print a given time and afterwards tries to put the result into ...
Definition: gnc-date.cpp:1130
time64 gnc_time(time64 *tbuf)
get the current local time
Definition: gnc-date.cpp:239
gint64 time64
Many systems, including Microsoft Windows and BSD-derived Unixes like Darwin, are retaining the int-3...
Definition: gnc-date.h:83
Take from locale information.
Definition: gnc-date.h:127
Britain: dd/mm/yyyy.
Definition: gnc-date.h:124
United states: mm/dd/yyyy.
Definition: gnc-date.h:123

◆ 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 233 of file gnc-date.cpp.

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

◆ gnc_date_get_last_mday()

int gnc_date_get_last_mday ( int  month,
int  year 
)

Get the numerical last date of the month.

(28, 29, 30, 31)

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

485 {
486  static int last_day_of_month[2][12] =
487  {
488  /* non leap */ {31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31},
489  /* leap */ {31, 29, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31}
490  };
491 
492  /* Is this a leap year? */
493  if (year % 2000 == 0) return last_day_of_month[1][month];
494  if (year % 400 == 0 ) return last_day_of_month[0][month];
495  if (year % 4 == 0 ) return last_day_of_month[1][month];
496  return last_day_of_month[0][month];
497 }

◆ 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_date_timestamp()

char* gnc_date_timestamp ( void  )

Make a timestamp in YYYYMMDDHHMMSS format.

Returns
A pointer to the generated string.
Note
The caller owns this buffer and must g_free it when done.

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

1177 {
1178  return gnc_print_time64(gnc_time(nullptr), "%Y%m%d%H%M%S");
1179 }
char * gnc_print_time64(time64 time, const char *format)
print a time64 as a date string per format
Definition: gnc-date.cpp:347
time64 gnc_time(time64 *tbuf)
get the current local time
Definition: gnc-date.cpp:239

◆ 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 249 of file gnc-date.cpp.

250 {
251  return (double)secs1 - (double)secs2;
252 }

◆ gnc_dmy2timespec_neutral()

Timespec gnc_dmy2timespec_neutral ( gint  day,
gint  month,
gint  year 
)

Converts a day, month, and year to a Timespec 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_dow_abbrev()

void gnc_dow_abbrev ( gchar *  buf,
int  buf_len,
int  dow 
)

Localized DOW abbreviation.

Parameters
buf_lenat least MIN_BUF_LEN
dowstruct tm semantics: 0=sunday .. 6=saturday

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

1430 {
1431  struct tm my_tm;
1432  int i;
1433 
1434  memset(buf, 0, buf_len);
1435  memset(&my_tm, 0, sizeof(struct tm));
1436  my_tm.tm_wday = dow;
1437  i = qof_strftime(buf, buf_len, "%a", &my_tm);
1438  buf[i] = 0;
1439 }
gsize qof_strftime(gchar *buf, gsize max, const gchar *format, const struct tm *tm)
qof_strftime calls qof_format_time to print a given time and afterwards tries to put the result into ...
Definition: gnc-date.cpp:1130

◆ 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 1338 of file gnc-date.cpp.

1339 {
1340  GncDate gncd;
1341  auto ymd = gncd.year_month_day();
1342  auto month = static_cast<GDateMonth>(ymd.month);
1343  auto result = g_date_new_dmy (ymd.day, month, ymd.year);
1344  g_assert(g_date_valid (result));
1345  return result;
1346 }
ymd year_month_day() const
Get the year, month, and day from the date as a ymd.
GnuCash Date class.

◆ 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 187 of file gnc-date.cpp.

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

◆ gnc_iso8601_to_timespec_gmt()

Timespec gnc_iso8601_to_timespec_gmt ( const gchar *  )

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

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 103 of file gnc-date.cpp.

104 {
105  auto time = static_cast<struct tm*>(calloc(1, sizeof(struct tm)));
106  if (gnc_localtime_r (secs, time) == NULL)
107  {
108  gnc_tm_free (time);
109  return NULL;
110  }
111  return time;
112 }
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:115
void gnc_tm_free(struct tm *time)
free a struct tm* created with gnc_localtime() or gnc_gmtime()
Definition: gnc-date.cpp:97

◆ 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 115 of file gnc-date.cpp.

116 {
117  try
118  {
119  *time = static_cast<struct tm>(GncDateTime(*secs));
120  return time;
121  }
122  catch(std::invalid_argument)
123  {
124  return NULL;
125  }
126 }
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 204 of file gnc-date.cpp.

205 {
206  try
207  {
208  normalize_struct_tm (time);
209  GncDateTime gncdt(*time);
210  return static_cast<time64>(gncdt) - gncdt.offset();
211  }
212  catch(std::invalid_argument)
213  {
214  return 0;
215  }
216 }
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:83

◆ gnc_print_date()

const char* gnc_print_date ( Timespec  ts)

Convenience; calls through to qof_print_date_dmy_buff().

Return: static global string.

Warning
This routine is not thread-safe, because it uses a single global buffer to store the return value. Use qof_print_date_buff() or qof_print_date() instead.

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

688 {
689  static char buff[MAX_DATE_LENGTH];
690  time64 t;
691 
692  memset (buff, 0, sizeof (buff));
693  t = ts.tv_sec + (time64)(ts.tv_nsec / 1000000000.0);
694 
696 
697  return buff;
698 }
#define MAX_DATE_LENGTH
The maximum length of a string created by the date printers.
Definition: gnc-date.h:106
gint64 time64
Many systems, including Microsoft Windows and BSD-derived Unixes like Darwin, are retaining the int-3...
Definition: gnc-date.h:83
size_t qof_print_date_buff(char *buff, size_t len, time64 t)
Convenience: calls through to qof_print_date_dmy_buff().
Definition: gnc-date.cpp:642

◆ gnc_print_time64()

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

print a time64 as a date string per format

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

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

348 {
349  try
350  {
351  GncDateTime gncdt(time);
352  auto sstr = gncdt.format(format);
353  //ugly C allocation so that the ptr can be freed at the other end
354  char* cstr = static_cast<char*>(malloc(sstr.length() + 1));
355  memset(cstr, 0, sstr.length() + 1);
356  strncpy(cstr, sstr.c_str(), sstr.length());
357  return cstr;
358  }
359  catch(std::runtime_error& err)
360  {
361  PWARN("Error processing time64 %" PRId64 ": %s", time, err.what());
362  return nullptr;
363  }
364  catch(std::logic_error& err)
365  {
366  PWARN("Error processing time64 %" PRId64 ": %s", time, err.what());
367  return nullptr;
368  }
369 }
GnuCash DateTime class.
#define PWARN(format, args...)
Log a warning.
Definition: qoflog.h:243

◆ 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 239 of file gnc-date.cpp.

240 {
241  GncDateTime gncdt;
242  auto time = static_cast<time64>(gncdt);
243  if (tbuf != NULL)
244  *tbuf = time;
245  return time;
246 }
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:83

◆ gnc_time64_get_day_end()

time64 gnc_time64_get_day_end ( time64  time_val)

The gnc_time64_get_day_end() routine will take the given time in seconds and adjust it to the last second of that day.

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

1386 {
1387  struct tm tm;
1388  time64 new_time;
1389 
1390  gnc_tm_get_day_end(&tm, time_val);
1391  new_time = gnc_mktime(&tm);
1392  return new_time;
1393 }
time64 gnc_mktime(struct tm *time)
calculate seconds from the epoch given a time struct
Definition: gnc-date.cpp:204
gint64 time64
Many systems, including Microsoft Windows and BSD-derived Unixes like Darwin, are retaining the int-3...
Definition: gnc-date.h:83

◆ gnc_time64_get_day_start()

time64 gnc_time64_get_day_start ( time64  time_val)

The gnc_time64_get_day_start() routine will take the given time in seconds and adjust it to the last second of that day.

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

1375 {
1376  struct tm tm;
1377  time64 new_time;
1378 
1379  gnc_tm_get_day_start(&tm, time_val);
1380  new_time = gnc_mktime(&tm);
1381  return new_time;
1382 }
time64 gnc_mktime(struct tm *time)
calculate seconds from the epoch given a time struct
Definition: gnc-date.cpp:204
gint64 time64
Many systems, including Microsoft Windows and BSD-derived Unixes like Darwin, are retaining the int-3...
Definition: gnc-date.h:83

◆ gnc_time64_get_today_end()

time64 gnc_time64_get_today_end ( void  )

The gnc_time64_get_today_end() routine returns a time64 value corresponding to the last second of today.

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

1421 {
1422  struct tm tm;
1423 
1424  gnc_tm_get_day_end(&tm, time(NULL));
1425  return gnc_mktime(&tm);
1426 }
time64 gnc_mktime(struct tm *time)
calculate seconds from the epoch given a time struct
Definition: gnc-date.cpp:204

◆ gnc_time64_get_today_start()

time64 gnc_time64_get_today_start ( void  )

The gnc_time64_get_today_start() routine returns a time64 value corresponding to the first second of today.

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

1412 {
1413  struct tm tm;
1414 
1415  gnc_tm_get_day_start(&tm, time(NULL));
1416  return gnc_mktime(&tm);
1417 }
time64 gnc_mktime(struct tm *time)
calculate seconds from the epoch given a time struct
Definition: gnc-date.cpp:204

◆ 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 219 of file gnc-date.cpp.

220 {
221  try
222  {
223  normalize_struct_tm(time);
224  return static_cast<time64>(GncDateTime(*time));
225  }
226  catch(std::invalid_argument)
227  {
228  return 0;
229  }
230 }
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:83

◆ gnc_timespec2dmy()

void gnc_timespec2dmy ( Timespec  ts,
gint *  day,
gint *  month,
gint *  year 
)

Set the proleptic Gregorian day, month, and year from a Timespec.

Parameters
tsinput timespec
dayoutput day, 1 - 31
monthoutput month, 1 - 12
yearoutput year, 0001 - 9999 CE

◆ gnc_timespec_to_iso8601_buff()

gchar* gnc_timespec_to_iso8601_buff ( Timespec  ts,
gchar *  buff 
)

The gnc_timespec_to_iso8601_buff() routine takes the input UTC Timespec 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.

◆ 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 97 of file gnc-date.cpp.

98 {
99  free(time);
100 }

◆ gnc_tm_get_today_end()

void gnc_tm_get_today_end ( struct tm *  tm)

The gnc_tm_get_today_end() routine takes a pointer to a struct tm and fills it in with the last second of the today.

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

1406 {
1407  gnc_tm_get_day_end(tm, time(NULL));
1408 }

◆ gnc_tm_get_today_start()

void gnc_tm_get_today_start ( struct tm *  tm)

The gnc_tm_get_today_start() routine takes a pointer to a struct tm and fills it in with the first second of the today.

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

1400 {
1401  gnc_tm_get_day_start(tm, time(NULL));
1402 }

◆ qof_date_completion_set()

void qof_date_completion_set ( QofDateCompletion  dc,
int  backmonths 
)

The qof_date_completion_set() routing sets the date completion method to one of QOF_DATE_COMPLETION_THISYEAR (for completing the year to the current calendar year) or QOF_DATE_COMPLETION_SLIDING (for using a sliding 12-month window).

The sliding window starts 'backmonth' months before the current month (0-11)

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

538 {
539  if (dc == QOF_DATE_COMPLETION_THISYEAR ||
541  {
542  dateCompletion = dc;
543  }
544  else
545  {
546  /* hack alert - Use a neutral default. */
547  PERR("non-existent date completion set attempted. Setting current year completion as default");
548  dateCompletion = QOF_DATE_COMPLETION_THISYEAR;
549  }
550 
551  if (backmonths < 0)
552  {
553  backmonths = 0;
554  }
555  else if (backmonths > 11)
556  {
557  backmonths = 11;
558  }
559  dateCompletionBackMonths = backmonths;
560 
561  return;
562 }
#define PERR(format, args...)
Log a serious error.
Definition: qoflog.h:237
use sliding 12-month window
Definition: gnc-date.h:140
use current year
Definition: gnc-date.h:139

◆ qof_date_format_get()

QofDateFormat qof_date_format_get ( void  )

The qof_date_format_get routine returns the date format that the date printing will use when printing a date, and the scanning routines will assume when parsing a date.

Returns
: the one of the enumerated date formats.

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

500 {
501  return dateFormat;
502 }

◆ qof_date_format_get_string()

const gchar* qof_date_format_get_string ( QofDateFormat  df)

This function returns a strftime formatting string for printing an all numeric date (e.g.

2005-09-14). The string returned is based upon the location specified.

Parameters
dfThe date style (us, uk, iso, etc) that should be provided.
Returns
A formatting string that will print a date in the requested style

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

572 {
573  switch (df)
574  {
575  case QOF_DATE_FORMAT_US:
576  return "%m/%d/%Y";
577  case QOF_DATE_FORMAT_UK:
578  return "%d/%m/%Y";
579  case QOF_DATE_FORMAT_CE:
580  return "%d.%m.%Y";
581  case QOF_DATE_FORMAT_UTC:
582  return "%Y-%m-%dT%H:%M:%SZ";
583  case QOF_DATE_FORMAT_ISO:
584  return "%Y-%m-%d";
585  case QOF_DATE_FORMAT_UNSET: // use global
586  return qof_date_format_get_string (dateFormat);
588  default:
589  break;
590  };
591  return GNC_D_FMT;
592 }
ISO: yyyy-mm-dd.
Definition: gnc-date.h:126
Continental Europe: dd.mm.yyyy.
Definition: gnc-date.h:125
No Fancy Date Format, use Global.
Definition: gnc-date.h:130
const gchar * qof_date_format_get_string(QofDateFormat df)
This function returns a strftime formatting string for printing an all numeric date (e...
Definition: gnc-date.cpp:571
UTC: 2004-12-12T23:39:11Z.
Definition: gnc-date.h:128
Take from locale information.
Definition: gnc-date.h:127
Britain: dd/mm/yyyy.
Definition: gnc-date.h:124
United states: mm/dd/yyyy.
Definition: gnc-date.h:123

◆ qof_date_format_set()

void qof_date_format_set ( QofDateFormat  df)

The qof_date_format_set() routine sets date format to one of US, UK, CE, OR ISO.

Checks to make sure it's a legal value. Args: QofDateFormat: enumeration indicating preferred format

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

505 {
506  if (df >= DATE_FORMAT_FIRST && df <= DATE_FORMAT_LAST)
507  {
508  prevQofDateFormat = dateFormat;
509  dateFormat = df;
510  }
511  else
512  {
513  /* hack alert - Use a neutral default. */
514  PERR("non-existent date format set attempted. Setting ISO default");
515  prevQofDateFormat = dateFormat;
516  dateFormat = QOF_DATE_FORMAT_ISO;
517  }
518 
519  return;
520 }
ISO: yyyy-mm-dd.
Definition: gnc-date.h:126
#define PERR(format, args...)
Log a serious error.
Definition: qoflog.h:237

◆ qof_date_text_format_get_string()

const gchar* qof_date_text_format_get_string ( QofDateFormat  df)

This function returns a strftime formatting string for printing a date using words and numbers (e.g.

2005-September-14). The string returned is based upon the location specified.

Parameters
dfThe date style (us, uk, iso, etc) that should be provided.
Returns
A formatting string that will print a date in the requested style

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

595 {
596  switch (df)
597  {
598  case QOF_DATE_FORMAT_US:
599  return "%b %d, %Y";
600  case QOF_DATE_FORMAT_UK:
601  case QOF_DATE_FORMAT_CE:
602  return "%d %b %Y";
603  case QOF_DATE_FORMAT_UTC:
604  return "%Y-%m-%dT%H:%M:%SZ";
605  case QOF_DATE_FORMAT_ISO:
606  return "%Y-%b-%d";
607  case QOF_DATE_FORMAT_UNSET: // use global
608  return qof_date_text_format_get_string (dateFormat);
610  default:
611  break;
612  };
613  return GNC_D_FMT;
614 }
ISO: yyyy-mm-dd.
Definition: gnc-date.h:126
Continental Europe: dd.mm.yyyy.
Definition: gnc-date.h:125
const gchar * qof_date_text_format_get_string(QofDateFormat df)
This function returns a strftime formatting string for printing a date using words and numbers (e...
Definition: gnc-date.cpp:594
No Fancy Date Format, use Global.
Definition: gnc-date.h:130
UTC: 2004-12-12T23:39:11Z.
Definition: gnc-date.h:128
Take from locale information.
Definition: gnc-date.h:127
Britain: dd/mm/yyyy.
Definition: gnc-date.h:124
United states: mm/dd/yyyy.
Definition: gnc-date.h:123

◆ qof_print_date()

char* qof_print_date ( time64  secs)

Convenience; calls through to qof_print_date_dmy_buff().

Return: string, which should be freed when no longer needed.

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

679 {
680  char buff[MAX_DATE_LENGTH];
681  memset (buff, 0, sizeof (buff));
683  return g_strdup (buff);
684 }
#define MAX_DATE_LENGTH
The maximum length of a string created by the date printers.
Definition: gnc-date.h:106
size_t qof_print_date_buff(char *buff, size_t len, time64 t)
Convenience: calls through to qof_print_date_dmy_buff().
Definition: gnc-date.cpp:642

◆ qof_print_date_buff()

size_t qof_print_date_buff ( char *  buff,
size_t  buflen,
time64  secs 
)

Convenience: calls through to qof_print_date_dmy_buff().

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

643 {
644  if (!buff) return 0;
645 
646  try
647  {
648  GncDateTime gncdt(t);
649  std::string str = gncdt.format(qof_date_format_get_string(dateFormat));
650  strncpy(buff, str.c_str(), len);
651  if (str.length() >= len)
652  buff[len - 1] = '\0';
653  }
654  catch(std::logic_error& err)
655  {
656  PWARN("Error processing time64 %" PRId64 ": %s", t, err.what());
657  }
658  catch(std::runtime_error& err)
659  {
660  PWARN("Error processing time64 %" PRId64 ": %s", t, err.what());
661  }
662  return strlen(buff);
663 }
GnuCash DateTime class.
#define PWARN(format, args...)
Log a warning.
Definition: qoflog.h:243
const gchar * qof_date_format_get_string(QofDateFormat df)
This function returns a strftime formatting string for printing an all numeric date (e...
Definition: gnc-date.cpp:571

◆ qof_print_date_dmy_buff()

size_t qof_print_date_dmy_buff ( gchar *  buff,
size_t  buflen,
int  day,
int  month,
int  year 
)

qof_print_date_dmy_buff Convert a date as day / month / year integers into a localized string representation

Args: buff - pointer to previously allocated character array; its size must be at lease MAX_DATE_LENTH bytes. len - length of the buffer, in bytes. day - day of the month as 1 ... 31 month - month of the year as 1 ... 12 year - year (4-digit)

Returns: number of characters printed

Globals: global dateFormat value

◆ qof_print_gdate()

size_t qof_print_gdate ( char *  buf,
size_t  bufflen,
const GDate *  gd 
)

Convenience; calls through to qof_print_date_dmy_buff().

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

667 {
668  GDate date;
669  g_date_clear (&date, 1);
670  date = *gd;
671  return qof_print_date_dmy_buff( buf, len,
672  g_date_get_day(&date),
673  g_date_get_month(&date),
674  g_date_get_year(&date) );
675 }
size_t qof_print_date_dmy_buff(gchar *buff, size_t buflen, int day, int month, int year)
qof_print_date_dmy_buff Convert a date as day / month / year integers into a localized string represe...

◆ qof_scan_date()

gboolean qof_scan_date ( const char *  buff,
int *  day,
int *  month,
int *  year 
)

qof_scan_date Convert a string into day / month / year integers according to the current dateFormat value.

Args: buff - pointer to date string day - will store day of the month as 1 ... 31 month - will store month of the year as 1 ... 12 year - will store the year (4-digit)

Return: TRUE if the string seemed to be a valid date; else FALSE.

Globals: uses global dateFormat value to assist in parsing.

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

994 {
995  return qof_scan_date_internal(buff, day, month, year, dateFormat);
996 }

◆ qof_strftime()

gsize qof_strftime ( gchar *  buf,
gsize  max,
const gchar *  format,
const struct tm *  tm 
)

qof_strftime calls qof_format_time to print a given time and afterwards tries to put the result into a buffer of fixed size.

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 thing needs date handling, it should do it itself, instead of depending on the routines here.
Parameters
bufA buffer.
maxThe size of buf in bytes.
formatA format specification in UTF-8.
tmA broken-down time.
Returns
The number of characters written, not include the null byte, if the complete string, including the null byte, fits into the buffer. Otherwise 0.

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

1131 {
1132  gsize convlen, retval;
1133  gchar *convbuf;
1134 
1135  g_return_val_if_fail(buf, 0);
1136  g_return_val_if_fail(max > 0, 0);
1137  g_return_val_if_fail(format, 0);
1138  g_return_val_if_fail(tm, 0);
1139 
1140  convbuf = qof_format_time(format, tm);
1141  if (!convbuf)
1142  {
1143  buf[0] = '\0';
1144  return 0;
1145  }
1146 
1147  convlen = strlen(convbuf);
1148 
1149  if (max <= convlen)
1150  {
1151  /* Ensure only whole characters are copied into the buffer. */
1152  gchar *end = g_utf8_find_prev_char(convbuf, convbuf + max);
1153  g_assert(end != NULL);
1154  convlen = end - convbuf;
1155 
1156  /* Return 0 because the buffer isn't large enough. */
1157  retval = 0;
1158  }
1159  else
1160  {
1161  retval = convlen;
1162  }
1163 
1164  memcpy(buf, convbuf, convlen);
1165  buf[convlen] = '\0';
1166  g_free(convbuf);
1167 
1168  return retval;
1169 }

◆ timespec_now()

Timespec timespec_now ( void  )

Returns the current clock time as a Timespec, taken from time(2).

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

1308 {
1309  Timespec ts;
1310  ts.tv_sec = gnc_time(NULL);
1311  ts.tv_nsec = 0;
1312  return ts;
1313 }
time64 gnc_time(time64 *tbuf)
get the current local time
Definition: gnc-date.cpp:239

◆ timespecCanonicalDayTime()

Timespec timespecCanonicalDayTime ( Timespec  t)

convert a timepair on a certain day (localtime) to the timepair 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 Timespec.

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

472 {
473  struct tm tm;
474  Timespec retval;
475  time64 t_secs = t.tv_sec + (t.tv_nsec / NANOS_PER_SECOND);
476  gnc_localtime_r(&t_secs, &tm);
477  gnc_tm_set_day_middle(&tm);
478  retval.tv_sec = gnc_mktime(&tm);
479  retval.tv_nsec = 0;
480  return retval;
481 }
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:115
time64 gnc_mktime(struct tm *time)
calculate seconds from the epoch given a time struct
Definition: gnc-date.cpp:204
gint64 time64
Many systems, including Microsoft Windows and BSD-derived Unixes like Darwin, are retaining the int-3...
Definition: gnc-date.h:83

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 74 of file gnc-date.cpp.