GnuCash
2.6.99
|
Files | |
file | gnc-date.h |
Date and Time handling routines. | |
Data Structures | |
struct | timespec64 |
Use a 64-bit unsigned int timespec. More... | |
Macros | |
#define | MAX_DATE_LENGTH 34 |
#define | QOF_UTC_DATE_FORMAT "%Y-%m-%dT%H:%M:%SZ" |
UTC date format string. 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 |
typedef struct 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_UTC, QOF_DATE_FORMAT_CUSTOM } |
enum | QofDateCompletion { QOF_DATE_COMPLETION_THISYEAR, QOF_DATE_COMPLETION_SLIDING } |
enum | GNCDateMonthFormat { GNCDATE_MONTH_NUMBER, GNCDATE_MONTH_ABBREV, GNCDATE_MONTH_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... | |
time64 | gnc_time_utc (time64 *tbuf) |
get the current utc time More... | |
gdouble | gnc_difftime (const time64 secs1, const time64 secs2) |
Find the difference in seconds between two time values. More... | |
GDateTime * | gnc_g_date_time_new_from_unix_local (time64 time) |
void | gnc_tm_free (struct tm *time) |
free a struct tm* created with gnc_localtime() or gnc_gmtime() More... | |
GDateTime * | gnc_g_date_time_new_from_timespec_local (Timespec tm) |
Create a GDateTime from a Timespec. More... | |
void | qof_date_completion_set (QofDateCompletion dc, int backmonths) |
gchar | dateSeparator (void) |
Variables | |
const char * | gnc_default_strftime_date_format |
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... | |
Timespec functions | |
gboolean | timespec_equal (const Timespec *ta, const Timespec *tb) |
gint | 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) |
Timespec | timespec_now (void) |
void | timespecFromTime64 (Timespec *ts, time64 t) |
time64 | timespecToTime64 (Timespec ts) |
GDate * | gnc_g_date_new_today (void) |
GDate | timespec_to_gdate (Timespec ts) |
Timespec | gdate_to_timespec (GDate d) |
Timespec | gnc_dmy2timespec (gint day, gint month, gint year) |
Timespec | gnc_dmy2timespec_end (gint day, gint month, gint year) |
Timespec | gnc_iso8601_to_timespec_gmt (const gchar *) |
gchar * | gnc_timespec_to_iso8601_buff (Timespec ts, gchar *buff) |
void | gnc_timespec2dmy (Timespec ts, gint *day, gint *month, gint *year) |
glong | gnc_timezone (const 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 | |
gsize | qof_strftime (gchar *buf, gsize max, const gchar *format, const struct tm *tm) |
size_t | qof_print_date_dmy_buff (gchar *buff, size_t buflen, int day, int month, int year) |
size_t | qof_print_date_buff (char *buff, size_t buflen, time64 secs) |
size_t | qof_print_gdate (char *buf, size_t bufflen, const GDate *gd) |
char * | qof_print_date (time64 secs) |
const char * | gnc_print_date (Timespec ts) |
size_t | qof_print_date_time_buff (char *buff, size_t len, time64 secs) |
gboolean | qof_scan_date (const char *buff, int *day, int *month, int *year) |
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) |
time64 | gnc_time64_get_day_end (time64 time_val) |
int | gnc_date_get_last_mday (int month, int year) |
Today's Date | |
void | gnc_tm_get_today_start (struct tm *tm) |
void | gnc_tm_get_today_end (struct tm *tm) |
time64 | gnc_time64_get_today_start (void) |
time64 | gnc_time64_get_today_end (void) |
char * | gnc_date_timestamp (void) |
Make a timestamp in YYYYMMDDHHMMSS format. More... | |
void | gnc_dow_abbrev (gchar *buf, int buf_len, int dow) |
#define | MIN_BUF_LEN 10 |
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...
(to be renamed qofdate.h in libqof2.)
#define MAX_DATE_LENGTH 34 |
The maximum length of a string created by the date printers
Definition at line 106 of file gnc-date.h.
#define qof_date_format_get_format qof_date_text_format_get_string |
Definition at line 144 of file gnc-date.h.
#define QOF_UTC_DATE_FORMAT "%Y-%m-%dT%H:%M:%SZ" |
UTC date format string.
ConstantsTimezone 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 118 of file gnc-date.h.
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.
typedef struct timespec64 Timespec |
The Timespec is just like the unix 'struct timespec' except that we use a 64-bit unsigned 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 Values of this type can range from -9,223,372,036,854,775,808 to 9,223,372,036,854,775,807.
Definition at line 93 of file gnc-date.h.
enum GNCDateMonthFormat |
This is how to format the month, as a number, an abbreviated string, or the full name.
Definition at line 150 of file gnc-date.h.
enum 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 136 of file gnc-date.h.
enum QofDateFormat |
Enum for determining a date format
Definition at line 121 of file gnc-date.h.
gchar dateSeparator | ( | void | ) |
dateSeparator Return the field separator for the current date format
Args: none
Return: date character
Globals: global dateFormat value
Timespec gdate_to_timespec | ( | GDate | d | ) |
Turns a GDate into a Timespec, returning the first second of the day
gchar* gnc_ctime | ( | const time64 * | secs | ) |
Return a string representation of a date from a 64-bit time value.
secs | Seconds since 00:00:01 UTC 01 January 1970 (negative values are seconds before that moment) |
int gnc_date_get_last_mday | ( | int | month, |
int | year | ||
) |
Get the numerical last date of the month. (28, 29, 30, 31)
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!
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!
char* gnc_date_timestamp | ( | void | ) |
Make a timestamp in YYYYMMDDHHMMSS format.
Find the difference in seconds between two time values.
secs1 | The first time value, in Seconds since 00:00:01 UTC 01 January 1970 (negative values are seconds before that moment) |
secs2 | The second time value, in Seconds since 00:00:01 UTC 01 January 1970 (negative values are seconds before that moment) |
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
void gnc_dow_abbrev | ( | gchar * | buf, |
int | buf_len, | ||
int | dow | ||
) |
Localized DOW abbreviation.
buf_len | at least MIN_BUF_LEN |
dow | struct tm semantics: 0=sunday .. 6=saturday |
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.
GDateTime* gnc_g_date_time_new_from_timespec_local | ( | Timespec | tm | ) |
Create a GDateTime from a Timespec.
ts | A local (int64-based) Timespec |
GDateTime* gnc_g_date_time_new_from_unix_local | ( | time64 | time | ) |
Wrapper for g_date_time_new_from_unix_local() that takes special care on windows to take the local timezone into account. On unix, it just calles the g_date function.
struct tm* gnc_gmtime | ( | const time64 * | secs | ) |
fill out a time struct from a 64-bit time value
secs | Seconds since 00:00:01 UTC 01 January 1970 (negative values are seconds before that moment) |
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 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.
XXX Caution: this routine does not handle strings that specify times before January 1 1970.
struct tm* gnc_localtime | ( | const time64 * | secs | ) |
fill out a time struct from a 64-bit time value.
secs | Seconds since 00:00:01 UTC 01 January 1970 (negative values are seconds before that moment). |
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.
secs | Seconds since 00:00:01 UTC 01 January 1970 (negative values are seconds before that moment) |
time | A struct tm* for the function to fill. The time is adjusted for the current local time zone. |
time64 gnc_mktime | ( | struct tm * | time | ) |
calculate seconds from the epoch given a time struct
time | A struct tm* for the function to fill. The time is understood to be in the current local time zone. |
const char* gnc_print_date | ( | Timespec | ts | ) |
Convenience; calls through to qof_print_date_dmy_buff(). Return: static global string.
get the current local time
A | time64* which, if not NULL, will be filled in with the same value as is returned. |
The gnc_time64_get_day_end() routine will take the given time in seconds and adjust it to the last second of that day.
The gnc_time64_get_day_start() routine will take the given time in seconds and adjust it to the last second of that day.
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.
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.
get the current utc time
A | time64* which, if not NULL, will be filled in with the same value as is returned. |
time64 gnc_timegm | ( | struct tm * | time | ) |
calculate seconds from the epoch given a time struct
time | A struct tm* for the function to fill. The time is understood to be utc. |
void gnc_timespec2dmy | ( | Timespec | ts, |
gint * | day, | ||
gint * | month, | ||
gint * | year | ||
) |
Set the proleptic Gregorian day, month, and year from a Timespec
ts | input timespec |
day | output day, 1 - 31 |
month | output month, 1 - 12 |
year | output year, 0001 - 9999 CE |
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 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.
glong gnc_timezone | ( | const 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.
void gnc_tm_free | ( | struct tm * | time | ) |
free a struct tm* created with gnc_localtime() or gnc_gmtime()
time | The struct tm* to be freed. |
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.
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.
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)
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.
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.
df | The date style (us, uk, iso, etc) that should be provided. |
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
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.
df | The date style (us, uk, iso, etc) that should be provided. |
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.
size_t qof_print_date_buff | ( | char * | buff, |
size_t | buflen, | ||
time64 | secs | ||
) |
Convenience: calls through to 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
size_t qof_print_date_time_buff | ( | char * | buff, |
size_t | len, | ||
time64 | secs | ||
) |
Returns the number of bytes printed.
size_t qof_print_gdate | ( | char * | buf, |
size_t | bufflen, | ||
const GDate * | gd | ||
) |
Convenience; calls through to qof_print_date_dmy_buff().
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.
gsize qof_strftime | ( | gchar * | buf, |
gsize | max, | ||
const gchar * | format, | ||
const struct tm * | tm | ||
) |
buf | A buffer. |
max | The size of buf in bytes. |
format | A format specification in UTF-8. |
tm | A broken-down time. |
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
Timespec timespec_now | ( | void | ) |
Returns the current clock time as a Timespec, taken from time(2).
GDate timespec_to_gdate | ( | Timespec | ts | ) |
Turns a Timespec into a GDate
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.
const char* gnc_default_strftime_date_format |
The default date format for use with strftime.