Branch data 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 : : /* ------------------------------------------------------------------ */
486 : : /* time printing utilities */
487 : :
488 : : /**
489 : : * Returns the number of bytes printed.
490 : : */
491 : :
492 : : size_t qof_print_date_time_buff (char * buff, size_t len, time64 secs);
493 : :
494 : : /** qof_scan_date
495 : : * Convert a string into day / month / year integers according to
496 : : * the current dateFormat value.
497 : : *
498 : : * Args: buff - pointer to date string
499 : : * day - will store day of the month as 1 ... 31
500 : : * month - will store month of the year as 1 ... 12
501 : : * year - will store the year (4-digit)
502 : : *
503 : : * Return: TRUE if the string seemed to be a valid date; else FALSE.
504 : : *
505 : : * Globals: uses global dateFormat value to assist in parsing.
506 : : */
507 : : gboolean qof_scan_date (const char *buff, int *day, int *month, int *year);
508 : :
509 : : // @}
510 : :
511 : : /* ======================================================== */
512 : :
513 : : /** \name Date Start/End Adjustment routines
514 : : * Given a time value, adjust it to be the beginning or end of that day.
515 : : */
516 : : // @{
517 : :
518 : : /** The gnc_tm_set_day_start() inline routine will set the appropriate
519 : : * fields in the struct tm to indicate the first second of that day.
520 : : * This routine assumes that the contents of the data structure is
521 : : * already in normalized form. */
522 : : static inline
523 : 73 : void gnc_tm_set_day_start (struct tm *tm)
524 : : {
525 : : /* First second of the day */
526 : 73 : g_return_if_fail (tm != NULL);
527 : 73 : tm->tm_hour = 0;
528 : 73 : tm->tm_min = 0;
529 : 73 : tm->tm_sec = 0;
530 : : }
531 : :
532 : : /** The gnc_tm_set_day_neutral() inline routine will set the appropriate
533 : : * fields in the struct tm to indicate 10:59am of that day.
534 : : */
535 : : void gnc_tm_set_day_neutral (struct tm *tm);
536 : :
537 : : /** The gnc_tm_set_day_middle() inline routine will set the appropriate
538 : : * fields in the struct tm to indicate noon of that day. This
539 : : * routine assumes that the contents of the data structure is already
540 : : * in normalized form.*/
541 : : static inline
542 : 4722 : void gnc_tm_set_day_middle (struct tm *tm)
543 : : {
544 : : /* First second of the day */
545 : 4722 : g_return_if_fail (tm != NULL);
546 : 4722 : tm->tm_hour = 12;
547 : 4722 : tm->tm_min = 0;
548 : 4722 : tm->tm_sec = 0;
549 : : }
550 : :
551 : : /** The gnc_tm_set_day_end() inline routine will set the appropriate
552 : : * fields in the struct tm to indicate the last second of that day.
553 : : * This routine assumes that the contents of the data structure is
554 : : * already in normalized form.*/
555 : : static inline
556 : 124 : void gnc_tm_set_day_end (struct tm *tm)
557 : : {
558 : : /* Last second of the day */
559 : 124 : g_return_if_fail (tm != NULL);
560 : 124 : tm->tm_hour = 23;
561 : 124 : tm->tm_min = 59;
562 : 124 : tm->tm_sec = 59;
563 : : }
564 : :
565 : : /** The gnc_time64_get_day_start() routine will take the given time in
566 : : * seconds and adjust it to the first second of that day. */
567 : : time64 gnc_time64_get_day_start(time64 time_val);
568 : :
569 : : /** The gnc_time64_get_day_neutral() routine will take the given time in
570 : : * seconds and adjust it to 10:59:00Z of that day. */
571 : : time64 gnc_time64_get_day_neutral(time64 time_val);
572 : :
573 : : /** The gnc_time64_get_day_end() routine will take the given time in
574 : : * seconds and adjust it to the last second of that day. */
575 : : time64 gnc_time64_get_day_end(time64 time_val);
576 : :
577 : : /** Get the numerical last date of the month. (28, 29, 30, 31) */
578 : : int gnc_date_get_last_mday (int month, int year);
579 : :
580 : : // @}
581 : :
582 : : /* ======================================================== */
583 : :
584 : : /** \name Today's Date */
585 : : // @{
586 : : /** The gnc_tm_get_today_start() routine takes a pointer to a struct
587 : : * tm and fills it in with the first second of the today. */
588 : : void gnc_tm_get_today_start(struct tm *tm);
589 : :
590 : : /** The gnc_tm_get_today_start() routine takes a pointer to a struct
591 : : * tm and fills it in with the timezone neutral time (10:59:00Z). */
592 : : void gnc_tm_get_today_neutral(struct tm *tm);
593 : :
594 : : /** The gnc_tm_get_today_end() routine takes a pointer to a struct
595 : : * tm and fills it in with the last second of the today. */
596 : : void gnc_tm_get_today_end(struct tm *tm);
597 : :
598 : : /** The gnc_time64_get_today_start() routine returns a time64 value
599 : : * corresponding to the first second of today. */
600 : : time64 gnc_time64_get_today_start(void);
601 : :
602 : : /** The gnc_time64_get_today_end() routine returns a time64 value
603 : : * corresponding to the last second of today. */
604 : : time64 gnc_time64_get_today_end(void);
605 : :
606 : : /** \brief Make a timestamp in YYYYMMDDHHMMSS format.
607 : : * @return A pointer to the generated string.
608 : : * @note The caller owns this buffer and must g_free it when done. */
609 : : char * gnc_date_timestamp (void);
610 : :
611 : : #define MIN_BUF_LEN 10
612 : : /**
613 : : * Localized DOW abbreviation.
614 : : * @param buf_len at least MIN_BUF_LEN
615 : : * @param dow struct tm semantics: 0=sunday .. 6=saturday
616 : : **/
617 : : void gnc_dow_abbrev(gchar *buf, int buf_len, int dow);
618 : :
619 : : //@}
620 : :
621 : : /* ======================================================== */
622 : :
623 : : /** \name GDate hash table support */
624 : : // @{
625 : :
626 : : /** Compares two GDate*'s for equality; useful for using GDate*'s as
627 : : * GHashTable keys. */
628 : : gint gnc_gdate_equal(gconstpointer gda, gconstpointer gdb);
629 : :
630 : :
631 : : /** Provides a "hash" of a GDate* value; useful for using GDate*'s as
632 : : * GHashTable keys. */
633 : : guint gnc_gdate_hash( gconstpointer gd );
634 : :
635 : : //@}
636 : :
637 : : /* ======================================================== */
638 : :
639 : : /** \name GDate to time64 conversions */
640 : : // @{
641 : : /** Returns the GDate in which the time64 occurs.
642 : : * @param t The time64
643 : : * @returns A GDate for the day in which the time64 occurs.
644 : : */
645 : : GDate time64_to_gdate (time64 t);
646 : :
647 : : /** The gnc_time64_get_day_start() routine will take the given time in
648 : : * GLib GDate format and adjust it to the first second of that day.
649 : : */
650 : : time64 gnc_time64_get_day_start_gdate (const GDate *date);
651 : :
652 : : /** The gnc_time64_get_day_end() routine will take the given time in
653 : : * GLib GDate format and adjust it to the last second of that day.
654 : : */
655 : : time64 gnc_time64_get_day_end_gdate (const GDate *date);
656 : :
657 : : //@}
658 : :
659 : : /* ======================================================== */
660 : :
661 : : /** \name Date Manipulation */
662 : : // @{
663 : :
664 : : /** This function modifies a GDate to set it to the first day of the
665 : : * month in which it falls. For example, if this function is called
666 : : * with a date of 2003-09-24 the date will be modified to 2003-09-01.
667 : : *
668 : : * @param date The GDate to modify. */
669 : : void gnc_gdate_set_month_start (GDate *date);
670 : :
671 : :
672 : : /** This function modifies a GDate to set it to the last day of the
673 : : * month in which it falls. For example, if this function is called
674 : : * with a date of 2003-09-24 the date will be modified to 2003-09-30.
675 : : *
676 : : * @param date The GDate to modify. */
677 : : void gnc_gdate_set_month_end (GDate *date);
678 : :
679 : :
680 : : /** This function modifies a GDate to set it to the first day of the
681 : : * month prior to the one in which it falls. For example, if this
682 : : * function is called with a date of 2003-09-24 the date will be
683 : : * modified to 2003-08-01.
684 : : *
685 : : * @param date The GDate to modify. */
686 : : void gnc_gdate_set_prev_month_start (GDate *date);
687 : :
688 : :
689 : : /** This function modifies a GDate to set it to the last day of the
690 : : * month prior to the one in which it falls. For example, if this
691 : : * function is called with a date of 2003-09-24 the date will be
692 : : * modified to 2003-08-31.
693 : : *
694 : : * @param date The GDate to modify. */
695 : : void gnc_gdate_set_prev_month_end (GDate *date);
696 : :
697 : :
698 : : /** This function modifies a GDate to set it to the first day of the
699 : : * quarter in which it falls. For example, if this function is called
700 : : * with a date of 2003-09-24 the date will be modified to 2003-07-01.
701 : : *
702 : : * @param date The GDate to modify. */
703 : : void gnc_gdate_set_quarter_start (GDate *date);
704 : :
705 : :
706 : : /** This function modifies a GDate to set it to the last day of the
707 : : * quarter in which it falls. For example, if this function is called
708 : : * with a date of 2003-09-24 the date will be modified to 2003-09-30.
709 : : *
710 : : * @param date The GDate to modify. */
711 : : void gnc_gdate_set_quarter_end (GDate *date);
712 : :
713 : :
714 : : /** This function modifies a GDate to set it to the first day of the
715 : : * quarter prior to the one in which it falls. For example, if this
716 : : * function is called with a date of 2003-09-24 the date will be
717 : : * modified to 2003-04-01.
718 : : *
719 : : * @param date The GDate to modify. */
720 : : void gnc_gdate_set_prev_quarter_start (GDate *date);
721 : :
722 : :
723 : : /** This function modifies a GDate to set it to the last day of the
724 : : * quarter prior to the one in which it falls. For example, if this
725 : : * function is called with a date of 2003-09-24 the date will be
726 : : * modified to 2003-06-30.
727 : : *
728 : : * @param date The GDate to modify. */
729 : : void gnc_gdate_set_prev_quarter_end (GDate *date);
730 : :
731 : :
732 : : /** This function modifies a GDate to set it to the first day of the
733 : : * year in which it falls. For example, if this function is called
734 : : * with a date of 2003-09-24 the date will be modified to 2003-01-01.
735 : : *
736 : : * @param date The GDate to modify. */
737 : : void gnc_gdate_set_year_start (GDate *date);
738 : :
739 : :
740 : : /** This function modifies a GDate to set it to the last day of the
741 : : * year in which it falls. For example, if this function is called
742 : : * with a date of 2003-09-24 the date will be modified to 2003-12-31.
743 : : *
744 : : * @param date The GDate to modify. */
745 : : void gnc_gdate_set_year_end (GDate *date);
746 : :
747 : :
748 : : /** This function modifies a GDate to set it to the first day of the
749 : : * year prior to the one in which it falls. For example, if this
750 : : * function is called with a date of 2003-09-24 the date will be
751 : : * modified to 2002-01-01.
752 : : *
753 : : * @param date The GDate to modify. */
754 : : void gnc_gdate_set_prev_year_start (GDate *date);
755 : :
756 : :
757 : : /** This function modifies a GDate to set it to the last day of the
758 : : * year prior to the one in which it falls. For example, if this
759 : : * function is called with a date of 2003-09-24 the date will be
760 : : * modified to 2002-12-31.
761 : : *
762 : : * @param date The GDate to modify. */
763 : : void gnc_gdate_set_prev_year_end (GDate *date);
764 : :
765 : :
766 : : /** This function modifies a GDate to set it to the first day of the
767 : : * fiscal year in which it falls. For example, if this function is
768 : : * called with a date of 2003-09-24 and a fiscal year ending July
769 : : * 31st, the date will be modified to 2003-08-01.
770 : : *
771 : : * @param date The GDate to modify.
772 : : *
773 : : * @param year_end A GDate containing the last month and day of the
774 : : * fiscal year. The year field of this argument is ignored. */
775 : : void gnc_gdate_set_fiscal_year_start (GDate *date, const GDate *year_end);
776 : :
777 : :
778 : : /** This function modifies a GDate to set it to the last day of the
779 : : * fiscal year in which it falls. For example, if this function is
780 : : * called with a date of 2003-09-24 and a fiscal year ending July
781 : : * 31st, the date will be modified to 2004-07-31.
782 : : *
783 : : * @param date The GDate to modify.
784 : : *
785 : : * @param year_end A GDate containing the last month and day of the
786 : : * fiscal year. The year field of this argument is ignored. */
787 : : void gnc_gdate_set_fiscal_year_end (GDate *date, const GDate *year_end);
788 : :
789 : :
790 : : /** This function modifies a GDate to set it to the first day of the
791 : : * fiscal year prior to the one in which it falls. For example, if
792 : : * this function is called with a date of 2003-09-24 and a fiscal
793 : : * year ending July 31st, the date will be modified to 2002-08-01.
794 : : *
795 : : * @param date The GDate to modify.
796 : : *
797 : : * @param year_end A GDate containing the last month and day of the
798 : : * fiscal year. The year field of this argument is ignored. */
799 : : void gnc_gdate_set_prev_fiscal_year_start (GDate *date, const GDate *year_end);
800 : :
801 : :
802 : : /** This function modifies a GDate to set it to the last day of the
803 : : * fiscal year prior to the one in which it falls. For example, if
804 : : * this function is called with a date of 2003-09-24 and a fiscal
805 : : * year ending July 31st, the date will be modified to 2003-07-31.
806 : : *
807 : : * @param date The GDate to modify.
808 : : *
809 : : * @param year_end A GDate containing the last month and day of the
810 : : * fiscal year. The year field of this argument is ignored. */
811 : : void gnc_gdate_set_prev_fiscal_year_end (GDate *date, const GDate *year_end);
812 : :
813 : : //@}
814 : :
815 : : //@}
816 : : #ifdef __cplusplus
817 : : }
818 : : #endif
819 : :
820 : : #endif /* GNC_DATE_H */
|
