3 * Copyright (C) 2009-2010 Christian Hergert <chris@dronelabs.com>
4 * Copyright (C) 2010 Thiago Santos <thiago.sousa.santos@collabora.co.uk>
5 * Copyright (C) 2010 Emmanuele Bassi <ebassi@linux.intel.com>
6 * Copyright © 2010 Codethink Limited
8 * This library is free software; you can redistribute it and/or modify
9 * it under the terms of the GNU Lesser General Public License as
10 * published by the Free Software Foundation; either version 2.1 of the
11 * licence, or (at your option) any later version.
13 * This is distributed in the hope that it will be useful, but WITHOUT
14 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
15 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public
16 * License for more details.
18 * You should have received a copy of the GNU Lesser General Public
19 * License along with this library; if not, write to the Free Software
20 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301
23 * Authors: Christian Hergert <chris@dronelabs.com>
24 * Thiago Santos <thiago.sousa.santos@collabora.co.uk>
25 * Emmanuele Bassi <ebassi@linux.intel.com>
26 * Ryan Lortie <desrt@desrt.ca>
29 /* Algorithms within this file are based on the Calendar FAQ by
30 * Claus Tondering. It can be found at
31 * http://www.tondering.dk/claus/cal/calendar29.txt
33 * Copyright and disclaimer
34 * ------------------------
35 * This document is Copyright (C) 2008 by Claus Tondering.
36 * E-mail: claus@tondering.dk. (Please include the word
37 * "calendar" in the subject line.)
38 * The document may be freely distributed, provided this
39 * copyright notice is included and no money is charged for
42 * This document is provided "as is". No warranties are made as
53 #ifdef HAVE_LANGINFO_TIME
57 #include "gdatetime.h"
63 #include "gfileutils.h"
66 #include "gmappedfile.h"
67 #include "gstrfuncs.h"
68 #include "gtestutils.h"
70 #include "gtimezone.h"
77 #endif /* !G_OS_WIN32 */
82 * @short_description: a structure representing Date and Time
83 * @see_also: #GTimeZone
85 * #GDateTime is a structure that combines a Gregorian date and time
86 * into a single structure. It provides many conversion and methods to
87 * manipulate dates and times. Time precision is provided down to
88 * microseconds and the time can range (proleptically) from 0001-01-01
89 * 00:00:00 to 9999-12-31 23:59:59.999999. #GDateTime follows POSIX
90 * time in the sense that it is oblivious to leap seconds.
92 * #GDateTime is an immutable object; once it has been created it cannot
93 * be modified further. All modifiers will create a new #GDateTime.
94 * Nearly all such functions can fail due to the date or time going out
95 * of range, in which case %NULL will be returned.
97 * #GDateTime is reference counted: the reference count is increased by calling
98 * g_date_time_ref() and decreased by calling g_date_time_unref(). When the
99 * reference count drops to 0, the resources allocated by the #GDateTime
100 * structure are released.
102 * Many parts of the API may produce non-obvious results. As an
103 * example, adding two months to January 31st will yield March 31st
104 * whereas adding one month and then one month again will yield either
105 * March 28th or March 29th. Also note that adding 24 hours is not
106 * always the same as adding one day (since days containing daylight
107 * savings time transitions are either 23 or 25 hours in length).
109 * #GDateTime is available since GLib 2.26.
114 /* Microsecond timekeeping within Day */
117 /* TimeZone information */
121 /* 1 is 0001-01-01 in Proleptic Gregorian */
124 volatile gint ref_count;
127 /* Time conversion {{{1 */
129 #define UNIX_EPOCH_START 719163
130 #define INSTANT_TO_UNIX(instant) \
131 ((instant)/USEC_PER_SECOND - UNIX_EPOCH_START * SEC_PER_DAY)
132 #define UNIX_TO_INSTANT(unix) \
133 (((unix) + UNIX_EPOCH_START * SEC_PER_DAY) * USEC_PER_SECOND)
135 #define DAYS_IN_4YEARS 1461 /* days in 4 years */
136 #define DAYS_IN_100YEARS 36524 /* days in 100 years */
137 #define DAYS_IN_400YEARS 146097 /* days in 400 years */
139 #define USEC_PER_SECOND (G_GINT64_CONSTANT (1000000))
140 #define USEC_PER_MINUTE (G_GINT64_CONSTANT (60000000))
141 #define USEC_PER_HOUR (G_GINT64_CONSTANT (3600000000))
142 #define USEC_PER_MILLISECOND (G_GINT64_CONSTANT (1000))
143 #define USEC_PER_DAY (G_GINT64_CONSTANT (86400000000))
144 #define SEC_PER_DAY (G_GINT64_CONSTANT (86400))
146 #define SECS_PER_MINUTE (60)
147 #define SECS_PER_HOUR (60 * SECS_PER_MINUTE)
148 #define SECS_PER_DAY (24 * SECS_PER_HOUR)
149 #define SECS_PER_YEAR (365 * SECS_PER_DAY)
150 #define SECS_PER_JULIAN (DAYS_PER_PERIOD * SECS_PER_DAY)
152 #define GREGORIAN_LEAP(y) ((((y) % 4) == 0) && (!((((y) % 100) == 0) && (((y) % 400) != 0))))
153 #define JULIAN_YEAR(d) ((d)->julian / 365.25)
154 #define DAYS_PER_PERIOD (G_GINT64_CONSTANT (2914695))
156 static const guint16 days_in_months[2][13] =
158 { 0, 31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31 },
159 { 0, 31, 29, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31 }
162 static const guint16 days_in_year[2][13] =
164 { 0, 31, 59, 90, 120, 151, 181, 212, 243, 273, 304, 334, 365 },
165 { 0, 31, 60, 91, 121, 152, 182, 213, 244, 274, 305, 335, 366 }
168 #ifdef HAVE_LANGINFO_TIME
170 #define GET_AMPM(d) ((g_date_time_get_hour (d) < 12) ? \
171 nl_langinfo (AM_STR) : \
172 nl_langinfo (PM_STR))
174 #define PREFERRED_DATE_TIME_FMT nl_langinfo (D_T_FMT)
175 #define PREFERRED_DATE_FMT nl_langinfo (D_FMT)
176 #define PREFERRED_TIME_FMT nl_langinfo (T_FMT)
177 #define PREFERRED_TIME_FMT nl_langinfo (T_FMT)
178 #define PREFERRED_12HR_TIME_FMT nl_langinfo (T_FMT_AMPM)
180 static const gint weekday_item[2][7] =
182 { ABDAY_2, ABDAY_3, ABDAY_4, ABDAY_5, ABDAY_6, ABDAY_7, ABDAY_1 },
183 { DAY_2, DAY_3, DAY_4, DAY_5, DAY_6, DAY_7, DAY_1 }
186 static const gint month_item[2][12] =
188 { ABMON_1, ABMON_2, ABMON_3, ABMON_4, ABMON_5, ABMON_6, ABMON_7, ABMON_8, ABMON_9, ABMON_10, ABMON_11, ABMON_12 },
189 { MON_1, MON_2, MON_3, MON_4, MON_5, MON_6, MON_7, MON_8, MON_9, MON_10, MON_11, MON_12 },
192 #define WEEKDAY_ABBR(d) nl_langinfo (weekday_item[0][g_date_time_get_day_of_week (d) - 1])
193 #define WEEKDAY_FULL(d) nl_langinfo (weekday_item[1][g_date_time_get_day_of_week (d) - 1])
194 #define MONTH_ABBR(d) nl_langinfo (month_item[0][g_date_time_get_month (d) - 1])
195 #define MONTH_FULL(d) nl_langinfo (month_item[1][g_date_time_get_month (d) - 1])
199 #define GET_AMPM(d) ((g_date_time_get_hour (d) < 12) \
200 /* Translators: 'before midday' indicator */ \
201 ? C_("GDateTime", "AM") \
202 /* Translators: 'after midday' indicator */ \
203 : C_("GDateTime", "PM"))
205 /* Translators: this is the preferred format for expressing the date and the time */
206 #define PREFERRED_DATE_TIME_FMT C_("GDateTime", "%a %b %e %H:%M:%S %Y")
208 /* Translators: this is the preferred format for expressing the date */
209 #define PREFERRED_DATE_FMT C_("GDateTime", "%m/%d/%y")
211 /* Translators: this is the preferred format for expressing the time */
212 #define PREFERRED_TIME_FMT C_("GDateTime", "%H:%M:%S")
214 /* Translators: this is the preferred format for expressing 12 hour time */
215 #define PREFERRED_12HR_TIME_FMT C_("GDateTime", "%I:%M:%S %p")
217 #define WEEKDAY_ABBR(d) (get_weekday_name_abbr (g_date_time_get_day_of_week (d)))
218 #define WEEKDAY_FULL(d) (get_weekday_name (g_date_time_get_day_of_week (d)))
219 #define MONTH_ABBR(d) (get_month_name_abbr (g_date_time_get_month (d)))
220 #define MONTH_FULL(d) (get_month_name (g_date_time_get_month (d)))
223 get_month_name (gint month)
228 return C_("full month name", "January");
230 return C_("full month name", "February");
232 return C_("full month name", "March");
234 return C_("full month name", "April");
236 return C_("full month name", "May");
238 return C_("full month name", "June");
240 return C_("full month name", "July");
242 return C_("full month name", "August");
244 return C_("full month name", "September");
246 return C_("full month name", "October");
248 return C_("full month name", "November");
250 return C_("full month name", "December");
253 g_warning ("Invalid month number %d", month);
260 get_month_name_abbr (gint month)
265 return C_("abbreviated month name", "Jan");
267 return C_("abbreviated month name", "Feb");
269 return C_("abbreviated month name", "Mar");
271 return C_("abbreviated month name", "Apr");
273 return C_("abbreviated month name", "May");
275 return C_("abbreviated month name", "Jun");
277 return C_("abbreviated month name", "Jul");
279 return C_("abbreviated month name", "Aug");
281 return C_("abbreviated month name", "Sep");
283 return C_("abbreviated month name", "Oct");
285 return C_("abbreviated month name", "Nov");
287 return C_("abbreviated month name", "Dec");
290 g_warning ("Invalid month number %d", month);
297 get_weekday_name (gint day)
302 return C_("full weekday name", "Monday");
304 return C_("full weekday name", "Tuesday");
306 return C_("full weekday name", "Wednesday");
308 return C_("full weekday name", "Thursday");
310 return C_("full weekday name", "Friday");
312 return C_("full weekday name", "Saturday");
314 return C_("full weekday name", "Sunday");
317 g_warning ("Invalid week day number %d", day);
324 get_weekday_name_abbr (gint day)
329 return C_("abbreviated weekday name", "Mon");
331 return C_("abbreviated weekday name", "Tue");
333 return C_("abbreviated weekday name", "Wed");
335 return C_("abbreviated weekday name", "Thu");
337 return C_("abbreviated weekday name", "Fri");
339 return C_("abbreviated weekday name", "Sat");
341 return C_("abbreviated weekday name", "Sun");
344 g_warning ("Invalid week day number %d", day);
350 #endif /* HAVE_LANGINFO_TIME */
353 ymd_to_days (gint year,
359 days = (year - 1) * 365 + ((year - 1) / 4) - ((year - 1) / 100)
360 + ((year - 1) / 400);
362 days += days_in_year[0][month - 1];
363 if (GREGORIAN_LEAP (year) && month > 2)
372 g_date_time_get_week_number (GDateTime *datetime,
377 gint a, b, c, d, e, f, g, n, s, month, day, year;
379 g_date_time_get_ymd (datetime, &year, &month, &day);
383 a = g_date_time_get_year (datetime) - 1;
384 b = (a / 4) - (a / 100) + (a / 400);
385 c = ((a - 1) / 4) - ((a - 1) / 100) + ((a - 1) / 400);
388 f = day - 1 + (31 * (month - 1));
393 b = (a / 4) - (a / 100) + (a / 400);
394 c = ((a - 1) / 4) - ((a - 1) / 100) + ((a - 1) / 400);
397 f = day + (((153 * (month - 3)) + 2) / 5) + 58 + s;
407 *week_number = 53 - ((g - s) / 5);
408 else if (n > 364 + s)
411 *week_number = (n / 7) + 1;
415 *day_of_week = d + 1;
418 *day_of_year = f + 1;
424 g_date_time_alloc (GTimeZone *tz)
428 datetime = g_slice_new0 (GDateTime);
429 datetime->tz = g_time_zone_ref (tz);
430 datetime->ref_count = 1;
437 * @datetime: a #GDateTime
439 * Atomically increments the reference count of @datetime by one.
441 * Returns: the #GDateTime with the reference count increased
446 g_date_time_ref (GDateTime *datetime)
448 g_return_val_if_fail (datetime != NULL, NULL);
449 g_return_val_if_fail (datetime->ref_count > 0, NULL);
451 g_atomic_int_inc (&datetime->ref_count);
458 * @datetime: a #GDateTime
460 * Atomically decrements the reference count of @datetime by one.
462 * When the reference count reaches zero, the resources allocated by
463 * @datetime are freed
468 g_date_time_unref (GDateTime *datetime)
470 g_return_if_fail (datetime != NULL);
471 g_return_if_fail (datetime->ref_count > 0);
473 if (g_atomic_int_dec_and_test (&datetime->ref_count))
475 g_time_zone_unref (datetime->tz);
476 g_slice_free (GDateTime, datetime);
480 /* Internal state transformers {{{1 */
482 * g_date_time_to_instant:
483 * @datetime: a #GDateTime
485 * Convert a @datetime into an instant.
487 * An instant is a number that uniquely describes a particular
488 * microsecond in time, taking time zone considerations into account.
489 * (ie: "03:00 -0400" is the same instant as "02:00 -0500").
491 * An instant is always positive but we use a signed return value to
492 * avoid troubles with C.
495 g_date_time_to_instant (GDateTime *datetime)
499 offset = g_time_zone_get_offset (datetime->tz, datetime->interval);
500 offset *= USEC_PER_SECOND;
502 return datetime->days * USEC_PER_DAY + datetime->usec - offset;
506 * g_date_time_from_instant:
508 * @instant: a instant in time
510 * Creates a #GDateTime from a time zone and an instant.
512 * This might fail if the time ends up being out of range.
515 g_date_time_from_instant (GTimeZone *tz,
521 if (instant < 0 || instant > G_GINT64_CONSTANT (1000000000000000000))
524 datetime = g_date_time_alloc (tz);
525 datetime->interval = g_time_zone_find_interval (tz,
526 G_TIME_TYPE_UNIVERSAL,
527 INSTANT_TO_UNIX (instant));
528 offset = g_time_zone_get_offset (datetime->tz, datetime->interval);
529 offset *= USEC_PER_SECOND;
533 datetime->days = instant / USEC_PER_DAY;
534 datetime->usec = instant % USEC_PER_DAY;
536 if (datetime->days < 1 || 3652059 < datetime->days)
538 g_date_time_unref (datetime);
547 * g_date_time_deal_with_date_change:
548 * @datetime: a #GDateTime
550 * This function should be called whenever the date changes by adding
551 * days, months or years. It does three things.
553 * First, we ensure that the date falls between 0001-01-01 and
554 * 9999-12-31 and return %FALSE if it does not.
556 * Next we update the ->interval field.
558 * Finally, we ensure that the resulting date and time pair exists (by
559 * ensuring that our time zone has an interval containing it) and
560 * adjusting as required. For example, if we have the time 02:30:00 on
561 * March 13 2010 in Toronto and we add 1 day to it, we would end up with
562 * 2:30am on March 14th, which doesn't exist. In that case, we bump the
566 g_date_time_deal_with_date_change (GDateTime *datetime)
572 if (datetime->days < 1 || datetime->days > 3652059)
575 was_dst = g_time_zone_is_dst (datetime->tz, datetime->interval);
577 full_time = datetime->days * USEC_PER_DAY + datetime->usec;
580 usec = full_time % USEC_PER_SECOND;
581 full_time /= USEC_PER_SECOND;
582 full_time -= UNIX_EPOCH_START * SEC_PER_DAY;
584 datetime->interval = g_time_zone_adjust_time (datetime->tz,
587 full_time += UNIX_EPOCH_START * SEC_PER_DAY;
588 full_time *= USEC_PER_SECOND;
591 datetime->days = full_time / USEC_PER_DAY;
592 datetime->usec = full_time % USEC_PER_DAY;
594 /* maybe daylight time caused us to shift to a different day,
595 * but it definitely didn't push us into a different year */
600 g_date_time_replace_days (GDateTime *datetime,
605 new = g_date_time_alloc (datetime->tz);
606 new->interval = datetime->interval;
607 new->usec = datetime->usec;
610 if (!g_date_time_deal_with_date_change (new))
612 g_date_time_unref (new);
619 /* now/unix/timeval Constructors {{{1 */
622 * g_date_time_new_from_timeval:
626 * Creates a #GDateTime corresponding to the given #GTimeVal @tv in the
627 * given time zone @tz.
629 * The time contained in a #GTimeVal is always stored in the form of
630 * seconds elapsed since 1970-01-01 00:00:00 UTC, regardless of the
633 * This call can fail (returning %NULL) if @tv represents a time outside
634 * of the supported range of #GDateTime.
636 * You should release the return value by calling g_date_time_unref()
637 * when you are done with it.
639 * Returns: a new #GDateTime, or %NULL
644 g_date_time_new_from_timeval (GTimeZone *tz,
647 return g_date_time_from_instant (tz, tv->tv_usec +
648 UNIX_TO_INSTANT (tv->tv_sec));
652 * g_date_time_new_from_unix:
656 * Creates a #GDateTime corresponding to the given Unix time @t in the
657 * given time zone @tz.
659 * Unix time is the number of seconds that have elapsed since 1970-01-01
660 * 00:00:00 UTC, regardless of the time zone given.
662 * This call can fail (returning %NULL) if @t represents a time outside
663 * of the supported range of #GDateTime.
665 * You should release the return value by calling g_date_time_unref()
666 * when you are done with it.
668 * Returns: a new #GDateTime, or %NULL
673 g_date_time_new_from_unix (GTimeZone *tz,
676 return g_date_time_from_instant (tz, UNIX_TO_INSTANT (secs));
680 * g_date_time_new_now:
683 * Creates a #GDateTime corresponding to this exact instant in the given
684 * time zone @tz. The time is as accurate as the system allows, to a
685 * maximum accuracy of 1 microsecond.
687 * This function will always succeed unless the system clock is set to
688 * truly insane values (or unless GLib is still being used after the
691 * You should release the return value by calling g_date_time_unref()
692 * when you are done with it.
694 * Returns: a new #GDateTime, or %NULL
699 g_date_time_new_now (GTimeZone *tz)
703 g_get_current_time (&tv);
705 return g_date_time_new_from_timeval (tz, &tv);
709 * g_date_time_new_now_local:
711 * Creates a #GDateTime corresponding to this exact instant in the local
714 * This is equivalent to calling g_date_time_new_now() with the time
715 * zone returned by g_time_zone_new_local().
717 * Returns: a new #GDateTime, or %NULL
722 g_date_time_new_now_local (void)
727 local = g_time_zone_new_local ();
728 datetime = g_date_time_new_now (local);
729 g_time_zone_unref (local);
735 * g_date_time_new_now_utc:
737 * Creates a #GDateTime corresponding to this exact instant in UTC.
739 * This is equivalent to calling g_date_time_new_now() with the time
740 * zone returned by g_time_zone_new_utc().
742 * Returns: a new #GDateTime, or %NULL
747 g_date_time_new_now_utc (void)
752 utc = g_time_zone_new_utc ();
753 datetime = g_date_time_new_now (utc);
754 g_time_zone_unref (utc);
760 * g_date_time_new_from_unix_local:
763 * Creates a #GDateTime corresponding to the given Unix time @t in the
766 * Unix time is the number of seconds that have elapsed since 1970-01-01
767 * 00:00:00 UTC, regardless of the local time offset.
769 * This call can fail (returning %NULL) if @t represents a time outside
770 * of the supported range of #GDateTime.
772 * You should release the return value by calling g_date_time_unref()
773 * when you are done with it.
775 * Returns: a new #GDateTime, or %NULL
780 g_date_time_new_from_unix_local (gint64 t)
785 local = g_time_zone_new_local ();
786 datetime = g_date_time_new_from_unix (local, t);
787 g_time_zone_unref (local);
793 * g_date_time_new_from_unix_utc:
796 * Creates a #GDateTime corresponding to the given Unix time @t in UTC.
798 * Unix time is the number of seconds that have elapsed since 1970-01-01
801 * This call can fail (returning %NULL) if @t represents a time outside
802 * of the supported range of #GDateTime.
804 * You should release the return value by calling g_date_time_unref()
805 * when you are done with it.
807 * Returns: a new #GDateTime, or %NULL
812 g_date_time_new_from_unix_utc (gint64 t)
817 utc = g_time_zone_new_utc ();
818 datetime = g_date_time_new_from_unix (utc, t);
819 g_time_zone_unref (utc);
825 * g_date_time_new_from_timeval_local:
828 * Creates a #GDateTime corresponding to the given #GTimeVal @tv in the
831 * The time contained in a #GTimeVal is always stored in the form of
832 * seconds elapsed since 1970-01-01 00:00:00 UTC, regardless of the
835 * This call can fail (returning %NULL) if @tv represents a time outside
836 * of the supported range of #GDateTime.
838 * You should release the return value by calling g_date_time_unref()
839 * when you are done with it.
841 * Returns: a new #GDateTime, or %NULL
846 g_date_time_new_from_timeval_local (const GTimeVal *tv)
851 local = g_time_zone_new_local ();
852 datetime = g_date_time_new_from_timeval (local, tv);
853 g_time_zone_unref (local);
859 * g_date_time_new_from_timeval_utc:
862 * Creates a #GDateTime corresponding to the given #GTimeVal @tv in UTC.
864 * The time contained in a #GTimeVal is always stored in the form of
865 * seconds elapsed since 1970-01-01 00:00:00 UTC.
867 * This call can fail (returning %NULL) if @tv represents a time outside
868 * of the supported range of #GDateTime.
870 * You should release the return value by calling g_date_time_unref()
871 * when you are done with it.
873 * Returns: a new #GDateTime, or %NULL
878 g_date_time_new_from_timeval_utc (const GTimeVal *tv)
883 utc = g_time_zone_new_utc ();
884 datetime = g_date_time_new_from_timeval (utc, tv);
885 g_time_zone_unref (utc);
890 /* full new functions {{{1 */
895 * @year: the year component of the date
896 * @month: the month component of the date
897 * @day: the day component of the date
898 * @hour: the hour component of the date
899 * @minute: the minute component of the date
900 * @seconds: the number of seconds past the minute
902 * Creates a new #GDateTime corresponding to the given date and time in
905 * The @year must be between 1 and 9999, @month between 1 and 12 and @day
906 * between 1 and 28, 29, 30 or 31 depending on the month and the year.
908 * @hour must be between 0 and 23 and @minute must be between 0 and 59.
910 * @seconds must be at least 0.0 and must be strictly less than 60.0.
911 * It will be rounded down to the nearest microsecond.
913 * If the given time is not representable in the given time zone (for
914 * example, 02:30 on March 14th 2010 in Toronto, due to daylight savings
915 * time) then the time will be rounded up to the nearest existing time
916 * (in this case, 03:00). If this matters to you then you should verify
917 * the return value for containing the same as the numbers you gave.
919 * In the case that the given time is ambiguous in the given time zone
920 * (for example, 01:30 on November 7th 2010 in Toronto, due to daylight
921 * savings time) then the time falling within standard (ie:
922 * non-daylight) time is taken.
924 * It not considered a programmer error for the values to this function
925 * to be out of range, but in the case that they are, the function will
928 * You should release the return value by calling g_date_time_unref()
929 * when you are done with it.
931 * Returns: a new #GDateTime, or %NULL
936 g_date_time_new (GTimeZone *tz,
947 g_return_val_if_fail (tz != NULL, NULL);
949 if (year < 1 || year > 9999 ||
950 month < 1 || month > 12 ||
951 day < 1 || day > 31 ||
952 hour < 0 || hour > 23 ||
953 minute < 0 || minute > 59 ||
954 seconds < 0.0 || seconds >= 60.0)
957 datetime = g_date_time_alloc (tz);
958 datetime->days = ymd_to_days (year, month, day);
959 datetime->usec = (hour * USEC_PER_HOUR)
960 + (minute * USEC_PER_MINUTE)
961 + (gint64) (seconds * USEC_PER_SECOND);
963 full_time = SEC_PER_DAY *
964 (ymd_to_days (year, month, day) - UNIX_EPOCH_START) +
965 SECS_PER_HOUR * hour +
966 SECS_PER_MINUTE * minute +
969 datetime->interval = g_time_zone_adjust_time (datetime->tz,
970 G_TIME_TYPE_STANDARD,
973 full_time += UNIX_EPOCH_START * SEC_PER_DAY;
974 datetime->days = full_time / SEC_PER_DAY;
975 datetime->usec = (full_time % SEC_PER_DAY) * USEC_PER_SECOND;
976 datetime->usec += ((int) (seconds * USEC_PER_SECOND)) % USEC_PER_SECOND;
982 * g_date_time_new_local:
983 * @year: the year component of the date
984 * @month: the month component of the date
985 * @day: the day component of the date
986 * @hour: the hour component of the date
987 * @minute: the minute component of the date
988 * @seconds: the number of seconds past the minute
990 * Creates a new #GDateTime corresponding to the given date and time in
991 * the local time zone.
993 * This call is equivalent to calling g_date_time_new() with the time
994 * zone returned by g_time_zone_new_local().
996 * Returns: a #GDateTime, or %NULL
1001 g_date_time_new_local (gint year,
1008 GDateTime *datetime;
1011 local = g_time_zone_new_local ();
1012 datetime = g_date_time_new (local, year, month, day, hour, minute, seconds);
1013 g_time_zone_unref (local);
1019 * g_date_time_new_utc:
1020 * @year: the year component of the date
1021 * @month: the month component of the date
1022 * @day: the day component of the date
1023 * @hour: the hour component of the date
1024 * @minute: the minute component of the date
1025 * @seconds: the number of seconds past the minute
1027 * Creates a new #GDateTime corresponding to the given date and time in
1030 * This call is equivalent to calling g_date_time_new() with the time
1031 * zone returned by g_time_zone_new_utc().
1033 * Returns: a #GDateTime, or %NULL
1038 g_date_time_new_utc (gint year,
1045 GDateTime *datetime;
1048 utc = g_time_zone_new_utc ();
1049 datetime = g_date_time_new (utc, year, month, day, hour, minute, seconds);
1050 g_time_zone_unref (utc);
1059 * @datetime: a #GDateTime
1060 * @timespan: a #GTimeSpan
1062 * Creates a copy of @datetime and adds the specified timespan to the copy.
1064 * Returns: the newly created #GDateTime which should be freed with
1065 * g_date_time_unref().
1070 g_date_time_add (GDateTime *datetime,
1073 return g_date_time_from_instant (datetime->tz, timespan +
1074 g_date_time_to_instant (datetime));
1078 * g_date_time_add_years:
1079 * @datetime: a #GDateTime
1080 * @years: the number of years
1082 * Creates a copy of @datetime and adds the specified number of years to the
1083 * copy. Add negative values to subtract years.
1085 * Returns: the newly created #GDateTime which should be freed with
1086 * g_date_time_unref().
1091 g_date_time_add_years (GDateTime *datetime,
1094 gint year, month, day;
1096 g_return_val_if_fail (datetime != NULL, NULL);
1098 if (years < -10000 || years > 10000)
1101 g_date_time_get_ymd (datetime, &year, &month, &day);
1104 /* only possible issue is if we've entered a year with no February 29
1106 if (month == 2 && day == 29 && !GREGORIAN_LEAP (year))
1109 return g_date_time_replace_days (datetime, ymd_to_days (year, month, day));
1113 * g_date_time_add_months:
1114 * @datetime: a #GDateTime
1115 * @months: the number of months
1117 * Creates a copy of @datetime and adds the specified number of months to the
1118 * copy. Add negative values to subtract months.
1120 * Returns: the newly created #GDateTime which should be freed with
1121 * g_date_time_unref().
1126 g_date_time_add_months (GDateTime *datetime,
1129 gint year, month, day;
1131 g_return_val_if_fail (datetime != NULL, NULL);
1132 g_date_time_get_ymd (datetime, &year, &month, &day);
1134 if (months < -120000 || months > 120000)
1137 year += months / 12;
1138 month += months % 12;
1144 else if (month > 12)
1150 day = MIN (day, days_in_months[GREGORIAN_LEAP (year)][month]);
1152 return g_date_time_replace_days (datetime, ymd_to_days (year, month, day));
1156 * g_date_time_add_weeks:
1157 * @datetime: a #GDateTime
1158 * @weeks: the number of weeks
1160 * Creates a copy of @datetime and adds the specified number of weeks to the
1161 * copy. Add negative values to subtract weeks.
1163 * Returns: the newly created #GDateTime which should be freed with
1164 * g_date_time_unref().
1169 g_date_time_add_weeks (GDateTime *datetime,
1172 g_return_val_if_fail (datetime != NULL, NULL);
1174 return g_date_time_add_days (datetime, weeks * 7);
1178 * g_date_time_add_days:
1179 * @datetime: a #GDateTime
1180 * @days: the number of days
1182 * Creates a copy of @datetime and adds the specified number of days to the
1183 * copy. Add negative values to subtract days.
1185 * Returns: the newly created #GDateTime which should be freed with
1186 * g_date_time_unref().
1191 g_date_time_add_days (GDateTime *datetime,
1194 g_return_val_if_fail (datetime != NULL, NULL);
1196 if (days < -3660000 || days > 3660000)
1199 return g_date_time_replace_days (datetime, datetime->days + days);
1203 * g_date_time_add_hours:
1204 * @datetime: a #GDateTime
1205 * @hours: the number of hours to add
1207 * Creates a copy of @datetime and adds the specified number of hours.
1208 * Add negative values to subtract hours.
1210 * Returns: the newly created #GDateTime which should be freed with
1211 * g_date_time_unref().
1216 g_date_time_add_hours (GDateTime *datetime,
1219 return g_date_time_add (datetime, hours * USEC_PER_HOUR);
1223 * g_date_time_add_minutes:
1224 * @datetime: a #GDateTime
1225 * @minutes: the number of minutes to add
1227 * Creates a copy of @datetime adding the specified number of minutes.
1228 * Add negative values to subtract minutes.
1230 * Returns: the newly created #GDateTime which should be freed with
1231 * g_date_time_unref().
1236 g_date_time_add_minutes (GDateTime *datetime,
1239 return g_date_time_add (datetime, minutes * USEC_PER_MINUTE);
1244 * g_date_time_add_seconds:
1245 * @datetime: a #GDateTime
1246 * @seconds: the number of seconds to add
1248 * Creates a copy of @datetime and adds the specified number of seconds.
1249 * Add negative values to subtract seconds.
1251 * Returns: the newly created #GDateTime which should be freed with
1252 * g_date_time_unref().
1257 g_date_time_add_seconds (GDateTime *datetime,
1260 return g_date_time_add (datetime, seconds * USEC_PER_SECOND);
1264 * g_date_time_add_full:
1265 * @datetime: a #GDateTime
1266 * @years: the number of years to add
1267 * @months: the number of months to add
1268 * @days: the number of days to add
1269 * @hours: the number of hours to add
1270 * @minutes: the number of minutes to add
1271 * @seconds: the number of seconds to add
1273 * Creates a new #GDateTime adding the specified values to the current date and
1274 * time in @datetime. Add negative values to subtract.
1276 * Returns: the newly created #GDateTime that should be freed with
1277 * g_date_time_unref().
1282 g_date_time_add_full (GDateTime *datetime,
1290 gint year, month, day;
1295 g_return_val_if_fail (datetime != NULL, NULL);
1296 g_date_time_get_ymd (datetime, &year, &month, &day);
1298 months += years * 12;
1300 if (months < -120000 || months > 120000)
1303 if (days < -3660000 || days > 3660000)
1306 year += months / 12;
1307 month += months % 12;
1313 else if (month > 12)
1319 day = MIN (day, days_in_months[GREGORIAN_LEAP (year)][month]);
1321 /* full_time is now in unix (local) time */
1322 full_time = datetime->usec / USEC_PER_SECOND + SEC_PER_DAY *
1323 (ymd_to_days (year, month, day) + days - UNIX_EPOCH_START);
1325 interval = g_time_zone_adjust_time (datetime->tz,
1326 g_time_zone_is_dst (datetime->tz,
1327 datetime->interval),
1330 /* move to UTC unix time */
1331 full_time -= g_time_zone_get_offset (datetime->tz, interval);
1333 /* convert back to an instant, add back fractional seconds */
1334 full_time += UNIX_EPOCH_START * SEC_PER_DAY;
1335 full_time = full_time * USEC_PER_SECOND +
1336 datetime->usec % USEC_PER_SECOND;
1338 /* do the actual addition now */
1339 full_time += (hours * USEC_PER_HOUR) +
1340 (minutes * USEC_PER_MINUTE) +
1341 (gint64) (seconds * USEC_PER_SECOND);
1343 /* find the new interval */
1344 interval = g_time_zone_find_interval (datetime->tz,
1345 G_TIME_TYPE_UNIVERSAL,
1346 INSTANT_TO_UNIX (full_time));
1348 /* convert back into local time */
1349 full_time += USEC_PER_SECOND *
1350 g_time_zone_get_offset (datetime->tz, interval);
1352 /* split into days and usec of a new datetime */
1353 new = g_date_time_alloc (datetime->tz);
1354 new->interval = interval;
1355 new->days = full_time / USEC_PER_DAY;
1356 new->usec = full_time % USEC_PER_DAY;
1363 /* Compare, difference, hash, equal {{{1 */
1365 * g_date_time_compare:
1366 * @dt1: first #GDateTime to compare
1367 * @dt2: second #GDateTime to compare
1369 * A comparison function for #GDateTimes that is suitable
1370 * as a #GCompareFunc. Both #GDateTimes must be non-%NULL.
1372 * Returns: -1, 0 or 1 if @dt1 is less than, equal to or greater
1378 g_date_time_compare (gconstpointer dt1,
1383 difference = g_date_time_difference ((GDateTime *) dt1, (GDateTime *) dt2);
1388 else if (difference > 0)
1396 * g_date_time_difference:
1397 * @end: a #GDateTime
1398 * @begin: a #GDateTime
1400 * Calculates the difference in time between @end and @begin. The
1401 * #GTimeSpan that is returned is effectively @end - @begin (ie:
1402 * positive if the first parameter is larger).
1404 * Returns: the difference between the two #GDateTime, as a time
1405 * span expressed in microseconds.
1410 g_date_time_difference (GDateTime *end,
1413 g_return_val_if_fail (begin != NULL, 0);
1414 g_return_val_if_fail (end != NULL, 0);
1416 return g_date_time_to_instant (end) -
1417 g_date_time_to_instant (begin);
1422 * @datetime: a #GDateTime
1424 * Hashes @datetime into a #guint, suitable for use within #GHashTable.
1426 * Returns: a #guint containing the hash
1431 g_date_time_hash (gconstpointer datetime)
1433 return g_date_time_to_instant ((GDateTime *) datetime);
1437 * g_date_time_equal:
1438 * @dt1: a #GDateTime
1439 * @dt2: a #GDateTime
1441 * Checks to see if @dt1 and @dt2 are equal.
1443 * Equal here means that they represent the same moment after converting
1444 * them to the same time zone.
1446 * Returns: %TRUE if @dt1 and @dt2 are equal
1451 g_date_time_equal (gconstpointer dt1,
1454 return g_date_time_difference ((GDateTime *) dt1, (GDateTime *) dt2) == 0;
1457 /* Year, Month, Day Getters {{{1 */
1459 * g_date_time_get_ymd:
1460 * @datetime: a #GDateTime.
1461 * @year: (out) (allow-none): the return location for the gregorian year, or %NULL.
1462 * @month: (out) (allow-none): the return location for the month of the year, or %NULL.
1463 * @day: (out) (allow-none): the return location for the day of the month, or %NULL.
1465 * Retrieves the Gregorian day, month, and year of a given #GDateTime.
1470 g_date_time_get_ymd (GDateTime *datetime,
1478 gint remaining_days;
1485 g_return_if_fail (datetime != NULL);
1487 remaining_days = datetime->days;
1490 * We need to convert an offset in days to its year/month/day representation.
1491 * Leap years makes this a little trickier than it should be, so we use
1492 * 400, 100 and 4 years cycles here to get to the correct year.
1495 /* Our days offset starts sets 0001-01-01 as day 1, if it was day 0 our
1496 * math would be simpler, so let's do it */
1499 the_year = (remaining_days / DAYS_IN_400YEARS) * 400 + 1;
1500 remaining_days = remaining_days % DAYS_IN_400YEARS;
1502 y100_cycles = remaining_days / DAYS_IN_100YEARS;
1503 remaining_days = remaining_days % DAYS_IN_100YEARS;
1504 the_year += y100_cycles * 100;
1506 y4_cycles = remaining_days / DAYS_IN_4YEARS;
1507 remaining_days = remaining_days % DAYS_IN_4YEARS;
1508 the_year += y4_cycles * 4;
1510 y1_cycles = remaining_days / 365;
1511 the_year += y1_cycles;
1512 remaining_days = remaining_days % 365;
1514 if (y1_cycles == 4 || y100_cycles == 4) {
1515 g_assert (remaining_days == 0);
1517 /* special case that indicates that the date is actually one year before,
1518 * in the 31th of December */
1525 /* now get the month and the day */
1526 leap = y1_cycles == 3 && (y4_cycles != 24 || y100_cycles == 3);
1528 g_assert (leap == GREGORIAN_LEAP(the_year));
1530 the_month = (remaining_days + 50) >> 5;
1531 preceding = (days_in_year[0][the_month - 1] + (the_month > 2 && leap));
1532 if (preceding > remaining_days)
1534 /* estimate is too large */
1536 preceding -= leap ? days_in_months[1][the_month]
1537 : days_in_months[0][the_month];
1540 remaining_days -= preceding;
1541 g_assert(0 <= remaining_days);
1543 the_day = remaining_days + 1;
1555 * g_date_time_get_year:
1556 * @datetime: A #GDateTime
1558 * Retrieves the year represented by @datetime in the Gregorian calendar.
1560 * Returns: the year represented by @datetime
1565 g_date_time_get_year (GDateTime *datetime)
1569 g_return_val_if_fail (datetime != NULL, 0);
1571 g_date_time_get_ymd (datetime, &year, NULL, NULL);
1577 * g_date_time_get_month:
1578 * @datetime: a #GDateTime
1580 * Retrieves the month of the year represented by @datetime in the Gregorian
1583 * Returns: the month represented by @datetime
1588 g_date_time_get_month (GDateTime *datetime)
1592 g_return_val_if_fail (datetime != NULL, 0);
1594 g_date_time_get_ymd (datetime, NULL, &month, NULL);
1600 * g_date_time_get_day_of_month:
1601 * @datetime: a #GDateTime
1603 * Retrieves the day of the month represented by @datetime in the gregorian
1606 * Returns: the day of the month
1611 g_date_time_get_day_of_month (GDateTime *datetime)
1615 const guint16 *days;
1618 g_return_val_if_fail (datetime != NULL, 0);
1620 days = days_in_year[GREGORIAN_LEAP (g_date_time_get_year (datetime)) ? 1 : 0];
1621 g_date_time_get_week_number (datetime, NULL, NULL, &day_of_year);
1623 for (i = 1; i <= 12; i++)
1625 if (days [i] >= day_of_year)
1626 return day_of_year - last;
1630 g_warn_if_reached ();
1634 /* Week of year / day of week getters {{{1 */
1636 * g_date_time_get_week_numbering_year:
1637 * @datetime: a #GDateTime
1639 * Returns the ISO 8601 week-numbering year in which the week containing
1642 * This function, taken together with g_date_time_get_week_of_year() and
1643 * g_date_time_get_day_of_week() can be used to determine the full ISO
1644 * week date on which @datetime falls.
1646 * This is usually equal to the normal Gregorian year (as returned by
1647 * g_date_time_get_year()), except as detailed below:
1649 * For Thursday, the week-numbering year is always equal to the usual
1650 * calendar year. For other days, the number is such that every day
1651 * within a complete week (Monday to Sunday) is contained within the
1652 * same week-numbering year.
1654 * For Monday, Tuesday and Wednesday occurring near the end of the year,
1655 * this may mean that the week-numbering year is one greater than the
1656 * calendar year (so that these days have the same week-numbering year
1657 * as the Thursday occurring early in the next year).
1659 * For Friday, Saturaday and Sunday occurring near the start of the year,
1660 * this may mean that the week-numbering year is one less than the
1661 * calendar year (so that these days have the same week-numbering year
1662 * as the Thursday occurring late in the previous year).
1664 * An equivalent description is that the week-numbering year is equal to
1665 * the calendar year containing the majority of the days in the current
1666 * week (Monday to Sunday).
1668 * Note that January 1 0001 in the proleptic Gregorian calendar is a
1669 * Monday, so this function never returns 0.
1671 * Returns: the ISO 8601 week-numbering year for @datetime
1676 g_date_time_get_week_numbering_year (GDateTime *datetime)
1678 gint year, month, day, weekday;
1680 g_date_time_get_ymd (datetime, &year, &month, &day);
1681 weekday = g_date_time_get_day_of_week (datetime);
1683 /* January 1, 2, 3 might be in the previous year if they occur after
1686 * Jan 1: Friday, Saturday, Sunday => day 1: weekday 5, 6, 7
1687 * Jan 2: Saturday, Sunday => day 2: weekday 6, 7
1688 * Jan 3: Sunday => day 3: weekday 7
1690 * So we have a special case if (day - weekday) <= -4
1692 if (month == 1 && (day - weekday) <= -4)
1695 /* December 29, 30, 31 might be in the next year if they occur before
1698 * Dec 31: Monday, Tuesday, Wednesday => day 31: weekday 1, 2, 3
1699 * Dec 30: Monday, Tuesday => day 30: weekday 1, 2
1700 * Dec 29: Monday => day 29: weekday 1
1702 * So we have a special case if (day - weekday) >= 28
1704 else if (month == 12 && (day - weekday) >= 28)
1712 * g_date_time_get_week_of_year:
1713 * @datetime: a #GDateTime
1715 * Returns the ISO 8601 week number for the week containing @datetime.
1716 * The ISO 8601 week number is the same for every day of the week (from
1717 * Moday through Sunday). That can produce some unusual results
1718 * (described below).
1720 * The first week of the year is week 1. This is the week that contains
1721 * the first Thursday of the year. Equivalently, this is the first week
1722 * that has more than 4 of its days falling within the calendar year.
1724 * The value 0 is never returned by this function. Days contained
1725 * within a year but occurring before the first ISO 8601 week of that
1726 * year are considered as being contained in the last week of the
1727 * previous year. Similarly, the final days of a calendar year may be
1728 * considered as being part of the first ISO 8601 week of the next year
1729 * if 4 or more days of that week are contained within the new year.
1731 * Returns: the ISO 8601 week number for @datetime.
1736 g_date_time_get_week_of_year (GDateTime *datetime)
1740 g_return_val_if_fail (datetime != NULL, 0);
1742 g_date_time_get_week_number (datetime, &weeknum, NULL, NULL);
1748 * g_date_time_get_day_of_week:
1749 * @datetime: a #GDateTime
1751 * Retrieves the ISO 8601 day of the week on which @datetime falls (1 is
1752 * Monday, 2 is Tuesday... 7 is Sunday).
1754 * Returns: the day of the week
1759 g_date_time_get_day_of_week (GDateTime *datetime)
1761 g_return_val_if_fail (datetime != NULL, 0);
1763 return (datetime->days - 1) % 7 + 1;
1766 /* Day of year getter {{{1 */
1768 * g_date_time_get_day_of_year:
1769 * @datetime: a #GDateTime
1771 * Retrieves the day of the year represented by @datetime in the Gregorian
1774 * Returns: the day of the year
1779 g_date_time_get_day_of_year (GDateTime *datetime)
1783 g_return_val_if_fail (datetime != NULL, 0);
1785 g_date_time_get_week_number (datetime, NULL, NULL, &doy);
1789 /* Time component getters {{{1 */
1792 * g_date_time_get_hour:
1793 * @datetime: a #GDateTime
1795 * Retrieves the hour of the day represented by @datetime
1797 * Returns: the hour of the day
1802 g_date_time_get_hour (GDateTime *datetime)
1804 g_return_val_if_fail (datetime != NULL, 0);
1806 return (datetime->usec / USEC_PER_HOUR);
1810 * g_date_time_get_minute:
1811 * @datetime: a #GDateTime
1813 * Retrieves the minute of the hour represented by @datetime
1815 * Returns: the minute of the hour
1820 g_date_time_get_minute (GDateTime *datetime)
1822 g_return_val_if_fail (datetime != NULL, 0);
1824 return (datetime->usec % USEC_PER_HOUR) / USEC_PER_MINUTE;
1828 * g_date_time_get_second:
1829 * @datetime: a #GDateTime
1831 * Retrieves the second of the minute represented by @datetime
1833 * Returns: the second represented by @datetime
1838 g_date_time_get_second (GDateTime *datetime)
1840 g_return_val_if_fail (datetime != NULL, 0);
1842 return (datetime->usec % USEC_PER_MINUTE) / USEC_PER_SECOND;
1846 * g_date_time_get_microsecond:
1847 * @datetime: a #GDateTime
1849 * Retrieves the microsecond of the date represented by @datetime
1851 * Returns: the microsecond of the second
1856 g_date_time_get_microsecond (GDateTime *datetime)
1858 g_return_val_if_fail (datetime != NULL, 0);
1860 return (datetime->usec % USEC_PER_SECOND);
1864 * g_date_time_get_seconds:
1865 * @datetime: a #GDateTime
1867 * Retrieves the number of seconds since the start of the last minute,
1868 * including the fractional part.
1870 * Returns: the number of seconds
1875 g_date_time_get_seconds (GDateTime *datetime)
1877 g_return_val_if_fail (datetime != NULL, 0);
1879 return (datetime->usec % USEC_PER_MINUTE) / 1000000.0;
1882 /* Exporters {{{1 */
1884 * g_date_time_to_unix:
1885 * @datetime: a #GDateTime
1887 * Gives the Unix time corresponding to @datetime, rounding down to the
1890 * Unix time is the number of seconds that have elapsed since 1970-01-01
1891 * 00:00:00 UTC, regardless of the time zone associated with @datetime.
1893 * Returns: the Unix time corresponding to @datetime
1898 g_date_time_to_unix (GDateTime *datetime)
1900 return INSTANT_TO_UNIX (g_date_time_to_instant (datetime));
1904 * g_date_time_to_timeval:
1905 * @datetime: a #GDateTime
1906 * @tv: a #GTimeVal to modify
1908 * Stores the instant in time that @datetime represents into @tv.
1910 * The time contained in a #GTimeVal is always stored in the form of
1911 * seconds elapsed since 1970-01-01 00:00:00 UTC, regardless of the time
1912 * zone associated with @datetime.
1914 * On systems where 'long' is 32bit (ie: all 32bit systems and all
1915 * Windows systems), a #GTimeVal is incapable of storing the entire
1916 * range of values that #GDateTime is capable of expressing. On those
1917 * systems, this function returns %FALSE to indicate that the time is
1920 * On systems where 'long' is 64bit, this function never fails.
1922 * Returns: %TRUE if successful, else %FALSE
1927 g_date_time_to_timeval (GDateTime *datetime,
1930 tv->tv_sec = INSTANT_TO_UNIX (g_date_time_to_instant (datetime));
1931 tv->tv_usec = datetime->usec % USEC_PER_SECOND;
1936 /* Timezone queries {{{1 */
1938 * g_date_time_get_utc_offset:
1939 * @datetime: a #GDateTime
1941 * Determines the offset to UTC in effect at the time and in the time
1942 * zone of @datetime.
1944 * The offset is the number of microseconds that you add to UTC time to
1945 * arrive at local time for the time zone (ie: negative numbers for time
1946 * zones west of GMT, positive numbers for east).
1948 * If @datetime represents UTC time, then the offset is always zero.
1950 * Returns: the number of microseconds that should be added to UTC to
1951 * get the local time
1956 g_date_time_get_utc_offset (GDateTime *datetime)
1960 g_return_val_if_fail (datetime != NULL, 0);
1962 offset = g_time_zone_get_offset (datetime->tz, datetime->interval);
1964 return (gint64) offset * USEC_PER_SECOND;
1968 * g_date_time_get_timezone_abbreviation:
1969 * @datetime: a #GDateTime
1971 * Determines the time zone abbreviation to be used at the time and in
1972 * the time zone of @datetime.
1974 * For example, in Toronto this is currently "EST" during the winter
1975 * months and "EDT" during the summer months when daylight savings
1976 * time is in effect.
1978 * Returns: (transfer none): the time zone abbreviation. The returned
1979 * string is owned by the #GDateTime and it should not be
1985 g_date_time_get_timezone_abbreviation (GDateTime *datetime)
1987 g_return_val_if_fail (datetime != NULL, NULL);
1989 return g_time_zone_get_abbreviation (datetime->tz, datetime->interval);
1993 * g_date_time_is_daylight_savings:
1994 * @datetime: a #GDateTime
1996 * Determines if daylight savings time is in effect at the time and in
1997 * the time zone of @datetime.
1999 * Returns: %TRUE if daylight savings time is in effect
2004 g_date_time_is_daylight_savings (GDateTime *datetime)
2006 g_return_val_if_fail (datetime != NULL, FALSE);
2008 return g_time_zone_is_dst (datetime->tz, datetime->interval);
2011 /* Timezone convert {{{1 */
2013 * g_date_time_to_timezone:
2014 * @datetime: a #GDateTime
2015 * @tz: the new #GTimeZone
2017 * Create a new #GDateTime corresponding to the same instant in time as
2018 * @datetime, but in the time zone @tz.
2020 * This call can fail in the case that the time goes out of bounds. For
2021 * example, converting 0001-01-01 00:00:00 UTC to a time zone west of
2022 * Greenwich will fail (due to the year 0 being out of range).
2024 * You should release the return value by calling g_date_time_unref()
2025 * when you are done with it.
2027 * Returns: a new #GDateTime, or %NULL
2032 g_date_time_to_timezone (GDateTime *datetime,
2035 return g_date_time_from_instant (tz, g_date_time_to_instant (datetime));
2039 * g_date_time_to_local:
2040 * @datetime: a #GDateTime
2042 * Creates a new #GDateTime corresponding to the same instant in time as
2043 * @datetime, but in the local time zone.
2045 * This call is equivalent to calling g_date_time_to_timezone() with the
2046 * time zone returned by g_time_zone_new_local().
2048 * Returns: the newly created #GDateTime
2053 g_date_time_to_local (GDateTime *datetime)
2058 local = g_time_zone_new_local ();
2059 new = g_date_time_to_timezone (datetime, local);
2060 g_time_zone_unref (local);
2066 * g_date_time_to_utc:
2067 * @datetime: a #GDateTime
2069 * Creates a new #GDateTime corresponding to the same instant in time as
2070 * @datetime, but in UTC.
2072 * This call is equivalent to calling g_date_time_to_timezone() with the
2073 * time zone returned by g_time_zone_new_utc().
2075 * Returns: the newly created #GDateTime
2080 g_date_time_to_utc (GDateTime *datetime)
2085 utc = g_time_zone_new_utc ();
2086 new = g_date_time_to_timezone (datetime, utc);
2087 g_time_zone_unref (utc);
2095 format_z (GString *outstr,
2103 hours = offset / 3600;
2104 minutes = ABS (offset) / 60 % 60;
2105 seconds = ABS (offset) % 60;
2110 g_string_append_printf (outstr, "%+03d%02d",
2116 g_string_append_printf (outstr, "%+03d:%02d",
2122 g_string_append_printf (outstr, "%+03d:%02d:%02d",
2129 g_string_append_printf (outstr, "%+03d", hours);
2131 if (minutes != 0 || seconds != 0)
2133 g_string_append_printf (outstr, ":%02d", minutes);
2136 g_string_append_printf (outstr, ":%02d", seconds);
2148 format_number (GString *str,
2149 gboolean use_alt_digits,
2154 const gchar *ascii_digits[10] = {
2155 "0", "1", "2", "3", "4", "5", "6", "7", "8", "9"
2157 const gchar **digits = ascii_digits;
2158 const gchar *tmp[10];
2161 g_return_if_fail (width <= 10);
2163 #ifdef HAVE_LANGINFO_OUTDIGIT
2166 static const gchar *alt_digits[10];
2167 static gsize initialised;
2168 /* 2^32 has 10 digits */
2170 if G_UNLIKELY (g_once_init_enter (&initialised))
2172 #define DO_DIGIT(n) \
2173 alt_digits[n] = nl_langinfo (_NL_CTYPE_OUTDIGIT## n ##_MB)
2174 DO_DIGIT(0); DO_DIGIT(1); DO_DIGIT(2); DO_DIGIT(3); DO_DIGIT(4);
2175 DO_DIGIT(5); DO_DIGIT(6); DO_DIGIT(7); DO_DIGIT(8); DO_DIGIT(9);
2177 g_once_init_leave (&initialised, TRUE);
2180 digits = alt_digits;
2182 #endif /* HAVE_LANGINFO_OUTDIGIT */
2186 tmp[i++] = digits[number % 10];
2191 while (pad && i < width)
2192 tmp[i++] = *pad == '0' ? digits[0] : pad;
2194 /* should really be impossible */
2198 g_string_append (str, tmp[--i]);
2201 static gboolean g_date_time_format_locale (GDateTime *datetime,
2202 const gchar *format,
2204 gboolean locale_is_utf8);
2206 /* g_date_time_format() subroutine that takes a locale-encoded format
2207 * string and produces a locale-encoded date/time string.
2210 g_date_time_locale_format_locale (GDateTime *datetime,
2211 const gchar *format,
2213 gboolean locale_is_utf8)
2219 return g_date_time_format_locale (datetime, format, outstr,
2222 utf8_format = g_locale_to_utf8 (format, -1, NULL, NULL, NULL);
2226 success = g_date_time_format_locale (datetime, utf8_format, outstr,
2228 g_free (utf8_format);
2232 /* g_date_time_format() subroutine that takes a UTF-8 format
2233 * string and produces a locale-encoded date/time string.
2236 g_date_time_format_locale (GDateTime *datetime,
2237 const gchar *format,
2239 gboolean locale_is_utf8)
2245 gboolean alt_digits = FALSE;
2246 gboolean pad_set = FALSE;
2253 len = strcspn (format, "%");
2257 g_string_append_len (outstr, format, len);
2260 tmp = g_locale_from_utf8 (format, len, NULL, NULL, NULL);
2263 g_string_append (outstr, tmp);
2272 g_assert (*format == '%');
2282 c = g_utf8_get_char (format);
2283 format = g_utf8_next_char (format);
2287 g_string_append (outstr, WEEKDAY_ABBR (datetime));
2290 g_string_append (outstr, WEEKDAY_FULL (datetime));
2293 g_string_append (outstr, MONTH_ABBR (datetime));
2296 g_string_append (outstr, MONTH_FULL (datetime));
2300 if (!g_date_time_locale_format_locale (datetime, PREFERRED_DATE_TIME_FMT,
2301 outstr, locale_is_utf8))
2306 format_number (outstr, alt_digits, pad_set ? pad : "0", 2,
2307 g_date_time_get_year (datetime) / 100);
2310 format_number (outstr, alt_digits, pad_set ? pad : "0", 2,
2311 g_date_time_get_day_of_month (datetime));
2314 format_number (outstr, alt_digits, pad_set ? pad : " ", 2,
2315 g_date_time_get_day_of_month (datetime));
2318 g_string_append_printf (outstr, "%d-%02d-%02d",
2319 g_date_time_get_year (datetime),
2320 g_date_time_get_month (datetime),
2321 g_date_time_get_day_of_month (datetime));
2324 format_number (outstr, alt_digits, pad_set ? pad : "0", 2,
2325 g_date_time_get_week_numbering_year (datetime) % 100);
2328 format_number (outstr, alt_digits, pad_set ? pad : 0, 0,
2329 g_date_time_get_week_numbering_year (datetime));
2332 g_string_append (outstr, MONTH_ABBR (datetime));
2335 format_number (outstr, alt_digits, pad_set ? pad : "0", 2,
2336 g_date_time_get_hour (datetime));
2339 format_number (outstr, alt_digits, pad_set ? pad : "0", 2,
2340 (g_date_time_get_hour (datetime) + 11) % 12 + 1);
2343 format_number (outstr, alt_digits, pad_set ? pad : "0", 3,
2344 g_date_time_get_day_of_year (datetime));
2347 format_number (outstr, alt_digits, pad_set ? pad : " ", 2,
2348 g_date_time_get_hour (datetime));
2351 format_number (outstr, alt_digits, pad_set ? pad : " ", 2,
2352 (g_date_time_get_hour (datetime) + 11) % 12 + 1);
2355 g_string_append_c (outstr, '\n');
2358 format_number (outstr, alt_digits, pad_set ? pad : "0", 2,
2359 g_date_time_get_month (datetime));
2362 format_number (outstr, alt_digits, pad_set ? pad : "0", 2,
2363 g_date_time_get_minute (datetime));
2369 ampm = (gchar *) GET_AMPM (datetime);
2370 if (!locale_is_utf8)
2372 ampm = tmp = g_locale_to_utf8 (ampm, -1, NULL, NULL, NULL);
2376 ampm = g_utf8_strup (ampm, -1);
2377 if (!locale_is_utf8)
2380 tmp = g_locale_from_utf8 (ampm, -1, NULL, NULL, NULL);
2386 g_string_append (outstr, ampm);
2390 ampm = (gchar *) GET_AMPM (datetime);
2391 if (!locale_is_utf8)
2393 ampm = tmp = g_locale_to_utf8 (ampm, -1, NULL, NULL, NULL);
2397 ampm = g_utf8_strdown (ampm, -1);
2398 if (!locale_is_utf8)
2401 tmp = g_locale_from_utf8 (ampm, -1, NULL, NULL, NULL);
2407 g_string_append (outstr, ampm);
2412 if (!g_date_time_locale_format_locale (datetime, PREFERRED_12HR_TIME_FMT,
2413 outstr, locale_is_utf8))
2418 g_string_append_printf (outstr, "%02d:%02d",
2419 g_date_time_get_hour (datetime),
2420 g_date_time_get_minute (datetime));
2423 g_string_append_printf (outstr, "%" G_GINT64_FORMAT, g_date_time_to_unix (datetime));
2426 format_number (outstr, alt_digits, pad_set ? pad : "0", 2,
2427 g_date_time_get_second (datetime));
2430 g_string_append_c (outstr, '\t');
2433 g_string_append_printf (outstr, "%02d:%02d:%02d",
2434 g_date_time_get_hour (datetime),
2435 g_date_time_get_minute (datetime),
2436 g_date_time_get_second (datetime));
2439 format_number (outstr, alt_digits, 0, 0,
2440 g_date_time_get_day_of_week (datetime));
2443 format_number (outstr, alt_digits, pad_set ? pad : "0", 2,
2444 g_date_time_get_week_of_year (datetime));
2447 format_number (outstr, alt_digits, 0, 0,
2448 g_date_time_get_day_of_week (datetime) % 7);
2452 if (!g_date_time_locale_format_locale (datetime, PREFERRED_DATE_FMT,
2453 outstr, locale_is_utf8))
2459 if (!g_date_time_locale_format_locale (datetime, PREFERRED_TIME_FMT,
2460 outstr, locale_is_utf8))
2465 format_number (outstr, alt_digits, pad_set ? pad : "0", 2,
2466 g_date_time_get_year (datetime) % 100);
2469 format_number (outstr, alt_digits, 0, 0,
2470 g_date_time_get_year (datetime));
2475 if (datetime->tz != NULL)
2476 offset = g_date_time_get_utc_offset (datetime) / USEC_PER_SECOND;
2479 if (!format_z (outstr, (int) offset, colons))
2484 tz = g_date_time_get_timezone_abbreviation (datetime);
2485 if (!locale_is_utf8)
2487 tz = tmp = g_locale_from_utf8 (tz, -1, NULL, NULL, NULL);
2491 g_string_append (outstr, tz);
2492 if (!locale_is_utf8)
2496 g_string_append_c (outstr, '%');
2511 /* Colons are only allowed before 'z' */
2512 if (*format && *format != 'z' && *format != ':')
2525 * g_date_time_format:
2526 * @datetime: A #GDateTime
2527 * @format: a valid UTF-8 string, containing the format for the
2530 * Creates a newly allocated string representing the requested @format.
2532 * The format strings understood by this function are a subset of the
2533 * strftime() format language as specified by C99. The \%D, \%U and \%W
2534 * conversions are not supported, nor is the 'E' modifier. The GNU
2535 * extensions \%k, \%l, \%s and \%P are supported, however, as are the
2536 * '0', '_' and '-' modifiers.
2538 * In contrast to strftime(), this function always produces a UTF-8
2539 * string, regardless of the current locale. Note that the rendering of
2540 * many formats is locale-dependent and may not match the strftime()
2543 * The following format specifiers are supported:
2545 * - \%a: the abbreviated weekday name according to the current locale
2546 * - \%A: the full weekday name according to the current locale
2547 * - \%b: the abbreviated month name according to the current locale
2548 * - \%B: the full month name according to the current locale
2549 * - \%c: the preferred date and time rpresentation for the current locale
2550 * - \%C: the century number (year/100) as a 2-digit integer (00-99)
2551 * - \%d: the day of the month as a decimal number (range 01 to 31)
2552 * - \%e: the day of the month as a decimal number (range 1 to 31)
2553 * - \%F: equivalent to `%Y-%m-%d` (the ISO 8601 date format)
2554 * - \%g: the last two digits of the ISO 8601 week-based year as a
2555 * decimal number (00-99). This works well with \%V and \%u.
2556 * - \%G: the ISO 8601 week-based year as a decimal number. This works
2557 * well with \%V and \%u.
2558 * - \%h: equivalent to \%b
2559 * - \%H: the hour as a decimal number using a 24-hour clock (range 00 to 23)
2560 * - \%I: the hour as a decimal number using a 12-hour clock (range 01 to 12)
2561 * - \%j: the day of the year as a decimal number (range 001 to 366)
2562 * - \%k: the hour (24-hour clock) as a decimal number (range 0 to 23);
2563 * single digits are preceded by a blank
2564 * - \%l: the hour (12-hour clock) as a decimal number (range 1 to 12);
2565 * single digits are preceded by a blank
2566 * - \%m: the month as a decimal number (range 01 to 12)
2567 * - \%M: the minute as a decimal number (range 00 to 59)
2568 * - \%p: either "AM" or "PM" according to the given time value, or the
2569 * corresponding strings for the current locale. Noon is treated as
2570 * "PM" and midnight as "AM".
2571 * - \%P: like \%p but lowercase: "am" or "pm" or a corresponding string for
2572 * the current locale
2573 * - \%r: the time in a.m. or p.m. notation
2574 * - \%R: the time in 24-hour notation (\%H:\%M)
2575 * - \%s: the number of seconds since the Epoch, that is, since 1970-01-01
2577 * - \%S: the second as a decimal number (range 00 to 60)
2578 * - \%t: a tab character
2579 * - \%T: the time in 24-hour notation with seconds (\%H:\%M:\%S)
2580 * - \%u: the ISO 8601 standard day of the week as a decimal, range 1 to 7,
2581 * Monday being 1. This works well with \%G and \%V.
2582 * - \%V: the ISO 8601 standard week number of the current year as a decimal
2583 * number, range 01 to 53, where week 1 is the first week that has at
2584 * least 4 days in the new year. See g_date_time_get_week_of_year().
2585 * This works well with \%G and \%u.
2586 * - \%w: the day of the week as a decimal, range 0 to 6, Sunday being 0.
2587 * This is not the ISO 8601 standard format -- use \%u instead.
2588 * - \%x: the preferred date representation for the current locale without
2590 * - \%X: the preferred time representation for the current locale without
2592 * - \%y: the year as a decimal number without the century
2593 * - \%Y: the year as a decimal number including the century
2594 * - \%z: the time zone as an offset from UTC (+hhmm)
2595 * - \%:z: the time zone as an offset from UTC (+hh:mm).
2596 * This is a gnulib strftime() extension. Since: 2.38
2597 * - \%::z: the time zone as an offset from UTC (+hh:mm:ss). This is a
2598 * gnulib strftime() extension. Since: 2.38
2599 * - \%:::z: the time zone as an offset from UTC, with : to necessary
2600 * precision (e.g., -04, +05:30). This is a gnulib strftime() extension. Since: 2.38
2601 * - \%Z: the time zone or name or abbreviation
2602 * - \%\%: a literal \% character
2604 * Some conversion specifications can be modified by preceding the
2605 * conversion specifier by one or more modifier characters. The
2606 * following modifiers are supported for many of the numeric
2609 * - O: Use alternative numeric symbols, if the current locale supports those.
2610 * - _: Pad a numeric result with spaces. This overrides the default padding
2611 * for the specifier.
2612 * - -: Do not pad a numeric result. This overrides the default padding
2613 * for the specifier.
2614 * - 0: Pad a numeric result with zeros. This overrides the default padding
2615 * for the specifier.
2617 * Returns: a newly allocated string formatted to the requested format
2618 * or %NULL in the case that there was an error. The string
2619 * should be freed with g_free().
2624 g_date_time_format (GDateTime *datetime,
2625 const gchar *format)
2629 gboolean locale_is_utf8 = g_get_charset (NULL);
2631 g_return_val_if_fail (datetime != NULL, NULL);
2632 g_return_val_if_fail (format != NULL, NULL);
2633 g_return_val_if_fail (g_utf8_validate (format, -1, NULL), NULL);
2635 outstr = g_string_sized_new (strlen (format) * 2);
2637 if (!g_date_time_format_locale (datetime, format, outstr, locale_is_utf8))
2639 g_string_free (outstr, TRUE);
2644 return g_string_free (outstr, FALSE);
2646 utf8 = g_locale_to_utf8 (outstr->str, outstr->len, NULL, NULL, NULL);
2647 g_string_free (outstr, TRUE);
2653 /* vim:set foldmethod=marker: */