Date: Date and Time Printing, Parsing and Manipulation

Utility functions to handle date and time (adjusting, getting the current date, printing the date and time, etc.) More...

Files
file	gnc-date.h
	Date and Time handling routines.

Data Structures
struct	Time64

Macros
#define	MAX_DATE_LENGTH   34
	The maximum length of a string created by the date printers.
#define	QOF_UTC_DATE_FORMAT   "%Y-%m-%dT%H:%M:%SZ"
	Constants.
#define	DATE_FORMAT_FIRST   QOF_DATE_FORMAT_US
#define	DATE_FORMAT_LAST   QOF_DATE_FORMAT_UTC

Typedefs
typedef gint64	time64
	Most systems that are currently maintained, including Microsoft Windows, BSD-derived Unixes and Linux, support 64-bit time_t even on 32-bit architectures.

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 , QOF_DATE_FORMAT_UNSET }
	Enum for determining a date format. More...
enum	QofDateCompletion { QOF_DATE_COMPLETION_THISYEAR , QOF_DATE_COMPLETION_SLIDING }
	Enum for date completion modes (for dates entered without year) More...
enum	GNCDateMonthFormat { GNCDATE_MONTH_NUMBER , GNCDATE_MONTH_ABBREV , GNCDATE_MONTH_NAME }
	This is how to format the month, as a number, an abbreviated string, or the full name. More...

Functions
struct tm *	gnc_localtime (const time64 *secs)
	fill out a time struct from a 64-bit time value.
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.
struct tm *	gnc_gmtime (const time64 *secs)
	fill out a time struct from a 64-bit time value
gint	gnc_start_of_week (void)
	returns an integer corresponding to locale start of week
time64	gnc_mktime (struct tm *time)
	calculate seconds from the epoch given a time struct
time64	gnc_timegm (struct tm *time)
	calculate seconds from the epoch given a time struct
gchar *	gnc_ctime (const time64 *secs)
	Return a string representation of a date from a 64-bit time value.
time64	gnc_time (time64 *tbuf)
	get the current time
gdouble	gnc_difftime (const time64 secs1, const time64 secs2)
	Find the difference in seconds between two time values (deprecated)
void	gnc_tm_free (struct tm *time)
	free a struct tm* created with gnc_localtime() or gnc_gmtime()
time64	time64CanonicalDayTime (time64 t)
	convert a time64 on a certain day (localtime) to the time64 representing midday on that day.
time64	gdate_to_time64 (GDate d)
	Turns a GDate into a time64, returning the first second of the day.
time64	gnc_dmy2time64 (gint day, gint month, gint year)
	Convert a day, month, and year to a time64, returning the first second of the day.
time64	gnc_dmy2time64_neutral (gint day, gint month, gint year)
	Converts a day, month, and year to a time64 representing 11:00:00 UTC 11:00:00 UTC falls on the same time in almost all timezones, the exceptions being the +13, +14, and -12 timezones used by countries along the International Date Line.
time64	gnc_dmy2time64_end (gint day, gint month, gint year)
	Same as gnc_dmy2time64, but last second of the day.
time64	gnc_iso8601_to_time64_gmt (const gchar *)
	The gnc_iso8601_to_time64_gmt() routine converts an ISO-8601 style date/time string to time64.
gchar *	gnc_time64_to_iso8601_buff (time64, char *buff)
	The gnc_time64_to_iso8601_buff() routine takes the input UTC time64 value and prints it as an ISO-8601 style string.

Variables
time64	Time64::t
const char *	gnc_default_strftime_date_format
	The default date format for use with strftime.

GValue
GType	time64_get_type (void)
#define	GNC_TYPE_TIME64   (time64_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.
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.
char *	gnc_print_time64 (time64 time, const char *format)
	print a time64 as a date string per format

GDate time64 setters
GDate *	gnc_g_date_new_today (void)
	Returns a newly allocated date of the current clock time, taken from time(2).
void	gnc_gdate_set_today (GDate *gd)
	Set a GDate to the current day.
void	gnc_gdate_set_time64 (GDate *gd, time64 time)
	Set a GDate to a time64.

QofDateFormat functions
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 scanning routines will assume when parsing a date.
void	qof_date_format_set (QofDateFormat df)
	The qof_date_format_set() routine sets date format to one of US, UK, CE, OR ISO.
const gchar *	qof_date_format_get_string (QofDateFormat df)
	This function returns a strftime formatting string for printing an all numeric date (e.g.
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.
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).
gchar	dateSeparator (void)
	dateSeparator Return the field separator for the current date format

Date Printing/Scanning functions
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.
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
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_gdate (char *buf, size_t bufflen, const GDate *gd)
	Convenience; calls through to qof_print_date_dmy_buff().
char *	qof_print_date (time64 secs)
	Convenience; calls through to qof_print_date_dmy_buff().
gchar *	gnc_date_interval_format (time64 from_date, time64 to_date)
size_t	qof_print_date_time_buff (char *buff, size_t len, time64 secs)
	Returns the number of bytes printed.
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.

Date Start/End Adjustment routines
Given a time value, adjust it to be the beginning or end of that day.
void	gnc_tm_set_day_neutral (struct tm *tm)
	The gnc_tm_set_day_neutral() inline routine will set the appropriate fields in the struct tm to indicate 10:59am of that day.
time64	gnc_time64_get_day_start (time64 time_val)
	The gnc_time64_get_day_start() routine will take the given time in seconds and adjust it to the first second of that day.
time64	gnc_time64_get_day_neutral (time64 time_val)
	The gnc_time64_get_day_neutral() routine will take the given time in seconds and adjust it to 10:59:00Z of that day.
time64	gnc_time64_get_day_end (time64 time_val)
	The gnc_time64_get_day_end() routine will take the given time in seconds and adjust it to the last second of that day.
int	gnc_date_get_last_mday (int month, int year)
	Get the numerical last date of the month.

Today's Date
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	gnc_tm_get_today_neutral (struct tm *tm)
	The gnc_tm_get_today_start() routine takes a pointer to a struct tm and fills it in with the timezone neutral time (10:59:00Z).
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.
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.
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.
char *	gnc_date_timestamp (void)
	Make a timestamp in YYYYMMDDHHMMSS format.
void	gnc_dow_abbrev (gchar *buf, int buf_len, int dow)
	Localized DOW abbreviation.
#define	MIN_BUF_LEN   10

GDate hash table support
gint	gnc_gdate_equal (gconstpointer gda, gconstpointer gdb)
	Compares two GDate*'s for equality; useful for using GDate*'s as GHashTable keys.
guint	gnc_gdate_hash (gconstpointer gd)
	Provides a "hash" of a GDate* value; useful for using GDate*'s as GHashTable keys.

GDate to time64 conversions
GDate	time64_to_gdate (time64 t)
	Returns the GDate in which the time64 occurs.
time64	gnc_time64_get_day_start_gdate (const GDate *date)
	The gnc_time64_get_day_start() routine will take the given time in GLib GDate format and adjust it to the first second of that day.
time64	gnc_time64_get_day_end_gdate (const GDate *date)
	The gnc_time64_get_day_end() routine will take the given time in GLib GDate format and adjust it to the last second of that day.

Date Manipulation
void	gnc_gdate_set_month_start (GDate *date)
	This function modifies a GDate to set it to the first day of the month in which it falls.
void	gnc_gdate_set_month_end (GDate *date)
	This function modifies a GDate to set it to the last day of the month in which it falls.
void	gnc_gdate_set_prev_month_start (GDate *date)
	This function modifies a GDate to set it to the first day of the month prior to the one in which it falls.
void	gnc_gdate_set_prev_month_end (GDate *date)
	This function modifies a GDate to set it to the last day of the month prior to the one in which it falls.
void	gnc_gdate_set_quarter_start (GDate *date)
	This function modifies a GDate to set it to the first day of the quarter in which it falls.
void	gnc_gdate_set_quarter_end (GDate *date)
	This function modifies a GDate to set it to the last day of the quarter in which it falls.
void	gnc_gdate_set_prev_quarter_start (GDate *date)
	This function modifies a GDate to set it to the first day of the quarter prior to the one in which it falls.
void	gnc_gdate_set_prev_quarter_end (GDate *date)
	This function modifies a GDate to set it to the last day of the quarter prior to the one in which it falls.
void	gnc_gdate_set_year_start (GDate *date)
	This function modifies a GDate to set it to the first day of the year in which it falls.
void	gnc_gdate_set_year_end (GDate *date)
	This function modifies a GDate to set it to the last day of the year in which it falls.
void	gnc_gdate_set_prev_year_start (GDate *date)
	This function modifies a GDate to set it to the first day of the year prior to the one in which it falls.
void	gnc_gdate_set_prev_year_end (GDate *date)
	This function modifies a GDate to set it to the last day of the year prior to the one in which it falls.
void	gnc_gdate_set_fiscal_year_start (GDate *date, const GDate *year_end)
	This function modifies a GDate to set it to the first day of the fiscal year in which it falls.
void	gnc_gdate_set_fiscal_year_end (GDate *date, const GDate *year_end)
	This function modifies a GDate to set it to the last day of the fiscal year in which it falls.
void	gnc_gdate_set_prev_fiscal_year_start (GDate *date, const GDate *year_end)
	This function modifies a GDate to set it to the first day of the fiscal year prior to the one in which it falls.
void	gnc_gdate_set_prev_fiscal_year_end (GDate *date, const GDate *year_end)
	This function modifies a GDate to set it to the last day of the fiscal year prior to the one in which it falls.

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.

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-Greenwich (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 rclar.nosp@m.k@cs.nosp@m..hmc..nosp@m.edu

Copyright (C) 1998-2001,2003 Linas Vepstas linas.nosp@m.@lin.nosp@m.as.or.nosp@m.g

Macro Definition Documentation

DATE_FORMAT_FIRST

#define DATE_FORMAT_FIRST   QOF_DATE_FORMAT_US

Definition at line 134 of file gnc-date.h.

DATE_FORMAT_LAST

#define DATE_FORMAT_LAST   QOF_DATE_FORMAT_UTC

Definition at line 135 of file gnc-date.h.

GNC_TYPE_TIME64

#define GNC_TYPE_TIME64   (time64_get_type ())

Definition at line 101 of file gnc-date.h.

MAX_DATE_LENGTH

#define MAX_DATE_LENGTH   34

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

Definition at line 108 of file gnc-date.h.

MIN_BUF_LEN

#define MIN_BUF_LEN   10

Definition at line 613 of file gnc-date.h.

QOF_UTC_DATE_FORMAT

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

Constants.

UTC date format string.

Time zone 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 time zone independent and include all specified fields. Remember to use gmtime() NOT localtime()!

Definition at line 119 of file gnc-date.h.

Typedef Documentation

time64

typedef gint64 time64

Most systems that are currently maintained, including Microsoft Windows, BSD-derived Unixes and Linux, support 64-bit time_t even on 32-bit architectures.

See https://en.wikipedia.org/wiki/Year_2038_problem

For practical reasons – as not all have made the transition to 64-bit – we define our own 64-bit time type.

Definition at line 87 of file gnc-date.h.

Enumeration Type Documentation

GNCDateMonthFormat

enum GNCDateMonthFormat

This is how to format the month, as a number, an abbreviated string, or the full name.

Definition at line 148 of file gnc-date.h.

{
    GNCDATE_MONTH_NUMBER,
    GNCDATE_MONTH_ABBREV,
    GNCDATE_MONTH_NAME
} GNCDateMonthFormat;

QofDateCompletion

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

{
    QOF_DATE_COMPLETION_THISYEAR, 
    QOF_DATE_COMPLETION_SLIDING,  
} QofDateCompletion;

QofDateFormat

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_LOCALE	Take from locale information.
QOF_DATE_FORMAT_UTC	UTC: 2004-12-12T23:39:11Z.
QOF_DATE_FORMAT_CUSTOM	Used by the check printing code.
QOF_DATE_FORMAT_UNSET	No Fancy Date Format, use Global.

Definition at line 122 of file gnc-date.h.

{
    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,   
    QOF_DATE_FORMAT_UNSET     
} QofDateFormat;

Function Documentation

dateSeparator()

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 999 of file gnc-date.cpp.

{
    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 */
            gchar string[256];
            struct tm tm;
            time64 secs;
            gchar *s;
 
            secs = gnc_time (nullptr);
            gnc_localtime_r(&secs, &tm);
            auto normalized_fmt =
                normalize_format(qof_date_format_get_string(dateFormat));
            qof_strftime(string, sizeof(string), normalized_fmt.c_str(), &tm);
 
            for (s = string; *s != '\0'; s++)
                if (!isdigit(*s))
                    return (locale_separator = *s);
        }
        break;
    }
    return '\0';
}

gdate_to_time64()

time64 gdate_to_time64

(

GDate

d

)

Turns a GDate into a time64, returning the first second of the day.

Definition at line 1323 of file gnc-date.cpp.

{
    return gnc_dmy2time64_neutral (g_date_get_day(&d),
                                     g_date_get_month(&d),
                                     g_date_get_year(&d));
}

gnc_ctime()

gchar * gnc_ctime

(

const time64 *

secs

)

Return a string representation of a date from a 64-bit time value.

Parameters

secs	Seconds since 00:00:00 UTC 01 January 1970 (negative values are seconds before that moment)

Returns

A string, which must be freed with g_free(), representing the date in the following format: Thu Nov 24 18:22:48 1986
\0 This is equivalent to the strftime format a b H:M:S Y.

Definition at line 256 of file gnc-date.cpp.

{
    return gnc_print_time64(*secs, "%a %b %d %H:%M:%S %Y");
}

gnc_date_dateformat_to_string()

const gchar * gnc_date_dateformat_to_string

(

QofDateFormat

format

)

The string->value versions return FALSE on success and TRUE on failure.

Definition at line 281 of file gnc-date.cpp.

{
    switch (format)
    {
    case QOF_DATE_FORMAT_US:
        return "us";
    case QOF_DATE_FORMAT_UK:
        return "uk";
    case QOF_DATE_FORMAT_CE:
        return "ce";
    case QOF_DATE_FORMAT_ISO:
        return "iso";
    case QOF_DATE_FORMAT_UTC:
        return "utc";
    case QOF_DATE_FORMAT_LOCALE:
        return "locale";
    case QOF_DATE_FORMAT_CUSTOM:
        return "custom";
    case QOF_DATE_FORMAT_UNSET:
        return "unset";
    default:
        return nullptr;
    }
}

gnc_date_get_last_mday()

int gnc_date_get_last_mday	(	int	month,
		int	year
	)

Get the numerical last date of the month.

(28, 29, 30, 31)

Definition at line 413 of file gnc-date.cpp.

{
    static int last_day_of_month[12] =
        {31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31};
  
    g_assert(month >= 0 && month < 12);
 
    // To be a leap year, the year number must be divisible by four,
    // except for end-of-century years, which must be divisible by 400.
 
    return last_day_of_month[month] +
        (month == 1 && year % 4 == 0 && !(year % 100 == 0 && year % 400 != 0) ?
        1 : 0);
}

gnc_date_interval_format()

gchar * gnc_date_interval_format	(	time64	from_date,
		time64	to_date
	)

Definition at line 664 of file gnc-date.cpp.

{
    gchar* rv = nullptr;
 
    if (qof_date_format_get() == QOF_DATE_FORMAT_LOCALE)
        rv = icu_date_interval_format (from_date, to_date);
 
    // not using locale, or icu failure
    if (!rv)
    {
        gchar from_buff[MAX_DATE_LENGTH+1], to_buff[MAX_DATE_LENGTH+1];
        qof_print_date_buff (from_buff, MAX_DATE_LENGTH, from_date);
        qof_print_date_buff (to_buff, MAX_DATE_LENGTH, to_date);
        rv = g_strdup_printf (gettext("%s to %s"), from_buff, to_buff);
    }
 
    return rv;
}

gnc_date_monthformat_to_string()

const gchar * gnc_date_monthformat_to_string

(

GNCDateMonthFormat

format

)

Definition at line 335 of file gnc-date.cpp.

{
 //avoid UB if format is out of range
    switch (static_cast<uint8_t>(format))
    {
    case GNCDATE_MONTH_NUMBER:
        return "number";
    case GNCDATE_MONTH_ABBREV:
        return "abbrev";
    case GNCDATE_MONTH_NAME:
        return "name";
    default:
        return nullptr;
    }
}

gnc_date_string_to_dateformat()

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.

gnc_date_string_to_monthformat()

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.

gnc_date_timestamp()

char * gnc_date_timestamp

(

void

)

Make a timestamp in YYYYMMDDHHMMSS format.

Returns

A pointer to the generated string.

Note

The caller owns this buffer and must g_free it when done.

Definition at line 1174 of file gnc-date.cpp.

{
    auto timestamp = GncDateTime::timestamp();
    return g_strdup(timestamp.c_str());
}

gnc_difftime()

gdouble gnc_difftime	(	const time64	secs1,
		const time64	secs2
	)

Find the difference in seconds between two time values (deprecated)

Parameters

secs1	The first time value, in Seconds since 00:00:00 UTC 01 January 1970 (negative values are seconds before that moment)
secs2	The second time value, in Seconds since 00:00:00 UTC 01 January 1970 (negative values are seconds before that moment)

Returns

The difference in seconds between secs1 and secs2. If secs2 is later than secs1 the value will be negative.

Definition at line 272 of file gnc-date.cpp.

{
    PWARN ("gnc_difftime is deprecated");
    return (double)secs1 - (double)secs2;
}

gnc_dmy2time64_neutral()

time64 gnc_dmy2time64_neutral	(	gint	day,
		gint	month,
		gint	year
	)

Converts a day, month, and year to a time64 representing 11:00:00 UTC 11:00:00 UTC falls on the same time in almost all timezones, the exceptions being the +13, +14, and -12 timezones used by countries along the International Date Line.

Since users in those timezones would see dates immediately change by one day, the function checks the current timezone for those changes and adjusts the UTC time so that the date will be consistent.

gnc_dow_abbrev()

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 1435 of file gnc-date.cpp.

{
    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;
}

gnc_g_date_new_today()

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.

Definition at line 1298 of file gnc-date.cpp.

{
    GDate* rv = g_date_new ();
    gnc_gdate_set_today (rv);
    return rv;
}

gnc_gdate_equal()

gint gnc_gdate_equal	(	gconstpointer	gda,
		gconstpointer	gdb
	)

Compares two GDate*'s for equality; useful for using GDate*'s as GHashTable keys.

Definition at line 1471 of file gnc-date.cpp.

{
    return (g_date_compare( (GDate*)gda, (GDate*)gdb ) == 0 ? TRUE : FALSE);
}

gnc_gdate_hash()

guint gnc_gdate_hash

(

gconstpointer

gd

)

Provides a "hash" of a GDate* value; useful for using GDate*'s as GHashTable keys.

Definition at line 1477 of file gnc-date.cpp.

{
    gint val = (g_date_get_year( (GDate*)gd ) * 10000)
               + (g_date_get_month( (GDate*)gd ) * 100)
               + g_date_get_day( (GDate*)gd );
    return g_int_hash( &val );
}

gnc_gdate_set_fiscal_year_end()

void gnc_gdate_set_fiscal_year_end	(	GDate *	date,
		const GDate *	year_end
	)

This function modifies a GDate to set it to the last day of the fiscal year in which it falls.

For example, if this function is called with a date of 2003-09-24 and a fiscal year ending July 31st, the date will be modified to 2004-07-31.

Parameters

date	The GDate to modify.
year_end	A GDate containing the last month and day of the fiscal year. The year field of this argument is ignored.

Definition at line 1674 of file gnc-date.cpp.

{
    GDate temp;
    gboolean new_fy;
 
    g_return_if_fail(date);
    g_return_if_fail(fy_end);
 
    /* Compute the FY end that occurred this CY */
    temp = *fy_end;
    g_date_set_year(&temp, g_date_get_year(date));
 
    /* Has it already passed? */
    new_fy = (g_date_compare(date, &temp) > 0);
 
    /* Set end date */
    *date = temp;
    if (new_fy)
        g_date_add_years(date, 1);
}

gnc_gdate_set_fiscal_year_start()

void gnc_gdate_set_fiscal_year_start	(	GDate *	date,
		const GDate *	year_end
	)

This function modifies a GDate to set it to the first day of the fiscal year in which it falls.

For example, if this function is called with a date of 2003-09-24 and a fiscal year ending July 31st, the date will be modified to 2003-08-01.

Parameters

date	The GDate to modify.
year_end	A GDate containing the last month and day of the fiscal year. The year field of this argument is ignored.

Definition at line 1650 of file gnc-date.cpp.

{
    GDate temp;
    gboolean new_fy;
 
    g_return_if_fail(date);
    g_return_if_fail(fy_end);
 
    /* Compute the FY end that occurred this CY */
    temp = *fy_end;
    g_date_set_year(&temp, g_date_get_year(date));
 
    /* Has it already passed? */
    new_fy = (g_date_compare(date, &temp) > 0);
 
    /* Set start date */
    *date = temp;
    g_date_add_days(date, 1);
    if (!new_fy)
        g_date_subtract_years(date, 1);
}

gnc_gdate_set_month_end()

void gnc_gdate_set_month_end

(

GDate *

date

)

This function modifies a GDate to set it to the last day of the month in which it falls.

For example, if this function is called with a date of 2003-09-24 the date will be modified to 2003-09-30.

Parameters

date	The GDate to modify.

This function modifies a GDate to set it to the last day of the month in which it falls.

This routine has no knowledge of how many days are in a month, whether its a leap year, etc. All that information is contained in the glib date functions.

Parameters

date	The GDate to modify.

Definition at line 1537 of file gnc-date.cpp.

{
    /* First set the start of next month. */
    g_date_set_day(date, 1);
    g_date_add_months(date, 1);
 
    /* Then back up one day */
    g_date_subtract_days(date, 1);
}

gnc_gdate_set_month_start()

void gnc_gdate_set_month_start

(

GDate *

date

)

This function modifies a GDate to set it to the first day of the month in which it falls.

For example, if this function is called with a date of 2003-09-24 the date will be modified to 2003-09-01.

Parameters

date	The GDate to modify.

Definition at line 1524 of file gnc-date.cpp.

{
    g_date_set_day(date, 1);
}

gnc_gdate_set_prev_fiscal_year_end()

void gnc_gdate_set_prev_fiscal_year_end	(	GDate *	date,
		const GDate *	year_end
	)

This function modifies a GDate to set it to the last day of the fiscal year prior to the one in which it falls.

For example, if this function is called with a date of 2003-09-24 and a fiscal year ending July 31st, the date will be modified to 2003-07-31.

Parameters

date	The GDate to modify.
year_end	A GDate containing the last month and day of the fiscal year. The year field of this argument is ignored.

Definition at line 1708 of file gnc-date.cpp.

{
    g_return_if_fail(date);
    g_return_if_fail(fy_end);
 
    gnc_gdate_set_fiscal_year_end(date, fy_end);
    g_date_subtract_years(date, 1);
}

gnc_gdate_set_prev_fiscal_year_start()

void gnc_gdate_set_prev_fiscal_year_start	(	GDate *	date,
		const GDate *	year_end
	)

This function modifies a GDate to set it to the first day of the fiscal year prior to the one in which it falls.

For example, if this function is called with a date of 2003-09-24 and a fiscal year ending July 31st, the date will be modified to 2002-08-01.

Parameters

date	The GDate to modify.
year_end	A GDate containing the last month and day of the fiscal year. The year field of this argument is ignored.

Definition at line 1697 of file gnc-date.cpp.

{
    g_return_if_fail(date);
    g_return_if_fail(fy_end);
 
    gnc_gdate_set_fiscal_year_start(date, fy_end);
    g_date_subtract_years(date, 1);
}

gnc_gdate_set_prev_month_end()

void gnc_gdate_set_prev_month_end

(

GDate *

date

)

This function modifies a GDate to set it to the last day of the month prior to the one in which it falls.

For example, if this function is called with a date of 2003-09-24 the date will be modified to 2003-08-31.

Parameters

date	The GDate to modify.

This function modifies a GDate to set it to the last day of the month prior to the one in which it falls.

This routine has no knowledge of how many days are in a month, whether its a leap year, etc. All that information is contained in the glib date functions.

Parameters

date	The GDate to modify.

Definition at line 1569 of file gnc-date.cpp.

{
    /* This will correctly handle the varying month lengths */
    g_date_set_day(date, 1);
    g_date_subtract_days(date, 1);
}

gnc_gdate_set_prev_month_start()

void gnc_gdate_set_prev_month_start

(

GDate *

date

)

This function modifies a GDate to set it to the first day of the month prior to the one in which it falls.

For example, if this function is called with a date of 2003-09-24 the date will be modified to 2003-08-01.

Parameters

date	The GDate to modify.

This function modifies a GDate to set it to the first day of the month prior to the one in which it falls.

This routine has no knowledge of how many days are in a month, whether its a leap year, etc. All that information is contained in the glib date functions.

Parameters

date	The GDate to modify.

Definition at line 1555 of file gnc-date.cpp.

{
    g_date_set_day(date, 1);
    g_date_subtract_months(date, 1);
}

gnc_gdate_set_prev_quarter_end()

void gnc_gdate_set_prev_quarter_end

(

GDate *

date

)

This function modifies a GDate to set it to the last day of the quarter prior to the one in which it falls.

For example, if this function is called with a date of 2003-09-24 the date will be modified to 2003-06-30.

Parameters

date	The GDate to modify.

Definition at line 1611 of file gnc-date.cpp.

{
    g_date_subtract_months(date, 3);
    gnc_gdate_set_quarter_end(date);
}

gnc_gdate_set_prev_quarter_start()

void gnc_gdate_set_prev_quarter_start

(

GDate *

date

)

This function modifies a GDate to set it to the first day of the quarter prior to the one in which it falls.

For example, if this function is called with a date of 2003-09-24 the date will be modified to 2003-04-01.

Parameters

date	The GDate to modify.

Definition at line 1604 of file gnc-date.cpp.

{
    g_date_subtract_months(date, 3);
    gnc_gdate_set_quarter_start(date);
}

gnc_gdate_set_prev_year_end()

void gnc_gdate_set_prev_year_end

(

GDate *

date

)

This function modifies a GDate to set it to the last day of the year prior to the one in which it falls.

For example, if this function is called with a date of 2003-09-24 the date will be modified to 2002-12-31.

Parameters

date	The GDate to modify.

Definition at line 1641 of file gnc-date.cpp.

{
    gnc_gdate_set_year_end(date);
    g_date_subtract_years(date, 1);
}

gnc_gdate_set_prev_year_start()

void gnc_gdate_set_prev_year_start

(

GDate *

date

)

This function modifies a GDate to set it to the first day of the year prior to the one in which it falls.

For example, if this function is called with a date of 2003-09-24 the date will be modified to 2002-01-01.

Parameters

date	The GDate to modify.

Definition at line 1634 of file gnc-date.cpp.

{
    gnc_gdate_set_year_start(date);
    g_date_subtract_years(date, 1);
}

gnc_gdate_set_quarter_end()

void gnc_gdate_set_quarter_end

(

GDate *

date

)

This function modifies a GDate to set it to the last day of the quarter in which it falls.

For example, if this function is called with a date of 2003-09-24 the date will be modified to 2003-09-30.

Parameters

date	The GDate to modify.

Definition at line 1592 of file gnc-date.cpp.

{
     const GDateMonth months[] = {G_DATE_MARCH, G_DATE_JUNE,
                                  G_DATE_SEPTEMBER, G_DATE_DECEMBER};
     const GDateDay days[] = {31, 30, 30, 31};
     int quarter = (g_date_get_month (date) - 1) / 3;
 
     g_date_set_month (date, months[quarter]);
     g_date_set_day (date, days[quarter]);
}

gnc_gdate_set_quarter_start()

void gnc_gdate_set_quarter_start

(

GDate *

date

)

This function modifies a GDate to set it to the first day of the quarter in which it falls.

For example, if this function is called with a date of 2003-09-24 the date will be modified to 2003-07-01.

Parameters

date	The GDate to modify.

Definition at line 1579 of file gnc-date.cpp.

{
    gint months;
 
    /* Set the date to the first day of the specified month. */
    g_date_set_day(date, 1);
 
    /* Back up 0-2 months */
    months = (g_date_get_month(date) - G_DATE_JANUARY) % 3;
    g_date_subtract_months(date, months);
}

gnc_gdate_set_time64()

void gnc_gdate_set_time64	(	GDate *	gd,
		time64	time
	)

Set a GDate to a time64.

Parameters

gd	the date to act on
time	the time to set it to.

Definition at line 1314 of file gnc-date.cpp.

{
    struct tm tm;
    gnc_localtime_r(&time, &tm);
    g_date_set_dmy (gd, tm.tm_mday,
                    static_cast<GDateMonth>(tm.tm_mon + 1),
                    tm.tm_year + 1900);
}

gnc_gdate_set_today()

void gnc_gdate_set_today

(

GDate *

gd

)

Set a GDate to the current day.

Parameters

gd	The date to act on

Definition at line 1306 of file gnc-date.cpp.

{
    g_return_if_fail (gd != nullptr);
    auto ymd = GncDate().year_month_day();
    g_date_set_dmy (gd, ymd.day, static_cast<GDateMonth>(ymd.month), ymd.year);
}

gnc_gdate_set_year_end()

void gnc_gdate_set_year_end

(

GDate *

date

)

This function modifies a GDate to set it to the last day of the year in which it falls.

For example, if this function is called with a date of 2003-09-24 the date will be modified to 2003-12-31.

Parameters

date	The GDate to modify.

Definition at line 1627 of file gnc-date.cpp.

{
    g_date_set_month(date, G_DATE_DECEMBER);
    g_date_set_day(date, 31);
}

gnc_gdate_set_year_start()

void gnc_gdate_set_year_start

(

GDate *

date

)

This function modifies a GDate to set it to the first day of the year in which it falls.

For example, if this function is called with a date of 2003-09-24 the date will be modified to 2003-01-01.

Parameters

date	The GDate to modify.

Definition at line 1620 of file gnc-date.cpp.

{
    g_date_set_month(date, G_DATE_JANUARY);
    g_date_set_day(date, 1);
}

gnc_gmtime()

struct tm * gnc_gmtime

(

const time64 *

secs

)

fill out a time struct from a 64-bit time value

Parameters

secs	Seconds since 00:00:00 UTC 01 January 1970 (negative values are seconds before that moment)

Returns

A struct tm*, allocated on the heap. Must be freed with gnc_tm_free() The time is UTC.

Definition at line 178 of file gnc-date.cpp.

{
    try
    {
        GncDateTime gncdt(*secs);
        auto time = static_cast<struct tm*>(calloc(1, sizeof(struct tm)));
        *time = gncdt.utc_tm();
        return time;
    }
    catch(std::invalid_argument&)
    {
        return nullptr;
    }
 
}

gnc_iso8601_to_time64_gmt()

time64 gnc_iso8601_to_time64_gmt

(

const gchar *

)

The gnc_iso8601_to_time64_gmt() routine converts an ISO-8601 style date/time string to time64.

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 time zone information along with a local-time string. But fundamentally, they are UTC. Thus, this 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 milliseconds after 16:00:00 hours UTC.

Returns

The universal time.

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

gnc_localtime()

struct tm * gnc_localtime

(

const time64 *

secs

)

fill out a time struct from a 64-bit time value.

Parameters

secs	Seconds since 00:00:00 UTC 01 January 1970 (negative values are seconds before that moment).

Returns

A struct tm*, allocated on the heap. Must be freed with gnc_tm_free(). The time is adjusted for the current local time zone.

Definition at line 103 of file gnc-date.cpp.

{
    auto time = static_cast<struct tm*>(calloc(1, sizeof(struct tm)));
    if (gnc_localtime_r (secs, time) == nullptr)
    {
        gnc_tm_free (time);
        return nullptr;
    }
    return time;
}

gnc_localtime_r()

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.

Parameters

secs	Seconds since 00:00:00 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.

Definition at line 115 of file gnc-date.cpp.

{
    try
    {
        *time = static_cast<struct tm>(GncDateTime(*secs));
        return time;
    }
    catch(std::invalid_argument&)
    {
        return nullptr;
    }
}

gnc_mktime()

time64 gnc_mktime

(

struct tm *

time

)

calculate seconds from the epoch given a time struct

Parameters

time	A struct tm* containing the date-time information. The time is understood to be in the current local time zone.

Returns

Seconds since 00:00:00 UTC 01 January 1970 (negative values are seconds before that moment).

Definition at line 219 of file gnc-date.cpp.

{
    try
    {
        normalize_struct_tm (time);
        GncDateTime gncdt(*time);
        *time = static_cast<struct tm>(gncdt);
        return static_cast<time64>(gncdt);
    }
    catch(std::invalid_argument&)
    {
        return 0;
    }
}

gnc_print_time64()

char * gnc_print_time64	(	time64	time,
		const char *	format
	)

print a time64 as a date string per format

Parameters

time	The time64 to print
format	A date format conforming to the strftime format rules.

Returns

a raw heap-allocated char* which must be freed.

Definition at line 370 of file gnc-date.cpp.

{
    try
    {
        GncDateTime gncdt(time);
        auto sstr = gncdt.format(format);
        //ugly C allocation so that the ptr can be freed at the other end
        char* cstr = static_cast<char*>(malloc(sstr.length() + 1));
        memset(cstr, 0, sstr.length() + 1);
        strncpy(cstr, sstr.c_str(), sstr.length());
        return cstr;
    }
    catch(std::runtime_error& err)
    {
        PWARN("Error processing time64 %" PRId64 ": %s", time, err.what());
        return nullptr;
    }
    catch(std::logic_error& err)
    {
        PWARN("Error processing time64 %" PRId64 ": %s", time, err.what());
        return nullptr;
    }
}

gnc_start_of_week()

gint gnc_start_of_week

(

void

)

returns an integer corresponding to locale start of week

Returns

An integer 1=Sunday, 2=Monday etc. If error, return 0.

Definition at line 195 of file gnc-date.cpp.

{
    /* icu's day of week is 1 based. Using 0 here to mean unset or error while setting */
    static int cached_result = 0;
 
    if (!cached_result)
    {
        UErrorCode err = U_ZERO_ERROR;
        auto cal = icu::Calendar::createInstance (err);
        if (!cal)
        {
            PERR("ICU error: %s\n", u_errorName (err));
            return 0;
        }
 
        /* 1 for sunday, 2 for monday, etc. */
        cached_result = cal->getFirstDayOfWeek (err);
        delete cal;
    }
 
    return cached_result;
}

gnc_time()

time64 gnc_time

(

time64 *

tbuf

)

get the current time

Parameters

A	time64* which, if not NULL, will be filled in with the same value as is returned.

Returns

Seconds since 00:00:00 UTC 01 January 1970 (negative values are seconds before that moment)

Definition at line 262 of file gnc-date.cpp.

{
    GncDateTime gncdt;
    auto time = static_cast<time64>(gncdt);
    if (tbuf != nullptr)
        *tbuf = time;
    return time;
}

gnc_time64_get_day_end()

time64 gnc_time64_get_day_end

(

time64

time_val

)

The gnc_time64_get_day_end() routine will take the given time in seconds and adjust it to the last second of that day.

Definition at line 1386 of file gnc-date.cpp.

{
    struct tm tm;
    time64 new_time;
 
    gnc_tm_get_day_end(&tm, time_val);
    new_time = gnc_mktime(&tm);
    return new_time;
}

gnc_time64_get_day_end_gdate()

time64 gnc_time64_get_day_end_gdate

(

const GDate *

date

)

The gnc_time64_get_day_end() routine will take the given time in GLib GDate format and adjust it to the last second of that day.

Definition at line 1502 of file gnc-date.cpp.

{
    struct tm stm;
    time64 secs;
 
    /* First convert to a 'struct tm' */
    g_date_to_struct_tm(date, &stm);
 
    /* Force to th last second of the day */
    stm.tm_hour = 23;
    stm.tm_min = 59;
    stm.tm_sec = 59;
    stm.tm_isdst = -1;
 
    /* Then convert to number of seconds */
    secs = gnc_mktime (&stm);
    return secs;
}

gnc_time64_get_day_neutral()

time64 gnc_time64_get_day_neutral

(

time64

time_val

)

The gnc_time64_get_day_neutral() routine will take the given time in seconds and adjust it to 10:59:00Z of that day.

Definition at line 1377 of file gnc-date.cpp.

{
    struct tm tm;
    gnc_localtime_r(&time_val, &tm);
    return gnc_dmy2time64_internal(tm.tm_mday, tm.tm_mon + 1, tm.tm_year + 1900,
                                   DayPart::neutral);
}

gnc_time64_get_day_start()

time64 gnc_time64_get_day_start

(

time64

time_val

)

The gnc_time64_get_day_start() routine will take the given time in seconds and adjust it to the first second of that day.

Definition at line 1366 of file gnc-date.cpp.

{
    struct tm tm;
    time64 new_time;
 
    gnc_tm_get_day_start(&tm, time_val);
    new_time = gnc_mktime(&tm);
    return new_time;
}

gnc_time64_get_day_start_gdate()

time64 gnc_time64_get_day_start_gdate

(

const GDate *

date

)

The gnc_time64_get_day_start() routine will take the given time in GLib GDate format and adjust it to the first second of that day.

Definition at line 1488 of file gnc-date.cpp.

{
    struct tm stm;
    time64 secs;
 
    /* First convert to a 'struct tm' */
    g_date_to_struct_tm (date, &stm);
 
    /* Then convert to number of seconds */
    secs = gnc_mktime (&stm);
    return secs;
}

gnc_time64_get_today_end()

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.

Definition at line 1426 of file gnc-date.cpp.

{
    struct tm tm;
 
    gnc_tm_get_day_end(&tm, gnc_time(nullptr));
    return gnc_mktime(&tm);
}

gnc_time64_get_today_start()

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.

Definition at line 1417 of file gnc-date.cpp.

{
    struct tm tm;
 
    gnc_tm_get_day_start(&tm, gnc_time(nullptr));
    return gnc_mktime(&tm);
}

gnc_time64_to_iso8601_buff()

gchar * gnc_time64_to_iso8601_buff	(	time64	time,
		char *	buff
	)

The gnc_time64_to_iso8601_buff() routine takes the input UTC time64 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 time zone 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 time zone on the machine on which it is executing to create the time string.

Definition at line 1213 of file gnc-date.cpp.

{
    if (!buff) return nullptr;
    try
    {
        GncDateTime gncdt(time);
        auto sstr = gncdt.format_iso8601();
 
        memset(buff, 0, sstr.length() + 1);
        strncpy(buff, sstr.c_str(), sstr.length());
        return buff + sstr.length();
    }
    catch(std::logic_error& err)
    {
        PWARN("Error processing time64 %" PRId64 ": %s", time, err.what());
        return buff;
    }
    catch(std::runtime_error& err)
    {
        PWARN("Error processing time64 %" PRId64 ": %s", time, err.what());
        return buff;
    }
}

gnc_timegm()

time64 gnc_timegm

(

struct tm *

time

)

calculate seconds from the epoch given a time struct

Parameters

time	A struct tm* containing the date-time information The time is understood to be utc.

Returns

Seconds since 00:00:00 UTC 01 January 1970 (negative values are seconds before that moment).

Definition at line 235 of file gnc-date.cpp.

{
    try
    {
        normalize_struct_tm(time);
        GncDateTime gncdt(*time);
        *time = static_cast<struct tm>(gncdt);
        time->tm_sec -= gncdt.offset();
        normalize_struct_tm(time);
#ifdef HAVE_STRUCT_TM_GMTOFF
        time->tm_gmtoff = 0;
#endif
        return static_cast<time64>(gncdt) - gncdt.offset();
    }
    catch(std::invalid_argument&)
    {
        return 0;
    }
}

gnc_tm_free()

void gnc_tm_free

(

struct tm *

time

)

free a struct tm* created with gnc_localtime() or gnc_gmtime()

Parameters

time	The struct tm* to be freed.

Definition at line 97 of file gnc-date.cpp.

{
    free(time);
}

gnc_tm_get_today_end()

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 1411 of file gnc-date.cpp.

{
    gnc_tm_get_day_end(tm, gnc_time(nullptr));
}

gnc_tm_get_today_neutral()

void gnc_tm_get_today_neutral

(

struct tm *

tm

)

The gnc_tm_get_today_start() routine takes a pointer to a struct tm and fills it in with the timezone neutral time (10:59:00Z).

Definition at line 1405 of file gnc-date.cpp.

{
    gnc_tm_get_day_neutral(tm, gnc_time(nullptr));
}

gnc_tm_get_today_start()

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 1399 of file gnc-date.cpp.

{
    gnc_tm_get_day_start(tm, gnc_time(nullptr));
}

gnc_tm_set_day_neutral()

void gnc_tm_set_day_neutral

(

struct tm *

tm

)

The gnc_tm_set_day_neutral() inline routine will set the appropriate fields in the struct tm to indicate 10:59am of that day.

Definition at line 1340 of file gnc-date.cpp.

{
    auto time_val{gnc_dmy2time64_internal(tm->tm_mday, tm->tm_mon + 1,
                                          tm->tm_year + 1900, DayPart::neutral)};
    gnc_localtime_r(&time_val, tm);
}

qof_date_completion_set()

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)

Definition at line 468 of file gnc-date.cpp.

{
    if (dc == QOF_DATE_COMPLETION_THISYEAR ||
            dc == QOF_DATE_COMPLETION_SLIDING)
    {
        dateCompletion = dc;
    }
    else
    {
        /* hack alert - Use a neutral default. */
        PERR("non-existent date completion set attempted. Setting current year completion as default");
        dateCompletion = QOF_DATE_COMPLETION_THISYEAR;
    }
 
    if (backmonths < 0)
    {
        backmonths = 0;
    }
    else if (backmonths > 11)
    {
        backmonths = 11;
    }
    dateCompletionBackMonths = backmonths;
 
    return;
}

qof_date_format_get()

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 scanning routines will assume when parsing a date.

Returns

: the one of the enumerated date formats.

Definition at line 428 of file gnc-date.cpp.

{
    return dateFormat;
}

qof_date_format_get_string()

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 502 of file gnc-date.cpp.

{
    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_UNSET: // use global
        return qof_date_format_get_string (dateFormat);
    case QOF_DATE_FORMAT_LOCALE:
    default:
        break;
    };
    return GNC_D_FMT;
}

qof_date_format_set()

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 433 of file gnc-date.cpp.

{
//avoid UB if df is out of range
    auto dfi{static_cast<uint8_t>(df)};
    if (dfi >= DATE_FORMAT_FIRST && dfi <= 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;
}

qof_date_text_format_get_string()

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 525 of file gnc-date.cpp.

{
    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_UNSET: // use global
        return qof_date_text_format_get_string (dateFormat);
    case QOF_DATE_FORMAT_LOCALE:
    default:
        break;
    };
    return GNC_D_FMT;
}

qof_print_date()

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.

Definition at line 610 of file gnc-date.cpp.

{
    char buff[MAX_DATE_LENGTH + 1];
    memset (buff, 0, sizeof (buff));
    qof_print_date_buff (buff, MAX_DATE_LENGTH, t);
    return g_strdup (buff);
}

qof_print_date_buff()

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

Convenience: calls through to qof_print_date_dmy_buff().

Definition at line 574 of file gnc-date.cpp.

{
    if (!buff) return 0;
 
    try
    {
        GncDateTime gncdt(t);
        std::string str = gncdt.format(qof_date_format_get_string(dateFormat));
        strncpy(buff, str.c_str(), len);
        if (str.length() >= len)
            buff[len - 1] = '\0';
    }
    catch(std::logic_error& err)
    {
        PWARN("Error processing time64 %" PRId64 ": %s", t, err.what());
    }
    catch(std::runtime_error& err)
    {
        PWARN("Error processing time64 %" PRId64 ": %s", t, err.what());
    }
    return strlen(buff);
}

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

qof_print_gdate()

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 598 of file gnc-date.cpp.

{
    GDate date;
    g_date_clear (&date, 1);
    date = *gd;
    return qof_print_date_dmy_buff( buf, len,
                                    g_date_get_day(&date),
                                    g_date_get_month(&date),
                                    g_date_get_year(&date) );
}

qof_scan_date()

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 991 of file gnc-date.cpp.

{
    return qof_scan_date_internal(buff, day, month, year, dateFormat);
}

qof_strftime()

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.

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.

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 1129 of file gnc-date.cpp.

{
    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 != nullptr);
        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;
}

time64_to_gdate()

GDate time64_to_gdate

(

time64

t

)

Returns the GDate in which the time64 occurs.

Parameters

t	The time64

Returns

A GDate for the day in which the time64 occurs.

Definition at line 1284 of file gnc-date.cpp.

{
    GDate result;
 
    g_date_clear (&result, 1);
    GncDateTime time(t);
    auto date = time.date().year_month_day();
    g_date_set_dmy (&result, date.day, static_cast<GDateMonth>(date.month),
                    date.year);
    g_assert(g_date_valid (&result));
 
    return result;
}

time64CanonicalDayTime()

time64 time64CanonicalDayTime

(

time64

t

)

convert a time64 on a certain day (localtime) to the time64 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 time64.

Definition at line 404 of file gnc-date.cpp.

{
    struct tm tm;
    gnc_localtime_r(&t, &tm);
    gnc_tm_set_day_middle(&tm);
    return gnc_mktime (&tm);
}

Variable Documentation

gnc_default_strftime_date_format

const char* gnc_default_strftime_date_format

extern

The default date format for use with strftime.

Definition at line 74 of file gnc-date.cpp.

t

time64 Time64::t

Definition at line 93 of file gnc-date.h.