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 unsigned int timespec. More...
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.
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.
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)
void	timespecFromTime_t (Timespec *ts, time_t t)
time_t	timespecToTime_t (Timespec ts)
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)
time_t	xaccDMYToSec (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
gchar *	qof_format_time (const gchar *format, const struct tm *tm)
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, time_t secs)
size_t	qof_print_gdate (char *buf, size_t bufflen, const GDate *gd)
char *	qof_print_date (time_t secs)
const char *	gnc_print_date (Timespec ts)
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)
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)
int	date_get_last_mday (const struct tm *tm)
gboolean	date_is_last_mday (const 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)
void	gnc_dow_abbrev (gchar *buf, int buf_len, int dow)
#define	MIN_BUF_LEN   10
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
gchar	dateSeparator (void)
Variables
const char *	gnc_default_strftime_date_format

---

Define Documentation

#define MAX_DATE_LENGTH   31

The maximum length of a string created by the date printers

Definition at line 76 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 107 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 88 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 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 174 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.

Enumerator:

GNCDATE_MONTH_NUMBER
GNCDATE_MONTH_ABBREV
GNCDATE_MONTH_NAME

Definition at line 113 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 91 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

int date_get_last_mday

(

const struct tm *

tm

)

Get the numerical last date of the month. (28, 29, 30, 31)

Definition at line 292 of file gnc-date.c.

{
  return gnc_date_my_last_mday (tm->tm_mon+1, tm->tm_year+1900);
}

gboolean date_is_last_mday

(

const struct tm *

tm

)

Is the mday field the last day of the specified month.

Definition at line 304 of file gnc-date.c.

{
  return(tm->tm_mday == date_get_last_mday(tm));
}

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 804 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 */
        unsigned char string[256];
        struct tm tm;
        time_t secs;
        unsigned char *s;

        secs = time(NULL);
        localtime_r(&secs, &tm);
        qof_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
	)

Deprecated:

Use date_get_last_mday()

Definition at line 270 of file gnc-date.c.

{
  static int last_day_of_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) return last_day_of_month[1][month-1];
  if (year % 400 == 0 ) return last_day_of_month[0][month-1];
  if (year % 4   == 0 ) return last_day_of_month[1][month-1];
  return last_day_of_month[0][month-1];
}

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.

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.

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

Convert a day, month, and year to a Timespec

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.

Parameters:

	buf_len	at least MIN_BUF_LEN
	dow	struct tm semantics: 0=sunday .. 6=saturday

Definition at line 1404 of file gnc-date.c.

{
    struct tm my_tm;
    int i;

    memset(buf, 0, buf_len);
    memset(&my_tm, 0, sizeof(struct tm));
    my_tm.tm_wday = dow;
    i = qof_strftime(buf, buf_len, "%a", &my_tm);
    buf[i] = 0;
}

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.

Returns:

The universl time.

XXX Caution: this routine does not handle strings that specify times before January 1 1970.

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 502 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,
		gint *	day,
		gint *	month,
		gint *	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()

Definition at line 1205 of file gnc-date.c.

{
  struct tm result;
  time_t t_secs = t.tv_sec + (t.tv_nsec / NANOS_PER_SECOND);
  localtime_r(&t_secs, &result);
  return date_get_last_mday (&result);
}

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.

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 1362 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_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 1353 of file gnc-date.c.

{
  struct tm tm;

  gnc_tm_get_day_start(&tm, time_val);
  return mktime(&tm);
}

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 1395 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 1386 of file gnc-date.c.

{
  struct tm tm;

  gnc_tm_get_day_start(&tm, time(NULL));
  return mktime(&tm);
}

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.

Definition at line 1306 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 (long int)(timezone - (tm->tm_isdst > 0 ? 3600 : 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 1345 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 1337 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 1380 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 1374 of file gnc-date.c.

{
  gnc_tm_get_day_start(tm, time(NULL));
}

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 315 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 355 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 331 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 383 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;
  };
}

gchar* qof_format_time	(	const gchar *	format,
		const struct tm *	tm
	)

qof_format_time takes a format specification in UTF-8 and a broken-down time, tries to call strftime with a sufficiently large buffer and, if successful, return a newly allocated string in UTF-8 for the printing result.

Parameters:

	format	A format specification in UTF-8.
	tm	A broken-down time.

Returns:

A newly allocated string on success, or NULL otherwise.

Definition at line 878 of file gnc-date.c.

{
    gchar *locale_format, *tmpbuf, *retval;
    gsize tmplen, tmpbufsize;

    g_return_val_if_fail(format, 0);
    g_return_val_if_fail(tm, 0);

    locale_format = qof_time_format_from_utf8(format);
    if (!locale_format)
        return NULL;

    tmpbufsize = MAX(128, strlen(locale_format) * 2);
    while (TRUE) {
        tmpbuf = g_malloc(tmpbufsize);

        /* Set the first byte to something other than '\0', to be able to
         * recognize whether strftime actually failed or just returned "".
         */
        tmpbuf[0] = '\1';
        tmplen = strftime(tmpbuf, tmpbufsize, locale_format, tm);

        if (tmplen == 0 && tmpbuf[0] != '\0') {
            g_free(tmpbuf);
            tmpbufsize *= 2;

            if (tmpbufsize > 65536) {
                g_warning("Maximum buffer size for qof_format_time "
                          "exceeded: giving up");
                g_free(locale_format);

                return NULL;
            }
        } else {
            break;
        }
    }
    g_free(locale_format);

    retval = qof_formatted_time_to_utf8(tmpbuf);
    g_free(tmpbuf);

    return retval;
}

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 494 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 470 of file gnc-date.c.

{
  struct tm theTime;

  if (!buff) return 0 ;

  localtime_r(&t, &theTime);

  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	(	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_gdate	(	char *	buf,
		size_t	bufflen,
		const GDate *	gd
	)

Convenience; calls through to qof_print_date_dmy_buff().

Definition at line 485 of file gnc-date.c.

{
  return qof_print_date_dmy_buff( buf, len,
             g_date_get_day(gd),
             g_date_get_month(gd),
             g_date_get_year(gd) );
}

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 573 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 = qof_strftime(buff, len, QOF_UTC_DATE_FORMAT, &gtm);
                return flen;
        }
        ltm = *localtime (&secs);
        flen = qof_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 784 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 790 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;
}

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.

Parameters:

	buf	A buffer.
	max	The size of buf in bytes.
	format	A format specification in UTF-8.
	tm	A 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 924 of file gnc-date.c.

{
    gsize convlen, retval;
    gchar *convbuf;

    g_return_val_if_fail(buf, 0);
    g_return_val_if_fail(max > 0, 0);
    g_return_val_if_fail(format, 0);
    g_return_val_if_fail(tm, 0);

    convbuf = qof_format_time(format, tm);
    if (!convbuf) {
        buf[0] = '\0';
        return 0;
    }

    convlen = strlen(convbuf);

    if (max <= convlen) {
        /* Ensure only whole characters are copied into the buffer. */
        gchar *end = g_utf8_find_prev_char(convbuf, convbuf + max);
        g_assert(end != NULL);
        convlen = end - convbuf;

        /* Return 0 because the buffer isn't large enough. */
        retval = 0;
    } else {
        retval = convlen;
    }

    memcpy(buf, convbuf, convlen);
    buf[convlen] = '\0';
    g_free(convbuf);

    return retval;
}

Timespec timespec_abs

(

const Timespec *

t

)

absolute value, also normalised

Definition at line 238 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;
}

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

comparison: if (ta < tb) -1; else if (ta > tb) 1; else 0;

Definition at line 217 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 228 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 208 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 258 of file gnc-date.c.

{
  struct tm tm;
  Timespec retval;
  time_t t_secs = t.tv_sec + (t.tv_nsec / NANOS_PER_SECOND);
  localtime_r(&t_secs, &tm);
  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 1324 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 1331 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 975 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 1002 of file gnc-date.c.

{
   time_t now;
   time (&now);
   return xaccDateUtilGetStamp (now);
}

time_t xaccDMYToSec	(	gint	day,
		gint	month,
		gint	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.

---

Variable Documentation

const char* gnc_default_strftime_date_format

The default date format for use with strftime.

Definition at line 73 of file gnc-date.c.

---