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...
Copyright (C) 1998-2001,2003 Linas Vepstas <linas@linas.org>
Files | |
file | gnc-date.h |
Date and Time handling routines. | |
Data Structures | |
struct | timespec64 |
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) |
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_format_get_format (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. | |
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 11 |
#define | getDateFormatString qof_date_format_get_string |
#define | getDateTextFormatString qof_date_format_get_format |
#define | getDateFormat qof_date_format_get |
#define | setDateFormat qof_date_format_set |
#define | DateFormat QofDateFormat |
#define | printDateSecs(B, S) qof_print_date_buff(B,MAX_DATE_LENGTH,S) |
#define | printDate(B, D, M, Y) qof_print_date_dmy_buff(B,MAX_DATE_LENGTH,D,M,Y) |
#define | printGDate(B, D) qof_print_gdate(B,MAX_DATE_LENGTH,D) |
#define | xaccPrintDateSecs qof_print_date |
#define | scanDate qof_scan_date |
#define | DATE_FORMAT_US QOF_DATE_FORMAT_US |
#define | DATE_FORMAT_UK QOF_DATE_FORMAT_UK |
#define | DATE_FORMAT_CE QOF_DATE_FORMAT_CE |
#define | DATE_FORMAT_ISO QOF_DATE_FORMAT_ISO |
#define | DATE_FORMAT_LOCALE QOF_DATE_FORMAT_LOCALE |
#define | DATE_FORMAT_CUSTOM QOF_DATE_FORMAT_CUSTOM |
#define | DATE_FORMAT_FIRST QOF_DATE_FORMAT_US |
#define | DATE_FORMAT_LAST QOF_DATE_FORMAT_LOCALE |
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_LOCALE, QOF_DATE_FORMAT_CUSTOM } |
enum | GNCDateMonthFormat { GNCDATE_MONTH_NUMBER, GNCDATE_MONTH_ABBREV, GNCDATE_MONTH_NAME } |
Functions | |
const char * | gnc_date_dateformat_to_string (QofDateFormat format) |
gboolean | gnc_date_string_to_dateformat (const char *format_string, QofDateFormat *format) |
const char * | gnc_date_monthformat_to_string (GNCDateMonthFormat format) |
gboolean | gnc_date_string_to_monthformat (const char *format_string, GNCDateMonthFormat *format) |
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) |
char | dateSeparator (void) |
|
The maximum length of a string created by the date printers |
|
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. |
|
This is how to format the month, as a number, an abbreviated string, or the full name. |
|
Enum for determining a date format |
|
date_add_months Add a number of months to a time value, and normalize. Optionally also track the last day of hte month, i.e. 1/31 -> 2/28 -> 3/30. Args: tm: base time value months: The number of months to add to this time track_last_day: Coerce the date value if necessary. returns: nothing |
|
date_get_last_mday Retrieve the last nomerical day for the month specified in the tm_year and tm_mon fields. Args: tm: the time value in question returns: T/F |
|
date_is_last_mday Determines whether the tm_mday field contains the last day of the month as specified in the tm_year and tm_mon fields. Args: tm: the time value in question returns: T/F |
|
dateSeparator Return the field separator for the current date format Args: none Return: date character Globals: global dateFormat value |
|
DOCUMENT ME! Probably the same as date_get_last_mday() |
|
Convert a day, month, and year to a Timespec |
|
Same as gnc_dmy2timespec, but last second of the day |
|
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.
|
|
Convenience; calls through to qof_print_date_dmy_buff(). Return: static global string.
|
|
DOCUMENT ME! FIXME: Probably similar to xaccDMYToSec() this date routine might return incorrect values for dates before 1970. |
|
DOCUMENT ME! Probably the same as date_get_last_mday() |
|
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. |
|
The gnc_timet_get_day_end() routine will take the given time in seconds and adjust it to the last second of that day. |
|
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. |
|
The gnc_timet_get_day_start() routine will take the given time in seconds and adjust it to the last second of that day. |
|
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. |
|
The gnc_timet_get_today_end() routine returns a time_t value corresponding to the last second of today. |
|
The gnc_timet_get_today_start() routine returns a time_t value corresponding to the first second of today. |
|
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. |
|
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. |
|
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. |
|
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. |
|
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. |
|
qof_date_format_get Args: nothing returns: QofDateFormat: enumeration indicating preferred format Globals: dateFormat |
|
qof_date_format_get_format get the date format string for the current format returns: string Globals: dateFormat |
|
qof_date_format_get_string get the date format string for the current format returns: string Globals: dateFormat |
|
qof_date_format_set set 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 returns: nothing Globals: dateFormat |
|
The qof_is_same_day() routine returns 0 if both times are in the same day. |
|
Convenience; calls through to qof_print_date_dmy_buff(). Return: string, which should be freed when no longer needed. * |
|
Convenience: calls through to qof_print_date_dmy_buff(). * |
|
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. day - day of the month as 1 ... 31 month - month of the year as 1 ... 12 year - year (4-digit) Return: nothing Globals: global dateFormat value |
|
Convenience; calls through to qof_print_date_dmy_buff(). * |
|
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. |
|
The qof_print_time_buff() routine prints only the hour-part of the date. Thus, if secs is ... Returns the number of bytes printed. |
|
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. |
|
as above, but returns seconds |
|
absolute value, also normalised |
|
comparison: if (ta < tb) -1; else if (ta > tb) 1; else 0; |
|
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 |
|
strict equality |
|
timespecCanonicalDayTime given a timepair contains any time on a certain day (local time) converts it to be midday that day. |
|
Turns a time_t into a Timespec |
|
Turns a Timespec into a time_t |
|
The xaccDateUtilGetStamp() routine will take the given time in seconds and return a buffer containing a textual for the date.
|
|
The xaccDateUtilGetStampNow() routine returns the current time in seconds in textual format.
|
|
|