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 License
19 * along with this library; if not, see <http://www.gnu.org/licenses/>.
21 * Authors: Christian Hergert <chris@dronelabs.com>
22 * Thiago Santos <thiago.sousa.santos@collabora.co.uk>
23 * Emmanuele Bassi <ebassi@linux.intel.com>
24 * Ryan Lortie <desrt@desrt.ca>
27 /* Algorithms within this file are based on the Calendar FAQ by
28 * Claus Tondering. It can be found at
29 * http://www.tondering.dk/claus/cal/calendar29.txt
31 * Copyright and disclaimer
32 * ------------------------
33 * This document is Copyright (C) 2008 by Claus Tondering.
34 * E-mail: claus@tondering.dk. (Please include the word
35 * "calendar" in the subject line.)
36 * The document may be freely distributed, provided this
37 * copyright notice is included and no money is charged for
40 * This document is provided "as is". No warranties are made as
51 #ifdef HAVE_LANGINFO_TIME
55 #include "gdatetime.h"
61 #include "gfileutils.h"
64 #include "gmappedfile.h"
65 #include "gstrfuncs.h"
66 #include "gtestutils.h"
68 #include "gtimezone.h"
75 #endif /* !G_OS_WIN32 */
80 * @short_description: a structure representing Date and Time
81 * @see_also: #GTimeZone
83 * #GDateTime is a structure that combines a Gregorian date and time
84 * into a single structure. It provides many conversion and methods to
85 * manipulate dates and times. Time precision is provided down to
86 * microseconds and the time can range (proleptically) from 0001-01-01
87 * 00:00:00 to 9999-12-31 23:59:59.999999. #GDateTime follows POSIX
88 * time in the sense that it is oblivious to leap seconds.
90 * #GDateTime is an immutable object; once it has been created it cannot
91 * be modified further. All modifiers will create a new #GDateTime.
92 * Nearly all such functions can fail due to the date or time going out
93 * of range, in which case %NULL will be returned.
95 * #GDateTime is reference counted: the reference count is increased by calling
96 * g_date_time_ref() and decreased by calling g_date_time_unref(). When the
97 * reference count drops to 0, the resources allocated by the #GDateTime
98 * structure are released.
100 * Many parts of the API may produce non-obvious results. As an
101 * example, adding two months to January 31st will yield March 31st
102 * whereas adding one month and then one month again will yield either
103 * March 28th or March 29th. Also note that adding 24 hours is not
104 * always the same as adding one day (since days containing daylight
105 * savings time transitions are either 23 or 25 hours in length).
107 * #GDateTime is available since GLib 2.26.
112 /* Microsecond timekeeping within Day */
115 /* TimeZone information */
119 /* 1 is 0001-01-01 in Proleptic Gregorian */
122 volatile gint ref_count
;
125 /* Time conversion {{{1 */
127 #define UNIX_EPOCH_START 719163
128 #define INSTANT_TO_UNIX(instant) \
129 ((instant)/USEC_PER_SECOND - UNIX_EPOCH_START * SEC_PER_DAY)
130 #define UNIX_TO_INSTANT(unix) \
131 (((unix) + UNIX_EPOCH_START * SEC_PER_DAY) * USEC_PER_SECOND)
133 #define DAYS_IN_4YEARS 1461 /* days in 4 years */
134 #define DAYS_IN_100YEARS 36524 /* days in 100 years */
135 #define DAYS_IN_400YEARS 146097 /* days in 400 years */
137 #define USEC_PER_SECOND (G_GINT64_CONSTANT (1000000))
138 #define USEC_PER_MINUTE (G_GINT64_CONSTANT (60000000))
139 #define USEC_PER_HOUR (G_GINT64_CONSTANT (3600000000))
140 #define USEC_PER_MILLISECOND (G_GINT64_CONSTANT (1000))
141 #define USEC_PER_DAY (G_GINT64_CONSTANT (86400000000))
142 #define SEC_PER_DAY (G_GINT64_CONSTANT (86400))
144 #define SECS_PER_MINUTE (60)
145 #define SECS_PER_HOUR (60 * SECS_PER_MINUTE)
146 #define SECS_PER_DAY (24 * SECS_PER_HOUR)
147 #define SECS_PER_YEAR (365 * SECS_PER_DAY)
148 #define SECS_PER_JULIAN (DAYS_PER_PERIOD * SECS_PER_DAY)
150 #define GREGORIAN_LEAP(y) ((((y) % 4) == 0) && (!((((y) % 100) == 0) && (((y) % 400) != 0))))
151 #define JULIAN_YEAR(d) ((d)->julian / 365.25)
152 #define DAYS_PER_PERIOD (G_GINT64_CONSTANT (2914695))
154 static const guint16 days_in_months
[2][13] =
156 { 0, 31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31 },
157 { 0, 31, 29, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31 }
160 static const guint16 days_in_year
[2][13] =
162 { 0, 31, 59, 90, 120, 151, 181, 212, 243, 273, 304, 334, 365 },
163 { 0, 31, 60, 91, 121, 152, 182, 213, 244, 274, 305, 335, 366 }
166 #ifdef HAVE_LANGINFO_TIME
168 #define GET_AMPM(d) ((g_date_time_get_hour (d) < 12) ? \
169 nl_langinfo (AM_STR) : \
170 nl_langinfo (PM_STR))
172 #define PREFERRED_DATE_TIME_FMT nl_langinfo (D_T_FMT)
173 #define PREFERRED_DATE_FMT nl_langinfo (D_FMT)
174 #define PREFERRED_TIME_FMT nl_langinfo (T_FMT)
175 #define PREFERRED_TIME_FMT nl_langinfo (T_FMT)
176 #define PREFERRED_12HR_TIME_FMT nl_langinfo (T_FMT_AMPM)
178 static const gint weekday_item
[2][7] =
180 { ABDAY_2
, ABDAY_3
, ABDAY_4
, ABDAY_5
, ABDAY_6
, ABDAY_7
, ABDAY_1
},
181 { DAY_2
, DAY_3
, DAY_4
, DAY_5
, DAY_6
, DAY_7
, DAY_1
}
184 static const gint month_item
[2][12] =
186 { ABMON_1
, ABMON_2
, ABMON_3
, ABMON_4
, ABMON_5
, ABMON_6
, ABMON_7
, ABMON_8
, ABMON_9
, ABMON_10
, ABMON_11
, ABMON_12
},
187 { MON_1
, MON_2
, MON_3
, MON_4
, MON_5
, MON_6
, MON_7
, MON_8
, MON_9
, MON_10
, MON_11
, MON_12
},
190 #define WEEKDAY_ABBR(d) nl_langinfo (weekday_item[0][g_date_time_get_day_of_week (d) - 1])
191 #define WEEKDAY_FULL(d) nl_langinfo (weekday_item[1][g_date_time_get_day_of_week (d) - 1])
192 #define MONTH_ABBR(d) nl_langinfo (month_item[0][g_date_time_get_month (d) - 1])
193 #define MONTH_FULL(d) nl_langinfo (month_item[1][g_date_time_get_month (d) - 1])
197 #define GET_AMPM(d) (get_fallback_ampm (g_date_time_get_hour (d)))
199 /* Translators: this is the preferred format for expressing the date and the time */
200 #define PREFERRED_DATE_TIME_FMT C_("GDateTime", "%a %b %e %H:%M:%S %Y")
202 /* Translators: this is the preferred format for expressing the date */
203 #define PREFERRED_DATE_FMT C_("GDateTime", "%m/%d/%y")
205 /* Translators: this is the preferred format for expressing the time */
206 #define PREFERRED_TIME_FMT C_("GDateTime", "%H:%M:%S")
208 /* Translators: this is the preferred format for expressing 12 hour time */
209 #define PREFERRED_12HR_TIME_FMT C_("GDateTime", "%I:%M:%S %p")
211 #define WEEKDAY_ABBR(d) (get_weekday_name_abbr (g_date_time_get_day_of_week (d)))
212 #define WEEKDAY_FULL(d) (get_weekday_name (g_date_time_get_day_of_week (d)))
213 #define MONTH_ABBR(d) (get_month_name_abbr (g_date_time_get_month (d)))
214 #define MONTH_FULL(d) (get_month_name (g_date_time_get_month (d)))
217 get_month_name (gint month
)
222 return C_("full month name", "January");
224 return C_("full month name", "February");
226 return C_("full month name", "March");
228 return C_("full month name", "April");
230 return C_("full month name", "May");
232 return C_("full month name", "June");
234 return C_("full month name", "July");
236 return C_("full month name", "August");
238 return C_("full month name", "September");
240 return C_("full month name", "October");
242 return C_("full month name", "November");
244 return C_("full month name", "December");
247 g_warning ("Invalid month number %d", month
);
254 get_month_name_abbr (gint month
)
259 return C_("abbreviated month name", "Jan");
261 return C_("abbreviated month name", "Feb");
263 return C_("abbreviated month name", "Mar");
265 return C_("abbreviated month name", "Apr");
267 return C_("abbreviated month name", "May");
269 return C_("abbreviated month name", "Jun");
271 return C_("abbreviated month name", "Jul");
273 return C_("abbreviated month name", "Aug");
275 return C_("abbreviated month name", "Sep");
277 return C_("abbreviated month name", "Oct");
279 return C_("abbreviated month name", "Nov");
281 return C_("abbreviated month name", "Dec");
284 g_warning ("Invalid month number %d", month
);
291 get_weekday_name (gint day
)
296 return C_("full weekday name", "Monday");
298 return C_("full weekday name", "Tuesday");
300 return C_("full weekday name", "Wednesday");
302 return C_("full weekday name", "Thursday");
304 return C_("full weekday name", "Friday");
306 return C_("full weekday name", "Saturday");
308 return C_("full weekday name", "Sunday");
311 g_warning ("Invalid week day number %d", day
);
318 get_weekday_name_abbr (gint day
)
323 return C_("abbreviated weekday name", "Mon");
325 return C_("abbreviated weekday name", "Tue");
327 return C_("abbreviated weekday name", "Wed");
329 return C_("abbreviated weekday name", "Thu");
331 return C_("abbreviated weekday name", "Fri");
333 return C_("abbreviated weekday name", "Sat");
335 return C_("abbreviated weekday name", "Sun");
338 g_warning ("Invalid week day number %d", day
);
344 #endif /* HAVE_LANGINFO_TIME */
346 /* Format AM/PM indicator if the locale does not have a localized version. */
348 get_fallback_ampm (gint hour
)
351 /* Translators: 'before midday' indicator */
352 return C_("GDateTime", "AM");
354 /* Translators: 'after midday' indicator */
355 return C_("GDateTime", "PM");
359 ymd_to_days (gint year
,
365 days
= (year
- 1) * 365 + ((year
- 1) / 4) - ((year
- 1) / 100)
366 + ((year
- 1) / 400);
368 days
+= days_in_year
[0][month
- 1];
369 if (GREGORIAN_LEAP (year
) && month
> 2)
378 g_date_time_get_week_number (GDateTime
*datetime
,
383 gint a
, b
, c
, d
, e
, f
, g
, n
, s
, month
, day
, year
;
385 g_date_time_get_ymd (datetime
, &year
, &month
, &day
);
389 a
= g_date_time_get_year (datetime
) - 1;
390 b
= (a
/ 4) - (a
/ 100) + (a
/ 400);
391 c
= ((a
- 1) / 4) - ((a
- 1) / 100) + ((a
- 1) / 400);
394 f
= day
- 1 + (31 * (month
- 1));
399 b
= (a
/ 4) - (a
/ 100) + (a
/ 400);
400 c
= ((a
- 1) / 4) - ((a
- 1) / 100) + ((a
- 1) / 400);
403 f
= day
+ (((153 * (month
- 3)) + 2) / 5) + 58 + s
;
413 *week_number
= 53 - ((g
- s
) / 5);
414 else if (n
> 364 + s
)
417 *week_number
= (n
/ 7) + 1;
421 *day_of_week
= d
+ 1;
424 *day_of_year
= f
+ 1;
430 g_date_time_alloc (GTimeZone
*tz
)
434 datetime
= g_slice_new0 (GDateTime
);
435 datetime
->tz
= g_time_zone_ref (tz
);
436 datetime
->ref_count
= 1;
443 * @datetime: a #GDateTime
445 * Atomically increments the reference count of @datetime by one.
447 * Returns: the #GDateTime with the reference count increased
452 g_date_time_ref (GDateTime
*datetime
)
454 g_return_val_if_fail (datetime
!= NULL
, NULL
);
455 g_return_val_if_fail (datetime
->ref_count
> 0, NULL
);
457 g_atomic_int_inc (&datetime
->ref_count
);
464 * @datetime: a #GDateTime
466 * Atomically decrements the reference count of @datetime by one.
468 * When the reference count reaches zero, the resources allocated by
469 * @datetime are freed
474 g_date_time_unref (GDateTime
*datetime
)
476 g_return_if_fail (datetime
!= NULL
);
477 g_return_if_fail (datetime
->ref_count
> 0);
479 if (g_atomic_int_dec_and_test (&datetime
->ref_count
))
481 g_time_zone_unref (datetime
->tz
);
482 g_slice_free (GDateTime
, datetime
);
486 /* Internal state transformers {{{1 */
488 * g_date_time_to_instant:
489 * @datetime: a #GDateTime
491 * Convert a @datetime into an instant.
493 * An instant is a number that uniquely describes a particular
494 * microsecond in time, taking time zone considerations into account.
495 * (ie: "03:00 -0400" is the same instant as "02:00 -0500").
497 * An instant is always positive but we use a signed return value to
498 * avoid troubles with C.
501 g_date_time_to_instant (GDateTime
*datetime
)
505 offset
= g_time_zone_get_offset (datetime
->tz
, datetime
->interval
);
506 offset
*= USEC_PER_SECOND
;
508 return datetime
->days
* USEC_PER_DAY
+ datetime
->usec
- offset
;
512 * g_date_time_from_instant:
514 * @instant: a instant in time
516 * Creates a #GDateTime from a time zone and an instant.
518 * This might fail if the time ends up being out of range.
521 g_date_time_from_instant (GTimeZone
*tz
,
527 if (instant
< 0 || instant
> G_GINT64_CONSTANT (1000000000000000000))
530 datetime
= g_date_time_alloc (tz
);
531 datetime
->interval
= g_time_zone_find_interval (tz
,
532 G_TIME_TYPE_UNIVERSAL
,
533 INSTANT_TO_UNIX (instant
));
534 offset
= g_time_zone_get_offset (datetime
->tz
, datetime
->interval
);
535 offset
*= USEC_PER_SECOND
;
539 datetime
->days
= instant
/ USEC_PER_DAY
;
540 datetime
->usec
= instant
% USEC_PER_DAY
;
542 if (datetime
->days
< 1 || 3652059 < datetime
->days
)
544 g_date_time_unref (datetime
);
553 * g_date_time_deal_with_date_change:
554 * @datetime: a #GDateTime
556 * This function should be called whenever the date changes by adding
557 * days, months or years. It does three things.
559 * First, we ensure that the date falls between 0001-01-01 and
560 * 9999-12-31 and return %FALSE if it does not.
562 * Next we update the ->interval field.
564 * Finally, we ensure that the resulting date and time pair exists (by
565 * ensuring that our time zone has an interval containing it) and
566 * adjusting as required. For example, if we have the time 02:30:00 on
567 * March 13 2010 in Toronto and we add 1 day to it, we would end up with
568 * 2:30am on March 14th, which doesn't exist. In that case, we bump the
572 g_date_time_deal_with_date_change (GDateTime
*datetime
)
578 if (datetime
->days
< 1 || datetime
->days
> 3652059)
581 was_dst
= g_time_zone_is_dst (datetime
->tz
, datetime
->interval
);
583 full_time
= datetime
->days
* USEC_PER_DAY
+ datetime
->usec
;
586 usec
= full_time
% USEC_PER_SECOND
;
587 full_time
/= USEC_PER_SECOND
;
588 full_time
-= UNIX_EPOCH_START
* SEC_PER_DAY
;
590 datetime
->interval
= g_time_zone_adjust_time (datetime
->tz
,
593 full_time
+= UNIX_EPOCH_START
* SEC_PER_DAY
;
594 full_time
*= USEC_PER_SECOND
;
597 datetime
->days
= full_time
/ USEC_PER_DAY
;
598 datetime
->usec
= full_time
% USEC_PER_DAY
;
600 /* maybe daylight time caused us to shift to a different day,
601 * but it definitely didn't push us into a different year */
606 g_date_time_replace_days (GDateTime
*datetime
,
611 new = g_date_time_alloc (datetime
->tz
);
612 new->interval
= datetime
->interval
;
613 new->usec
= datetime
->usec
;
616 if (!g_date_time_deal_with_date_change (new))
618 g_date_time_unref (new);
625 /* now/unix/timeval Constructors {{{1 */
628 * g_date_time_new_from_timeval:
632 * Creates a #GDateTime corresponding to the given #GTimeVal @tv in the
633 * given time zone @tz.
635 * The time contained in a #GTimeVal is always stored in the form of
636 * seconds elapsed since 1970-01-01 00:00:00 UTC, regardless of the
639 * This call can fail (returning %NULL) if @tv represents a time outside
640 * of the supported range of #GDateTime.
642 * You should release the return value by calling g_date_time_unref()
643 * when you are done with it.
645 * Returns: a new #GDateTime, or %NULL
650 g_date_time_new_from_timeval (GTimeZone
*tz
,
653 return g_date_time_from_instant (tz
, tv
->tv_usec
+
654 UNIX_TO_INSTANT (tv
->tv_sec
));
658 * g_date_time_new_from_unix:
662 * Creates a #GDateTime corresponding to the given Unix time @t in the
663 * given time zone @tz.
665 * Unix time is the number of seconds that have elapsed since 1970-01-01
666 * 00:00:00 UTC, regardless of the time zone given.
668 * This call can fail (returning %NULL) if @t represents a time outside
669 * of the supported range of #GDateTime.
671 * You should release the return value by calling g_date_time_unref()
672 * when you are done with it.
674 * Returns: a new #GDateTime, or %NULL
679 g_date_time_new_from_unix (GTimeZone
*tz
,
682 return g_date_time_from_instant (tz
, UNIX_TO_INSTANT (secs
));
686 * g_date_time_new_now:
689 * Creates a #GDateTime corresponding to this exact instant in the given
690 * time zone @tz. The time is as accurate as the system allows, to a
691 * maximum accuracy of 1 microsecond.
693 * This function will always succeed unless the system clock is set to
694 * truly insane values (or unless GLib is still being used after the
697 * You should release the return value by calling g_date_time_unref()
698 * when you are done with it.
700 * Returns: a new #GDateTime, or %NULL
705 g_date_time_new_now (GTimeZone
*tz
)
709 g_get_current_time (&tv
);
711 return g_date_time_new_from_timeval (tz
, &tv
);
715 * g_date_time_new_now_local:
717 * Creates a #GDateTime corresponding to this exact instant in the local
720 * This is equivalent to calling g_date_time_new_now() with the time
721 * zone returned by g_time_zone_new_local().
723 * Returns: a new #GDateTime, or %NULL
728 g_date_time_new_now_local (void)
733 local
= g_time_zone_new_local ();
734 datetime
= g_date_time_new_now (local
);
735 g_time_zone_unref (local
);
741 * g_date_time_new_now_utc:
743 * Creates a #GDateTime corresponding to this exact instant in UTC.
745 * This is equivalent to calling g_date_time_new_now() with the time
746 * zone returned by g_time_zone_new_utc().
748 * Returns: a new #GDateTime, or %NULL
753 g_date_time_new_now_utc (void)
758 utc
= g_time_zone_new_utc ();
759 datetime
= g_date_time_new_now (utc
);
760 g_time_zone_unref (utc
);
766 * g_date_time_new_from_unix_local:
769 * Creates a #GDateTime corresponding to the given Unix time @t in the
772 * Unix time is the number of seconds that have elapsed since 1970-01-01
773 * 00:00:00 UTC, regardless of the local time offset.
775 * This call can fail (returning %NULL) if @t represents a time outside
776 * of the supported range of #GDateTime.
778 * You should release the return value by calling g_date_time_unref()
779 * when you are done with it.
781 * Returns: a new #GDateTime, or %NULL
786 g_date_time_new_from_unix_local (gint64 t
)
791 local
= g_time_zone_new_local ();
792 datetime
= g_date_time_new_from_unix (local
, t
);
793 g_time_zone_unref (local
);
799 * g_date_time_new_from_unix_utc:
802 * Creates a #GDateTime corresponding to the given Unix time @t in UTC.
804 * Unix time is the number of seconds that have elapsed since 1970-01-01
807 * This call can fail (returning %NULL) if @t represents a time outside
808 * of the supported range of #GDateTime.
810 * You should release the return value by calling g_date_time_unref()
811 * when you are done with it.
813 * Returns: a new #GDateTime, or %NULL
818 g_date_time_new_from_unix_utc (gint64 t
)
823 utc
= g_time_zone_new_utc ();
824 datetime
= g_date_time_new_from_unix (utc
, t
);
825 g_time_zone_unref (utc
);
831 * g_date_time_new_from_timeval_local:
834 * Creates a #GDateTime corresponding to the given #GTimeVal @tv in the
837 * The time contained in a #GTimeVal is always stored in the form of
838 * seconds elapsed since 1970-01-01 00:00:00 UTC, regardless of the
841 * This call can fail (returning %NULL) if @tv represents a time outside
842 * of the supported range of #GDateTime.
844 * You should release the return value by calling g_date_time_unref()
845 * when you are done with it.
847 * Returns: a new #GDateTime, or %NULL
852 g_date_time_new_from_timeval_local (const GTimeVal
*tv
)
857 local
= g_time_zone_new_local ();
858 datetime
= g_date_time_new_from_timeval (local
, tv
);
859 g_time_zone_unref (local
);
865 * g_date_time_new_from_timeval_utc:
868 * Creates a #GDateTime corresponding to the given #GTimeVal @tv in UTC.
870 * The time contained in a #GTimeVal is always stored in the form of
871 * seconds elapsed since 1970-01-01 00:00:00 UTC.
873 * This call can fail (returning %NULL) if @tv represents a time outside
874 * of the supported range of #GDateTime.
876 * You should release the return value by calling g_date_time_unref()
877 * when you are done with it.
879 * Returns: a new #GDateTime, or %NULL
884 g_date_time_new_from_timeval_utc (const GTimeVal
*tv
)
889 utc
= g_time_zone_new_utc ();
890 datetime
= g_date_time_new_from_timeval (utc
, tv
);
891 g_time_zone_unref (utc
);
896 /* full new functions {{{1 */
901 * @year: the year component of the date
902 * @month: the month component of the date
903 * @day: the day component of the date
904 * @hour: the hour component of the date
905 * @minute: the minute component of the date
906 * @seconds: the number of seconds past the minute
908 * Creates a new #GDateTime corresponding to the given date and time in
911 * The @year must be between 1 and 9999, @month between 1 and 12 and @day
912 * between 1 and 28, 29, 30 or 31 depending on the month and the year.
914 * @hour must be between 0 and 23 and @minute must be between 0 and 59.
916 * @seconds must be at least 0.0 and must be strictly less than 60.0.
917 * It will be rounded down to the nearest microsecond.
919 * If the given time is not representable in the given time zone (for
920 * example, 02:30 on March 14th 2010 in Toronto, due to daylight savings
921 * time) then the time will be rounded up to the nearest existing time
922 * (in this case, 03:00). If this matters to you then you should verify
923 * the return value for containing the same as the numbers you gave.
925 * In the case that the given time is ambiguous in the given time zone
926 * (for example, 01:30 on November 7th 2010 in Toronto, due to daylight
927 * savings time) then the time falling within standard (ie:
928 * non-daylight) time is taken.
930 * It not considered a programmer error for the values to this function
931 * to be out of range, but in the case that they are, the function will
934 * You should release the return value by calling g_date_time_unref()
935 * when you are done with it.
937 * Returns: a new #GDateTime, or %NULL
942 g_date_time_new (GTimeZone
*tz
,
953 g_return_val_if_fail (tz
!= NULL
, NULL
);
955 if (year
< 1 || year
> 9999 ||
956 month
< 1 || month
> 12 ||
957 day
< 1 || day
> 31 ||
958 hour
< 0 || hour
> 23 ||
959 minute
< 0 || minute
> 59 ||
960 seconds
< 0.0 || seconds
>= 60.0)
963 datetime
= g_date_time_alloc (tz
);
964 datetime
->days
= ymd_to_days (year
, month
, day
);
965 datetime
->usec
= (hour
* USEC_PER_HOUR
)
966 + (minute
* USEC_PER_MINUTE
)
967 + (gint64
) (seconds
* USEC_PER_SECOND
);
969 full_time
= SEC_PER_DAY
*
970 (ymd_to_days (year
, month
, day
) - UNIX_EPOCH_START
) +
971 SECS_PER_HOUR
* hour
+
972 SECS_PER_MINUTE
* minute
+
975 datetime
->interval
= g_time_zone_adjust_time (datetime
->tz
,
976 G_TIME_TYPE_STANDARD
,
979 full_time
+= UNIX_EPOCH_START
* SEC_PER_DAY
;
980 datetime
->days
= full_time
/ SEC_PER_DAY
;
981 datetime
->usec
= (full_time
% SEC_PER_DAY
) * USEC_PER_SECOND
;
982 datetime
->usec
+= ((int) (seconds
* USEC_PER_SECOND
)) % USEC_PER_SECOND
;
988 * g_date_time_new_local:
989 * @year: the year component of the date
990 * @month: the month component of the date
991 * @day: the day component of the date
992 * @hour: the hour component of the date
993 * @minute: the minute component of the date
994 * @seconds: the number of seconds past the minute
996 * Creates a new #GDateTime corresponding to the given date and time in
997 * the local time zone.
999 * This call is equivalent to calling g_date_time_new() with the time
1000 * zone returned by g_time_zone_new_local().
1002 * Returns: a #GDateTime, or %NULL
1007 g_date_time_new_local (gint year
,
1014 GDateTime
*datetime
;
1017 local
= g_time_zone_new_local ();
1018 datetime
= g_date_time_new (local
, year
, month
, day
, hour
, minute
, seconds
);
1019 g_time_zone_unref (local
);
1025 * g_date_time_new_utc:
1026 * @year: the year component of the date
1027 * @month: the month component of the date
1028 * @day: the day component of the date
1029 * @hour: the hour component of the date
1030 * @minute: the minute component of the date
1031 * @seconds: the number of seconds past the minute
1033 * Creates a new #GDateTime corresponding to the given date and time in
1036 * This call is equivalent to calling g_date_time_new() with the time
1037 * zone returned by g_time_zone_new_utc().
1039 * Returns: a #GDateTime, or %NULL
1044 g_date_time_new_utc (gint year
,
1051 GDateTime
*datetime
;
1054 utc
= g_time_zone_new_utc ();
1055 datetime
= g_date_time_new (utc
, year
, month
, day
, hour
, minute
, seconds
);
1056 g_time_zone_unref (utc
);
1065 * @datetime: a #GDateTime
1066 * @timespan: a #GTimeSpan
1068 * Creates a copy of @datetime and adds the specified timespan to the copy.
1070 * Returns: the newly created #GDateTime which should be freed with
1071 * g_date_time_unref().
1076 g_date_time_add (GDateTime
*datetime
,
1079 return g_date_time_from_instant (datetime
->tz
, timespan
+
1080 g_date_time_to_instant (datetime
));
1084 * g_date_time_add_years:
1085 * @datetime: a #GDateTime
1086 * @years: the number of years
1088 * Creates a copy of @datetime and adds the specified number of years to the
1089 * copy. Add negative values to subtract years.
1091 * Returns: the newly created #GDateTime which should be freed with
1092 * g_date_time_unref().
1097 g_date_time_add_years (GDateTime
*datetime
,
1100 gint year
, month
, day
;
1102 g_return_val_if_fail (datetime
!= NULL
, NULL
);
1104 if (years
< -10000 || years
> 10000)
1107 g_date_time_get_ymd (datetime
, &year
, &month
, &day
);
1110 /* only possible issue is if we've entered a year with no February 29
1112 if (month
== 2 && day
== 29 && !GREGORIAN_LEAP (year
))
1115 return g_date_time_replace_days (datetime
, ymd_to_days (year
, month
, day
));
1119 * g_date_time_add_months:
1120 * @datetime: a #GDateTime
1121 * @months: the number of months
1123 * Creates a copy of @datetime and adds the specified number of months to the
1124 * copy. Add negative values to subtract months.
1126 * Returns: the newly created #GDateTime which should be freed with
1127 * g_date_time_unref().
1132 g_date_time_add_months (GDateTime
*datetime
,
1135 gint year
, month
, day
;
1137 g_return_val_if_fail (datetime
!= NULL
, NULL
);
1138 g_date_time_get_ymd (datetime
, &year
, &month
, &day
);
1140 if (months
< -120000 || months
> 120000)
1143 year
+= months
/ 12;
1144 month
+= months
% 12;
1150 else if (month
> 12)
1156 day
= MIN (day
, days_in_months
[GREGORIAN_LEAP (year
)][month
]);
1158 return g_date_time_replace_days (datetime
, ymd_to_days (year
, month
, day
));
1162 * g_date_time_add_weeks:
1163 * @datetime: a #GDateTime
1164 * @weeks: the number of weeks
1166 * Creates a copy of @datetime and adds the specified number of weeks to the
1167 * copy. Add negative values to subtract weeks.
1169 * Returns: the newly created #GDateTime which should be freed with
1170 * g_date_time_unref().
1175 g_date_time_add_weeks (GDateTime
*datetime
,
1178 g_return_val_if_fail (datetime
!= NULL
, NULL
);
1180 return g_date_time_add_days (datetime
, weeks
* 7);
1184 * g_date_time_add_days:
1185 * @datetime: a #GDateTime
1186 * @days: the number of days
1188 * Creates a copy of @datetime and adds the specified number of days to the
1189 * copy. Add negative values to subtract days.
1191 * Returns: the newly created #GDateTime which should be freed with
1192 * g_date_time_unref().
1197 g_date_time_add_days (GDateTime
*datetime
,
1200 g_return_val_if_fail (datetime
!= NULL
, NULL
);
1202 if (days
< -3660000 || days
> 3660000)
1205 return g_date_time_replace_days (datetime
, datetime
->days
+ days
);
1209 * g_date_time_add_hours:
1210 * @datetime: a #GDateTime
1211 * @hours: the number of hours to add
1213 * Creates a copy of @datetime and adds the specified number of hours.
1214 * Add negative values to subtract hours.
1216 * Returns: the newly created #GDateTime which should be freed with
1217 * g_date_time_unref().
1222 g_date_time_add_hours (GDateTime
*datetime
,
1225 return g_date_time_add (datetime
, hours
* USEC_PER_HOUR
);
1229 * g_date_time_add_minutes:
1230 * @datetime: a #GDateTime
1231 * @minutes: the number of minutes to add
1233 * Creates a copy of @datetime adding the specified number of minutes.
1234 * Add negative values to subtract minutes.
1236 * Returns: the newly created #GDateTime which should be freed with
1237 * g_date_time_unref().
1242 g_date_time_add_minutes (GDateTime
*datetime
,
1245 return g_date_time_add (datetime
, minutes
* USEC_PER_MINUTE
);
1250 * g_date_time_add_seconds:
1251 * @datetime: a #GDateTime
1252 * @seconds: the number of seconds to add
1254 * Creates a copy of @datetime and adds the specified number of seconds.
1255 * Add negative values to subtract seconds.
1257 * Returns: the newly created #GDateTime which should be freed with
1258 * g_date_time_unref().
1263 g_date_time_add_seconds (GDateTime
*datetime
,
1266 return g_date_time_add (datetime
, seconds
* USEC_PER_SECOND
);
1270 * g_date_time_add_full:
1271 * @datetime: a #GDateTime
1272 * @years: the number of years to add
1273 * @months: the number of months to add
1274 * @days: the number of days to add
1275 * @hours: the number of hours to add
1276 * @minutes: the number of minutes to add
1277 * @seconds: the number of seconds to add
1279 * Creates a new #GDateTime adding the specified values to the current date and
1280 * time in @datetime. Add negative values to subtract.
1282 * Returns: the newly created #GDateTime that should be freed with
1283 * g_date_time_unref().
1288 g_date_time_add_full (GDateTime
*datetime
,
1296 gint year
, month
, day
;
1301 g_return_val_if_fail (datetime
!= NULL
, NULL
);
1302 g_date_time_get_ymd (datetime
, &year
, &month
, &day
);
1304 months
+= years
* 12;
1306 if (months
< -120000 || months
> 120000)
1309 if (days
< -3660000 || days
> 3660000)
1312 year
+= months
/ 12;
1313 month
+= months
% 12;
1319 else if (month
> 12)
1325 day
= MIN (day
, days_in_months
[GREGORIAN_LEAP (year
)][month
]);
1327 /* full_time is now in unix (local) time */
1328 full_time
= datetime
->usec
/ USEC_PER_SECOND
+ SEC_PER_DAY
*
1329 (ymd_to_days (year
, month
, day
) + days
- UNIX_EPOCH_START
);
1331 interval
= g_time_zone_adjust_time (datetime
->tz
,
1332 g_time_zone_is_dst (datetime
->tz
,
1333 datetime
->interval
),
1336 /* move to UTC unix time */
1337 full_time
-= g_time_zone_get_offset (datetime
->tz
, interval
);
1339 /* convert back to an instant, add back fractional seconds */
1340 full_time
+= UNIX_EPOCH_START
* SEC_PER_DAY
;
1341 full_time
= full_time
* USEC_PER_SECOND
+
1342 datetime
->usec
% USEC_PER_SECOND
;
1344 /* do the actual addition now */
1345 full_time
+= (hours
* USEC_PER_HOUR
) +
1346 (minutes
* USEC_PER_MINUTE
) +
1347 (gint64
) (seconds
* USEC_PER_SECOND
);
1349 /* find the new interval */
1350 interval
= g_time_zone_find_interval (datetime
->tz
,
1351 G_TIME_TYPE_UNIVERSAL
,
1352 INSTANT_TO_UNIX (full_time
));
1354 /* convert back into local time */
1355 full_time
+= USEC_PER_SECOND
*
1356 g_time_zone_get_offset (datetime
->tz
, interval
);
1358 /* split into days and usec of a new datetime */
1359 new = g_date_time_alloc (datetime
->tz
);
1360 new->interval
= interval
;
1361 new->days
= full_time
/ USEC_PER_DAY
;
1362 new->usec
= full_time
% USEC_PER_DAY
;
1369 /* Compare, difference, hash, equal {{{1 */
1371 * g_date_time_compare:
1372 * @dt1: (not nullable): first #GDateTime to compare
1373 * @dt2: (not nullable): second #GDateTime to compare
1375 * A comparison function for #GDateTimes that is suitable
1376 * as a #GCompareFunc. Both #GDateTimes must be non-%NULL.
1378 * Returns: -1, 0 or 1 if @dt1 is less than, equal to or greater
1384 g_date_time_compare (gconstpointer dt1
,
1389 difference
= g_date_time_difference ((GDateTime
*) dt1
, (GDateTime
*) dt2
);
1394 else if (difference
> 0)
1402 * g_date_time_difference:
1403 * @end: a #GDateTime
1404 * @begin: a #GDateTime
1406 * Calculates the difference in time between @end and @begin. The
1407 * #GTimeSpan that is returned is effectively @end - @begin (ie:
1408 * positive if the first parameter is larger).
1410 * Returns: the difference between the two #GDateTime, as a time
1411 * span expressed in microseconds.
1416 g_date_time_difference (GDateTime
*end
,
1419 g_return_val_if_fail (begin
!= NULL
, 0);
1420 g_return_val_if_fail (end
!= NULL
, 0);
1422 return g_date_time_to_instant (end
) -
1423 g_date_time_to_instant (begin
);
1428 * @datetime: (not nullable): a #GDateTime
1430 * Hashes @datetime into a #guint, suitable for use within #GHashTable.
1432 * Returns: a #guint containing the hash
1437 g_date_time_hash (gconstpointer datetime
)
1439 return g_date_time_to_instant ((GDateTime
*) datetime
);
1443 * g_date_time_equal:
1444 * @dt1: (not nullable): a #GDateTime
1445 * @dt2: (not nullable): a #GDateTime
1447 * Checks to see if @dt1 and @dt2 are equal.
1449 * Equal here means that they represent the same moment after converting
1450 * them to the same time zone.
1452 * Returns: %TRUE if @dt1 and @dt2 are equal
1457 g_date_time_equal (gconstpointer dt1
,
1460 return g_date_time_difference ((GDateTime
*) dt1
, (GDateTime
*) dt2
) == 0;
1463 /* Year, Month, Day Getters {{{1 */
1465 * g_date_time_get_ymd:
1466 * @datetime: a #GDateTime.
1467 * @year: (out) (optional): the return location for the gregorian year, or %NULL.
1468 * @month: (out) (optional): the return location for the month of the year, or %NULL.
1469 * @day: (out) (optional): the return location for the day of the month, or %NULL.
1471 * Retrieves the Gregorian day, month, and year of a given #GDateTime.
1476 g_date_time_get_ymd (GDateTime
*datetime
,
1484 gint remaining_days
;
1491 g_return_if_fail (datetime
!= NULL
);
1493 remaining_days
= datetime
->days
;
1496 * We need to convert an offset in days to its year/month/day representation.
1497 * Leap years makes this a little trickier than it should be, so we use
1498 * 400, 100 and 4 years cycles here to get to the correct year.
1501 /* Our days offset starts sets 0001-01-01 as day 1, if it was day 0 our
1502 * math would be simpler, so let's do it */
1505 the_year
= (remaining_days
/ DAYS_IN_400YEARS
) * 400 + 1;
1506 remaining_days
= remaining_days
% DAYS_IN_400YEARS
;
1508 y100_cycles
= remaining_days
/ DAYS_IN_100YEARS
;
1509 remaining_days
= remaining_days
% DAYS_IN_100YEARS
;
1510 the_year
+= y100_cycles
* 100;
1512 y4_cycles
= remaining_days
/ DAYS_IN_4YEARS
;
1513 remaining_days
= remaining_days
% DAYS_IN_4YEARS
;
1514 the_year
+= y4_cycles
* 4;
1516 y1_cycles
= remaining_days
/ 365;
1517 the_year
+= y1_cycles
;
1518 remaining_days
= remaining_days
% 365;
1520 if (y1_cycles
== 4 || y100_cycles
== 4) {
1521 g_assert (remaining_days
== 0);
1523 /* special case that indicates that the date is actually one year before,
1524 * in the 31th of December */
1531 /* now get the month and the day */
1532 leap
= y1_cycles
== 3 && (y4_cycles
!= 24 || y100_cycles
== 3);
1534 g_assert (leap
== GREGORIAN_LEAP(the_year
));
1536 the_month
= (remaining_days
+ 50) >> 5;
1537 preceding
= (days_in_year
[0][the_month
- 1] + (the_month
> 2 && leap
));
1538 if (preceding
> remaining_days
)
1540 /* estimate is too large */
1542 preceding
-= leap
? days_in_months
[1][the_month
]
1543 : days_in_months
[0][the_month
];
1546 remaining_days
-= preceding
;
1547 g_assert(0 <= remaining_days
);
1549 the_day
= remaining_days
+ 1;
1561 * g_date_time_get_year:
1562 * @datetime: A #GDateTime
1564 * Retrieves the year represented by @datetime in the Gregorian calendar.
1566 * Returns: the year represented by @datetime
1571 g_date_time_get_year (GDateTime
*datetime
)
1575 g_return_val_if_fail (datetime
!= NULL
, 0);
1577 g_date_time_get_ymd (datetime
, &year
, NULL
, NULL
);
1583 * g_date_time_get_month:
1584 * @datetime: a #GDateTime
1586 * Retrieves the month of the year represented by @datetime in the Gregorian
1589 * Returns: the month represented by @datetime
1594 g_date_time_get_month (GDateTime
*datetime
)
1598 g_return_val_if_fail (datetime
!= NULL
, 0);
1600 g_date_time_get_ymd (datetime
, NULL
, &month
, NULL
);
1606 * g_date_time_get_day_of_month:
1607 * @datetime: a #GDateTime
1609 * Retrieves the day of the month represented by @datetime in the gregorian
1612 * Returns: the day of the month
1617 g_date_time_get_day_of_month (GDateTime
*datetime
)
1621 const guint16
*days
;
1624 g_return_val_if_fail (datetime
!= NULL
, 0);
1626 days
= days_in_year
[GREGORIAN_LEAP (g_date_time_get_year (datetime
)) ? 1 : 0];
1627 g_date_time_get_week_number (datetime
, NULL
, NULL
, &day_of_year
);
1629 for (i
= 1; i
<= 12; i
++)
1631 if (days
[i
] >= day_of_year
)
1632 return day_of_year
- last
;
1636 g_warn_if_reached ();
1640 /* Week of year / day of week getters {{{1 */
1642 * g_date_time_get_week_numbering_year:
1643 * @datetime: a #GDateTime
1645 * Returns the ISO 8601 week-numbering year in which the week containing
1648 * This function, taken together with g_date_time_get_week_of_year() and
1649 * g_date_time_get_day_of_week() can be used to determine the full ISO
1650 * week date on which @datetime falls.
1652 * This is usually equal to the normal Gregorian year (as returned by
1653 * g_date_time_get_year()), except as detailed below:
1655 * For Thursday, the week-numbering year is always equal to the usual
1656 * calendar year. For other days, the number is such that every day
1657 * within a complete week (Monday to Sunday) is contained within the
1658 * same week-numbering year.
1660 * For Monday, Tuesday and Wednesday occurring near the end of the year,
1661 * this may mean that the week-numbering year is one greater than the
1662 * calendar year (so that these days have the same week-numbering year
1663 * as the Thursday occurring early in the next year).
1665 * For Friday, Saturday and Sunday occurring near the start of the year,
1666 * this may mean that the week-numbering year is one less than the
1667 * calendar year (so that these days have the same week-numbering year
1668 * as the Thursday occurring late in the previous year).
1670 * An equivalent description is that the week-numbering year is equal to
1671 * the calendar year containing the majority of the days in the current
1672 * week (Monday to Sunday).
1674 * Note that January 1 0001 in the proleptic Gregorian calendar is a
1675 * Monday, so this function never returns 0.
1677 * Returns: the ISO 8601 week-numbering year for @datetime
1682 g_date_time_get_week_numbering_year (GDateTime
*datetime
)
1684 gint year
, month
, day
, weekday
;
1686 g_date_time_get_ymd (datetime
, &year
, &month
, &day
);
1687 weekday
= g_date_time_get_day_of_week (datetime
);
1689 /* January 1, 2, 3 might be in the previous year if they occur after
1692 * Jan 1: Friday, Saturday, Sunday => day 1: weekday 5, 6, 7
1693 * Jan 2: Saturday, Sunday => day 2: weekday 6, 7
1694 * Jan 3: Sunday => day 3: weekday 7
1696 * So we have a special case if (day - weekday) <= -4
1698 if (month
== 1 && (day
- weekday
) <= -4)
1701 /* December 29, 30, 31 might be in the next year if they occur before
1704 * Dec 31: Monday, Tuesday, Wednesday => day 31: weekday 1, 2, 3
1705 * Dec 30: Monday, Tuesday => day 30: weekday 1, 2
1706 * Dec 29: Monday => day 29: weekday 1
1708 * So we have a special case if (day - weekday) >= 28
1710 else if (month
== 12 && (day
- weekday
) >= 28)
1718 * g_date_time_get_week_of_year:
1719 * @datetime: a #GDateTime
1721 * Returns the ISO 8601 week number for the week containing @datetime.
1722 * The ISO 8601 week number is the same for every day of the week (from
1723 * Moday through Sunday). That can produce some unusual results
1724 * (described below).
1726 * The first week of the year is week 1. This is the week that contains
1727 * the first Thursday of the year. Equivalently, this is the first week
1728 * that has more than 4 of its days falling within the calendar year.
1730 * The value 0 is never returned by this function. Days contained
1731 * within a year but occurring before the first ISO 8601 week of that
1732 * year are considered as being contained in the last week of the
1733 * previous year. Similarly, the final days of a calendar year may be
1734 * considered as being part of the first ISO 8601 week of the next year
1735 * if 4 or more days of that week are contained within the new year.
1737 * Returns: the ISO 8601 week number for @datetime.
1742 g_date_time_get_week_of_year (GDateTime
*datetime
)
1746 g_return_val_if_fail (datetime
!= NULL
, 0);
1748 g_date_time_get_week_number (datetime
, &weeknum
, NULL
, NULL
);
1754 * g_date_time_get_day_of_week:
1755 * @datetime: a #GDateTime
1757 * Retrieves the ISO 8601 day of the week on which @datetime falls (1 is
1758 * Monday, 2 is Tuesday... 7 is Sunday).
1760 * Returns: the day of the week
1765 g_date_time_get_day_of_week (GDateTime
*datetime
)
1767 g_return_val_if_fail (datetime
!= NULL
, 0);
1769 return (datetime
->days
- 1) % 7 + 1;
1772 /* Day of year getter {{{1 */
1774 * g_date_time_get_day_of_year:
1775 * @datetime: a #GDateTime
1777 * Retrieves the day of the year represented by @datetime in the Gregorian
1780 * Returns: the day of the year
1785 g_date_time_get_day_of_year (GDateTime
*datetime
)
1789 g_return_val_if_fail (datetime
!= NULL
, 0);
1791 g_date_time_get_week_number (datetime
, NULL
, NULL
, &doy
);
1795 /* Time component getters {{{1 */
1798 * g_date_time_get_hour:
1799 * @datetime: a #GDateTime
1801 * Retrieves the hour of the day represented by @datetime
1803 * Returns: the hour of the day
1808 g_date_time_get_hour (GDateTime
*datetime
)
1810 g_return_val_if_fail (datetime
!= NULL
, 0);
1812 return (datetime
->usec
/ USEC_PER_HOUR
);
1816 * g_date_time_get_minute:
1817 * @datetime: a #GDateTime
1819 * Retrieves the minute of the hour represented by @datetime
1821 * Returns: the minute of the hour
1826 g_date_time_get_minute (GDateTime
*datetime
)
1828 g_return_val_if_fail (datetime
!= NULL
, 0);
1830 return (datetime
->usec
% USEC_PER_HOUR
) / USEC_PER_MINUTE
;
1834 * g_date_time_get_second:
1835 * @datetime: a #GDateTime
1837 * Retrieves the second of the minute represented by @datetime
1839 * Returns: the second represented by @datetime
1844 g_date_time_get_second (GDateTime
*datetime
)
1846 g_return_val_if_fail (datetime
!= NULL
, 0);
1848 return (datetime
->usec
% USEC_PER_MINUTE
) / USEC_PER_SECOND
;
1852 * g_date_time_get_microsecond:
1853 * @datetime: a #GDateTime
1855 * Retrieves the microsecond of the date represented by @datetime
1857 * Returns: the microsecond of the second
1862 g_date_time_get_microsecond (GDateTime
*datetime
)
1864 g_return_val_if_fail (datetime
!= NULL
, 0);
1866 return (datetime
->usec
% USEC_PER_SECOND
);
1870 * g_date_time_get_seconds:
1871 * @datetime: a #GDateTime
1873 * Retrieves the number of seconds since the start of the last minute,
1874 * including the fractional part.
1876 * Returns: the number of seconds
1881 g_date_time_get_seconds (GDateTime
*datetime
)
1883 g_return_val_if_fail (datetime
!= NULL
, 0);
1885 return (datetime
->usec
% USEC_PER_MINUTE
) / 1000000.0;
1888 /* Exporters {{{1 */
1890 * g_date_time_to_unix:
1891 * @datetime: a #GDateTime
1893 * Gives the Unix time corresponding to @datetime, rounding down to the
1896 * Unix time is the number of seconds that have elapsed since 1970-01-01
1897 * 00:00:00 UTC, regardless of the time zone associated with @datetime.
1899 * Returns: the Unix time corresponding to @datetime
1904 g_date_time_to_unix (GDateTime
*datetime
)
1906 return INSTANT_TO_UNIX (g_date_time_to_instant (datetime
));
1910 * g_date_time_to_timeval:
1911 * @datetime: a #GDateTime
1912 * @tv: a #GTimeVal to modify
1914 * Stores the instant in time that @datetime represents into @tv.
1916 * The time contained in a #GTimeVal is always stored in the form of
1917 * seconds elapsed since 1970-01-01 00:00:00 UTC, regardless of the time
1918 * zone associated with @datetime.
1920 * On systems where 'long' is 32bit (ie: all 32bit systems and all
1921 * Windows systems), a #GTimeVal is incapable of storing the entire
1922 * range of values that #GDateTime is capable of expressing. On those
1923 * systems, this function returns %FALSE to indicate that the time is
1926 * On systems where 'long' is 64bit, this function never fails.
1928 * Returns: %TRUE if successful, else %FALSE
1933 g_date_time_to_timeval (GDateTime
*datetime
,
1936 tv
->tv_sec
= INSTANT_TO_UNIX (g_date_time_to_instant (datetime
));
1937 tv
->tv_usec
= datetime
->usec
% USEC_PER_SECOND
;
1942 /* Timezone queries {{{1 */
1944 * g_date_time_get_utc_offset:
1945 * @datetime: a #GDateTime
1947 * Determines the offset to UTC in effect at the time and in the time
1948 * zone of @datetime.
1950 * The offset is the number of microseconds that you add to UTC time to
1951 * arrive at local time for the time zone (ie: negative numbers for time
1952 * zones west of GMT, positive numbers for east).
1954 * If @datetime represents UTC time, then the offset is always zero.
1956 * Returns: the number of microseconds that should be added to UTC to
1957 * get the local time
1962 g_date_time_get_utc_offset (GDateTime
*datetime
)
1966 g_return_val_if_fail (datetime
!= NULL
, 0);
1968 offset
= g_time_zone_get_offset (datetime
->tz
, datetime
->interval
);
1970 return (gint64
) offset
* USEC_PER_SECOND
;
1974 * g_date_time_get_timezone_abbreviation:
1975 * @datetime: a #GDateTime
1977 * Determines the time zone abbreviation to be used at the time and in
1978 * the time zone of @datetime.
1980 * For example, in Toronto this is currently "EST" during the winter
1981 * months and "EDT" during the summer months when daylight savings
1982 * time is in effect.
1984 * Returns: (transfer none): the time zone abbreviation. The returned
1985 * string is owned by the #GDateTime and it should not be
1991 g_date_time_get_timezone_abbreviation (GDateTime
*datetime
)
1993 g_return_val_if_fail (datetime
!= NULL
, NULL
);
1995 return g_time_zone_get_abbreviation (datetime
->tz
, datetime
->interval
);
1999 * g_date_time_is_daylight_savings:
2000 * @datetime: a #GDateTime
2002 * Determines if daylight savings time is in effect at the time and in
2003 * the time zone of @datetime.
2005 * Returns: %TRUE if daylight savings time is in effect
2010 g_date_time_is_daylight_savings (GDateTime
*datetime
)
2012 g_return_val_if_fail (datetime
!= NULL
, FALSE
);
2014 return g_time_zone_is_dst (datetime
->tz
, datetime
->interval
);
2017 /* Timezone convert {{{1 */
2019 * g_date_time_to_timezone:
2020 * @datetime: a #GDateTime
2021 * @tz: the new #GTimeZone
2023 * Create a new #GDateTime corresponding to the same instant in time as
2024 * @datetime, but in the time zone @tz.
2026 * This call can fail in the case that the time goes out of bounds. For
2027 * example, converting 0001-01-01 00:00:00 UTC to a time zone west of
2028 * Greenwich will fail (due to the year 0 being out of range).
2030 * You should release the return value by calling g_date_time_unref()
2031 * when you are done with it.
2033 * Returns: a new #GDateTime, or %NULL
2038 g_date_time_to_timezone (GDateTime
*datetime
,
2041 return g_date_time_from_instant (tz
, g_date_time_to_instant (datetime
));
2045 * g_date_time_to_local:
2046 * @datetime: a #GDateTime
2048 * Creates a new #GDateTime corresponding to the same instant in time as
2049 * @datetime, but in the local time zone.
2051 * This call is equivalent to calling g_date_time_to_timezone() with the
2052 * time zone returned by g_time_zone_new_local().
2054 * Returns: the newly created #GDateTime
2059 g_date_time_to_local (GDateTime
*datetime
)
2064 local
= g_time_zone_new_local ();
2065 new = g_date_time_to_timezone (datetime
, local
);
2066 g_time_zone_unref (local
);
2072 * g_date_time_to_utc:
2073 * @datetime: a #GDateTime
2075 * Creates a new #GDateTime corresponding to the same instant in time as
2076 * @datetime, but in UTC.
2078 * This call is equivalent to calling g_date_time_to_timezone() with the
2079 * time zone returned by g_time_zone_new_utc().
2081 * Returns: the newly created #GDateTime
2086 g_date_time_to_utc (GDateTime
*datetime
)
2091 utc
= g_time_zone_new_utc ();
2092 new = g_date_time_to_timezone (datetime
, utc
);
2093 g_time_zone_unref (utc
);
2101 format_z (GString
*outstr
,
2109 hours
= offset
/ 3600;
2110 minutes
= ABS (offset
) / 60 % 60;
2111 seconds
= ABS (offset
) % 60;
2116 g_string_append_printf (outstr
, "%+03d%02d",
2122 g_string_append_printf (outstr
, "%+03d:%02d",
2128 g_string_append_printf (outstr
, "%+03d:%02d:%02d",
2135 g_string_append_printf (outstr
, "%+03d", hours
);
2137 if (minutes
!= 0 || seconds
!= 0)
2139 g_string_append_printf (outstr
, ":%02d", minutes
);
2142 g_string_append_printf (outstr
, ":%02d", seconds
);
2154 format_number (GString
*str
,
2155 gboolean use_alt_digits
,
2160 const gchar
*ascii_digits
[10] = {
2161 "0", "1", "2", "3", "4", "5", "6", "7", "8", "9"
2163 const gchar
**digits
= ascii_digits
;
2164 const gchar
*tmp
[10];
2167 g_return_if_fail (width
<= 10);
2169 #ifdef HAVE_LANGINFO_OUTDIGIT
2172 static const gchar
*alt_digits
[10];
2173 static gsize initialised
;
2174 /* 2^32 has 10 digits */
2176 if G_UNLIKELY (g_once_init_enter (&initialised
))
2178 #define DO_DIGIT(n) \
2179 alt_digits[n] = nl_langinfo (_NL_CTYPE_OUTDIGIT## n ##_MB)
2180 DO_DIGIT(0); DO_DIGIT(1); DO_DIGIT(2); DO_DIGIT(3); DO_DIGIT(4);
2181 DO_DIGIT(5); DO_DIGIT(6); DO_DIGIT(7); DO_DIGIT(8); DO_DIGIT(9);
2183 g_once_init_leave (&initialised
, TRUE
);
2186 digits
= alt_digits
;
2188 #endif /* HAVE_LANGINFO_OUTDIGIT */
2192 tmp
[i
++] = digits
[number
% 10];
2197 while (pad
&& i
< width
)
2198 tmp
[i
++] = *pad
== '0' ? digits
[0] : pad
;
2200 /* should really be impossible */
2204 g_string_append (str
, tmp
[--i
]);
2208 format_ampm (GDateTime
*datetime
,
2210 gboolean locale_is_utf8
,
2214 gchar
*tmp
, *ampm_dup
;
2217 ampm
= GET_AMPM (datetime
);
2219 if (!ampm
|| ampm
[0] == '\0')
2220 ampm
= get_fallback_ampm (g_date_time_get_hour (datetime
));
2222 #if defined (HAVE_LANGINFO_TIME)
2223 if (!locale_is_utf8
)
2225 /* This assumes that locale encoding can't have embedded NULs */
2226 ampm
= tmp
= g_locale_to_utf8 (ampm
, -1, NULL
, NULL
, NULL
);
2232 ampm_dup
= g_utf8_strup (ampm
, -1);
2234 ampm_dup
= g_utf8_strdown (ampm
, -1);
2235 len
= strlen (ampm_dup
);
2236 if (!locale_is_utf8
)
2238 #if defined (HAVE_LANGINFO_TIME)
2241 tmp
= g_locale_from_utf8 (ampm_dup
, -1, NULL
, &len
, NULL
);
2247 g_string_append_len (outstr
, ampm_dup
, len
);
2253 static gboolean
g_date_time_format_locale (GDateTime
*datetime
,
2254 const gchar
*format
,
2256 gboolean locale_is_utf8
);
2258 /* g_date_time_format() subroutine that takes a locale-encoded format
2259 * string and produces a locale-encoded date/time string.
2262 g_date_time_locale_format_locale (GDateTime
*datetime
,
2263 const gchar
*format
,
2265 gboolean locale_is_utf8
)
2271 return g_date_time_format_locale (datetime
, format
, outstr
,
2274 utf8_format
= g_locale_to_utf8 (format
, -1, NULL
, NULL
, NULL
);
2278 success
= g_date_time_format_locale (datetime
, utf8_format
, outstr
,
2280 g_free (utf8_format
);
2284 /* g_date_time_format() subroutine that takes a UTF-8 format
2285 * string and produces a locale-encoded date/time string.
2288 g_date_time_format_locale (GDateTime
*datetime
,
2289 const gchar
*format
,
2291 gboolean locale_is_utf8
)
2298 gboolean alt_digits
= FALSE
;
2299 gboolean pad_set
= FALSE
;
2306 len
= strcspn (format
, "%");
2310 g_string_append_len (outstr
, format
, len
);
2313 tmp
= g_locale_from_utf8 (format
, len
, NULL
, &tmp_len
, NULL
);
2316 g_string_append_len (outstr
, tmp
, tmp_len
);
2325 g_assert (*format
== '%');
2335 c
= g_utf8_get_char (format
);
2336 format
= g_utf8_next_char (format
);
2340 name
= WEEKDAY_ABBR (datetime
);
2341 #if !defined (HAVE_LANGINFO_TIME)
2342 if (!locale_is_utf8
)
2344 tmp
= g_locale_from_utf8 (name
, -1, NULL
, &tmp_len
, NULL
);
2347 g_string_append_len (outstr
, tmp
, tmp_len
);
2353 g_string_append (outstr
, name
);
2357 name
= WEEKDAY_FULL (datetime
);
2358 #if !defined (HAVE_LANGINFO_TIME)
2359 if (!locale_is_utf8
)
2361 tmp
= g_locale_from_utf8 (name
, -1, NULL
, &tmp_len
, NULL
);
2364 g_string_append_len (outstr
, tmp
, tmp_len
);
2370 g_string_append (outstr
, name
);
2374 name
= MONTH_ABBR (datetime
);
2375 #if !defined (HAVE_LANGINFO_TIME)
2376 if (!locale_is_utf8
)
2378 tmp
= g_locale_from_utf8 (name
, -1, NULL
, &tmp_len
, NULL
);
2381 g_string_append_len (outstr
, tmp
, tmp_len
);
2387 g_string_append (outstr
, name
);
2391 name
= MONTH_FULL (datetime
);
2392 #if !defined (HAVE_LANGINFO_TIME)
2393 if (!locale_is_utf8
)
2395 tmp
= g_locale_from_utf8 (name
, -1, NULL
, &tmp_len
, NULL
);
2398 g_string_append_len (outstr
, tmp
, tmp_len
);
2404 g_string_append (outstr
, name
);
2409 if (!g_date_time_locale_format_locale (datetime
, PREFERRED_DATE_TIME_FMT
,
2410 outstr
, locale_is_utf8
))
2415 format_number (outstr
, alt_digits
, pad_set
? pad
: "0", 2,
2416 g_date_time_get_year (datetime
) / 100);
2419 format_number (outstr
, alt_digits
, pad_set
? pad
: "0", 2,
2420 g_date_time_get_day_of_month (datetime
));
2423 format_number (outstr
, alt_digits
, pad_set
? pad
: " ", 2,
2424 g_date_time_get_day_of_month (datetime
));
2427 g_string_append_printf (outstr
, "%d-%02d-%02d",
2428 g_date_time_get_year (datetime
),
2429 g_date_time_get_month (datetime
),
2430 g_date_time_get_day_of_month (datetime
));
2433 format_number (outstr
, alt_digits
, pad_set
? pad
: "0", 2,
2434 g_date_time_get_week_numbering_year (datetime
) % 100);
2437 format_number (outstr
, alt_digits
, pad_set
? pad
: 0, 0,
2438 g_date_time_get_week_numbering_year (datetime
));
2441 name
= MONTH_ABBR (datetime
);
2442 #if !defined (HAVE_LANGINFO_TIME)
2443 if (!locale_is_utf8
)
2445 tmp
= g_locale_from_utf8 (name
, -1, NULL
, &tmp_len
, NULL
);
2448 g_string_append_len (outstr
, tmp
, tmp_len
);
2454 g_string_append (outstr
, name
);
2458 format_number (outstr
, alt_digits
, pad_set
? pad
: "0", 2,
2459 g_date_time_get_hour (datetime
));
2462 format_number (outstr
, alt_digits
, pad_set
? pad
: "0", 2,
2463 (g_date_time_get_hour (datetime
) + 11) % 12 + 1);
2466 format_number (outstr
, alt_digits
, pad_set
? pad
: "0", 3,
2467 g_date_time_get_day_of_year (datetime
));
2470 format_number (outstr
, alt_digits
, pad_set
? pad
: " ", 2,
2471 g_date_time_get_hour (datetime
));
2474 format_number (outstr
, alt_digits
, pad_set
? pad
: " ", 2,
2475 (g_date_time_get_hour (datetime
) + 11) % 12 + 1);
2478 g_string_append_c (outstr
, '\n');
2481 format_number (outstr
, alt_digits
, pad_set
? pad
: "0", 2,
2482 g_date_time_get_month (datetime
));
2485 format_number (outstr
, alt_digits
, pad_set
? pad
: "0", 2,
2486 g_date_time_get_minute (datetime
));
2492 if (!format_ampm (datetime
, outstr
, locale_is_utf8
, TRUE
))
2496 if (!format_ampm (datetime
, outstr
, locale_is_utf8
, FALSE
))
2501 if (!g_date_time_locale_format_locale (datetime
, PREFERRED_12HR_TIME_FMT
,
2502 outstr
, locale_is_utf8
))
2507 g_string_append_printf (outstr
, "%02d:%02d",
2508 g_date_time_get_hour (datetime
),
2509 g_date_time_get_minute (datetime
));
2512 g_string_append_printf (outstr
, "%" G_GINT64_FORMAT
, g_date_time_to_unix (datetime
));
2515 format_number (outstr
, alt_digits
, pad_set
? pad
: "0", 2,
2516 g_date_time_get_second (datetime
));
2519 g_string_append_c (outstr
, '\t');
2522 g_string_append_printf (outstr
, "%02d:%02d:%02d",
2523 g_date_time_get_hour (datetime
),
2524 g_date_time_get_minute (datetime
),
2525 g_date_time_get_second (datetime
));
2528 format_number (outstr
, alt_digits
, 0, 0,
2529 g_date_time_get_day_of_week (datetime
));
2532 format_number (outstr
, alt_digits
, pad_set
? pad
: "0", 2,
2533 g_date_time_get_week_of_year (datetime
));
2536 format_number (outstr
, alt_digits
, 0, 0,
2537 g_date_time_get_day_of_week (datetime
) % 7);
2541 if (!g_date_time_locale_format_locale (datetime
, PREFERRED_DATE_FMT
,
2542 outstr
, locale_is_utf8
))
2548 if (!g_date_time_locale_format_locale (datetime
, PREFERRED_TIME_FMT
,
2549 outstr
, locale_is_utf8
))
2554 format_number (outstr
, alt_digits
, pad_set
? pad
: "0", 2,
2555 g_date_time_get_year (datetime
) % 100);
2558 format_number (outstr
, alt_digits
, 0, 0,
2559 g_date_time_get_year (datetime
));
2564 offset
= g_date_time_get_utc_offset (datetime
) / USEC_PER_SECOND
;
2565 if (!format_z (outstr
, (int) offset
, colons
))
2570 tz
= g_date_time_get_timezone_abbreviation (datetime
);
2571 tmp_len
= strlen (tz
);
2572 if (!locale_is_utf8
)
2574 tz
= tmp
= g_locale_from_utf8 (tz
, -1, NULL
, &tmp_len
, NULL
);
2578 g_string_append_len (outstr
, tz
, tmp_len
);
2579 if (!locale_is_utf8
)
2583 g_string_append_c (outstr
, '%');
2598 /* Colons are only allowed before 'z' */
2599 if (*format
&& *format
!= 'z' && *format
!= ':')
2612 * g_date_time_format:
2613 * @datetime: A #GDateTime
2614 * @format: a valid UTF-8 string, containing the format for the
2617 * Creates a newly allocated string representing the requested @format.
2619 * The format strings understood by this function are a subset of the
2620 * strftime() format language as specified by C99. The \%D, \%U and \%W
2621 * conversions are not supported, nor is the 'E' modifier. The GNU
2622 * extensions \%k, \%l, \%s and \%P are supported, however, as are the
2623 * '0', '_' and '-' modifiers.
2625 * In contrast to strftime(), this function always produces a UTF-8
2626 * string, regardless of the current locale. Note that the rendering of
2627 * many formats is locale-dependent and may not match the strftime()
2630 * The following format specifiers are supported:
2632 * - \%a: the abbreviated weekday name according to the current locale
2633 * - \%A: the full weekday name according to the current locale
2634 * - \%b: the abbreviated month name according to the current locale
2635 * - \%B: the full month name according to the current locale
2636 * - \%c: the preferred date and time representation for the current locale
2637 * - \%C: the century number (year/100) as a 2-digit integer (00-99)
2638 * - \%d: the day of the month as a decimal number (range 01 to 31)
2639 * - \%e: the day of the month as a decimal number (range 1 to 31)
2640 * - \%F: equivalent to `%Y-%m-%d` (the ISO 8601 date format)
2641 * - \%g: the last two digits of the ISO 8601 week-based year as a
2642 * decimal number (00-99). This works well with \%V and \%u.
2643 * - \%G: the ISO 8601 week-based year as a decimal number. This works
2644 * well with \%V and \%u.
2645 * - \%h: equivalent to \%b
2646 * - \%H: the hour as a decimal number using a 24-hour clock (range 00 to 23)
2647 * - \%I: the hour as a decimal number using a 12-hour clock (range 01 to 12)
2648 * - \%j: the day of the year as a decimal number (range 001 to 366)
2649 * - \%k: the hour (24-hour clock) as a decimal number (range 0 to 23);
2650 * single digits are preceded by a blank
2651 * - \%l: the hour (12-hour clock) as a decimal number (range 1 to 12);
2652 * single digits are preceded by a blank
2653 * - \%m: the month as a decimal number (range 01 to 12)
2654 * - \%M: the minute as a decimal number (range 00 to 59)
2655 * - \%p: either "AM" or "PM" according to the given time value, or the
2656 * corresponding strings for the current locale. Noon is treated as
2657 * "PM" and midnight as "AM".
2658 * - \%P: like \%p but lowercase: "am" or "pm" or a corresponding string for
2659 * the current locale
2660 * - \%r: the time in a.m. or p.m. notation
2661 * - \%R: the time in 24-hour notation (\%H:\%M)
2662 * - \%s: the number of seconds since the Epoch, that is, since 1970-01-01
2664 * - \%S: the second as a decimal number (range 00 to 60)
2665 * - \%t: a tab character
2666 * - \%T: the time in 24-hour notation with seconds (\%H:\%M:\%S)
2667 * - \%u: the ISO 8601 standard day of the week as a decimal, range 1 to 7,
2668 * Monday being 1. This works well with \%G and \%V.
2669 * - \%V: the ISO 8601 standard week number of the current year as a decimal
2670 * number, range 01 to 53, where week 1 is the first week that has at
2671 * least 4 days in the new year. See g_date_time_get_week_of_year().
2672 * This works well with \%G and \%u.
2673 * - \%w: the day of the week as a decimal, range 0 to 6, Sunday being 0.
2674 * This is not the ISO 8601 standard format -- use \%u instead.
2675 * - \%x: the preferred date representation for the current locale without
2677 * - \%X: the preferred time representation for the current locale without
2679 * - \%y: the year as a decimal number without the century
2680 * - \%Y: the year as a decimal number including the century
2681 * - \%z: the time zone as an offset from UTC (+hhmm)
2682 * - \%:z: the time zone as an offset from UTC (+hh:mm).
2683 * This is a gnulib strftime() extension. Since: 2.38
2684 * - \%::z: the time zone as an offset from UTC (+hh:mm:ss). This is a
2685 * gnulib strftime() extension. Since: 2.38
2686 * - \%:::z: the time zone as an offset from UTC, with : to necessary
2687 * precision (e.g., -04, +05:30). This is a gnulib strftime() extension. Since: 2.38
2688 * - \%Z: the time zone or name or abbreviation
2689 * - \%\%: a literal \% character
2691 * Some conversion specifications can be modified by preceding the
2692 * conversion specifier by one or more modifier characters. The
2693 * following modifiers are supported for many of the numeric
2696 * - O: Use alternative numeric symbols, if the current locale supports those.
2697 * - _: Pad a numeric result with spaces. This overrides the default padding
2698 * for the specifier.
2699 * - -: Do not pad a numeric result. This overrides the default padding
2700 * for the specifier.
2701 * - 0: Pad a numeric result with zeros. This overrides the default padding
2702 * for the specifier.
2704 * Returns: a newly allocated string formatted to the requested format
2705 * or %NULL in the case that there was an error. The string
2706 * should be freed with g_free().
2711 g_date_time_format (GDateTime
*datetime
,
2712 const gchar
*format
)
2716 gboolean locale_is_utf8
= g_get_charset (NULL
);
2718 g_return_val_if_fail (datetime
!= NULL
, NULL
);
2719 g_return_val_if_fail (format
!= NULL
, NULL
);
2720 g_return_val_if_fail (g_utf8_validate (format
, -1, NULL
), NULL
);
2722 outstr
= g_string_sized_new (strlen (format
) * 2);
2724 if (!g_date_time_format_locale (datetime
, format
, outstr
, locale_is_utf8
))
2726 g_string_free (outstr
, TRUE
);
2731 return g_string_free (outstr
, FALSE
);
2733 utf8
= g_locale_to_utf8 (outstr
->str
, outstr
->len
, NULL
, NULL
, NULL
);
2734 g_string_free (outstr
, TRUE
);
2740 /* vim:set foldmethod=marker: */