Line data Source code
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 : \********************************************************************/
28 : /** @addtogroup Date
29 : Utility functions to handle date and time (adjusting, getting
30 : the current date, printing the date and time, etc.)
31 :
32 : Overall, this file is quite a mess.
33 :
34 : An important note about time-keeping: The general goal of any
35 : program that works with numeric time values SHOULD BE to always
36 : stores and use UNIVERSAL TIME internally. Universal time is the
37 : 'one true time' that is independent of one's location on planet
38 : Earth. It is measured in seconds from midnight January 1, 1970
39 : in localtime-Greenwich (GMT). If one wants to display the local
40 : time, then the display-print routine should make all final
41 : tweaks to print the local time. The local time *must not* be
42 : kept as a numeric value anywhere in the program. If one wants
43 : to parse a user's input string as if it were local time, then
44 : the output of the parse routine MUST BE universal time.
45 : A sane program must never ever store (to file or db) a time
46 : that is not Universal Time. Break these rules, and you will
47 : rue the day...
48 :
49 : \warning HACK ALERT -- the scan and print routines should probably be moved
50 : to somewhere else. The engine really isn't involved with things
51 : like printing formats. This is needed mostly by the GUI and so on.
52 : If a file-io backend needs date handling, it should do it itself,
53 : instead of depending on the routines here.
54 :
55 : (to be renamed qofdate.h in libqof2.)
56 :
57 : @author Copyright (C) 1997 Robin D. Clark <rclark@cs.hmc.edu>
58 : @author Copyright (C) 1998-2001,2003 Linas Vepstas <linas@linas.org>
59 : */
60 :
61 : /** @{
62 : @file gnc-date.h
63 : @brief Date and Time handling routines
64 : */
65 :
66 : #ifndef GNC_DATE_H
67 : #define GNC_DATE_H
68 :
69 : #include <glib-object.h>
70 :
71 : #include <time.h>
72 :
73 : #ifdef __cplusplus
74 : extern "C"
75 : {
76 : #endif
77 :
78 :
79 : /**
80 : * Most systems that are currently maintained, including Microsoft Windows,
81 : * BSD-derived Unixes and Linux, support 64-bit time_t even on 32-bit
82 : * architectures. See https://en.wikipedia.org/wiki/Year_2038_problem
83 : *
84 : * For practical reasons -- as not all have made the transition to 64-bit --
85 : * we define our own 64-bit time type.
86 : */
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 :
97 : /** @name GValue
98 : @{
99 : */
100 : GType time64_get_type( void );
101 : #define GNC_TYPE_TIME64 (time64_get_type ())
102 :
103 : /** @} */
104 : /** The default date format for use with strftime. */
105 : extern const char *gnc_default_strftime_date_format;
106 :
107 : /** The maximum length of a string created by the date printers */
108 : #define MAX_DATE_LENGTH 34
109 : /** Constants *******************************************************/
110 : /** \brief UTC date format string.
111 :
112 : Time zone independent, date and time inclusive, as used in the QSF backend.
113 : The T and Z characters are from xsd:dateTime format in coordinated universal time, UTC.
114 : You can reproduce the string from the GNU/Linux command line using the date utility:
115 : date -u +%Y-%m-%dT%H:M:SZ = 2004-12-12T23:39:11Z The datestring must be time zone independent
116 : and include all specified fields. Remember to use gmtime() NOT localtime()!
117 : */
118 :
119 : #define QOF_UTC_DATE_FORMAT "%Y-%m-%dT%H:%M:%SZ"
120 :
121 : /** Enum for determining a date format */
122 : typedef enum
123 : {
124 : QOF_DATE_FORMAT_US, /**< United states: mm/dd/yyyy */
125 : QOF_DATE_FORMAT_UK, /**< Britain: dd/mm/yyyy */
126 : QOF_DATE_FORMAT_CE, /**< Continental Europe: dd.mm.yyyy */
127 : QOF_DATE_FORMAT_ISO, /**< ISO: yyyy-mm-dd */
128 : QOF_DATE_FORMAT_LOCALE, /**< Take from locale information */
129 : QOF_DATE_FORMAT_UTC, /**< UTC: 2004-12-12T23:39:11Z */
130 : QOF_DATE_FORMAT_CUSTOM, /**< Used by the check printing code */
131 : QOF_DATE_FORMAT_UNSET /**< No Fancy Date Format, use Global */
132 : } QofDateFormat;
133 :
134 : #define DATE_FORMAT_FIRST QOF_DATE_FORMAT_US
135 : #define DATE_FORMAT_LAST QOF_DATE_FORMAT_UTC
136 :
137 : /** Enum for date completion modes (for dates entered without year) */
138 : typedef enum
139 : {
140 : QOF_DATE_COMPLETION_THISYEAR, /**< use current year */
141 : QOF_DATE_COMPLETION_SLIDING, /**< use sliding 12-month window */
142 : } QofDateCompletion;
143 :
144 : /**
145 : * This is how to format the month, as a number, an abbreviated string,
146 : * or the full name.
147 : */
148 : typedef enum
149 : {
150 : GNCDATE_MONTH_NUMBER,
151 : GNCDATE_MONTH_ABBREV,
152 : GNCDATE_MONTH_NAME
153 : } GNCDateMonthFormat;
154 :
155 : /* Replacements for POSIX functions which use time_t. Time_t is still
156 : * 32 bits in Microsoft Windows, Apple OSX, and some BSD versions even
157 : * when the rest of the system is 64-bits, as well as all 32-bit
158 : * versions of Unix. 32-bit time_t overflows at 03:14:07 UTC on
159 : * Tuesday, 19 January 2038 and so cannot represent dates after that.
160 : *
161 : * These functions use boost::date_time internally.
162 : */
163 : /** \brief fill out a time struct from a 64-bit time value.
164 : * \param secs: Seconds since 00:00:00 UTC 01 January 1970 (negative values
165 : * are seconds before that moment).
166 : * \return A struct tm*, allocated on the heap. Must be freed with gnc_tm_free().
167 : * The time is adjusted for the current local time zone.
168 : */
169 : struct tm* gnc_localtime (const time64 *secs);
170 :
171 : /** \brief fill out a time struct from a 64-bit time value adjusted for the current time zone.
172 : * \param secs: Seconds since 00:00:00 UTC 01 January 1970 (negative values
173 : * are seconds before that moment)
174 : * \param time: A struct tm* for the function to fill.
175 : * The time is adjusted for the current local time zone.
176 : */
177 : struct tm* gnc_localtime_r (const time64 *secs, struct tm* time);
178 :
179 : /** \brief fill out a time struct from a 64-bit time value
180 : * \param secs: Seconds since 00:00:00 UTC 01 January 1970 (negative values
181 : * are seconds before that moment)
182 : * \return A struct tm*, allocated on the heap. Must be freed with gnc_tm_free()
183 : * The time is UTC.
184 : */
185 : struct tm* gnc_gmtime (const time64 *secs);
186 :
187 : /** \brief returns an integer corresponding to locale start of week
188 : * \return An integer 1=Sunday, 2=Monday etc. If error, return 0.
189 : */
190 : gint gnc_start_of_week (void);
191 :
192 : /** \brief calculate seconds from the epoch given a time struct
193 : * \param time: A struct tm* containing the date-time information.
194 : * The time is understood to be in the current local time zone.
195 : * \return Seconds since 00:00:00 UTC 01 January 1970 (negative values
196 : * are seconds before that moment).
197 : */
198 : time64 gnc_mktime (struct tm* time);
199 :
200 : /** \brief calculate seconds from the epoch given a time struct
201 : * \param time: A struct tm* containing the date-time information
202 : * The time is understood to be utc.
203 : * \return Seconds since 00:00:00 UTC 01 January 1970 (negative values
204 : * are seconds before that moment).
205 : */
206 : time64 gnc_timegm (struct tm* time);
207 :
208 : /** \brief Return a string representation of a date from a 64-bit time value
209 : * \param secs: Seconds since 00:00:00 UTC 01 January 1970 (negative values
210 : * are seconds before that moment)
211 : * \return A string, which must be freed with g_free(), representing the date
212 : * in the following format:
213 : * Thu Nov 24 18:22:48 1986\n\0
214 : * This is equivalent to the strftime format %a %b %H:%M:%S %Y.
215 : */
216 : gchar* gnc_ctime (const time64 *secs);
217 :
218 : /** \brief get the current time
219 : * \param A time64* which, if not NULL, will be filled in with the same
220 : * value as is returned.
221 : * \return Seconds since 00:00:00 UTC 01 January 1970 (negative values
222 : * are seconds before that moment)
223 : */
224 : time64 gnc_time (time64 *tbuf);
225 :
226 : /** \brief Find the difference in seconds between two time values
227 : * (deprecated)
228 : * \param secs1: The first time value, in Seconds since
229 : * 00:00:00 UTC 01 January 1970 (negative values are seconds before that moment)
230 : * \param secs2: The second time value, in Seconds since
231 : * 00:00:00 UTC 01 January 1970 (negative values are seconds before that moment)
232 : * \return The difference in seconds between secs1 and secs2. If secs2 is
233 : * later than secs1 the value will be negative.
234 : */
235 : gdouble gnc_difftime (const time64 secs1, const time64 secs2);
236 :
237 : /** \brief free a struct tm* created with gnc_localtime() or gnc_gmtime()
238 : * \param time: The struct tm* to be freed.
239 : */
240 : void gnc_tm_free (struct tm* time);
241 :
242 : /** \name String / DateFormat conversion. */
243 : //@{
244 :
245 : /** \brief The string->value versions return FALSE on success and TRUE on failure */
246 : const gchar* gnc_date_dateformat_to_string(QofDateFormat format);
247 :
248 : /** \brief Converts the date format to a printable string.
249 :
250 : Note the reversed return values!
251 : @return FALSE on success, TRUE on failure.
252 : */
253 : gboolean gnc_date_string_to_dateformat(const gchar* format_string,
254 : QofDateFormat *format);
255 :
256 : const gchar* gnc_date_monthformat_to_string(GNCDateMonthFormat format);
257 :
258 : /** \brief Converts the month format to a printable string.
259 :
260 : Note the reversed return values!
261 : @return FALSE on success, TRUE on failure.
262 : */
263 : gboolean gnc_date_string_to_monthformat(const gchar *format_string,
264 : GNCDateMonthFormat *format);
265 :
266 : /** \brief print a time64 as a date string per format
267 : * \param time The time64 to print
268 : * \param format A date format conforming to the strftime format rules.
269 : * \return a raw heap-allocated char* which must be freed.
270 : */
271 : char* gnc_print_time64(time64 time, const char* format);
272 :
273 : // @}
274 :
275 : /** @name GDate time64 setters
276 : * @{ */
277 : /** Returns a newly allocated date of the current clock time, taken from
278 : * time(2). The caller must g_date_free() the object afterwards. */
279 : GDate* gnc_g_date_new_today (void);
280 :
281 : /** Set a GDate to the current day
282 : * @param gd The date to act on
283 : */
284 : void gnc_gdate_set_today (GDate* gd);
285 :
286 : /** Set a GDate to a time64
287 : * @param gd the date to act on
288 : * @param time the time to set it to.
289 : */
290 : void gnc_gdate_set_time64 (GDate* gd, time64 time);
291 :
292 : /** @} */
293 : /** convert a time64 on a certain day (localtime) to
294 : * the time64 representing midday on that day. Watch out - this is *not* the
295 : * first second of the day, which is returned by various other functions
296 : * returning a time64. */
297 : time64 time64CanonicalDayTime(time64 t);
298 :
299 : /** Turns a GDate into a time64, returning the first second of the day */
300 : time64 gdate_to_time64 (GDate d);
301 :
302 : /** Convert a day, month, and year to a time64, returning the first second of the day */
303 : time64 gnc_dmy2time64 (gint day, gint month, gint year);
304 :
305 : /** Converts a day, month, and year to a time64 representing 11:00:00 UTC
306 : * 11:00:00 UTC falls on the same time in almost all timezones, the exceptions
307 : * being the +13, +14, and -12 timezones used by countries along the
308 : * International Date Line. Since users in those timezones would see dates
309 : * immediately change by one day, the function checks the current timezone for
310 : * those changes and adjusts the UTC time so that the date will be consistent.
311 : */
312 : time64 gnc_dmy2time64_neutral (gint day, gint month, gint year);
313 :
314 : /** Same as gnc_dmy2time64, but last second of the day */
315 : time64 gnc_dmy2time64_end (gint day, gint month, gint year);
316 :
317 : /** The gnc_iso8601_to_time64_gmt() routine converts an ISO-8601 style
318 : * date/time string to time64. Please note that ISO-8601 strings
319 : * are a representation of Universal Time (UTC), and as such, they
320 : * 'store' UTC. To make them human readable, they show time zone
321 : * information along with a local-time string. But fundamentally,
322 : * they *are* UTC. Thus, this routine takes a UTC input, and
323 : * returns a UTC output.
324 : *
325 : * For example: 1998-07-17 11:00:00.68-0500
326 : * is 680 milliseconds after 11 o'clock, central daylight time
327 : * It is also 680 milliseconds after 16:00:00 hours UTC.
328 : * \return The universal time.
329 : *
330 : * XXX Caution: this routine does not handle strings that specify
331 : * times before January 1 1970.
332 : */
333 : time64 gnc_iso8601_to_time64_gmt(const gchar *);
334 :
335 : /** The gnc_time64_to_iso8601_buff() routine takes the input
336 : * UTC time64 value and prints it as an ISO-8601 style string.
337 : * The buffer must be long enough to contain the NULL-terminated
338 : * string (32 characters + NUL). This routine returns a pointer
339 : * to the null terminator (and can thus be used in the 'stpcpy'
340 : * metaphor of string concatenation).
341 : *
342 : * Please note that ISO-8601 strings are a representation of
343 : * Universal Time (UTC), and as such, they 'store' UTC. To make them
344 : * human readable, they show time zone information along with a
345 : * local-time string. But fundamentally, they *are* UTC. Thus,
346 : * this routine takes a UTC input, and returns a UTC output.
347 : *
348 : * The string generated by this routine uses the local time zone
349 : * on the machine on which it is executing to create the time string.
350 : */
351 : gchar * gnc_time64_to_iso8601_buff (time64, char * buff);
352 : // @}
353 :
354 : /* ======================================================== */
355 :
356 : /** \name QofDateFormat functions */
357 : // @{
358 : /** The qof_date_format_get routine returns the date format that
359 : * the date printing will use when printing a date, and the scanning
360 : * routines will assume when parsing a date.
361 : * @returns: the one of the enumerated date formats.
362 : */
363 : QofDateFormat qof_date_format_get(void);
364 :
365 : /**
366 : * The qof_date_format_set() routine sets date format to one of
367 : * US, UK, CE, OR ISO. Checks to make sure it's a legal value.
368 : * Args: QofDateFormat: enumeration indicating preferred format
369 : */
370 : void qof_date_format_set(QofDateFormat df);
371 :
372 : /** This function returns a strftime formatting string for printing an
373 : * all numeric date (e.g. 2005-09-14). The string returned is based
374 : * upon the location specified.
375 : *
376 : * @param df The date style (us, uk, iso, etc) that should be provided.
377 : *
378 : * @return A formatting string that will print a date in the
379 : * requested style */
380 : const gchar *qof_date_format_get_string(QofDateFormat df);
381 :
382 : /** This function returns a strftime formatting string for printing a
383 : * date using words and numbers (e.g. 2005-September-14). The string
384 : * returned is based upon the location specified.
385 : *
386 : * @param df The date style (us, uk, iso, etc) that should be provided.
387 : *
388 : * @return A formatting string that will print a date in the
389 : * requested style */
390 : const gchar *qof_date_text_format_get_string(QofDateFormat df);
391 : // @}
392 :
393 : /* ======================================================== */
394 :
395 : /**
396 : * The qof_date_completion_set() routing sets the date completion method to
397 : * one of QOF_DATE_COMPLETION_THISYEAR (for completing the year to
398 : * the current calendar year) or QOF_DATE_COMPLETION_SLIDING (for
399 : * using a sliding 12-month window). The sliding window starts
400 : * 'backmonth' months before the current month (0-11) */
401 : void qof_date_completion_set(QofDateCompletion dc, int backmonths);
402 :
403 : /** dateSeparator
404 : * Return the field separator for the current date format
405 : *
406 : * Args: none
407 : *
408 : * Return: date character
409 : *
410 : * Globals: global dateFormat value
411 : */
412 : gchar dateSeparator(void);
413 :
414 : /* ======================================================== */
415 :
416 : /** \name Date Printing/Scanning functions
417 : */
418 : // @{
419 : /**
420 : * \warning HACK ALERT -- the scan and print routines should probably
421 : * be moved to somewhere else. The engine really isn't involved with
422 : * things like printing formats. This is needed mostly by the GUI and
423 : * so on. If a file-io thing needs date handling, it should do it
424 : * itself, instead of depending on the routines here.
425 : */
426 :
427 : /* qof_format_time takes a format specification in UTF-8 and a broken-down time,
428 : * tries to call strftime with a sufficiently large buffer and, if successful,
429 : * return a newly allocated string in UTF-8 for the printing result.
430 : *
431 : * @param format A format specification in UTF-8.
432 : *
433 : * @param tm A broken-down time.
434 : *
435 : * @return A newly allocated string on success, or NULL otherwise.
436 : */
437 : /* gchar *qof_format_time(const gchar *format, const struct tm *tm); */
438 :
439 : /** qof_strftime calls qof_format_time to print a given time and afterwards tries
440 : * to put the result into a buffer of fixed size.
441 : *
442 : * @param buf A buffer.
443 : *
444 : * @param max The size of buf in bytes.
445 : *
446 : * @param format A format specification in UTF-8.
447 : *
448 : * @param tm A broken-down time.
449 : *
450 : * @return The number of characters written, not include the null byte, if the
451 : * complete string, including the null byte, fits into the buffer. Otherwise 0.
452 : */
453 : gsize qof_strftime(gchar *buf, gsize max, const gchar *format,
454 : const struct tm *tm);
455 :
456 : /** qof_print_date_dmy_buff
457 : * Convert a date as day / month / year integers into a localized string
458 : * representation
459 : *
460 : * Args: buff - pointer to previously allocated character array; its size
461 : * must be at lease MAX_DATE_LENTH bytes.
462 : * len - length of the buffer, in bytes.
463 : * day - day of the month as 1 ... 31
464 : * month - month of the year as 1 ... 12
465 : * year - year (4-digit)
466 : *
467 : * Returns: number of characters printed
468 : *
469 : * Globals: global dateFormat value
470 : **/
471 : size_t qof_print_date_dmy_buff (gchar * buff, size_t buflen, int day, int month, int year);
472 :
473 : /** Convenience: calls through to qof_print_date_dmy_buff(). **/
474 : size_t qof_print_date_buff (char * buff, size_t buflen, time64 secs);
475 :
476 : /** Convenience; calls through to qof_print_date_dmy_buff(). **/
477 : size_t qof_print_gdate(char *buf, size_t bufflen, const GDate *gd);
478 :
479 : /** Convenience; calls through to qof_print_date_dmy_buff().
480 : * Return: string, which should be freed when no longer needed.
481 : * **/
482 : char * qof_print_date (time64 secs);
483 :
484 :
485 : gchar* gnc_date_interval_format (time64 from_date, time64 to_date);
486 :
487 : /* ------------------------------------------------------------------ */
488 : /* time printing utilities */
489 :
490 : /**
491 : * Returns the number of bytes printed.
492 : */
493 :
494 : size_t qof_print_date_time_buff (char * buff, size_t len, time64 secs);
495 :
496 : /** qof_scan_date
497 : * Convert a string into day / month / year integers according to
498 : * the current dateFormat value.
499 : *
500 : * Args: buff - pointer to date string
501 : * day - will store day of the month as 1 ... 31
502 : * month - will store month of the year as 1 ... 12
503 : * year - will store the year (4-digit)
504 : *
505 : * Return: TRUE if the string seemed to be a valid date; else FALSE.
506 : *
507 : * Globals: uses global dateFormat value to assist in parsing.
508 : */
509 : gboolean qof_scan_date (const char *buff, int *day, int *month, int *year);
510 :
511 : // @}
512 :
513 : /* ======================================================== */
514 :
515 : /** \name Date Start/End Adjustment routines
516 : * Given a time value, adjust it to be the beginning or end of that day.
517 : */
518 : // @{
519 :
520 : /** The gnc_tm_set_day_start() inline routine will set the appropriate
521 : * fields in the struct tm to indicate the first second of that day.
522 : * This routine assumes that the contents of the data structure is
523 : * already in normalized form. */
524 : static inline
525 105 : void gnc_tm_set_day_start (struct tm *tm)
526 : {
527 : /* First second of the day */
528 105 : g_return_if_fail (tm != NULL);
529 105 : tm->tm_hour = 0;
530 105 : tm->tm_min = 0;
531 105 : tm->tm_sec = 0;
532 : }
533 :
534 : /** The gnc_tm_set_day_neutral() inline routine will set the appropriate
535 : * fields in the struct tm to indicate 10:59am of that day.
536 : */
537 : void gnc_tm_set_day_neutral (struct tm *tm);
538 :
539 : /** The gnc_tm_set_day_middle() inline routine will set the appropriate
540 : * fields in the struct tm to indicate noon of that day. This
541 : * routine assumes that the contents of the data structure is already
542 : * in normalized form.*/
543 : static inline
544 4777 : void gnc_tm_set_day_middle (struct tm *tm)
545 : {
546 : /* First second of the day */
547 4777 : g_return_if_fail (tm != NULL);
548 4777 : tm->tm_hour = 12;
549 4777 : tm->tm_min = 0;
550 4777 : tm->tm_sec = 0;
551 : }
552 :
553 : /** The gnc_tm_set_day_end() inline routine will set the appropriate
554 : * fields in the struct tm to indicate the last second of that day.
555 : * This routine assumes that the contents of the data structure is
556 : * already in normalized form.*/
557 : static inline
558 114 : void gnc_tm_set_day_end (struct tm *tm)
559 : {
560 : /* Last second of the day */
561 114 : g_return_if_fail (tm != NULL);
562 114 : tm->tm_hour = 23;
563 114 : tm->tm_min = 59;
564 114 : tm->tm_sec = 59;
565 : }
566 :
567 : /** The gnc_time64_get_day_start() routine will take the given time in
568 : * seconds and adjust it to the first second of that day. */
569 : time64 gnc_time64_get_day_start(time64 time_val);
570 :
571 : /** The gnc_time64_get_day_neutral() routine will take the given time in
572 : * seconds and adjust it to 10:59:00Z of that day. */
573 : time64 gnc_time64_get_day_neutral(time64 time_val);
574 :
575 : /** The gnc_time64_get_day_end() routine will take the given time in
576 : * seconds and adjust it to the last second of that day. */
577 : time64 gnc_time64_get_day_end(time64 time_val);
578 :
579 : /** Get the numerical last date of the month. (28, 29, 30, 31) */
580 : int gnc_date_get_last_mday (int month, int year);
581 :
582 : // @}
583 :
584 : /* ======================================================== */
585 :
586 : /** \name Today's Date */
587 : // @{
588 : /** The gnc_tm_get_today_start() routine takes a pointer to a struct
589 : * tm and fills it in with the first second of the today. */
590 : void gnc_tm_get_today_start(struct tm *tm);
591 :
592 : /** The gnc_tm_get_today_start() routine takes a pointer to a struct
593 : * tm and fills it in with the timezone neutral time (10:59:00Z). */
594 : void gnc_tm_get_today_neutral(struct tm *tm);
595 :
596 : /** The gnc_tm_get_today_end() routine takes a pointer to a struct
597 : * tm and fills it in with the last second of the today. */
598 : void gnc_tm_get_today_end(struct tm *tm);
599 :
600 : /** The gnc_time64_get_today_start() routine returns a time64 value
601 : * corresponding to the first second of today. */
602 : time64 gnc_time64_get_today_start(void);
603 :
604 : /** The gnc_time64_get_today_end() routine returns a time64 value
605 : * corresponding to the last second of today. */
606 : time64 gnc_time64_get_today_end(void);
607 :
608 : /** \brief Make a timestamp in YYYYMMDDHHMMSS format.
609 : * @return A pointer to the generated string.
610 : * @note The caller owns this buffer and must g_free it when done. */
611 : char * gnc_date_timestamp (void);
612 :
613 : #define MIN_BUF_LEN 10
614 : /**
615 : * Localized DOW abbreviation.
616 : * @param buf_len at least MIN_BUF_LEN
617 : * @param dow struct tm semantics: 0=sunday .. 6=saturday
618 : **/
619 : void gnc_dow_abbrev(gchar *buf, int buf_len, int dow);
620 :
621 : //@}
622 :
623 : /* ======================================================== */
624 :
625 : /** \name GDate hash table support */
626 : // @{
627 :
628 : /** Compares two GDate*'s for equality; useful for using GDate*'s as
629 : * GHashTable keys. */
630 : gint gnc_gdate_equal(gconstpointer gda, gconstpointer gdb);
631 :
632 :
633 : /** Provides a "hash" of a GDate* value; useful for using GDate*'s as
634 : * GHashTable keys. */
635 : guint gnc_gdate_hash( gconstpointer gd );
636 :
637 : //@}
638 :
639 : /* ======================================================== */
640 :
641 : /** \name GDate to time64 conversions */
642 : // @{
643 : /** Returns the GDate in which the time64 occurs.
644 : * @param t The time64
645 : * @returns A GDate for the day in which the time64 occurs.
646 : */
647 : GDate time64_to_gdate (time64 t);
648 :
649 : /** The gnc_time64_get_day_start() routine will take the given time in
650 : * GLib GDate format and adjust it to the first second of that day.
651 : */
652 : time64 gnc_time64_get_day_start_gdate (const GDate *date);
653 :
654 : /** The gnc_time64_get_day_end() routine will take the given time in
655 : * GLib GDate format and adjust it to the last second of that day.
656 : */
657 : time64 gnc_time64_get_day_end_gdate (const GDate *date);
658 :
659 : //@}
660 :
661 : /* ======================================================== */
662 :
663 : /** \name Date Manipulation */
664 : // @{
665 :
666 : /** This function modifies a GDate to set it to the first day of the
667 : * month in which it falls. For example, if this function is called
668 : * with a date of 2003-09-24 the date will be modified to 2003-09-01.
669 : *
670 : * @param date The GDate to modify. */
671 : void gnc_gdate_set_month_start (GDate *date);
672 :
673 :
674 : /** This function modifies a GDate to set it to the last day of the
675 : * month in which it falls. For example, if this function is called
676 : * with a date of 2003-09-24 the date will be modified to 2003-09-30.
677 : *
678 : * @param date The GDate to modify. */
679 : void gnc_gdate_set_month_end (GDate *date);
680 :
681 :
682 : /** This function modifies a GDate to set it to the first day of the
683 : * month prior to the one in which it falls. For example, if this
684 : * function is called with a date of 2003-09-24 the date will be
685 : * modified to 2003-08-01.
686 : *
687 : * @param date The GDate to modify. */
688 : void gnc_gdate_set_prev_month_start (GDate *date);
689 :
690 :
691 : /** This function modifies a GDate to set it to the last day of the
692 : * month prior to the one in which it falls. For example, if this
693 : * function is called with a date of 2003-09-24 the date will be
694 : * modified to 2003-08-31.
695 : *
696 : * @param date The GDate to modify. */
697 : void gnc_gdate_set_prev_month_end (GDate *date);
698 :
699 :
700 : /** This function modifies a GDate to set it to the first day of the
701 : * quarter in which it falls. For example, if this function is called
702 : * with a date of 2003-09-24 the date will be modified to 2003-07-01.
703 : *
704 : * @param date The GDate to modify. */
705 : void gnc_gdate_set_quarter_start (GDate *date);
706 :
707 :
708 : /** This function modifies a GDate to set it to the last day of the
709 : * quarter in which it falls. For example, if this function is called
710 : * with a date of 2003-09-24 the date will be modified to 2003-09-30.
711 : *
712 : * @param date The GDate to modify. */
713 : void gnc_gdate_set_quarter_end (GDate *date);
714 :
715 :
716 : /** This function modifies a GDate to set it to the first day of the
717 : * quarter prior to the one in which it falls. For example, if this
718 : * function is called with a date of 2003-09-24 the date will be
719 : * modified to 2003-04-01.
720 : *
721 : * @param date The GDate to modify. */
722 : void gnc_gdate_set_prev_quarter_start (GDate *date);
723 :
724 :
725 : /** This function modifies a GDate to set it to the last day of the
726 : * quarter prior to the one in which it falls. For example, if this
727 : * function is called with a date of 2003-09-24 the date will be
728 : * modified to 2003-06-30.
729 : *
730 : * @param date The GDate to modify. */
731 : void gnc_gdate_set_prev_quarter_end (GDate *date);
732 :
733 :
734 : /** This function modifies a GDate to set it to the first day of the
735 : * year in which it falls. For example, if this function is called
736 : * with a date of 2003-09-24 the date will be modified to 2003-01-01.
737 : *
738 : * @param date The GDate to modify. */
739 : void gnc_gdate_set_year_start (GDate *date);
740 :
741 :
742 : /** This function modifies a GDate to set it to the last day of the
743 : * year in which it falls. For example, if this function is called
744 : * with a date of 2003-09-24 the date will be modified to 2003-12-31.
745 : *
746 : * @param date The GDate to modify. */
747 : void gnc_gdate_set_year_end (GDate *date);
748 :
749 :
750 : /** This function modifies a GDate to set it to the first day of the
751 : * year prior to the one in which it falls. For example, if this
752 : * function is called with a date of 2003-09-24 the date will be
753 : * modified to 2002-01-01.
754 : *
755 : * @param date The GDate to modify. */
756 : void gnc_gdate_set_prev_year_start (GDate *date);
757 :
758 :
759 : /** This function modifies a GDate to set it to the last day of the
760 : * year prior to the one in which it falls. For example, if this
761 : * function is called with a date of 2003-09-24 the date will be
762 : * modified to 2002-12-31.
763 : *
764 : * @param date The GDate to modify. */
765 : void gnc_gdate_set_prev_year_end (GDate *date);
766 :
767 :
768 : /** This function modifies a GDate to set it to the first day of the
769 : * fiscal year in which it falls. For example, if this function is
770 : * called with a date of 2003-09-24 and a fiscal year ending July
771 : * 31st, the date will be modified to 2003-08-01.
772 : *
773 : * @param date The GDate to modify.
774 : *
775 : * @param year_end A GDate containing the last month and day of the
776 : * fiscal year. The year field of this argument is ignored. */
777 : void gnc_gdate_set_fiscal_year_start (GDate *date, const GDate *year_end);
778 :
779 :
780 : /** This function modifies a GDate to set it to the last day of the
781 : * fiscal year in which it falls. For example, if this function is
782 : * called with a date of 2003-09-24 and a fiscal year ending July
783 : * 31st, the date will be modified to 2004-07-31.
784 : *
785 : * @param date The GDate to modify.
786 : *
787 : * @param year_end A GDate containing the last month and day of the
788 : * fiscal year. The year field of this argument is ignored. */
789 : void gnc_gdate_set_fiscal_year_end (GDate *date, const GDate *year_end);
790 :
791 :
792 : /** This function modifies a GDate to set it to the first day of the
793 : * fiscal year prior to the one in which it falls. For example, if
794 : * this function is called with a date of 2003-09-24 and a fiscal
795 : * year ending July 31st, the date will be modified to 2002-08-01.
796 : *
797 : * @param date The GDate to modify.
798 : *
799 : * @param year_end A GDate containing the last month and day of the
800 : * fiscal year. The year field of this argument is ignored. */
801 : void gnc_gdate_set_prev_fiscal_year_start (GDate *date, const GDate *year_end);
802 :
803 :
804 : /** This function modifies a GDate to set it to the last day of the
805 : * fiscal year prior to the one in which it falls. For example, if
806 : * this function is called with a date of 2003-09-24 and a fiscal
807 : * year ending July 31st, the date will be modified to 2003-07-31.
808 : *
809 : * @param date The GDate to modify.
810 : *
811 : * @param year_end A GDate containing the last month and day of the
812 : * fiscal year. The year field of this argument is ignored. */
813 : void gnc_gdate_set_prev_fiscal_year_end (GDate *date, const GDate *year_end);
814 :
815 : //@}
816 :
817 : //@}
818 : #ifdef __cplusplus
819 : }
820 : #endif
821 :
822 : #endif /* GNC_DATE_H */
|
