Main Page Modules Alphabetical List Data Structures File List Data Fields Globals

# Date

## Files

file | date.h
| Date 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_local (const char *)
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)

## DateFormat functions

DateFormat | getDateFormat (void)
void | setDateFormat (DateFormat df)
const gchar * | getDateFormatString (DateFormat df)
const gchar * | getDateTextFormatString (DateFormat df)

## Date Printing/Scanning functions

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.

void | printDate (char *buff, int day, int month, int year)
void | printDateSecs (char *buff, time_t secs)
void | printGDate (char *buf, GDate *gd)
char * | xaccPrintDateSecs (time_t secs)
const char * | gnc_print_date (Timespec ts)
char * | xaccDateUtilGetStamp (time_t thyme)
char | dateSeparator (void)
void | scanDate (const char *buff, int *day, int *month, int *year)
time_t | xaccScanDateS (const char *buff)

## 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)
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 | DATE_FORMAT_FIRST DATE_FORMAT_US
#define | DATE_FORMAT_LAST DATE_FORMAT_LOCALE
#define | MAX_DATE_LENGTH 11

## Typedefs

typedef timespec64 | Timespec

## Enumerations

enum | DateFormat { DATE_FORMAT_US, DATE_FORMAT_UK, DATE_FORMAT_CE, DATE_FORMAT_ISO, DATE_FORMAT_LOCALE, DATE_FORMAT_CUSTOM }

## Functions

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)

## Define Documentation

#define MAX_DATE_LENGTH 11

| The maximum length of a string created by the date printers

## 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.

## Enumeration Type Documentation

enum DateFormat

Enum for determining a date format

Enumeration values:

  DATE_FORMAT_US | United states: mm/dd/yyyy
  DATE_FORMAT_UK | Britain: dd/mm/yyyy
  DATE_FORMAT_CE | Continental Europe: dd.mm.yyyy
  DATE_FORMAT_ISO | ISO: yyyy-mm-dd
  DATE_FORMAT_LOCALE | Take from locale information
  DATE_FORMAT_CUSTOM | Used by the check printing code

## Function Documentation

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

| 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

int date_get_last_mday | ( | struct tm * | tm | ) |

| 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

gboolean date_is_last_mday | ( | struct tm * | tm | ) |

| 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

char dateSeparator | ( |  | ) |

| dateSeparator Return the field separator for the current date format Args: none Return: date character Globals: global dateFormat value

DateFormat getDateFormat | ( | void |  | ) |

| getDateFormat Args: nothing returns: DateFormat: enumeration indicating preferred format Globals: dateFormat

const gchar* getDateFormatString | ( | DateFormat | df | ) |

| getDateFormatString get the date format string for the current format returns: string Globals: dateFormat

const gchar* getDateTextFormatString | ( | DateFormat | df | ) |

| getDateTextFormatString get the date format string for the current format returns: string Globals: dateFormat

int gnc_date_my_last_mday | ( | int | month,
|  | int | year
| ) |

| DOCUMENT ME! Probably the same as date_get_last_mday()

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

| Convert a day, month, and year to a Timespec

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

| Same as gnc_dmy2timespec, but last second of the day

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. For example: 1998-07-17 11:00:00.68-05 is 680 milliseconds after 11 o'clock, central daylight time

Returns:
  The time in gmt.

Timespec gnc_iso8601_to_timespec_local | ( | const char * |  | ) |

The gnc_iso8601_to_timespec_local() routine converts an ISO-8601 style date/time string to Timespec. For example: 1998-07-17 11:00:00.68-05 is 680 milliseconds after 11 o'clock, central daylight time

Returns:
  The time in local time.

const char* gnc_print_date | ( | Timespec | ts | ) |

| DOCUMENT ME!

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.

int gnc_timespec_last_mday | ( | Timespec | ts | ) |

| DOCUMENT ME! Probably the same as date_get_last_mday()

char* gnc_timespec_to_iso8601_buff | ( | Timespec | ts,
|  | char * | buff
| ) |

| The gnc_timespec_to_iso8601_buff() routine prints a Timespec as an ISO-8601 style string. The buffer must be long enough to contain the string. The string is null-terminated. This routine returns a pointer to the null terminator (and can thus be used in the 'stpcpy' metaphor of string concatenation).

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.

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 first it to the last second of that day.

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.

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.

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.

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.

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.

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 printDate | ( | char * | buff,
|  | int | day,
|  | int | month,
|  | int | year
| ) |

| printDate 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

void printDateSecs | ( | char * | buff,
|  | time_t | secs
| ) |

| convenience: calls through to printDate(). *

void printGDate | ( | char * | buf,
|  | GDate * | gd
| ) |

| Convenience; calls through to printDate(). *

void scanDate | ( | const char * | buff,
|  | int * | day,
|  | int * | month,
|  | int * | year
| ) |

| scanDate 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: nothing Globals: global dateFormat value

void setDateFormat | ( | DateFormat | df | ) |

| setDateFormat set date format to one of US, UK, CE, OR ISO checks to make sure it's a legal value Args: DateFormat: enumeration indicating preferred format returns: nothing Globals: dateFormat

Timespec timespec_abs | ( | const Timespec * | t | ) |

| absolute value, also normalised

int 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 normalised ie tv_sec and tv_nsec of the result have the same size abs(result.tv_nsec) <= 1000000000

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

| strict equality

Timespec timespecCanonicalDayTime | ( | Timespec | t | ) |

| timespecCanonicalDayTime given a timepair contains any time on a certain day (local time) converts it to be midday that day.

void timespecFromTime_t | ( | Timespec * | ts,
|  | time_t | t
| ) |

| Turns a time_t into a Timespec

time_t timespecToTime_t | ( | Timespec | ts | ) |

| Turns a Timespec into a time_t

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.

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.

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 ...

char* xaccPrintDateSecs | ( | time_t | secs | ) |

| DOCUMENT ME!

time_t xaccScanDateS | ( | const char * | buff | ) |

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 ...