Date: Date and Time Printing, Parsing and Manipulation
[Query Object Framework]

---

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-Grenwich (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 <rclark@cs.hmc.edu>

Copyright (C) 1998-2001,2003 Linas Vepstas <linas@linas.org>

Files
file	gnc-date.h
	Date and Time handling routines.
Data Structures
struct	timespec64
	Use a 64-bit signed int timespec. More...
String / DateFormat conversion.
const char *	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 char *format_string, QofDateFormat *format)
	Converts the date format to a printable string.
const char *	gnc_date_monthformat_to_string (GNCDateMonthFormat format)
gboolean	gnc_date_string_to_monthformat (const char *format_string, GNCDateMonthFormat *format)
	Converts the month format to a printable string.
Timespec functions
gboolean	timespec_equal (const Timespec *ta, const Timespec *tb)
int	timespec_cmp (const Timespec *ta, const Timespec *tb)
Timespec	timespec_diff (const Timespec *ta, const Timespec *tb)
Timespec	timespec_abs (const Timespec *t)
Timespec	timespecCanonicalDayTime (Timespec t)
void	timespecFromTime_t (Timespec *ts, time_t t)
time_t	timespecToTime_t (Timespec ts)
Timespec	gnc_dmy2timespec (int day, int month, int year)
Timespec	gnc_dmy2timespec_end (int day, int month, int year)
Timespec	gnc_iso8601_to_timespec_gmt (const char *)
char *	gnc_timespec_to_iso8601_buff (Timespec ts, char *buff)
void	gnc_timespec2dmy (Timespec ts, int *day, int *month, int *year)
void	date_add_months (struct tm *tm, int months, gboolean track_last_day)
time_t	xaccDMYToSec (int day, int month, int year)
long int	gnc_timezone (struct tm *tm)
QofDateFormat functions
QofDateFormat	qof_date_format_get (void)
void	qof_date_format_set (QofDateFormat df)
const gchar *	qof_date_format_get_string (QofDateFormat df)
const gchar *	qof_date_text_format_get_string (QofDateFormat df)
Date Printing/Scanning functions
size_t	qof_print_date_dmy_buff (char *buff, size_t buflen, int day, int month, int year)
size_t	qof_print_date_buff (char *buff, size_t buflen, time_t secs)
size_t	qof_print_gdate (char *buf, size_t bufflen, GDate *gd)
char *	qof_print_date (time_t secs)
const char *	gnc_print_date (Timespec ts)
size_t	qof_print_hours_elapsed_buff (char *buff, size_t len, int secs, gboolean show_secs)
size_t	qof_print_minutes_elapsed_buff (char *buff, size_t len, int secs, gboolean show_secs)
size_t	qof_print_time_buff (char *buff, size_t len, time_t secs)
size_t	qof_print_date_time_buff (char *buff, size_t len, time_t secs)
gboolean	qof_is_same_day (time_t, time_t)
char *	xaccDateUtilGetStamp (time_t thyme)
gboolean	qof_scan_date (const char *buff, int *day, int *month, int *year)
gboolean	qof_scan_date_secs (const char *buff, time_t *secs)
Date Start/End Adjustment routines
Given a time value, adjust it to be the beginning or end of that day.
static void	gnc_tm_set_day_start (struct tm *tm)
static void	gnc_tm_set_day_middle (struct tm *tm)
static void	gnc_tm_set_day_end (struct tm *tm)
void	gnc_tm_get_day_start (struct tm *tm, time_t time_val)
void	gnc_tm_get_day_end (struct tm *tm, time_t time_val)
time_t	gnc_timet_get_day_start (time_t time_val)
time_t	gnc_timet_get_day_end (time_t time_val)
time_t	gnc_timet_get_day_start_gdate (GDate *date)
time_t	gnc_timet_get_day_end_gdate (GDate *date)
int	date_get_last_mday (struct tm *tm)
gboolean	date_is_last_mday (struct tm *tm)
int	gnc_date_my_last_mday (int month, int year)
int	gnc_timespec_last_mday (Timespec ts)
Today's Date
void	gnc_tm_get_today_start (struct tm *tm)
void	gnc_tm_get_today_end (struct tm *tm)
time_t	gnc_timet_get_today_start (void)
time_t	gnc_timet_get_today_end (void)
char *	xaccDateUtilGetStampNow (void)
Defines
#define	MAX_DATE_LENGTH   31
#define	QOF_UTC_DATE_FORMAT   "%Y-%m-%dT%H:%M:%SZ"
	UTC date format string.
#define	DATE_FORMAT_FIRST   QOF_DATE_FORMAT_US
#define	DATE_FORMAT_LAST   QOF_DATE_FORMAT_LOCALE
#define	qof_date_format_get_format   qof_date_text_format_get_string
Typedefs
typedef timespec64	Timespec
Enumerations
enum	QofDateFormat {   QOF_DATE_FORMAT_US, QOF_DATE_FORMAT_UK, QOF_DATE_FORMAT_CE, QOF_DATE_FORMAT_ISO,   QOF_DATE_FORMAT_UTC, QOF_DATE_FORMAT_LOCALE, QOF_DATE_FORMAT_CUSTOM }
enum	GNCDateMonthFormat { GNCDATE_MONTH_NUMBER, GNCDATE_MONTH_ABBREV, GNCDATE_MONTH_NAME }
Functions
char	dateSeparator (void)

---

Define Documentation

#define MAX_DATE_LENGTH   31

The maximum length of a string created by the date printers Definition at line 67 of file gnc-date.h.

#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 98 of file gnc-date.h.

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

UTC date format string. Timezone 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 timezone independent and include all specified fields. Remember to use gmtime() NOT localtime()! Definition at line 79 of file gnc-date.h.

---

Typedef Documentation

typedef struct timespec64 Timespec

The Timespec is just like the unix 'struct timespec' except that we use 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 they're not more than a couple dozen times the age of the universe. Note that both gcc and the IBM Toronto xlC compiler (aka CSet, VisualAge, etc) correctly handle long long as a 64 bit quantity, even on the 32-bit Intel x86 and PowerPC architectures. I'm assuming that all the other modern compilers are clean on this issue too. Definition at line 168 of file gnc-date.h.

---

Enumeration Type Documentation

enum GNCDateMonthFormat

This is how to format the month, as a number, an abbreviated string, or the full name. Definition at line 104 of file gnc-date.h. { GNCDATE_MONTH_NUMBER, GNCDATE_MONTH_ABBREV, GNCDATE_MONTH_NAME } GNCDateMonthFormat;

enum 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_UTC  UTC: 2004-12-12T23:39:11Z QOF_DATE_FORMAT_LOCALE  Take from locale information QOF_DATE_FORMAT_CUSTOM  Used by the check printing code Definition at line 82 of file gnc-date.h. { QOF_DATE_FORMAT_US, QOF_DATE_FORMAT_UK, QOF_DATE_FORMAT_CE, QOF_DATE_FORMAT_ISO, QOF_DATE_FORMAT_UTC, QOF_DATE_FORMAT_LOCALE, QOF_DATE_FORMAT_CUSTOM } QofDateFormat;

---

Function Documentation

void date_add_months (  struct tm *  tm, int  months, gboolean  track_last_day )

Add a number of months to a time value and normalize. Optionally also track the last day of the month, i.e. 1/31 -> 2/28 -> 3/30. Definition at line 311 of file gnc-date.c. { gboolean was_last_day; int new_last_mday; /* Have to do this now */ was_last_day = date_is_last_mday(tm); /* Add in the months and normalize */ tm->tm_mon += months; while (tm->tm_mon > 11) { tm->tm_mon -= 12; tm->tm_year++; } if (!track_last_day) return; /* Track last day of the month, i.e. 1/31 -> 2/28 -> 3/30 */ new_last_mday = date_get_last_mday(tm); if (was_last_day || (tm->tm_mday > new_last_mday)) tm->tm_mday = new_last_mday; }

int date_get_last_mday (  struct tm *  tm  )

Get the numerical last date of the month. (28, 29, 30, 31) Definition at line 283 of file gnc-date.c. { return gnc_date_my_last_mday (tm->tm_mon+1, tm->tm_year+1900); }

gboolean date_is_last_mday (  struct tm *  tm  )

Is the mday field the last day of the specified month. Definition at line 295 of file gnc-date.c. { return(tm->tm_mday == date_get_last_mday(tm)); }

char dateSeparator (  void   )

dateSeparator Return the field separator for the current date format Args: none Return: date character Globals: global dateFormat value Definition at line 920 of file gnc-date.c. { static char locale_separator = '\0'; switch (dateFormat) { case QOF_DATE_FORMAT_CE: return '.'; case QOF_DATE_FORMAT_ISO: case QOF_DATE_FORMAT_UTC: return '-'; case QOF_DATE_FORMAT_US: case QOF_DATE_FORMAT_UK: default: return '/'; case QOF_DATE_FORMAT_LOCALE: if (locale_separator != '\0') return locale_separator; else { /* Make a guess */ char string[256]; struct tm *tm; time_t secs; char *s; secs = time(NULL); tm = localtime(&secs); strftime(string, sizeof(string), GNC_D_FMT, tm); for (s = string; s != '\0'; s++) if (!isdigit(*s)) return (locale_separator = *s); } } return '\0'; }

int gnc_date_my_last_mday (  int  month, int  year )

DOCUMENT ME! Probably the same as date_get_last_mday() Definition at line 257 of file gnc-date.c. { gboolean is_leap; static int days_in_month[2][12] = {/* non leap */ {31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31}, /* leap */ {31, 29, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31}}; /* Is this a leap year? */ if (year % 2000 == 0) is_leap = TRUE; else if (year % 400 == 0) is_leap = FALSE; else is_leap = (year % 4 == 0); return days_in_month[is_leap][month-1]; }

gboolean gnc_date_string_to_dateformat (  const char *  format_string, QofDateFormat *  format )

Converts the date format to a printable string. Note the reversed return values! Returns: FALSE on success, TRUE on failure. Definition at line 101 of file gnc-date.c. { if (!fmt_str) return TRUE; if (!strcmp(fmt_str, "us")) *format = QOF_DATE_FORMAT_US; else if (!strcmp(fmt_str, "uk")) *format = QOF_DATE_FORMAT_UK; else if (!strcmp(fmt_str, "ce")) *format = QOF_DATE_FORMAT_CE; else if (!strcmp(fmt_str, "utc")) *format = QOF_DATE_FORMAT_UTC; else if (!strcmp(fmt_str, "iso")) *format = QOF_DATE_FORMAT_ISO; else if (!strcmp(fmt_str, "locale")) *format = QOF_DATE_FORMAT_LOCALE; else if (!strcmp(fmt_str, "custom")) *format = QOF_DATE_FORMAT_CUSTOM; else return TRUE; return FALSE; }

gboolean gnc_date_string_to_monthformat (  const char *  format_string, GNCDateMonthFormat *  format )

Converts the month format to a printable string. Note the reversed return values! Returns: FALSE on success, TRUE on failure. Definition at line 143 of file gnc-date.c. { if (!fmt_str) return TRUE; if (!strcmp(fmt_str, "number")) *format = GNCDATE_MONTH_NUMBER; else if (!strcmp(fmt_str, "abbrev")) *format = GNCDATE_MONTH_ABBREV; else if (!strcmp(fmt_str, "name")) *format = GNCDATE_MONTH_NAME; else return TRUE; return FALSE; }

Timespec gnc_dmy2timespec (  int  day, int  month, int  year )

Convert a day, month, and year to a Timespec Definition at line 1243 of file gnc-date.c. { return gnc_dmy2timespec_internal (day, month, year, TRUE); }

Timespec gnc_dmy2timespec_end (  int  day, int  month, int  year )

Same as gnc_dmy2timespec, but last second of the day Definition at line 1249 of file gnc-date.c. { return gnc_dmy2timespec_internal (day, month, year, FALSE); }

Timespec gnc_iso8601_to_timespec_gmt (  const char *   )

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 timezone information along with a local-time string. But fundamentally, they *are* UTC. Thus, thir 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 millisecs after 16:00:00 hours UTC. Returns: The universl time. XXX Caution: this routine does not handle strings that specify times before January 1 1970. Definition at line 1012 of file gnc-date.c. { char buf[4]; Timespec ts; struct tm stm; long int nsec =0; ts.tv_sec=0; ts.tv_nsec=0; if (!str) return ts; stm.tm_year = atoi(str) - 1900; str = strchr (str, '-'); if (str) { str++; } else { return ts; } stm.tm_mon = atoi(str) - 1; str = strchr (str, '-'); if (str) { str++; } else { return ts; } stm.tm_mday = atoi(str); str = strchr (str, ' '); if (str) { str++; } else { return ts; } stm.tm_hour = atoi(str); str = strchr (str, ':'); if (str) { str++; } else { return ts; } stm.tm_min = atoi(str); str = strchr (str, ':'); if (str) { str++; } else { return ts; } stm.tm_sec = atoi (str); /* The decimal point, optionally present ... */ /* hack alert -- this algo breaks if more than 9 decimal places present */ if (strchr (str, '.')) { int decimals, i, multiplier=1000000000; str = strchr (str, '.') +1; decimals = strcspn (str, "+- "); for (i=0; i<decimals; i++) multiplier /= 10; nsec = atoi(str) * multiplier; } stm.tm_isdst = -1; /* Timezone format can be +hh or +hhmm or +hh.mm (or -) (or not present) */ str += strcspn (str, "+-"); if (str) { buf[0] = str[0]; buf[1] = str[1]; buf[2] = str[2]; buf[3] = 0; stm.tm_hour -= atoi(buf); str +=3; if ('.' == *str) str++; if (isdigit (*str) && isdigit (*(str+1))) { int cyn; /* copy sign from hour part */ if ('+' == buf[0]) { cyn = -1; } else { cyn = +1; } buf[0] = str[0]; buf[1] = str[1]; buf[2] = str[2]; buf[3] = 0; stm.tm_min += cyn * atoi(buf); } } /* Note that mktime returns 'local seconds' which is the true time * minus the timezone offset. We don't want to work with local * seconds, since they swim around acording to daylight savings, etc. * We want to work with universal time. Thus, add an offset * to undo the damage that mktime causes. */ { struct tm tmp_tm; struct tm *tm; long int tz; int tz_hour; time_t secs; /* Use a temporary tm struct so the mktime call below * doesn't mess up stm. */ tmp_tm = stm; tmp_tm.tm_isdst = -1; secs = mktime (&tmp_tm); /* The call to localtime is 'bogus', but it forces 'timezone' to * be set. Note that we must use the accurate date, since the * value of 'gnc_timezone' includes daylight savings corrections * for that date. */ tm = localtime (&secs); tz = gnc_timezone (tm); tz_hour = tz / 3600; stm.tm_hour -= tz_hour; stm.tm_min -= (tz - (3600 * tz_hour)) / 60; stm.tm_isdst = tmp_tm.tm_isdst; } ts.tv_sec = mktime (&stm); ts.tv_nsec = nsec; return ts; }

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 528 of file gnc-date.c. { static char buff[MAX_DATE_LENGTH]; time_t t; t = ts.tv_sec + (ts.tv_nsec / 1000000000.0); qof_print_date_buff (buff, MAX_DATE_LENGTH, t); return buff; }

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

DOCUMENT ME! FIXME: Probably similar to xaccDMYToSec() this date routine might return incorrect values for dates before 1970. Definition at line 1166 of file gnc-date.c. { struct tm *result; time_t t_secs = t.tv_sec + (t.tv_nsec / NANOS_PER_SECOND); result = localtime(&t_secs); if (day) *day = result->tm_mday; if (month) *month = result->tm_mon+1; if (year) *year = result->tm_year+1900; }

int gnc_timespec_last_mday (  Timespec  ts  )

DOCUMENT ME! Probably the same as date_get_last_mday() Definition at line 1157 of file gnc-date.c. { struct tm *result; time_t t_secs = t.tv_sec + (t.tv_nsec / NANOS_PER_SECOND); result = localtime(&t_secs); return date_get_last_mday (result); }

char* gnc_timespec_to_iso8601_buff (  Timespec  ts, char *  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 timezone 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 timezone on the machine on which it is executing to create the timestring. Definition at line 1117 of file gnc-date.c. { int len; int tz_hour, tz_min; char cyn; time_t tmp; struct tm parsed; tmp = ts.tv_sec; localtime_r(&tmp, &parsed); tz_hour = gnc_timezone (&parsed) / 3600; tz_min = (gnc_timezone (&parsed) - 3600*tz_hour) / 60; if (0>tz_min) { tz_min +=60; tz_hour --; } if (60<=tz_min) { tz_min -=60; tz_hour ++; } /* We also have to print the sign by hand, to work around a bug * in the glibc 2.1.3 printf (where %+02d fails to zero-pad). */ cyn = '-'; if (0>tz_hour) { cyn = '+'; tz_hour = -tz_hour; } len = sprintf (buff, "%4d-%02d-%02d %02d:%02d:%02d.%06ld %c%02d%02d", parsed.tm_year + 1900, parsed.tm_mon + 1, parsed.tm_mday, parsed.tm_hour, parsed.tm_min, parsed.tm_sec, ts.tv_nsec / 1000, cyn, tz_hour, tz_min); /* Return pointer to end of string. */ buff += len; return buff; }

time_t gnc_timet_get_day_end (  time_t  time_val  )

The gnc_timet_get_day_end() routine will take the given time in seconds and adjust it to the last second of that day. Definition at line 1314 of file gnc-date.c. { struct tm tm; gnc_tm_get_day_end(&tm, time_val); return mktime(&tm); }

time_t gnc_timet_get_day_end_gdate (  GDate *  date  )

The gnc_timet_get_day_end() routine will take the given time in GLib GDate format and adjust it to the last second of that day. Deprecated: Definition at line 1341 of file gnc-date.c. { struct tm stm; time_t secs; stm.tm_year = g_date_year (date) - 1900; stm.tm_mon = g_date_month (date) - 1; stm.tm_mday = g_date_day (date); gnc_tm_set_day_end(&stm); /* Compute number of seconds */ secs = mktime (&stm); return secs; }

time_t gnc_timet_get_day_start (  time_t  time_val  )

The gnc_timet_get_day_start() routine will take the given time in seconds and adjust it to the last second of that day. Definition at line 1305 of file gnc-date.c. { struct tm tm; gnc_tm_get_day_start(&tm, time_val); return mktime(&tm); }

time_t gnc_timet_get_day_start_gdate (  GDate *  date  )

The gnc_timet_get_day_start() routine will take the given time in GLib GDate format and adjust it to the last second of that day. Deprecated: Definition at line 1325 of file gnc-date.c. { struct tm stm; time_t secs; stm.tm_year = g_date_year (date) - 1900; stm.tm_mon = g_date_month (date) - 1; stm.tm_mday = g_date_day (date); gnc_tm_set_day_start(&stm); /* Compute number of seconds */ secs = mktime (&stm); return secs; }

time_t gnc_timet_get_today_end (  void   )

The gnc_timet_get_today_end() routine returns a time_t value corresponding to the last second of today. Definition at line 1381 of file gnc-date.c. { struct tm tm; gnc_tm_get_day_end(&tm, time(NULL)); return mktime(&tm); }

time_t gnc_timet_get_today_start (  void   )

The gnc_timet_get_today_start() routine returns a time_t value corresponding to the first second of today. Definition at line 1372 of file gnc-date.c. { struct tm tm; gnc_tm_get_day_start(&tm, time(NULL)); return mktime(&tm); }

long int gnc_timezone (  struct tm *  tm  )

The gnc_timezone function returns the number of seconds *west* of UTC represented by the tm argument, adjusted for daylight savings time. This function requires a tm argument returned by localtime or set by mktime. This is a strange function! It requires that localtime or mktime be called before use. Subsequent calls to localtime or mktime *may* invalidate the result! The actual contents of tm *may* be used for both timezone offset and daylight savings time, or only daylight savings time! Timezone stuff under unix is not standardized and is a big mess. Definition at line 1258 of file gnc-date.c. { g_return_val_if_fail (tm != NULL, 0); #ifdef HAVE_STRUCT_TM_GMTOFF /* tm_gmtoff is seconds *east* of UTC and is * already adjusted for daylight savings time. */ return -(tm->tm_gmtoff); #else /* timezone is seconds *west* of UTC and is * not adjusted for daylight savings time. * In Spring, we spring forward, wheee! */ return timezone - (tm->tm_isdst > 0 ? 60 * 60 : 0); #endif }

void gnc_tm_get_day_end (  struct tm *  tm, time_t  time_val )

The gnc_tm_get_day_end() routine will convert the given time in seconds to the struct tm format, and then adjust it to the last second of that day. Definition at line 1297 of file gnc-date.c. { /* Get the equivalent time structure */ tm = localtime_r(&time_val, tm); gnc_tm_set_day_end(tm); }

void gnc_tm_get_day_start (  struct tm *  tm, time_t  time_val )

The gnc_tm_get_day_start() routine will convert the given time in seconds to the struct tm format, and then adjust it to the first second of that day. Definition at line 1289 of file gnc-date.c. { /* Get the equivalent time structure */ tm = localtime_r(&time_val, tm); gnc_tm_set_day_start(tm); }

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 1366 of file gnc-date.c. { gnc_tm_get_day_end(tm, time(NULL)); }

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 1360 of file gnc-date.c. { gnc_tm_get_day_start(tm, time(NULL)); }

static void gnc_tm_set_day_end (  struct tm *  tm  )  [inline, static]

The gnc_tm_set_day_start() inline routine will set the appropriate fields in the struct tm to indicate the last second of that day. This routine assumes that the contents of the data structure is already in normalized form. Definition at line 460 of file gnc-date.h. { /* Last second of the day */ tm->tm_hour = 23; tm->tm_min = 59; tm->tm_sec = 59; tm->tm_isdst = -1; }

static void gnc_tm_set_day_middle (  struct tm *  tm  )  [inline, static]

The gnc_tm_set_day_start() inline routine will set the appropriate fields in the struct tm to indicate noon of that day. This routine assumes that the contents of the data structure is already in normalized form. Definition at line 446 of file gnc-date.h. { /* First second of the day */ tm->tm_hour = 12; tm->tm_min = 0; tm->tm_sec = 0; tm->tm_isdst = -1; }

static void gnc_tm_set_day_start (  struct tm *  tm  )  [inline, static]

The gnc_tm_set_day_start() inline routine will set the appropriate fields in the struct tm to indicate the first second of that day. This routine assumes that the contents of the data structure is already in normalized form. Definition at line 432 of file gnc-date.h. { /* First second of the day */ tm->tm_hour = 0; tm->tm_min = 0; tm->tm_sec = 0; tm->tm_isdst = -1; }

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 scaning routines will assume when parsing a date. Returns: : the one of the enumerated date formats. Definition at line 341 of file gnc-date.c. { return dateFormat; }

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: df  The 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 381 of file gnc-date.c. { switch(df) { case QOF_DATE_FORMAT_US: return "%m/%d/%y"; case QOF_DATE_FORMAT_UK: return "%d/%m/%y"; case QOF_DATE_FORMAT_CE: return "%d.%m.%y"; case QOF_DATE_FORMAT_UTC: return "%Y-%m-%dT%H:%M:%SZ"; case QOF_DATE_FORMAT_ISO: return "%y-%m-%d"; case QOF_DATE_FORMAT_LOCALE: default: return GNC_D_FMT; }; }

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 357 of file gnc-date.c. { if(df >= DATE_FORMAT_FIRST && df <= DATE_FORMAT_LAST) { prevQofDateFormat = dateFormat; dateFormat = df; } else { /* hack alert - Use a neutral default. */ PERR("non-existent date format set attempted. Setting ISO default"); prevQofDateFormat = dateFormat; dateFormat = QOF_DATE_FORMAT_ISO; } return; }

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: df  The 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 409 of file gnc-date.c. { switch(df) { case QOF_DATE_FORMAT_US: return "%b %d, %y"; case QOF_DATE_FORMAT_UK: case QOF_DATE_FORMAT_CE: return "%d %b, %y"; case QOF_DATE_FORMAT_UTC: return "%Y-%m-%dT%H:%M:%SZ"; case QOF_DATE_FORMAT_ISO: return "%y-%b-%d"; case QOF_DATE_FORMAT_LOCALE: default: return GNC_D_FMT; }; }

gboolean qof_is_same_day (  time_t  , time_t  )

The qof_is_same_day() routine returns 0 if both times are in the same day. Definition at line 695 of file gnc-date.c. { struct tm lta, ltb; lta = *localtime (&ta); ltb = *localtime (&tb); if (lta.tm_year == ltb.tm_year) { return (ltb.tm_yday - lta.tm_yday); } return (ltb.tm_year - lta.tm_year)*365; /* very approximate */ }

char* qof_print_date (  time_t  secs  )

Convenience; calls through to qof_print_date_dmy_buff(). Return: string, which should be freed when no longer needed. Definition at line 520 of file gnc-date.c. { char buff[MAX_DATE_LENGTH]; qof_print_date_buff (buff, MAX_DATE_LENGTH, t); return g_strdup (buff); }

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

Convenience: calls through to qof_print_date_dmy_buff(). Definition at line 496 of file gnc-date.c. { struct tm *theTime; if (!buff) return 0 ; theTime = localtime (&t); return qof_print_date_dmy_buff (buff, len, theTime->tm_mday, theTime->tm_mon + 1, theTime->tm_year + 1900); }

size_t qof_print_date_dmy_buff (  char *  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 Definition at line 443 of file gnc-date.c. { int flen; if (!buff) return 0; /* Note that when printing year, we use %-4d in format string; * this causes a one, two or three-digit year to be left-adjusted * when printed (i.e. padded with blanks on the right). This is * important while the user is editing the year, since erasing a * digit can temporarily cause a three-digit year, and having the * blank on the left is a real pain for the user. So pad on the * right. */ switch(dateFormat) { case QOF_DATE_FORMAT_UK: flen = g_snprintf (buff, len, "%2d/%2d/%-4d", day, month, year); break; case QOF_DATE_FORMAT_CE: flen = g_snprintf (buff, len, "%2d.%2d.%-4d", day, month, year); break; case QOF_DATE_FORMAT_LOCALE: { struct tm tm_str; time_t t; tm_str.tm_mday = day; tm_str.tm_mon = month - 1; /* tm_mon = 0 through 11 */ tm_str.tm_year = year - 1900; /* this is what the standard * says, it's not a Y2K thing */ gnc_tm_set_day_start (&tm_str); t = mktime (&tm_str); localtime_r (&t, &tm_str); flen = strftime (buff, len, GNC_D_FMT, &tm_str); if (flen != 0) break; } /* FALLTHROUGH */ case QOF_DATE_FORMAT_ISO: case QOF_DATE_FORMAT_UTC: flen = g_snprintf (buff, len, "%04d-%02d-%02d", year, month, day); break; case QOF_DATE_FORMAT_US: default: flen = g_snprintf (buff, len, "%2d/%2d/%-4d", month, day, year); break; } return flen; }

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

Convenience; calls through to qof_print_date_dmy_buff(). Definition at line 511 of file gnc-date.c. { return qof_print_date_dmy_buff( buf, len, g_date_day(gd), g_date_month(gd), g_date_year(gd) ); }

size_t qof_print_hours_elapsed_buff (  char *  buff, size_t  len, int  secs, gboolean  show_secs )

The qof_print_hours_elapsed_buff() routine will print the 'secs' argument as HH:MM, and will print the seconds if show_secs is true. Thus, for example, secs=3599 will print as 0:59 Returns the number of bytes copied. Definition at line 543 of file gnc-date.c. { size_t flen; if (0 <= secs) { if (show_secs) { flen = g_snprintf(buff, len, "%02d:%02d:%02d", (int)(secs / 3600), (int)((secs % 3600) / 60), (int)(secs % 60)); } else { flen = g_snprintf(buff, len, "%02d:%02d", (int)(secs / 3600), (int)((secs % 3600) / 60)); } } else { if (show_secs) { flen = g_snprintf(buff, len, "-%02d:%02d:%02d", (int)(-secs / 3600), (int)((-secs % 3600) / 60), (int)(-secs % 60)); } else { flen = g_snprintf(buff, len, "-%02d:%02d", (int)(-secs / 3600), (int)((-secs % 3600) / 60)); } } return flen; }

size_t qof_print_time_buff (  char *  buff, size_t  len, time_t  secs )

The qof_print_time_buff() routine prints only the hour-part of the date. Thus, if secs is ... Returns the number of bytes printed. Definition at line 674 of file gnc-date.c. { int flen; struct tm ltm, gtm; if (!buff) return 0; if(dateFormat == QOF_DATE_FORMAT_UTC) { gtm = *gmtime (&secs); flen = strftime(buff, len, QOF_UTC_DATE_FORMAT, &gtm); return flen; } ltm = *localtime (&secs); flen = strftime (buff, len, GNC_T_FMT, &ltm); return flen; }

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 900 of file gnc-date.c. { return qof_scan_date_internal(buff, day, month, year, dateFormat); }

gboolean qof_scan_date_secs (  const char *  buff, time_t *  secs )

as above, but returns seconds Definition at line 906 of file gnc-date.c. { gboolean rc; int day, month, year; rc = qof_scan_date_internal(buff, &day, &month, &year, dateFormat); if (secs) *secs = xaccDMYToSec (day, month, year); return rc; }

Timespec timespec_abs (  const Timespec *  t  )

absolute value, also normalised Definition at line 224 of file gnc-date.c. { Timespec retval = *t; timespec_normalize(&retval); if (retval.tv_sec < 0) { retval.tv_sec = - retval.tv_sec; retval.tv_nsec = - retval.tv_nsec; } return retval; }

int timespec_cmp (  const Timespec *  ta, const Timespec *  tb )

comparison: if (ta < tb) -1; else if (ta > tb) 1; else 0; Definition at line 203 of file gnc-date.c. { if(ta == tb) return 0; if(ta->tv_sec < tb->tv_sec) return -1; if(ta->tv_sec > tb->tv_sec) return 1; if(ta->tv_nsec < tb->tv_nsec) return -1; if(ta->tv_nsec > tb->tv_nsec) return 1; return 0; }

Timespec timespec_diff (  const Timespec *  ta, const Timespec *  tb )

difference between ta and tb, results are normalised ie tv_sec and tv_nsec of the result have the same size abs(result.tv_nsec) <= 1000000000 Definition at line 214 of file gnc-date.c. { Timespec retval; retval.tv_sec = ta->tv_sec - tb->tv_sec; retval.tv_nsec = ta->tv_nsec - tb->tv_nsec; timespec_normalize(&retval); return retval; }

gboolean timespec_equal (  const Timespec *  ta, const Timespec *  tb )

strict equality Definition at line 194 of file gnc-date.c. { if(ta == tb) return TRUE; if(ta->tv_sec != tb->tv_sec) return FALSE; if(ta->tv_nsec != tb->tv_nsec) return FALSE; return TRUE; }

Timespec timespecCanonicalDayTime (  Timespec  t  )

convert a timepair on a certain day (localtime) to the timepair representing midday on that day Definition at line 244 of file gnc-date.c. { struct tm tm, *result; Timespec retval; time_t t_secs = t.tv_sec + (t.tv_nsec / NANOS_PER_SECOND); result = localtime(&t_secs); tm = *result; gnc_tm_set_day_middle(&tm); retval.tv_sec = mktime(&tm); retval.tv_nsec = 0; return retval; }

void timespecFromTime_t (  Timespec *  ts, time_t  t )

Turns a time_t into a Timespec Definition at line 1276 of file gnc-date.c. { ts->tv_sec = t; ts->tv_nsec = 0; }

time_t timespecToTime_t (  Timespec  ts  )

Turns a Timespec into a time_t Definition at line 1283 of file gnc-date.c. { return ts.tv_sec; }

char* xaccDateUtilGetStamp (  time_t  thyme  )

The xaccDateUtilGetStamp() routine will take the given time in seconds and return a buffer containing a textual for the date. Parameters: thyme  The time in seconds to convert. Returns: A pointer to the generated string. Note: The caller owns this buffer and must free it when done. Definition at line 971 of file gnc-date.c. { struct tm *stm; stm = localtime (&thyme); return g_strdup_printf("%04d%02d%02d%02d%02d%02d", (stm->tm_year + 1900), (stm->tm_mon +1), stm->tm_mday, stm->tm_hour, stm->tm_min, stm->tm_sec ); }

char* xaccDateUtilGetStampNow (  void   )

The xaccDateUtilGetStampNow() routine returns the current time in seconds in textual format. Returns: A pointer to the generated string. Note: The caller owns this buffer and must free it when done. Definition at line 998 of file gnc-date.c. { time_t now; time (&now); return xaccDateUtilGetStamp (now); }

time_t xaccDMYToSec (  int  day, int  month, int  year )

Warning: hack alert XXX FIXME -- these date routines return incorrect values for dates before 1970. Most of them are good only up till 2038. This needs fixing ... XXX This routine should be modified to assume that the the user wanted the time at noon, localtime. The returned time_t should be seconds (at GMT) of the local noon-time. Definition at line 1183 of file gnc-date.c. { struct tm stm; time_t secs; stm.tm_year = year - 1900; stm.tm_mon = month - 1; stm.tm_mday = day; gnc_tm_set_day_start(&stm); /* compute number of seconds */ secs = mktime (&stm); return secs; }

---