GnuCash  4.8a-176-g88ecf8dd1
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 
73 #ifdef __cplusplus
74 extern "C"
75 {
76 #endif
77 
78 #ifdef __cplusplus
79 extern "C++" {
80 #endif
81 #include <glib-object.h>
82 #ifdef __cplusplus
83 }
84 #endif
85 
86 #include <time.h>
87 
93 typedef gint64 time64;
94 /* A bit of a hack to create a type separate from the alias of int64_t so that
95  * compile-time dispatch can use the right KVP visitor.
96  */
97 typedef struct
98 {
99  time64 t;
100 } Time64;
101 
102 
106 GType time64_get_type( void );
107 #define GNC_TYPE_TIME64 (time64_get_type ())
108 
111 extern const char *gnc_default_strftime_date_format;
112 
114 #define MAX_DATE_LENGTH 34
115 
125 #define QOF_UTC_DATE_FORMAT "%Y-%m-%dT%H:%M:%SZ"
126 
128 typedef enum
129 {
138 } QofDateFormat;
139 
140 #define DATE_FORMAT_FIRST QOF_DATE_FORMAT_US
141 #define DATE_FORMAT_LAST QOF_DATE_FORMAT_UTC
142 
144 typedef enum
145 {
149 
152 #define qof_date_format_get_format qof_date_text_format_get_string
153 
158 typedef enum
159 {
160  GNCDATE_MONTH_NUMBER,
161  GNCDATE_MONTH_ABBREV,
162  GNCDATE_MONTH_NAME
164 
165 /* Replacements for POSIX functions which use time_t. Time_t is still
166  * 32 bits in Microsoft Windows, Apple OSX, and some BSD versions even
167  * when the rest of the system is 64-bits, as well as all 32-bit
168  * versions of Unix. 32-bit time_t overflows at 03:14:07 UTC on
169  * Tuesday, 19 January 2038 and so cannot represent dates after that.
170  *
171  * These functions use boost::date_time internally.
172  */
179 struct tm* gnc_localtime (const time64 *secs);
180 
187 struct tm* gnc_localtime_r (const time64 *secs, struct tm* time);
188 
195 struct tm* gnc_gmtime (const time64 *secs);
196 
200 gint gnc_start_of_week (void);
201 
208 time64 gnc_mktime (struct tm* time);
209 
216 time64 gnc_timegm (struct tm* time);
217 
226 gchar* gnc_ctime (const time64 *secs);
227 
234 time64 gnc_time (time64 *tbuf);
235 
244 gdouble gnc_difftime (const time64 secs1, const time64 secs2);
245 
249 void gnc_tm_free (struct tm* time);
250 
253 
255 const gchar* gnc_date_dateformat_to_string(QofDateFormat format);
256 
262 gboolean gnc_date_string_to_dateformat(const gchar* format_string,
263  QofDateFormat *format);
264 
265 const gchar* gnc_date_monthformat_to_string(GNCDateMonthFormat format);
266 
272 gboolean gnc_date_string_to_monthformat(const gchar *format_string,
273  GNCDateMonthFormat *format);
274 
280 char* gnc_print_time64(time64 time, const char* format);
281 
282 // @}
283 
288 GDate* gnc_g_date_new_today (void);
289 
293 void gnc_gdate_set_today (GDate* gd);
294 
299 void gnc_gdate_set_time64 (GDate* gd, time64 time);
300 
307 
309 time64 gdate_to_time64 (GDate d);
310 
312 time64 gnc_dmy2time64 (gint day, gint month, gint year);
313 
321 time64 gnc_dmy2time64_neutral (gint day, gint month, gint year);
322 
324 time64 gnc_dmy2time64_end (gint day, gint month, gint year);
325 
342 time64 gnc_iso8601_to_time64_gmt(const gchar *);
343 
360 gchar * gnc_time64_to_iso8601_buff (time64, char * buff);
361 // @}
362 
363 /* ======================================================== */
364 
366 // @{
373 
380 
390 
400 // @}
401 
402 /* ======================================================== */
403 
410 void qof_date_completion_set(QofDateCompletion dc, int backmonths);
411 
421 gchar dateSeparator(void);
422 
423 /* ======================================================== */
424 
427 // @{
436 /* qof_format_time takes a format specification in UTF-8 and a broken-down time,
437  * tries to call strftime with a sufficiently large buffer and, if successful,
438  * return a newly allocated string in UTF-8 for the printing result.
439  *
440  * @param format A format specification in UTF-8.
441  *
442  * @param tm A broken-down time.
443  *
444  * @return A newly allocated string on success, or NULL otherwise.
445  */
446 /* gchar *qof_format_time(const gchar *format, const struct tm *tm); */
447 
462 gsize qof_strftime(gchar *buf, gsize max, const gchar *format,
463  const struct tm *tm);
464 
480 size_t qof_print_date_dmy_buff (gchar * buff, size_t buflen, int day, int month, int year);
481 
483 size_t qof_print_date_buff (char * buff, size_t buflen, time64 secs);
484 
486 size_t qof_print_gdate(char *buf, size_t bufflen, const GDate *gd);
487 
491 char * qof_print_date (time64 secs);
492 
493 
494 /* ------------------------------------------------------------------ */
495 /* time printing utilities */
496 
501 size_t qof_print_date_time_buff (char * buff, size_t len, time64 secs);
502 
516 gboolean qof_scan_date (const char *buff, int *day, int *month, int *year);
517 
518 // @}
519 
520 /* ======================================================== */
521 
525 // @{
526 
531 static inline
532 void gnc_tm_set_day_start (struct tm *tm)
533 {
534  /* First second of the day */
535  g_return_if_fail (tm != NULL);
536  tm->tm_hour = 0;
537  tm->tm_min = 0;
538  tm->tm_sec = 0;
539 }
540 
544 void gnc_tm_set_day_neutral (struct tm *tm);
545 
550 static inline
551 void gnc_tm_set_day_middle (struct tm *tm)
552 {
553  /* First second of the day */
554  g_return_if_fail (tm != NULL);
555  tm->tm_hour = 12;
556  tm->tm_min = 0;
557  tm->tm_sec = 0;
558 }
559 
564 static inline
565 void gnc_tm_set_day_end (struct tm *tm)
566 {
567  /* Last second of the day */
568  g_return_if_fail (tm != NULL);
569  tm->tm_hour = 23;
570  tm->tm_min = 59;
571  tm->tm_sec = 59;
572 }
573 
577 
581 
585 
587 int gnc_date_get_last_mday (int month, int year);
588 
589 // @}
590 
591 /* ======================================================== */
592 
594 // @{
597 void gnc_tm_get_today_start(struct tm *tm);
598 
601 void gnc_tm_get_today_end(struct tm *tm);
602 
606 
610 
614 char * gnc_date_timestamp (void);
615 
616 #define MIN_BUF_LEN 10
617 
622 void gnc_dow_abbrev(gchar *buf, int buf_len, int dow);
623 
625 
626 /* ======================================================== */
627 
629 // @{
630 
633 gint gnc_gdate_equal(gconstpointer gda, gconstpointer gdb);
634 
635 
638 guint gnc_gdate_hash( gconstpointer gd );
639 
641 
642 /* ======================================================== */
643 
645 // @{
650 GDate time64_to_gdate (time64 t);
651 
655 time64 gnc_time64_get_day_start_gdate (const GDate *date);
656 
660 time64 gnc_time64_get_day_end_gdate (const GDate *date);
661 
663 
664 /* ======================================================== */
665 
667 // @{
668 
674 void gnc_gdate_set_month_start (GDate *date);
675 
676 
682 void gnc_gdate_set_month_end (GDate *date);
683 
684 
691 void gnc_gdate_set_prev_month_start (GDate *date);
692 
693 
700 void gnc_gdate_set_prev_month_end (GDate *date);
701 
702 
708 void gnc_gdate_set_quarter_start (GDate *date);
709 
710 
716 void gnc_gdate_set_quarter_end (GDate *date);
717 
718 
725 void gnc_gdate_set_prev_quarter_start (GDate *date);
726 
727 
734 void gnc_gdate_set_prev_quarter_end (GDate *date);
735 
736 
742 void gnc_gdate_set_year_start (GDate *date);
743 
744 
750 void gnc_gdate_set_year_end (GDate *date);
751 
752 
759 void gnc_gdate_set_prev_year_start (GDate *date);
760 
761 
768 void gnc_gdate_set_prev_year_end (GDate *date);
769 
770 
780 void gnc_gdate_set_fiscal_year_start (GDate *date, const GDate *year_end);
781 
782 
792 void gnc_gdate_set_fiscal_year_end (GDate *date, const GDate *year_end);
793 
794 
804 void gnc_gdate_set_prev_fiscal_year_start (GDate *date, const GDate *year_end);
805 
806 
816 void gnc_gdate_set_prev_fiscal_year_end (GDate *date, const GDate *year_end);
817 
819 
821 #ifdef __cplusplus
822 }
823 #endif
824 
825 #endif /* GNC_DATE_H */
ISO: yyyy-mm-dd.
Definition: gnc-date.h:133
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:1058
Used by the check printing code.
Definition: gnc-date.h:136
gchar dateSeparator(void)
dateSeparator Return the field separator for the current date format
Definition: gnc-date.cpp:928
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:291
char * gnc_date_timestamp(void)
Make a timestamp in YYYYMMDDHHMMSS format.
Definition: gnc-date.cpp:1103
QofDateCompletion
Enum for date completion modes (for dates entered without year)
Definition: gnc-date.h:144
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:1412
Continental Europe: dd.mm.yyyy.
Definition: gnc-date.h:132
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:1418
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:1520
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:605
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:137
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:1239
GDate time64_to_gdate(time64 t)
Returns the GDate in which the time64 occurs.
Definition: gnc-date.cpp:1215
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:1510
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:1332
int gnc_date_get_last_mday(int month, int year)
Get the numerical last date of the month.
Definition: gnc-date.cpp:422
const char * gnc_default_strftime_date_format
The default date format for use with strftime.
Definition: gnc-date.cpp:76
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:475
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:117
void gnc_tm_free(struct tm *time)
free a struct tm* created with gnc_localtime() or gnc_gmtime()
Definition: gnc-date.cpp:99
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:437
use sliding 12-month window
Definition: gnc-date.h:147
char * qof_print_date(time64 secs)
Convenience; calls through to qof_print_date_dmy_buff().
Definition: gnc-date.cpp:617
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:379
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:1299
void gnc_dow_abbrev(gchar *buf, int buf_len, int dow)
Localized DOW abbreviation.
Definition: gnc-date.cpp:1362
UTC: 2004-12-12T23:39:11Z.
Definition: gnc-date.h:135
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:1344
time64 gnc_mktime(struct tm *time)
calculate seconds from the epoch given a time struct
Definition: gnc-date.cpp:230
time64 gdate_to_time64(GDate d)
Turns a GDate into a time64, returning the first second of the day.
Definition: gnc-date.cpp:1256
GNCDateMonthFormat
This is how to format the month, as a number, an abbreviated string, or the full name.
Definition: gnc-date.h:158
time64 gnc_timegm(struct tm *time)
calculate seconds from the epoch given a time struct
Definition: gnc-date.cpp:246
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:1465
struct tm * gnc_localtime(const time64 *secs)
fill out a time struct from a 64-bit time value.
Definition: gnc-date.cpp:105
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:283
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:532
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:920
void gnc_gdate_set_time64(GDate *gd, time64 time)
Set a GDate to a time64.
Definition: gnc-date.cpp:1247
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:1478
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:1443
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:1533
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:1353
struct tm * gnc_gmtime(const time64 *secs)
fill out a time struct from a 64-bit time value
Definition: gnc-date.cpp:189
time64 gnc_time(time64 *tbuf)
get the current local time
Definition: gnc-date.cpp:273
gint64 time64
Many systems, including Microsoft Windows and BSD-derived Unixes like Darwin, are retaining the int-3...
Definition: gnc-date.h:93
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:146
gchar * gnc_ctime(const time64 *secs)
Return a string representation of a date from a 64-bit time value.
Definition: gnc-date.cpp:267
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:1319
Take from locale information.
Definition: gnc-date.h:134
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:442
time64 time64CanonicalDayTime(time64 t)
convert a time64 on a certain day (localtime) to the time64 representing midday on that day...
Definition: gnc-date.cpp:413
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:1338
Britain: dd/mm/yyyy.
Definition: gnc-date.h:131
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:1273
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:509
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:1429
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:1142
QofDateFormat
Enum for determining a date format.
Definition: gnc-date.h:128
United states: mm/dd/yyyy.
Definition: gnc-date.h:130
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:206
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:581
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:59am...
Definition: gnc-date.cpp:1310
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:1229
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:1496