GnuCash  4.901
gnc-date.h
Go to the documentation of this file.
1 /********************************************************************
2  * gnc-date.h (to be renamed qofdate.h)
3  *
4  * Copyright (C) 1997 Robin D. Clark <rclark@cs.hmc.edu>
5  * Copyright (C) 1998-2000, 2003 Linas Vepstas <linas@linas.org>
6  * Copyright 2005 Neil Williams <linux@codehelp.co.uk>
7  * Copyright (C) 2005 David Hampton <hampton@employees.org>
8  * Copyright 2012 John Ralls <jralls@ceridwen.us>
9  ********************************************************************/
10 /********************************************************************\
11  * This program is free software; you can redistribute it and/or *
12  * modify it under the terms of the GNU General Public License as *
13  * published by the Free Software Foundation; either version 2 of *
14  * the License, or (at your option) any later version. *
15  * *
16  * This program is distributed in the hope that it will be useful, *
17  * but WITHOUT ANY WARRANTY; without even the implied warranty of *
18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the *
19  * GNU General Public License for more details. *
20  * *
21  * You should have received a copy of the GNU General Public License*
22  * along with this program; if not, contact: *
23  * *
24  * Free Software Foundation Voice: +1-617-542-5942 *
25  * 51 Franklin Street, Fifth Floor Fax: +1-617-542-2652 *
26  * Boston, MA 02110-1301, USA gnu@gnu.org *
27 \********************************************************************/
69 #ifndef GNC_DATE_H
70 #define GNC_DATE_H
71 
72 #include <glib-object.h>
73 
74 #include <time.h>
75 
76 #ifdef __cplusplus
77 extern "C"
78 {
79 #endif
80 
81 
87 typedef gint64 time64;
88 /* A bit of a hack to create a type separate from the alias of int64_t so that
89  * compile-time dispatch can use the right KVP visitor.
90  */
91 typedef struct
92 {
93  time64 t;
94 } Time64;
95 
96 
100 GType time64_get_type( void );
101 #define GNC_TYPE_TIME64 (time64_get_type ())
102 
105 extern const char *gnc_default_strftime_date_format;
106 
108 #define MAX_DATE_LENGTH 34
109 
119 #define QOF_UTC_DATE_FORMAT "%Y-%m-%dT%H:%M:%SZ"
120 
122 typedef enum
123 {
132 } QofDateFormat;
133 
134 #define DATE_FORMAT_FIRST QOF_DATE_FORMAT_US
135 #define DATE_FORMAT_LAST QOF_DATE_FORMAT_UTC
136 
138 typedef enum
139 {
143 
146 #define qof_date_format_get_format qof_date_text_format_get_string
147 
152 typedef enum
153 {
154  GNCDATE_MONTH_NUMBER,
155  GNCDATE_MONTH_ABBREV,
156  GNCDATE_MONTH_NAME
158 
159 /* Replacements for POSIX functions which use time_t. Time_t is still
160  * 32 bits in Microsoft Windows, Apple OSX, and some BSD versions even
161  * when the rest of the system is 64-bits, as well as all 32-bit
162  * versions of Unix. 32-bit time_t overflows at 03:14:07 UTC on
163  * Tuesday, 19 January 2038 and so cannot represent dates after that.
164  *
165  * These functions use boost::date_time internally.
166  */
173 struct tm* gnc_localtime (const time64 *secs);
174 
181 struct tm* gnc_localtime_r (const time64 *secs, struct tm* time);
182 
189 struct tm* gnc_gmtime (const time64 *secs);
190 
194 gint gnc_start_of_week (void);
195 
202 time64 gnc_mktime (struct tm* time);
203 
210 time64 gnc_timegm (struct tm* time);
211 
220 gchar* gnc_ctime (const time64 *secs);
221 
228 time64 gnc_time (time64 *tbuf);
229 
238 gdouble gnc_difftime (const time64 secs1, const time64 secs2);
239 
243 void gnc_tm_free (struct tm* time);
244 
247 
249 const gchar* gnc_date_dateformat_to_string(QofDateFormat format);
250 
256 gboolean gnc_date_string_to_dateformat(const gchar* format_string,
257  QofDateFormat *format);
258 
259 const gchar* gnc_date_monthformat_to_string(GNCDateMonthFormat format);
260 
266 gboolean gnc_date_string_to_monthformat(const gchar *format_string,
267  GNCDateMonthFormat *format);
268 
274 char* gnc_print_time64(time64 time, const char* format);
275 
276 // @}
277 
282 GDate* gnc_g_date_new_today (void);
283 
287 void gnc_gdate_set_today (GDate* gd);
288 
293 void gnc_gdate_set_time64 (GDate* gd, time64 time);
294 
301 
303 time64 gdate_to_time64 (GDate d);
304 
306 time64 gnc_dmy2time64 (gint day, gint month, gint year);
307 
315 time64 gnc_dmy2time64_neutral (gint day, gint month, gint year);
316 
318 time64 gnc_dmy2time64_end (gint day, gint month, gint year);
319 
336 time64 gnc_iso8601_to_time64_gmt(const gchar *);
337 
354 gchar * gnc_time64_to_iso8601_buff (time64, char * buff);
355 // @}
356 
357 /* ======================================================== */
358 
360 // @{
367 
374 
384 
394 // @}
395 
396 /* ======================================================== */
397 
404 void qof_date_completion_set(QofDateCompletion dc, int backmonths);
405 
415 gchar dateSeparator(void);
416 
417 /* ======================================================== */
418 
421 // @{
430 /* qof_format_time takes a format specification in UTF-8 and a broken-down time,
431  * tries to call strftime with a sufficiently large buffer and, if successful,
432  * return a newly allocated string in UTF-8 for the printing result.
433  *
434  * @param format A format specification in UTF-8.
435  *
436  * @param tm A broken-down time.
437  *
438  * @return A newly allocated string on success, or NULL otherwise.
439  */
440 /* gchar *qof_format_time(const gchar *format, const struct tm *tm); */
441 
456 gsize qof_strftime(gchar *buf, gsize max, const gchar *format,
457  const struct tm *tm);
458 
474 size_t qof_print_date_dmy_buff (gchar * buff, size_t buflen, int day, int month, int year);
475 
477 size_t qof_print_date_buff (char * buff, size_t buflen, time64 secs);
478 
480 size_t qof_print_gdate(char *buf, size_t bufflen, const GDate *gd);
481 
485 char * qof_print_date (time64 secs);
486 
487 
488 /* ------------------------------------------------------------------ */
489 /* time printing utilities */
490 
495 size_t qof_print_date_time_buff (char * buff, size_t len, time64 secs);
496 
510 gboolean qof_scan_date (const char *buff, int *day, int *month, int *year);
511 
512 // @}
513 
514 /* ======================================================== */
515 
519 // @{
520 
525 static inline
526 void gnc_tm_set_day_start (struct tm *tm)
527 {
528  /* First second of the day */
529  g_return_if_fail (tm != NULL);
530  tm->tm_hour = 0;
531  tm->tm_min = 0;
532  tm->tm_sec = 0;
533 }
534 
538 void gnc_tm_set_day_neutral (struct tm *tm);
539 
544 static inline
545 void gnc_tm_set_day_middle (struct tm *tm)
546 {
547  /* First second of the day */
548  g_return_if_fail (tm != NULL);
549  tm->tm_hour = 12;
550  tm->tm_min = 0;
551  tm->tm_sec = 0;
552 }
553 
558 static inline
559 void gnc_tm_set_day_end (struct tm *tm)
560 {
561  /* Last second of the day */
562  g_return_if_fail (tm != NULL);
563  tm->tm_hour = 23;
564  tm->tm_min = 59;
565  tm->tm_sec = 59;
566 }
567 
571 
575 
579 
581 int gnc_date_get_last_mday (int month, int year);
582 
583 // @}
584 
585 /* ======================================================== */
586 
588 // @{
591 void gnc_tm_get_today_start(struct tm *tm);
592 
595 void gnc_tm_get_today_neutral(struct tm *tm);
596 
599 void gnc_tm_get_today_end(struct tm *tm);
600 
604 
608 
612 char * gnc_date_timestamp (void);
613 
614 #define MIN_BUF_LEN 10
615 
620 void gnc_dow_abbrev(gchar *buf, int buf_len, int dow);
621 
623 
624 /* ======================================================== */
625 
627 // @{
628 
631 gint gnc_gdate_equal(gconstpointer gda, gconstpointer gdb);
632 
633 
636 guint gnc_gdate_hash( gconstpointer gd );
637 
639 
640 /* ======================================================== */
641 
643 // @{
648 GDate time64_to_gdate (time64 t);
649 
653 time64 gnc_time64_get_day_start_gdate (const GDate *date);
654 
658 time64 gnc_time64_get_day_end_gdate (const GDate *date);
659 
661 
662 /* ======================================================== */
663 
665 // @{
666 
672 void gnc_gdate_set_month_start (GDate *date);
673 
674 
680 void gnc_gdate_set_month_end (GDate *date);
681 
682 
689 void gnc_gdate_set_prev_month_start (GDate *date);
690 
691 
698 void gnc_gdate_set_prev_month_end (GDate *date);
699 
700 
706 void gnc_gdate_set_quarter_start (GDate *date);
707 
708 
714 void gnc_gdate_set_quarter_end (GDate *date);
715 
716 
723 void gnc_gdate_set_prev_quarter_start (GDate *date);
724 
725 
732 void gnc_gdate_set_prev_quarter_end (GDate *date);
733 
734 
740 void gnc_gdate_set_year_start (GDate *date);
741 
742 
748 void gnc_gdate_set_year_end (GDate *date);
749 
750 
757 void gnc_gdate_set_prev_year_start (GDate *date);
758 
759 
766 void gnc_gdate_set_prev_year_end (GDate *date);
767 
768 
778 void gnc_gdate_set_fiscal_year_start (GDate *date, const GDate *year_end);
779 
780 
790 void gnc_gdate_set_fiscal_year_end (GDate *date, const GDate *year_end);
791 
792 
802 void gnc_gdate_set_prev_fiscal_year_start (GDate *date, const GDate *year_end);
803 
804 
814 void gnc_gdate_set_prev_fiscal_year_end (GDate *date, const GDate *year_end);
815 
817 
819 #ifdef __cplusplus
820 }
821 #endif
822 
823 #endif /* GNC_DATE_H */
ISO: yyyy-mm-dd.
Definition: gnc-date.h:127
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...
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 represe...
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 ...
Definition: gnc-date.cpp:1055
Used by the check printing code.
Definition: gnc-date.h:130
gchar dateSeparator(void)
dateSeparator Return the field separator for the current date format
Definition: gnc-date.cpp:925
gboolean gnc_date_string_to_monthformat(const gchar *format_string, GNCDateMonthFormat *format)
Converts the month format to a printable string.
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 ...
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...
Definition: gnc-date.cpp:1619
const gchar * gnc_date_dateformat_to_string(QofDateFormat format)
The string->value versions return FALSE on success and TRUE on failure.
Definition: gnc-date.cpp:288
char * gnc_date_timestamp(void)
Make a timestamp in YYYYMMDDHHMMSS format.
Definition: gnc-date.cpp:1100
QofDateCompletion
Enum for date completion modes (for dates entered without year)
Definition: gnc-date.h:138
gint gnc_gdate_equal(gconstpointer gda, gconstpointer gdb)
Compares two GDate*&#39;s for equality; useful for using GDate*&#39;s as GHashTable keys. ...
Definition: gnc-date.cpp:1416
Continental Europe: dd.mm.yyyy.
Definition: gnc-date.h:126
guint gnc_gdate_hash(gconstpointer gd)
Provides a "hash" of a GDate* value; useful for using GDate*&#39;s as GHashTable keys.
Definition: gnc-date.cpp:1422
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...
Definition: gnc-date.cpp:1524
size_t qof_print_gdate(char *buf, size_t bufflen, const GDate *gd)
Convenience; calls through to qof_print_date_dmy_buff().
Definition: gnc-date.cpp:602
size_t qof_print_date_time_buff(char *buff, size_t len, time64 secs)
Returns the number of bytes printed.
No Fancy Date Format, use Global.
Definition: gnc-date.h:131
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.
void gnc_gdate_set_today(GDate *gd)
Set a GDate to the current day.
Definition: gnc-date.cpp:1237
GDate time64_to_gdate(time64 t)
Returns the GDate in which the time64 occurs.
Definition: gnc-date.cpp:1212
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 fa...
Definition: gnc-date.cpp:1514
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 se...
Definition: gnc-date.cpp:1330
int gnc_date_get_last_mday(int month, int year)
Get the numerical last date of the month.
Definition: gnc-date.cpp:419
const char * gnc_default_strftime_date_format
The default date format for use with strftime.
Definition: gnc-date.cpp:73
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_T...
Definition: gnc-date.cpp:472
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.
Definition: gnc-date.cpp:114
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...
Definition: gnc-date.cpp:1336
void gnc_tm_free(struct tm *time)
free a struct tm* created with gnc_localtime() or gnc_gmtime()
Definition: gnc-date.cpp:96
QofDateFormat qof_date_format_get(void)
The qof_date_format_get routine returns the date format that the date printing will use when printing...
Definition: gnc-date.cpp:434
use sliding 12-month window
Definition: gnc-date.h:141
char * qof_print_date(time64 secs)
Convenience; calls through to qof_print_date_dmy_buff().
Definition: gnc-date.cpp:614
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 fal...
Definition: gnc-date.cpp:1586
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 fa...
Definition: gnc-date.cpp:1579
char * gnc_print_time64(time64 time, const char *format)
print a time64 as a date string per format
Definition: gnc-date.cpp:376
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...
Definition: gnc-date.cpp:1297
void gnc_dow_abbrev(gchar *buf, int buf_len, int dow)
Localized DOW abbreviation.
Definition: gnc-date.cpp:1366
UTC: 2004-12-12T23:39:11Z.
Definition: gnc-date.h:129
time64 gnc_time64_get_today_start(void)
The gnc_time64_get_today_start() routine returns a time64 value corresponding to the first second of ...
Definition: gnc-date.cpp:1348
time64 gnc_mktime(struct tm *time)
calculate seconds from the epoch given a time struct
Definition: gnc-date.cpp:227
time64 gdate_to_time64(GDate d)
Turns a GDate into a time64, returning the first second of the day.
Definition: gnc-date.cpp:1254
GNCDateMonthFormat
This is how to format the month, as a number, an abbreviated string, or the full name.
Definition: gnc-date.h:152
time64 gnc_timegm(struct tm *time)
calculate seconds from the epoch given a time struct
Definition: gnc-date.cpp:243
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...
Definition: gnc-date.cpp:1469
struct tm * gnc_localtime(const time64 *secs)
fill out a time struct from a 64-bit time value.
Definition: gnc-date.cpp:102
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...
Definition: gnc-date.cpp:1653
gdouble gnc_difftime(const time64 secs1, const time64 secs2)
Find the difference in seconds between two time values.
Definition: gnc-date.cpp:280
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...
Definition: gnc-date.cpp:1595
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.
Definition: gnc-date.cpp:1572
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...
Definition: gnc-date.cpp:529
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 v...
Definition: gnc-date.cpp:917
void gnc_gdate_set_time64(GDate *gd, time64 time)
Set a GDate to a time64.
Definition: gnc-date.cpp:1245
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...
Definition: gnc-date.cpp:1482
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 t...
Definition: gnc-date.cpp:1447
time64 gnc_dmy2time64_end(gint day, gint month, gint year)
Same as gnc_dmy2time64, but last second of the day.
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 whic...
Definition: gnc-date.cpp:1642
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...
Definition: gnc-date.cpp:1537
time64 gnc_time64_get_today_end(void)
The gnc_time64_get_today_end() routine returns a time64 value corresponding to the last second of tod...
Definition: gnc-date.cpp:1357
struct tm * gnc_gmtime(const time64 *secs)
fill out a time struct from a 64-bit time value
Definition: gnc-date.cpp:186
time64 gnc_time(time64 *tbuf)
get the current local time
Definition: gnc-date.cpp:270
gint64 time64
Many systems, including Microsoft Windows and BSD-derived Unixes like Darwin, are retaining the int-3...
Definition: gnc-date.h:87
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 ...
Definition: gnc-date.cpp:1556
use current year
Definition: gnc-date.h:140
gchar * gnc_ctime(const time64 *secs)
Return a string representation of a date from a 64-bit time value.
Definition: gnc-date.cpp:264
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 se...
Definition: gnc-date.cpp:1317
Take from locale information.
Definition: gnc-date.h:128
void qof_date_format_set(QofDateFormat df)
The qof_date_format_set() routine sets date format to one of US, UK, CE, OR ISO.
Definition: gnc-date.cpp:439
time64 time64CanonicalDayTime(time64 t)
convert a time64 on a certain day (localtime) to the time64 representing midday on that day...
Definition: gnc-date.cpp:410
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 secon...
Definition: gnc-date.cpp:1342
Britain: dd/mm/yyyy.
Definition: gnc-date.h:125
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 indic...
Definition: gnc-date.cpp:1271
gboolean gnc_date_string_to_dateformat(const gchar *format_string, QofDateFormat *format)
Converts the date format to a printable string.
const gchar * qof_date_format_get_string(QofDateFormat df)
This function returns a strftime formatting string for printing an all numeric date (e...
Definition: gnc-date.cpp:506
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...
Definition: gnc-date.cpp:1433
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-860...
Definition: gnc-date.cpp:1139
QofDateFormat
Enum for determining a date format.
Definition: gnc-date.h:122
United states: mm/dd/yyyy.
Definition: gnc-date.h:124
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...
Definition: gnc-date.cpp:1549
gint gnc_start_of_week(void)
returns an integer corresponding to locale start of week
Definition: gnc-date.cpp:203
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...
Definition: gnc-date.cpp:1565
size_t qof_print_date_buff(char *buff, size_t buflen, time64 secs)
Convenience: calls through to qof_print_date_dmy_buff().
Definition: gnc-date.cpp:578
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:0...
Definition: gnc-date.cpp:1308
GDate * gnc_g_date_new_today(void)
Returns a newly allocated date of the current clock time, taken from time(2).
Definition: gnc-date.cpp:1226
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 f...
Definition: gnc-date.cpp:1500