nexmon – Blame information for rev 1

Subversion Repositories:
Rev:
Rev Author Line No. Line
1 office 1 /* gdatetime.c
2 *
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
7 *
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.
12 *
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.
17 *
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
21 * USA.
22 *
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>
27 */
28  
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
32 *
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
40 * the document.
41 *
42 * This document is provided "as is". No warranties are made as
43 * to its correctness.
44 */
45  
46 /* Prologue {{{1 */
47  
48 #include "config.h"
49  
50 #include <stdlib.h>
51 #include <string.h>
52  
53 #ifdef HAVE_LANGINFO_TIME
54 #include <langinfo.h>
55 #endif
56  
57 #include "gdatetime.h"
58  
59 #include "gslice.h"
60 #include "gatomic.h"
61 #include "gcharset.h"
62 #include "gconvert.h"
63 #include "gfileutils.h"
64 #include "ghash.h"
65 #include "gmain.h"
66 #include "gmappedfile.h"
67 #include "gstrfuncs.h"
68 #include "gtestutils.h"
69 #include "gthread.h"
70 #include "gtimezone.h"
71  
72 #include "glibintl.h"
73  
74 #ifndef G_OS_WIN32
75 #include <sys/time.h>
76 #include <time.h>
77 #endif /* !G_OS_WIN32 */
78  
79 /**
80 * SECTION:date-time
81 * @title: GDateTime
82 * @short_description: a structure representing Date and Time
83 * @see_also: #GTimeZone
84 *
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.
91 *
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.
96 *
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.
101 *
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).
108 *
109 * #GDateTime is available since GLib 2.26.
110 */
111  
112 struct _GDateTime
113 {
114 /* Microsecond timekeeping within Day */
115 guint64 usec;
116  
117 /* TimeZone information */
118 GTimeZone *tz;
119 gint interval;
120  
121 /* 1 is 0001-01-01 in Proleptic Gregorian */
122 gint32 days;
123  
124 volatile gint ref_count;
125 };
126  
127 /* Time conversion {{{1 */
128  
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)
134  
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 */
138  
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))
145  
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)
151  
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))
155  
156 static const guint16 days_in_months[2][13] =
157 {
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 }
160 };
161  
162 static const guint16 days_in_year[2][13] =
163 {
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 }
166 };
167  
168 #ifdef HAVE_LANGINFO_TIME
169  
170 #define GET_AMPM(d) ((g_date_time_get_hour (d) < 12) ? \
171 nl_langinfo (AM_STR) : \
172 nl_langinfo (PM_STR))
173  
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)
179  
180 static const gint weekday_item[2][7] =
181 {
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 }
184 };
185  
186 static const gint month_item[2][12] =
187 {
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 },
190 };
191  
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])
196  
197 #else
198  
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"))
204  
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")
207  
208 /* Translators: this is the preferred format for expressing the date */
209 #define PREFERRED_DATE_FMT C_("GDateTime", "%m/%d/%y")
210  
211 /* Translators: this is the preferred format for expressing the time */
212 #define PREFERRED_TIME_FMT C_("GDateTime", "%H:%M:%S")
213  
214 /* Translators: this is the preferred format for expressing 12 hour time */
215 #define PREFERRED_12HR_TIME_FMT C_("GDateTime", "%I:%M:%S %p")
216  
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)))
221  
222 static const gchar *
223 get_month_name (gint month)
224 {
225 switch (month)
226 {
227 case 1:
228 return C_("full month name", "January");
229 case 2:
230 return C_("full month name", "February");
231 case 3:
232 return C_("full month name", "March");
233 case 4:
234 return C_("full month name", "April");
235 case 5:
236 return C_("full month name", "May");
237 case 6:
238 return C_("full month name", "June");
239 case 7:
240 return C_("full month name", "July");
241 case 8:
242 return C_("full month name", "August");
243 case 9:
244 return C_("full month name", "September");
245 case 10:
246 return C_("full month name", "October");
247 case 11:
248 return C_("full month name", "November");
249 case 12:
250 return C_("full month name", "December");
251  
252 default:
253 g_warning ("Invalid month number %d", month);
254 }
255  
256 return NULL;
257 }
258  
259 static const gchar *
260 get_month_name_abbr (gint month)
261 {
262 switch (month)
263 {
264 case 1:
265 return C_("abbreviated month name", "Jan");
266 case 2:
267 return C_("abbreviated month name", "Feb");
268 case 3:
269 return C_("abbreviated month name", "Mar");
270 case 4:
271 return C_("abbreviated month name", "Apr");
272 case 5:
273 return C_("abbreviated month name", "May");
274 case 6:
275 return C_("abbreviated month name", "Jun");
276 case 7:
277 return C_("abbreviated month name", "Jul");
278 case 8:
279 return C_("abbreviated month name", "Aug");
280 case 9:
281 return C_("abbreviated month name", "Sep");
282 case 10:
283 return C_("abbreviated month name", "Oct");
284 case 11:
285 return C_("abbreviated month name", "Nov");
286 case 12:
287 return C_("abbreviated month name", "Dec");
288  
289 default:
290 g_warning ("Invalid month number %d", month);
291 }
292  
293 return NULL;
294 }
295  
296 static const gchar *
297 get_weekday_name (gint day)
298 {
299 switch (day)
300 {
301 case 1:
302 return C_("full weekday name", "Monday");
303 case 2:
304 return C_("full weekday name", "Tuesday");
305 case 3:
306 return C_("full weekday name", "Wednesday");
307 case 4:
308 return C_("full weekday name", "Thursday");
309 case 5:
310 return C_("full weekday name", "Friday");
311 case 6:
312 return C_("full weekday name", "Saturday");
313 case 7:
314 return C_("full weekday name", "Sunday");
315  
316 default:
317 g_warning ("Invalid week day number %d", day);
318 }
319  
320 return NULL;
321 }
322  
323 static const gchar *
324 get_weekday_name_abbr (gint day)
325 {
326 switch (day)
327 {
328 case 1:
329 return C_("abbreviated weekday name", "Mon");
330 case 2:
331 return C_("abbreviated weekday name", "Tue");
332 case 3:
333 return C_("abbreviated weekday name", "Wed");
334 case 4:
335 return C_("abbreviated weekday name", "Thu");
336 case 5:
337 return C_("abbreviated weekday name", "Fri");
338 case 6:
339 return C_("abbreviated weekday name", "Sat");
340 case 7:
341 return C_("abbreviated weekday name", "Sun");
342  
343 default:
344 g_warning ("Invalid week day number %d", day);
345 }
346  
347 return NULL;
348 }
349  
350 #endif /* HAVE_LANGINFO_TIME */
351  
352 static inline gint
353 ymd_to_days (gint year,
354 gint month,
355 gint day)
356 {
357 gint64 days;
358  
359 days = (year - 1) * 365 + ((year - 1) / 4) - ((year - 1) / 100)
360 + ((year - 1) / 400);
361  
362 days += days_in_year[0][month - 1];
363 if (GREGORIAN_LEAP (year) && month > 2)
364 day++;
365  
366 days += day;
367  
368 return days;
369 }
370  
371 static void
372 g_date_time_get_week_number (GDateTime *datetime,
373 gint *week_number,
374 gint *day_of_week,
375 gint *day_of_year)
376 {
377 gint a, b, c, d, e, f, g, n, s, month, day, year;
378  
379 g_date_time_get_ymd (datetime, &year, &month, &day);
380  
381 if (month <= 2)
382 {
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);
386 s = b - c;
387 e = 0;
388 f = day - 1 + (31 * (month - 1));
389 }
390 else
391 {
392 a = year;
393 b = (a / 4) - (a / 100) + (a / 400);
394 c = ((a - 1) / 4) - ((a - 1) / 100) + ((a - 1) / 400);
395 s = b - c;
396 e = s + 1;
397 f = day + (((153 * (month - 3)) + 2) / 5) + 58 + s;
398 }
399  
400 g = (a + b) % 7;
401 d = (f + g - e) % 7;
402 n = f + 3 - d;
403  
404 if (week_number)
405 {
406 if (n < 0)
407 *week_number = 53 - ((g - s) / 5);
408 else if (n > 364 + s)
409 *week_number = 1;
410 else
411 *week_number = (n / 7) + 1;
412 }
413  
414 if (day_of_week)
415 *day_of_week = d + 1;
416  
417 if (day_of_year)
418 *day_of_year = f + 1;
419 }
420  
421 /* Lifecycle {{{1 */
422  
423 static GDateTime *
424 g_date_time_alloc (GTimeZone *tz)
425 {
426 GDateTime *datetime;
427  
428 datetime = g_slice_new0 (GDateTime);
429 datetime->tz = g_time_zone_ref (tz);
430 datetime->ref_count = 1;
431  
432 return datetime;
433 }
434  
435 /**
436 * g_date_time_ref:
437 * @datetime: a #GDateTime
438 *
439 * Atomically increments the reference count of @datetime by one.
440 *
441 * Returns: the #GDateTime with the reference count increased
442 *
443 * Since: 2.26
444 */
445 GDateTime *
446 g_date_time_ref (GDateTime *datetime)
447 {
448 g_return_val_if_fail (datetime != NULL, NULL);
449 g_return_val_if_fail (datetime->ref_count > 0, NULL);
450  
451 g_atomic_int_inc (&datetime->ref_count);
452  
453 return datetime;
454 }
455  
456 /**
457 * g_date_time_unref:
458 * @datetime: a #GDateTime
459 *
460 * Atomically decrements the reference count of @datetime by one.
461 *
462 * When the reference count reaches zero, the resources allocated by
463 * @datetime are freed
464 *
465 * Since: 2.26
466 */
467 void
468 g_date_time_unref (GDateTime *datetime)
469 {
470 g_return_if_fail (datetime != NULL);
471 g_return_if_fail (datetime->ref_count > 0);
472  
473 if (g_atomic_int_dec_and_test (&datetime->ref_count))
474 {
475 g_time_zone_unref (datetime->tz);
476 g_slice_free (GDateTime, datetime);
477 }
478 }
479  
480 /* Internal state transformers {{{1 */
481 /*< internal >
482 * g_date_time_to_instant:
483 * @datetime: a #GDateTime
484 *
485 * Convert a @datetime into an instant.
486 *
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").
490 *
491 * An instant is always positive but we use a signed return value to
492 * avoid troubles with C.
493 */
494 static gint64
495 g_date_time_to_instant (GDateTime *datetime)
496 {
497 gint64 offset;
498  
499 offset = g_time_zone_get_offset (datetime->tz, datetime->interval);
500 offset *= USEC_PER_SECOND;
501  
502 return datetime->days * USEC_PER_DAY + datetime->usec - offset;
503 }
504  
505 /*< internal >
506 * g_date_time_from_instant:
507 * @tz: a #GTimeZone
508 * @instant: a instant in time
509 *
510 * Creates a #GDateTime from a time zone and an instant.
511 *
512 * This might fail if the time ends up being out of range.
513 */
514 static GDateTime *
515 g_date_time_from_instant (GTimeZone *tz,
516 gint64 instant)
517 {
518 GDateTime *datetime;
519 gint64 offset;
520  
521 if (instant < 0 || instant > G_GINT64_CONSTANT (1000000000000000000))
522 return NULL;
523  
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;
530  
531 instant += offset;
532  
533 datetime->days = instant / USEC_PER_DAY;
534 datetime->usec = instant % USEC_PER_DAY;
535  
536 if (datetime->days < 1 || 3652059 < datetime->days)
537 {
538 g_date_time_unref (datetime);
539 datetime = NULL;
540 }
541  
542 return datetime;
543 }
544  
545  
546 /*< internal >
547 * g_date_time_deal_with_date_change:
548 * @datetime: a #GDateTime
549 *
550 * This function should be called whenever the date changes by adding
551 * days, months or years. It does three things.
552 *
553 * First, we ensure that the date falls between 0001-01-01 and
554 * 9999-12-31 and return %FALSE if it does not.
555 *
556 * Next we update the ->interval field.
557 *
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
563 * time up to 3:00am.
564 */
565 static gboolean
566 g_date_time_deal_with_date_change (GDateTime *datetime)
567 {
568 GTimeType was_dst;
569 gint64 full_time;
570 gint64 usec;
571  
572 if (datetime->days < 1 || datetime->days > 3652059)
573 return FALSE;
574  
575 was_dst = g_time_zone_is_dst (datetime->tz, datetime->interval);
576  
577 full_time = datetime->days * USEC_PER_DAY + datetime->usec;
578  
579  
580 usec = full_time % USEC_PER_SECOND;
581 full_time /= USEC_PER_SECOND;
582 full_time -= UNIX_EPOCH_START * SEC_PER_DAY;
583  
584 datetime->interval = g_time_zone_adjust_time (datetime->tz,
585 was_dst,
586 &full_time);
587 full_time += UNIX_EPOCH_START * SEC_PER_DAY;
588 full_time *= USEC_PER_SECOND;
589 full_time += usec;
590  
591 datetime->days = full_time / USEC_PER_DAY;
592 datetime->usec = full_time % USEC_PER_DAY;
593  
594 /* maybe daylight time caused us to shift to a different day,
595 * but it definitely didn't push us into a different year */
596 return TRUE;
597 }
598  
599 static GDateTime *
600 g_date_time_replace_days (GDateTime *datetime,
601 gint days)
602 {
603 GDateTime *new;
604  
605 new = g_date_time_alloc (datetime->tz);
606 new->interval = datetime->interval;
607 new->usec = datetime->usec;
608 new->days = days;
609  
610 if (!g_date_time_deal_with_date_change (new))
611 {
612 g_date_time_unref (new);
613 new = NULL;
614 }
615  
616 return new;
617 }
618  
619 /* now/unix/timeval Constructors {{{1 */
620  
621 /*< internal >
622 * g_date_time_new_from_timeval:
623 * @tz: a #GTimeZone
624 * @tv: a #GTimeVal
625 *
626 * Creates a #GDateTime corresponding to the given #GTimeVal @tv in the
627 * given time zone @tz.
628 *
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
631 * given time zone.
632 *
633 * This call can fail (returning %NULL) if @tv represents a time outside
634 * of the supported range of #GDateTime.
635 *
636 * You should release the return value by calling g_date_time_unref()
637 * when you are done with it.
638 *
639 * Returns: a new #GDateTime, or %NULL
640 *
641 * Since: 2.26
642 **/
643 static GDateTime *
644 g_date_time_new_from_timeval (GTimeZone *tz,
645 const GTimeVal *tv)
646 {
647 return g_date_time_from_instant (tz, tv->tv_usec +
648 UNIX_TO_INSTANT (tv->tv_sec));
649 }
650  
651 /*< internal >
652 * g_date_time_new_from_unix:
653 * @tz: a #GTimeZone
654 * @t: the Unix time
655 *
656 * Creates a #GDateTime corresponding to the given Unix time @t in the
657 * given time zone @tz.
658 *
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.
661 *
662 * This call can fail (returning %NULL) if @t represents a time outside
663 * of the supported range of #GDateTime.
664 *
665 * You should release the return value by calling g_date_time_unref()
666 * when you are done with it.
667 *
668 * Returns: a new #GDateTime, or %NULL
669 *
670 * Since: 2.26
671 **/
672 static GDateTime *
673 g_date_time_new_from_unix (GTimeZone *tz,
674 gint64 secs)
675 {
676 return g_date_time_from_instant (tz, UNIX_TO_INSTANT (secs));
677 }
678  
679 /**
680 * g_date_time_new_now:
681 * @tz: a #GTimeZone
682 *
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.
686 *
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
689 * year 9999).
690 *
691 * You should release the return value by calling g_date_time_unref()
692 * when you are done with it.
693 *
694 * Returns: a new #GDateTime, or %NULL
695 *
696 * Since: 2.26
697 **/
698 GDateTime *
699 g_date_time_new_now (GTimeZone *tz)
700 {
701 GTimeVal tv;
702  
703 g_get_current_time (&tv);
704  
705 return g_date_time_new_from_timeval (tz, &tv);
706 }
707  
708 /**
709 * g_date_time_new_now_local:
710 *
711 * Creates a #GDateTime corresponding to this exact instant in the local
712 * time zone.
713 *
714 * This is equivalent to calling g_date_time_new_now() with the time
715 * zone returned by g_time_zone_new_local().
716 *
717 * Returns: a new #GDateTime, or %NULL
718 *
719 * Since: 2.26
720 **/
721 GDateTime *
722 g_date_time_new_now_local (void)
723 {
724 GDateTime *datetime;
725 GTimeZone *local;
726  
727 local = g_time_zone_new_local ();
728 datetime = g_date_time_new_now (local);
729 g_time_zone_unref (local);
730  
731 return datetime;
732 }
733  
734 /**
735 * g_date_time_new_now_utc:
736 *
737 * Creates a #GDateTime corresponding to this exact instant in UTC.
738 *
739 * This is equivalent to calling g_date_time_new_now() with the time
740 * zone returned by g_time_zone_new_utc().
741 *
742 * Returns: a new #GDateTime, or %NULL
743 *
744 * Since: 2.26
745 **/
746 GDateTime *
747 g_date_time_new_now_utc (void)
748 {
749 GDateTime *datetime;
750 GTimeZone *utc;
751  
752 utc = g_time_zone_new_utc ();
753 datetime = g_date_time_new_now (utc);
754 g_time_zone_unref (utc);
755  
756 return datetime;
757 }
758  
759 /**
760 * g_date_time_new_from_unix_local:
761 * @t: the Unix time
762 *
763 * Creates a #GDateTime corresponding to the given Unix time @t in the
764 * local time zone.
765 *
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.
768 *
769 * This call can fail (returning %NULL) if @t represents a time outside
770 * of the supported range of #GDateTime.
771 *
772 * You should release the return value by calling g_date_time_unref()
773 * when you are done with it.
774 *
775 * Returns: a new #GDateTime, or %NULL
776 *
777 * Since: 2.26
778 **/
779 GDateTime *
780 g_date_time_new_from_unix_local (gint64 t)
781 {
782 GDateTime *datetime;
783 GTimeZone *local;
784  
785 local = g_time_zone_new_local ();
786 datetime = g_date_time_new_from_unix (local, t);
787 g_time_zone_unref (local);
788  
789 return datetime;
790 }
791  
792 /**
793 * g_date_time_new_from_unix_utc:
794 * @t: the Unix time
795 *
796 * Creates a #GDateTime corresponding to the given Unix time @t in UTC.
797 *
798 * Unix time is the number of seconds that have elapsed since 1970-01-01
799 * 00:00:00 UTC.
800 *
801 * This call can fail (returning %NULL) if @t represents a time outside
802 * of the supported range of #GDateTime.
803 *
804 * You should release the return value by calling g_date_time_unref()
805 * when you are done with it.
806 *
807 * Returns: a new #GDateTime, or %NULL
808 *
809 * Since: 2.26
810 **/
811 GDateTime *
812 g_date_time_new_from_unix_utc (gint64 t)
813 {
814 GDateTime *datetime;
815 GTimeZone *utc;
816  
817 utc = g_time_zone_new_utc ();
818 datetime = g_date_time_new_from_unix (utc, t);
819 g_time_zone_unref (utc);
820  
821 return datetime;
822 }
823  
824 /**
825 * g_date_time_new_from_timeval_local:
826 * @tv: a #GTimeVal
827 *
828 * Creates a #GDateTime corresponding to the given #GTimeVal @tv in the
829 * local time zone.
830 *
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
833 * local time offset.
834 *
835 * This call can fail (returning %NULL) if @tv represents a time outside
836 * of the supported range of #GDateTime.
837 *
838 * You should release the return value by calling g_date_time_unref()
839 * when you are done with it.
840 *
841 * Returns: a new #GDateTime, or %NULL
842 *
843 * Since: 2.26
844 **/
845 GDateTime *
846 g_date_time_new_from_timeval_local (const GTimeVal *tv)
847 {
848 GDateTime *datetime;
849 GTimeZone *local;
850  
851 local = g_time_zone_new_local ();
852 datetime = g_date_time_new_from_timeval (local, tv);
853 g_time_zone_unref (local);
854  
855 return datetime;
856 }
857  
858 /**
859 * g_date_time_new_from_timeval_utc:
860 * @tv: a #GTimeVal
861 *
862 * Creates a #GDateTime corresponding to the given #GTimeVal @tv in UTC.
863 *
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.
866 *
867 * This call can fail (returning %NULL) if @tv represents a time outside
868 * of the supported range of #GDateTime.
869 *
870 * You should release the return value by calling g_date_time_unref()
871 * when you are done with it.
872 *
873 * Returns: a new #GDateTime, or %NULL
874 *
875 * Since: 2.26
876 **/
877 GDateTime *
878 g_date_time_new_from_timeval_utc (const GTimeVal *tv)
879 {
880 GDateTime *datetime;
881 GTimeZone *utc;
882  
883 utc = g_time_zone_new_utc ();
884 datetime = g_date_time_new_from_timeval (utc, tv);
885 g_time_zone_unref (utc);
886  
887 return datetime;
888 }
889  
890 /* full new functions {{{1 */
891  
892 /**
893 * g_date_time_new:
894 * @tz: a #GTimeZone
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
901 *
902 * Creates a new #GDateTime corresponding to the given date and time in
903 * the time zone @tz.
904 *
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.
907 *
908 * @hour must be between 0 and 23 and @minute must be between 0 and 59.
909 *
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.
912 *
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.
918 *
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.
923 *
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
926 * return %NULL.
927 *
928 * You should release the return value by calling g_date_time_unref()
929 * when you are done with it.
930 *
931 * Returns: a new #GDateTime, or %NULL
932 *
933 * Since: 2.26
934 **/
935 GDateTime *
936 g_date_time_new (GTimeZone *tz,
937 gint year,
938 gint month,
939 gint day,
940 gint hour,
941 gint minute,
942 gdouble seconds)
943 {
944 GDateTime *datetime;
945 gint64 full_time;
946  
947 g_return_val_if_fail (tz != NULL, NULL);
948  
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)
955 return NULL;
956  
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);
962  
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 +
967 (int) seconds;
968  
969 datetime->interval = g_time_zone_adjust_time (datetime->tz,
970 G_TIME_TYPE_STANDARD,
971 &full_time);
972  
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;
977  
978 return datetime;
979 }
980  
981 /**
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
989 *
990 * Creates a new #GDateTime corresponding to the given date and time in
991 * the local time zone.
992 *
993 * This call is equivalent to calling g_date_time_new() with the time
994 * zone returned by g_time_zone_new_local().
995 *
996 * Returns: a #GDateTime, or %NULL
997 *
998 * Since: 2.26
999 **/
1000 GDateTime *
1001 g_date_time_new_local (gint year,
1002 gint month,
1003 gint day,
1004 gint hour,
1005 gint minute,
1006 gdouble seconds)
1007 {
1008 GDateTime *datetime;
1009 GTimeZone *local;
1010  
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);
1014  
1015 return datetime;
1016 }
1017  
1018 /**
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
1026 *
1027 * Creates a new #GDateTime corresponding to the given date and time in
1028 * UTC.
1029 *
1030 * This call is equivalent to calling g_date_time_new() with the time
1031 * zone returned by g_time_zone_new_utc().
1032 *
1033 * Returns: a #GDateTime, or %NULL
1034 *
1035 * Since: 2.26
1036 **/
1037 GDateTime *
1038 g_date_time_new_utc (gint year,
1039 gint month,
1040 gint day,
1041 gint hour,
1042 gint minute,
1043 gdouble seconds)
1044 {
1045 GDateTime *datetime;
1046 GTimeZone *utc;
1047  
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);
1051  
1052 return datetime;
1053 }
1054  
1055 /* Adders {{{1 */
1056  
1057 /**
1058 * g_date_time_add:
1059 * @datetime: a #GDateTime
1060 * @timespan: a #GTimeSpan
1061 *
1062 * Creates a copy of @datetime and adds the specified timespan to the copy.
1063 *
1064 * Returns: the newly created #GDateTime which should be freed with
1065 * g_date_time_unref().
1066 *
1067 * Since: 2.26
1068 */
1069 GDateTime*
1070 g_date_time_add (GDateTime *datetime,
1071 GTimeSpan timespan)
1072 {
1073 return g_date_time_from_instant (datetime->tz, timespan +
1074 g_date_time_to_instant (datetime));
1075 }
1076  
1077 /**
1078 * g_date_time_add_years:
1079 * @datetime: a #GDateTime
1080 * @years: the number of years
1081 *
1082 * Creates a copy of @datetime and adds the specified number of years to the
1083 * copy. Add negative values to subtract years.
1084 *
1085 * Returns: the newly created #GDateTime which should be freed with
1086 * g_date_time_unref().
1087 *
1088 * Since: 2.26
1089 */
1090 GDateTime *
1091 g_date_time_add_years (GDateTime *datetime,
1092 gint years)
1093 {
1094 gint year, month, day;
1095  
1096 g_return_val_if_fail (datetime != NULL, NULL);
1097  
1098 if (years < -10000 || years > 10000)
1099 return NULL;
1100  
1101 g_date_time_get_ymd (datetime, &year, &month, &day);
1102 year += years;
1103  
1104 /* only possible issue is if we've entered a year with no February 29
1105 */
1106 if (month == 2 && day == 29 && !GREGORIAN_LEAP (year))
1107 day = 28;
1108  
1109 return g_date_time_replace_days (datetime, ymd_to_days (year, month, day));
1110 }
1111  
1112 /**
1113 * g_date_time_add_months:
1114 * @datetime: a #GDateTime
1115 * @months: the number of months
1116 *
1117 * Creates a copy of @datetime and adds the specified number of months to the
1118 * copy. Add negative values to subtract months.
1119 *
1120 * Returns: the newly created #GDateTime which should be freed with
1121 * g_date_time_unref().
1122 *
1123 * Since: 2.26
1124 */
1125 GDateTime*
1126 g_date_time_add_months (GDateTime *datetime,
1127 gint months)
1128 {
1129 gint year, month, day;
1130  
1131 g_return_val_if_fail (datetime != NULL, NULL);
1132 g_date_time_get_ymd (datetime, &year, &month, &day);
1133  
1134 if (months < -120000 || months > 120000)
1135 return NULL;
1136  
1137 year += months / 12;
1138 month += months % 12;
1139 if (month < 1)
1140 {
1141 month += 12;
1142 year--;
1143 }
1144 else if (month > 12)
1145 {
1146 month -= 12;
1147 year++;
1148 }
1149  
1150 day = MIN (day, days_in_months[GREGORIAN_LEAP (year)][month]);
1151  
1152 return g_date_time_replace_days (datetime, ymd_to_days (year, month, day));
1153 }
1154  
1155 /**
1156 * g_date_time_add_weeks:
1157 * @datetime: a #GDateTime
1158 * @weeks: the number of weeks
1159 *
1160 * Creates a copy of @datetime and adds the specified number of weeks to the
1161 * copy. Add negative values to subtract weeks.
1162 *
1163 * Returns: the newly created #GDateTime which should be freed with
1164 * g_date_time_unref().
1165 *
1166 * Since: 2.26
1167 */
1168 GDateTime*
1169 g_date_time_add_weeks (GDateTime *datetime,
1170 gint weeks)
1171 {
1172 g_return_val_if_fail (datetime != NULL, NULL);
1173  
1174 return g_date_time_add_days (datetime, weeks * 7);
1175 }
1176  
1177 /**
1178 * g_date_time_add_days:
1179 * @datetime: a #GDateTime
1180 * @days: the number of days
1181 *
1182 * Creates a copy of @datetime and adds the specified number of days to the
1183 * copy. Add negative values to subtract days.
1184 *
1185 * Returns: the newly created #GDateTime which should be freed with
1186 * g_date_time_unref().
1187 *
1188 * Since: 2.26
1189 */
1190 GDateTime*
1191 g_date_time_add_days (GDateTime *datetime,
1192 gint days)
1193 {
1194 g_return_val_if_fail (datetime != NULL, NULL);
1195  
1196 if (days < -3660000 || days > 3660000)
1197 return NULL;
1198  
1199 return g_date_time_replace_days (datetime, datetime->days + days);
1200 }
1201  
1202 /**
1203 * g_date_time_add_hours:
1204 * @datetime: a #GDateTime
1205 * @hours: the number of hours to add
1206 *
1207 * Creates a copy of @datetime and adds the specified number of hours.
1208 * Add negative values to subtract hours.
1209 *
1210 * Returns: the newly created #GDateTime which should be freed with
1211 * g_date_time_unref().
1212 *
1213 * Since: 2.26
1214 */
1215 GDateTime*
1216 g_date_time_add_hours (GDateTime *datetime,
1217 gint hours)
1218 {
1219 return g_date_time_add (datetime, hours * USEC_PER_HOUR);
1220 }
1221  
1222 /**
1223 * g_date_time_add_minutes:
1224 * @datetime: a #GDateTime
1225 * @minutes: the number of minutes to add
1226 *
1227 * Creates a copy of @datetime adding the specified number of minutes.
1228 * Add negative values to subtract minutes.
1229 *
1230 * Returns: the newly created #GDateTime which should be freed with
1231 * g_date_time_unref().
1232 *
1233 * Since: 2.26
1234 */
1235 GDateTime*
1236 g_date_time_add_minutes (GDateTime *datetime,
1237 gint minutes)
1238 {
1239 return g_date_time_add (datetime, minutes * USEC_PER_MINUTE);
1240 }
1241  
1242  
1243 /**
1244 * g_date_time_add_seconds:
1245 * @datetime: a #GDateTime
1246 * @seconds: the number of seconds to add
1247 *
1248 * Creates a copy of @datetime and adds the specified number of seconds.
1249 * Add negative values to subtract seconds.
1250 *
1251 * Returns: the newly created #GDateTime which should be freed with
1252 * g_date_time_unref().
1253 *
1254 * Since: 2.26
1255 */
1256 GDateTime*
1257 g_date_time_add_seconds (GDateTime *datetime,
1258 gdouble seconds)
1259 {
1260 return g_date_time_add (datetime, seconds * USEC_PER_SECOND);
1261 }
1262  
1263 /**
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
1272 *
1273 * Creates a new #GDateTime adding the specified values to the current date and
1274 * time in @datetime. Add negative values to subtract.
1275 *
1276 * Returns: the newly created #GDateTime that should be freed with
1277 * g_date_time_unref().
1278 *
1279 * Since: 2.26
1280 */
1281 GDateTime *
1282 g_date_time_add_full (GDateTime *datetime,
1283 gint years,
1284 gint months,
1285 gint days,
1286 gint hours,
1287 gint minutes,
1288 gdouble seconds)
1289 {
1290 gint year, month, day;
1291 gint64 full_time;
1292 GDateTime *new;
1293 gint interval;
1294  
1295 g_return_val_if_fail (datetime != NULL, NULL);
1296 g_date_time_get_ymd (datetime, &year, &month, &day);
1297  
1298 months += years * 12;
1299  
1300 if (months < -120000 || months > 120000)
1301 return NULL;
1302  
1303 if (days < -3660000 || days > 3660000)
1304 return NULL;
1305  
1306 year += months / 12;
1307 month += months % 12;
1308 if (month < 1)
1309 {
1310 month += 12;
1311 year--;
1312 }
1313 else if (month > 12)
1314 {
1315 month -= 12;
1316 year++;
1317 }
1318  
1319 day = MIN (day, days_in_months[GREGORIAN_LEAP (year)][month]);
1320  
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);
1324  
1325 interval = g_time_zone_adjust_time (datetime->tz,
1326 g_time_zone_is_dst (datetime->tz,
1327 datetime->interval),
1328 &full_time);
1329  
1330 /* move to UTC unix time */
1331 full_time -= g_time_zone_get_offset (datetime->tz, interval);
1332  
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;
1337  
1338 /* do the actual addition now */
1339 full_time += (hours * USEC_PER_HOUR) +
1340 (minutes * USEC_PER_MINUTE) +
1341 (gint64) (seconds * USEC_PER_SECOND);
1342  
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));
1347  
1348 /* convert back into local time */
1349 full_time += USEC_PER_SECOND *
1350 g_time_zone_get_offset (datetime->tz, interval);
1351  
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;
1357  
1358 /* XXX validate */
1359  
1360 return new;
1361 }
1362  
1363 /* Compare, difference, hash, equal {{{1 */
1364 /**
1365 * g_date_time_compare:
1366 * @dt1: (not nullable): first #GDateTime to compare
1367 * @dt2: (not nullable): second #GDateTime to compare
1368 *
1369 * A comparison function for #GDateTimes that is suitable
1370 * as a #GCompareFunc. Both #GDateTimes must be non-%NULL.
1371 *
1372 * Returns: -1, 0 or 1 if @dt1 is less than, equal to or greater
1373 * than @dt2.
1374 *
1375 * Since: 2.26
1376 */
1377 gint
1378 g_date_time_compare (gconstpointer dt1,
1379 gconstpointer dt2)
1380 {
1381 gint64 difference;
1382  
1383 difference = g_date_time_difference ((GDateTime *) dt1, (GDateTime *) dt2);
1384  
1385 if (difference < 0)
1386 return -1;
1387  
1388 else if (difference > 0)
1389 return 1;
1390  
1391 else
1392 return 0;
1393 }
1394  
1395 /**
1396 * g_date_time_difference:
1397 * @end: a #GDateTime
1398 * @begin: a #GDateTime
1399 *
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).
1403 *
1404 * Returns: the difference between the two #GDateTime, as a time
1405 * span expressed in microseconds.
1406 *
1407 * Since: 2.26
1408 */
1409 GTimeSpan
1410 g_date_time_difference (GDateTime *end,
1411 GDateTime *begin)
1412 {
1413 g_return_val_if_fail (begin != NULL, 0);
1414 g_return_val_if_fail (end != NULL, 0);
1415  
1416 return g_date_time_to_instant (end) -
1417 g_date_time_to_instant (begin);
1418 }
1419  
1420 /**
1421 * g_date_time_hash:
1422 * @datetime: (not nullable): a #GDateTime
1423 *
1424 * Hashes @datetime into a #guint, suitable for use within #GHashTable.
1425 *
1426 * Returns: a #guint containing the hash
1427 *
1428 * Since: 2.26
1429 */
1430 guint
1431 g_date_time_hash (gconstpointer datetime)
1432 {
1433 return g_date_time_to_instant ((GDateTime *) datetime);
1434 }
1435  
1436 /**
1437 * g_date_time_equal:
1438 * @dt1: (not nullable): a #GDateTime
1439 * @dt2: (not nullable): a #GDateTime
1440 *
1441 * Checks to see if @dt1 and @dt2 are equal.
1442 *
1443 * Equal here means that they represent the same moment after converting
1444 * them to the same time zone.
1445 *
1446 * Returns: %TRUE if @dt1 and @dt2 are equal
1447 *
1448 * Since: 2.26
1449 */
1450 gboolean
1451 g_date_time_equal (gconstpointer dt1,
1452 gconstpointer dt2)
1453 {
1454 return g_date_time_difference ((GDateTime *) dt1, (GDateTime *) dt2) == 0;
1455 }
1456  
1457 /* Year, Month, Day Getters {{{1 */
1458 /**
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.
1464 *
1465 * Retrieves the Gregorian day, month, and year of a given #GDateTime.
1466 *
1467 * Since: 2.26
1468 **/
1469 void
1470 g_date_time_get_ymd (GDateTime *datetime,
1471 gint *year,
1472 gint *month,
1473 gint *day)
1474 {
1475 gint the_year;
1476 gint the_month;
1477 gint the_day;
1478 gint remaining_days;
1479 gint y100_cycles;
1480 gint y4_cycles;
1481 gint y1_cycles;
1482 gint preceding;
1483 gboolean leap;
1484  
1485 g_return_if_fail (datetime != NULL);
1486  
1487 remaining_days = datetime->days;
1488  
1489 /*
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.
1493 */
1494  
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 */
1497 remaining_days--;
1498  
1499 the_year = (remaining_days / DAYS_IN_400YEARS) * 400 + 1;
1500 remaining_days = remaining_days % DAYS_IN_400YEARS;
1501  
1502 y100_cycles = remaining_days / DAYS_IN_100YEARS;
1503 remaining_days = remaining_days % DAYS_IN_100YEARS;
1504 the_year += y100_cycles * 100;
1505  
1506 y4_cycles = remaining_days / DAYS_IN_4YEARS;
1507 remaining_days = remaining_days % DAYS_IN_4YEARS;
1508 the_year += y4_cycles * 4;
1509  
1510 y1_cycles = remaining_days / 365;
1511 the_year += y1_cycles;
1512 remaining_days = remaining_days % 365;
1513  
1514 if (y1_cycles == 4 || y100_cycles == 4) {
1515 g_assert (remaining_days == 0);
1516  
1517 /* special case that indicates that the date is actually one year before,
1518 * in the 31th of December */
1519 the_year--;
1520 the_month = 12;
1521 the_day = 31;
1522 goto end;
1523 }
1524  
1525 /* now get the month and the day */
1526 leap = y1_cycles == 3 && (y4_cycles != 24 || y100_cycles == 3);
1527  
1528 g_assert (leap == GREGORIAN_LEAP(the_year));
1529  
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)
1533 {
1534 /* estimate is too large */
1535 the_month -= 1;
1536 preceding -= leap ? days_in_months[1][the_month]
1537 : days_in_months[0][the_month];
1538 }
1539  
1540 remaining_days -= preceding;
1541 g_assert(0 <= remaining_days);
1542  
1543 the_day = remaining_days + 1;
1544  
1545 end:
1546 if (year)
1547 *year = the_year;
1548 if (month)
1549 *month = the_month;
1550 if (day)
1551 *day = the_day;
1552 }
1553  
1554 /**
1555 * g_date_time_get_year:
1556 * @datetime: A #GDateTime
1557 *
1558 * Retrieves the year represented by @datetime in the Gregorian calendar.
1559 *
1560 * Returns: the year represented by @datetime
1561 *
1562 * Since: 2.26
1563 */
1564 gint
1565 g_date_time_get_year (GDateTime *datetime)
1566 {
1567 gint year;
1568  
1569 g_return_val_if_fail (datetime != NULL, 0);
1570  
1571 g_date_time_get_ymd (datetime, &year, NULL, NULL);
1572  
1573 return year;
1574 }
1575  
1576 /**
1577 * g_date_time_get_month:
1578 * @datetime: a #GDateTime
1579 *
1580 * Retrieves the month of the year represented by @datetime in the Gregorian
1581 * calendar.
1582 *
1583 * Returns: the month represented by @datetime
1584 *
1585 * Since: 2.26
1586 */
1587 gint
1588 g_date_time_get_month (GDateTime *datetime)
1589 {
1590 gint month;
1591  
1592 g_return_val_if_fail (datetime != NULL, 0);
1593  
1594 g_date_time_get_ymd (datetime, NULL, &month, NULL);
1595  
1596 return month;
1597 }
1598  
1599 /**
1600 * g_date_time_get_day_of_month:
1601 * @datetime: a #GDateTime
1602 *
1603 * Retrieves the day of the month represented by @datetime in the gregorian
1604 * calendar.
1605 *
1606 * Returns: the day of the month
1607 *
1608 * Since: 2.26
1609 */
1610 gint
1611 g_date_time_get_day_of_month (GDateTime *datetime)
1612 {
1613 gint day_of_year,
1614 i;
1615 const guint16 *days;
1616 guint16 last = 0;
1617  
1618 g_return_val_if_fail (datetime != NULL, 0);
1619  
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);
1622  
1623 for (i = 1; i <= 12; i++)
1624 {
1625 if (days [i] >= day_of_year)
1626 return day_of_year - last;
1627 last = days [i];
1628 }
1629  
1630 g_warn_if_reached ();
1631 return 0;
1632 }
1633  
1634 /* Week of year / day of week getters {{{1 */
1635 /**
1636 * g_date_time_get_week_numbering_year:
1637 * @datetime: a #GDateTime
1638 *
1639 * Returns the ISO 8601 week-numbering year in which the week containing
1640 * @datetime falls.
1641 *
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.
1645 *
1646 * This is usually equal to the normal Gregorian year (as returned by
1647 * g_date_time_get_year()), except as detailed below:
1648 *
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.
1653 *
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).
1658 *
1659 * For Friday, Saturday 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).
1663 *
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).
1667 *
1668 * Note that January 1 0001 in the proleptic Gregorian calendar is a
1669 * Monday, so this function never returns 0.
1670 *
1671 * Returns: the ISO 8601 week-numbering year for @datetime
1672 *
1673 * Since: 2.26
1674 **/
1675 gint
1676 g_date_time_get_week_numbering_year (GDateTime *datetime)
1677 {
1678 gint year, month, day, weekday;
1679  
1680 g_date_time_get_ymd (datetime, &year, &month, &day);
1681 weekday = g_date_time_get_day_of_week (datetime);
1682  
1683 /* January 1, 2, 3 might be in the previous year if they occur after
1684 * Thursday.
1685 *
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
1689 *
1690 * So we have a special case if (day - weekday) <= -4
1691 */
1692 if (month == 1 && (day - weekday) <= -4)
1693 return year - 1;
1694  
1695 /* December 29, 30, 31 might be in the next year if they occur before
1696 * Thursday.
1697 *
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
1701 *
1702 * So we have a special case if (day - weekday) >= 28
1703 */
1704 else if (month == 12 && (day - weekday) >= 28)
1705 return year + 1;
1706  
1707 else
1708 return year;
1709 }
1710  
1711 /**
1712 * g_date_time_get_week_of_year:
1713 * @datetime: a #GDateTime
1714 *
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).
1719 *
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.
1723 *
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.
1730 *
1731 * Returns: the ISO 8601 week number for @datetime.
1732 *
1733 * Since: 2.26
1734 */
1735 gint
1736 g_date_time_get_week_of_year (GDateTime *datetime)
1737 {
1738 gint weeknum;
1739  
1740 g_return_val_if_fail (datetime != NULL, 0);
1741  
1742 g_date_time_get_week_number (datetime, &weeknum, NULL, NULL);
1743  
1744 return weeknum;
1745 }
1746  
1747 /**
1748 * g_date_time_get_day_of_week:
1749 * @datetime: a #GDateTime
1750 *
1751 * Retrieves the ISO 8601 day of the week on which @datetime falls (1 is
1752 * Monday, 2 is Tuesday... 7 is Sunday).
1753 *
1754 * Returns: the day of the week
1755 *
1756 * Since: 2.26
1757 */
1758 gint
1759 g_date_time_get_day_of_week (GDateTime *datetime)
1760 {
1761 g_return_val_if_fail (datetime != NULL, 0);
1762  
1763 return (datetime->days - 1) % 7 + 1;
1764 }
1765  
1766 /* Day of year getter {{{1 */
1767 /**
1768 * g_date_time_get_day_of_year:
1769 * @datetime: a #GDateTime
1770 *
1771 * Retrieves the day of the year represented by @datetime in the Gregorian
1772 * calendar.
1773 *
1774 * Returns: the day of the year
1775 *
1776 * Since: 2.26
1777 */
1778 gint
1779 g_date_time_get_day_of_year (GDateTime *datetime)
1780 {
1781 gint doy = 0;
1782  
1783 g_return_val_if_fail (datetime != NULL, 0);
1784  
1785 g_date_time_get_week_number (datetime, NULL, NULL, &doy);
1786 return doy;
1787 }
1788  
1789 /* Time component getters {{{1 */
1790  
1791 /**
1792 * g_date_time_get_hour:
1793 * @datetime: a #GDateTime
1794 *
1795 * Retrieves the hour of the day represented by @datetime
1796 *
1797 * Returns: the hour of the day
1798 *
1799 * Since: 2.26
1800 */
1801 gint
1802 g_date_time_get_hour (GDateTime *datetime)
1803 {
1804 g_return_val_if_fail (datetime != NULL, 0);
1805  
1806 return (datetime->usec / USEC_PER_HOUR);
1807 }
1808  
1809 /**
1810 * g_date_time_get_minute:
1811 * @datetime: a #GDateTime
1812 *
1813 * Retrieves the minute of the hour represented by @datetime
1814 *
1815 * Returns: the minute of the hour
1816 *
1817 * Since: 2.26
1818 */
1819 gint
1820 g_date_time_get_minute (GDateTime *datetime)
1821 {
1822 g_return_val_if_fail (datetime != NULL, 0);
1823  
1824 return (datetime->usec % USEC_PER_HOUR) / USEC_PER_MINUTE;
1825 }
1826  
1827 /**
1828 * g_date_time_get_second:
1829 * @datetime: a #GDateTime
1830 *
1831 * Retrieves the second of the minute represented by @datetime
1832 *
1833 * Returns: the second represented by @datetime
1834 *
1835 * Since: 2.26
1836 */
1837 gint
1838 g_date_time_get_second (GDateTime *datetime)
1839 {
1840 g_return_val_if_fail (datetime != NULL, 0);
1841  
1842 return (datetime->usec % USEC_PER_MINUTE) / USEC_PER_SECOND;
1843 }
1844  
1845 /**
1846 * g_date_time_get_microsecond:
1847 * @datetime: a #GDateTime
1848 *
1849 * Retrieves the microsecond of the date represented by @datetime
1850 *
1851 * Returns: the microsecond of the second
1852 *
1853 * Since: 2.26
1854 */
1855 gint
1856 g_date_time_get_microsecond (GDateTime *datetime)
1857 {
1858 g_return_val_if_fail (datetime != NULL, 0);
1859  
1860 return (datetime->usec % USEC_PER_SECOND);
1861 }
1862  
1863 /**
1864 * g_date_time_get_seconds:
1865 * @datetime: a #GDateTime
1866 *
1867 * Retrieves the number of seconds since the start of the last minute,
1868 * including the fractional part.
1869 *
1870 * Returns: the number of seconds
1871 *
1872 * Since: 2.26
1873 **/
1874 gdouble
1875 g_date_time_get_seconds (GDateTime *datetime)
1876 {
1877 g_return_val_if_fail (datetime != NULL, 0);
1878  
1879 return (datetime->usec % USEC_PER_MINUTE) / 1000000.0;
1880 }
1881  
1882 /* Exporters {{{1 */
1883 /**
1884 * g_date_time_to_unix:
1885 * @datetime: a #GDateTime
1886 *
1887 * Gives the Unix time corresponding to @datetime, rounding down to the
1888 * nearest second.
1889 *
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.
1892 *
1893 * Returns: the Unix time corresponding to @datetime
1894 *
1895 * Since: 2.26
1896 **/
1897 gint64
1898 g_date_time_to_unix (GDateTime *datetime)
1899 {
1900 return INSTANT_TO_UNIX (g_date_time_to_instant (datetime));
1901 }
1902  
1903 /**
1904 * g_date_time_to_timeval:
1905 * @datetime: a #GDateTime
1906 * @tv: a #GTimeVal to modify
1907 *
1908 * Stores the instant in time that @datetime represents into @tv.
1909 *
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.
1913 *
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
1918 * out of range.
1919 *
1920 * On systems where 'long' is 64bit, this function never fails.
1921 *
1922 * Returns: %TRUE if successful, else %FALSE
1923 *
1924 * Since: 2.26
1925 **/
1926 gboolean
1927 g_date_time_to_timeval (GDateTime *datetime,
1928 GTimeVal *tv)
1929 {
1930 tv->tv_sec = INSTANT_TO_UNIX (g_date_time_to_instant (datetime));
1931 tv->tv_usec = datetime->usec % USEC_PER_SECOND;
1932  
1933 return TRUE;
1934 }
1935  
1936 /* Timezone queries {{{1 */
1937 /**
1938 * g_date_time_get_utc_offset:
1939 * @datetime: a #GDateTime
1940 *
1941 * Determines the offset to UTC in effect at the time and in the time
1942 * zone of @datetime.
1943 *
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).
1947 *
1948 * If @datetime represents UTC time, then the offset is always zero.
1949 *
1950 * Returns: the number of microseconds that should be added to UTC to
1951 * get the local time
1952 *
1953 * Since: 2.26
1954 **/
1955 GTimeSpan
1956 g_date_time_get_utc_offset (GDateTime *datetime)
1957 {
1958 gint offset;
1959  
1960 g_return_val_if_fail (datetime != NULL, 0);
1961  
1962 offset = g_time_zone_get_offset (datetime->tz, datetime->interval);
1963  
1964 return (gint64) offset * USEC_PER_SECOND;
1965 }
1966  
1967 /**
1968 * g_date_time_get_timezone_abbreviation:
1969 * @datetime: a #GDateTime
1970 *
1971 * Determines the time zone abbreviation to be used at the time and in
1972 * the time zone of @datetime.
1973 *
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.
1977 *
1978 * Returns: (transfer none): the time zone abbreviation. The returned
1979 * string is owned by the #GDateTime and it should not be
1980 * modified or freed
1981 *
1982 * Since: 2.26
1983 **/
1984 const gchar *
1985 g_date_time_get_timezone_abbreviation (GDateTime *datetime)
1986 {
1987 g_return_val_if_fail (datetime != NULL, NULL);
1988  
1989 return g_time_zone_get_abbreviation (datetime->tz, datetime->interval);
1990 }
1991  
1992 /**
1993 * g_date_time_is_daylight_savings:
1994 * @datetime: a #GDateTime
1995 *
1996 * Determines if daylight savings time is in effect at the time and in
1997 * the time zone of @datetime.
1998 *
1999 * Returns: %TRUE if daylight savings time is in effect
2000 *
2001 * Since: 2.26
2002 **/
2003 gboolean
2004 g_date_time_is_daylight_savings (GDateTime *datetime)
2005 {
2006 g_return_val_if_fail (datetime != NULL, FALSE);
2007  
2008 return g_time_zone_is_dst (datetime->tz, datetime->interval);
2009 }
2010  
2011 /* Timezone convert {{{1 */
2012 /**
2013 * g_date_time_to_timezone:
2014 * @datetime: a #GDateTime
2015 * @tz: the new #GTimeZone
2016 *
2017 * Create a new #GDateTime corresponding to the same instant in time as
2018 * @datetime, but in the time zone @tz.
2019 *
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).
2023 *
2024 * You should release the return value by calling g_date_time_unref()
2025 * when you are done with it.
2026 *
2027 * Returns: a new #GDateTime, or %NULL
2028 *
2029 * Since: 2.26
2030 **/
2031 GDateTime *
2032 g_date_time_to_timezone (GDateTime *datetime,
2033 GTimeZone *tz)
2034 {
2035 return g_date_time_from_instant (tz, g_date_time_to_instant (datetime));
2036 }
2037  
2038 /**
2039 * g_date_time_to_local:
2040 * @datetime: a #GDateTime
2041 *
2042 * Creates a new #GDateTime corresponding to the same instant in time as
2043 * @datetime, but in the local time zone.
2044 *
2045 * This call is equivalent to calling g_date_time_to_timezone() with the
2046 * time zone returned by g_time_zone_new_local().
2047 *
2048 * Returns: the newly created #GDateTime
2049 *
2050 * Since: 2.26
2051 **/
2052 GDateTime *
2053 g_date_time_to_local (GDateTime *datetime)
2054 {
2055 GDateTime *new;
2056 GTimeZone *local;
2057  
2058 local = g_time_zone_new_local ();
2059 new = g_date_time_to_timezone (datetime, local);
2060 g_time_zone_unref (local);
2061  
2062 return new;
2063 }
2064  
2065 /**
2066 * g_date_time_to_utc:
2067 * @datetime: a #GDateTime
2068 *
2069 * Creates a new #GDateTime corresponding to the same instant in time as
2070 * @datetime, but in UTC.
2071 *
2072 * This call is equivalent to calling g_date_time_to_timezone() with the
2073 * time zone returned by g_time_zone_new_utc().
2074 *
2075 * Returns: the newly created #GDateTime
2076 *
2077 * Since: 2.26
2078 **/
2079 GDateTime *
2080 g_date_time_to_utc (GDateTime *datetime)
2081 {
2082 GDateTime *new;
2083 GTimeZone *utc;
2084  
2085 utc = g_time_zone_new_utc ();
2086 new = g_date_time_to_timezone (datetime, utc);
2087 g_time_zone_unref (utc);
2088  
2089 return new;
2090 }
2091  
2092 /* Format {{{1 */
2093  
2094 static gboolean
2095 format_z (GString *outstr,
2096 gint offset,
2097 guint colons)
2098 {
2099 gint hours;
2100 gint minutes;
2101 gint seconds;
2102  
2103 hours = offset / 3600;
2104 minutes = ABS (offset) / 60 % 60;
2105 seconds = ABS (offset) % 60;
2106  
2107 switch (colons)
2108 {
2109 case 0:
2110 g_string_append_printf (outstr, "%+03d%02d",
2111 hours,
2112 minutes);
2113 break;
2114  
2115 case 1:
2116 g_string_append_printf (outstr, "%+03d:%02d",
2117 hours,
2118 minutes);
2119 break;
2120  
2121 case 2:
2122 g_string_append_printf (outstr, "%+03d:%02d:%02d",
2123 hours,
2124 minutes,
2125 seconds);
2126 break;
2127  
2128 case 3:
2129 g_string_append_printf (outstr, "%+03d", hours);
2130  
2131 if (minutes != 0 || seconds != 0)
2132 {
2133 g_string_append_printf (outstr, ":%02d", minutes);
2134  
2135 if (seconds != 0)
2136 g_string_append_printf (outstr, ":%02d", seconds);
2137 }
2138 break;
2139  
2140 default:
2141 return FALSE;
2142 }
2143  
2144 return TRUE;
2145 }
2146  
2147 static void
2148 format_number (GString *str,
2149 gboolean use_alt_digits,
2150 gchar *pad,
2151 gint width,
2152 guint32 number)
2153 {
2154 const gchar *ascii_digits[10] = {
2155 "0", "1", "2", "3", "4", "5", "6", "7", "8", "9"
2156 };
2157 const gchar **digits = ascii_digits;
2158 const gchar *tmp[10];
2159 gint i = 0;
2160  
2161 g_return_if_fail (width <= 10);
2162  
2163 #ifdef HAVE_LANGINFO_OUTDIGIT
2164 if (use_alt_digits)
2165 {
2166 static const gchar *alt_digits[10];
2167 static gsize initialised;
2168 /* 2^32 has 10 digits */
2169  
2170 if G_UNLIKELY (g_once_init_enter (&initialised))
2171 {
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);
2176 #undef DO_DIGIT
2177 g_once_init_leave (&initialised, TRUE);
2178 }
2179  
2180 digits = alt_digits;
2181 }
2182 #endif /* HAVE_LANGINFO_OUTDIGIT */
2183  
2184 do
2185 {
2186 tmp[i++] = digits[number % 10];
2187 number /= 10;
2188 }
2189 while (number);
2190  
2191 while (pad && i < width)
2192 tmp[i++] = *pad == '0' ? digits[0] : pad;
2193  
2194 /* should really be impossible */
2195 g_assert (i <= 10);
2196  
2197 while (i)
2198 g_string_append (str, tmp[--i]);
2199 }
2200  
2201 static gboolean g_date_time_format_locale (GDateTime *datetime,
2202 const gchar *format,
2203 GString *outstr,
2204 gboolean locale_is_utf8);
2205  
2206 /* g_date_time_format() subroutine that takes a locale-encoded format
2207 * string and produces a locale-encoded date/time string.
2208 */
2209 static gboolean
2210 g_date_time_locale_format_locale (GDateTime *datetime,
2211 const gchar *format,
2212 GString *outstr,
2213 gboolean locale_is_utf8)
2214 {
2215 gchar *utf8_format;
2216 gboolean success;
2217  
2218 if (locale_is_utf8)
2219 return g_date_time_format_locale (datetime, format, outstr,
2220 locale_is_utf8);
2221  
2222 utf8_format = g_locale_to_utf8 (format, -1, NULL, NULL, NULL);
2223 if (!utf8_format)
2224 return FALSE;
2225  
2226 success = g_date_time_format_locale (datetime, utf8_format, outstr,
2227 locale_is_utf8);
2228 g_free (utf8_format);
2229 return success;
2230 }
2231  
2232 /* g_date_time_format() subroutine that takes a UTF-8 format
2233 * string and produces a locale-encoded date/time string.
2234 */
2235 static gboolean
2236 g_date_time_format_locale (GDateTime *datetime,
2237 const gchar *format,
2238 GString *outstr,
2239 gboolean locale_is_utf8)
2240 {
2241 guint len;
2242 guint colons;
2243 gchar *tmp;
2244 gunichar c;
2245 gboolean alt_digits = FALSE;
2246 gboolean pad_set = FALSE;
2247 gchar *pad = "";
2248 gchar *ampm;
2249 const gchar *tz;
2250  
2251 while (*format)
2252 {
2253 len = strcspn (format, "%");
2254 if (len)
2255 {
2256 if (locale_is_utf8)
2257 g_string_append_len (outstr, format, len);
2258 else
2259 {
2260 tmp = g_locale_from_utf8 (format, len, NULL, NULL, NULL);
2261 if (!tmp)
2262 return FALSE;
2263 g_string_append (outstr, tmp);
2264 g_free (tmp);
2265 }
2266 }
2267  
2268 format += len;
2269 if (!*format)
2270 break;
2271  
2272 g_assert (*format == '%');
2273 format++;
2274 if (!*format)
2275 break;
2276  
2277 colons = 0;
2278 alt_digits = FALSE;
2279 pad_set = FALSE;
2280  
2281 next_mod:
2282 c = g_utf8_get_char (format);
2283 format = g_utf8_next_char (format);
2284 switch (c)
2285 {
2286 case 'a':
2287 g_string_append (outstr, WEEKDAY_ABBR (datetime));
2288 break;
2289 case 'A':
2290 g_string_append (outstr, WEEKDAY_FULL (datetime));
2291 break;
2292 case 'b':
2293 g_string_append (outstr, MONTH_ABBR (datetime));
2294 break;
2295 case 'B':
2296 g_string_append (outstr, MONTH_FULL (datetime));
2297 break;
2298 case 'c':
2299 {
2300 if (!g_date_time_locale_format_locale (datetime, PREFERRED_DATE_TIME_FMT,
2301 outstr, locale_is_utf8))
2302 return FALSE;
2303 }
2304 break;
2305 case 'C':
2306 format_number (outstr, alt_digits, pad_set ? pad : "0", 2,
2307 g_date_time_get_year (datetime) / 100);
2308 break;
2309 case 'd':
2310 format_number (outstr, alt_digits, pad_set ? pad : "0", 2,
2311 g_date_time_get_day_of_month (datetime));
2312 break;
2313 case 'e':
2314 format_number (outstr, alt_digits, pad_set ? pad : " ", 2,
2315 g_date_time_get_day_of_month (datetime));
2316 break;
2317 case 'F':
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));
2322 break;
2323 case 'g':
2324 format_number (outstr, alt_digits, pad_set ? pad : "0", 2,
2325 g_date_time_get_week_numbering_year (datetime) % 100);
2326 break;
2327 case 'G':
2328 format_number (outstr, alt_digits, pad_set ? pad : 0, 0,
2329 g_date_time_get_week_numbering_year (datetime));
2330 break;
2331 case 'h':
2332 g_string_append (outstr, MONTH_ABBR (datetime));
2333 break;
2334 case 'H':
2335 format_number (outstr, alt_digits, pad_set ? pad : "0", 2,
2336 g_date_time_get_hour (datetime));
2337 break;
2338 case 'I':
2339 format_number (outstr, alt_digits, pad_set ? pad : "0", 2,
2340 (g_date_time_get_hour (datetime) + 11) % 12 + 1);
2341 break;
2342 case 'j':
2343 format_number (outstr, alt_digits, pad_set ? pad : "0", 3,
2344 g_date_time_get_day_of_year (datetime));
2345 break;
2346 case 'k':
2347 format_number (outstr, alt_digits, pad_set ? pad : " ", 2,
2348 g_date_time_get_hour (datetime));
2349 break;
2350 case 'l':
2351 format_number (outstr, alt_digits, pad_set ? pad : " ", 2,
2352 (g_date_time_get_hour (datetime) + 11) % 12 + 1);
2353 break;
2354 case 'n':
2355 g_string_append_c (outstr, '\n');
2356 break;
2357 case 'm':
2358 format_number (outstr, alt_digits, pad_set ? pad : "0", 2,
2359 g_date_time_get_month (datetime));
2360 break;
2361 case 'M':
2362 format_number (outstr, alt_digits, pad_set ? pad : "0", 2,
2363 g_date_time_get_minute (datetime));
2364 break;
2365 case 'O':
2366 alt_digits = TRUE;
2367 goto next_mod;
2368 case 'p':
2369 ampm = (gchar *) GET_AMPM (datetime);
2370 if (!locale_is_utf8)
2371 {
2372 ampm = tmp = g_locale_to_utf8 (ampm, -1, NULL, NULL, NULL);
2373 if (!tmp)
2374 return FALSE;
2375 }
2376 ampm = g_utf8_strup (ampm, -1);
2377 if (!locale_is_utf8)
2378 {
2379 g_free (tmp);
2380 tmp = g_locale_from_utf8 (ampm, -1, NULL, NULL, NULL);
2381 g_free (ampm);
2382 if (!tmp)
2383 return FALSE;
2384 ampm = tmp;
2385 }
2386 g_string_append (outstr, ampm);
2387 g_free (ampm);
2388 break;
2389 case 'P':
2390 ampm = (gchar *) GET_AMPM (datetime);
2391 if (!locale_is_utf8)
2392 {
2393 ampm = tmp = g_locale_to_utf8 (ampm, -1, NULL, NULL, NULL);
2394 if (!tmp)
2395 return FALSE;
2396 }
2397 ampm = g_utf8_strdown (ampm, -1);
2398 if (!locale_is_utf8)
2399 {
2400 g_free (tmp);
2401 tmp = g_locale_from_utf8 (ampm, -1, NULL, NULL, NULL);
2402 g_free (ampm);
2403 if (!tmp)
2404 return FALSE;
2405 ampm = tmp;
2406 }
2407 g_string_append (outstr, ampm);
2408 g_free (ampm);
2409 break;
2410 case 'r':
2411 {
2412 if (!g_date_time_locale_format_locale (datetime, PREFERRED_12HR_TIME_FMT,
2413 outstr, locale_is_utf8))
2414 return FALSE;
2415 }
2416 break;
2417 case 'R':
2418 g_string_append_printf (outstr, "%02d:%02d",
2419 g_date_time_get_hour (datetime),
2420 g_date_time_get_minute (datetime));
2421 break;
2422 case 's':
2423 g_string_append_printf (outstr, "%" G_GINT64_FORMAT, g_date_time_to_unix (datetime));
2424 break;
2425 case 'S':
2426 format_number (outstr, alt_digits, pad_set ? pad : "0", 2,
2427 g_date_time_get_second (datetime));
2428 break;
2429 case 't':
2430 g_string_append_c (outstr, '\t');
2431 break;
2432 case '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));
2437 break;
2438 case 'u':
2439 format_number (outstr, alt_digits, 0, 0,
2440 g_date_time_get_day_of_week (datetime));
2441 break;
2442 case 'V':
2443 format_number (outstr, alt_digits, pad_set ? pad : "0", 2,
2444 g_date_time_get_week_of_year (datetime));
2445 break;
2446 case 'w':
2447 format_number (outstr, alt_digits, 0, 0,
2448 g_date_time_get_day_of_week (datetime) % 7);
2449 break;
2450 case 'x':
2451 {
2452 if (!g_date_time_locale_format_locale (datetime, PREFERRED_DATE_FMT,
2453 outstr, locale_is_utf8))
2454 return FALSE;
2455 }
2456 break;
2457 case 'X':
2458 {
2459 if (!g_date_time_locale_format_locale (datetime, PREFERRED_TIME_FMT,
2460 outstr, locale_is_utf8))
2461 return FALSE;
2462 }
2463 break;
2464 case 'y':
2465 format_number (outstr, alt_digits, pad_set ? pad : "0", 2,
2466 g_date_time_get_year (datetime) % 100);
2467 break;
2468 case 'Y':
2469 format_number (outstr, alt_digits, 0, 0,
2470 g_date_time_get_year (datetime));
2471 break;
2472 case 'z':
2473 {
2474 gint64 offset;
2475 if (datetime->tz != NULL)
2476 offset = g_date_time_get_utc_offset (datetime) / USEC_PER_SECOND;
2477 else
2478 offset = 0;
2479 if (!format_z (outstr, (int) offset, colons))
2480 return FALSE;
2481 }
2482 break;
2483 case 'Z':
2484 tz = g_date_time_get_timezone_abbreviation (datetime);
2485 if (!locale_is_utf8)
2486 {
2487 tz = tmp = g_locale_from_utf8 (tz, -1, NULL, NULL, NULL);
2488 if (!tmp)
2489 return FALSE;
2490 }
2491 g_string_append (outstr, tz);
2492 if (!locale_is_utf8)
2493 g_free (tmp);
2494 break;
2495 case '%':
2496 g_string_append_c (outstr, '%');
2497 break;
2498 case '-':
2499 pad_set = TRUE;
2500 pad = "";
2501 goto next_mod;
2502 case '_':
2503 pad_set = TRUE;
2504 pad = " ";
2505 goto next_mod;
2506 case '0':
2507 pad_set = TRUE;
2508 pad = "0";
2509 goto next_mod;
2510 case ':':
2511 /* Colons are only allowed before 'z' */
2512 if (*format && *format != 'z' && *format != ':')
2513 return FALSE;
2514 colons++;
2515 goto next_mod;
2516 default:
2517 return FALSE;
2518 }
2519 }
2520  
2521 return TRUE;
2522 }
2523  
2524 /**
2525 * g_date_time_format:
2526 * @datetime: A #GDateTime
2527 * @format: a valid UTF-8 string, containing the format for the
2528 * #GDateTime
2529 *
2530 * Creates a newly allocated string representing the requested @format.
2531 *
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.
2537 *
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()
2541 * output exactly.
2542 *
2543 * The following format specifiers are supported:
2544 *
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 representation 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
2576 * 00:00:00 UTC
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
2589 * the time
2590 * - \%X: the preferred time representation for the current locale without
2591 * the date
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
2603 *
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
2607 * conversions:
2608 *
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.
2616 *
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().
2620 *
2621 * Since: 2.26
2622 */
2623 gchar *
2624 g_date_time_format (GDateTime *datetime,
2625 const gchar *format)
2626 {
2627 GString *outstr;
2628 gchar *utf8;
2629 gboolean locale_is_utf8 = g_get_charset (NULL);
2630  
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);
2634  
2635 outstr = g_string_sized_new (strlen (format) * 2);
2636  
2637 if (!g_date_time_format_locale (datetime, format, outstr, locale_is_utf8))
2638 {
2639 g_string_free (outstr, TRUE);
2640 return NULL;
2641 }
2642  
2643 if (locale_is_utf8)
2644 return g_string_free (outstr, FALSE);
2645  
2646 utf8 = g_locale_to_utf8 (outstr->str, outstr->len, NULL, NULL, NULL);
2647 g_string_free (outstr, TRUE);
2648 return utf8;
2649 }
2650  
2651  
2652 /* Epilogue {{{1 */
2653 /* vim:set foldmethod=marker: */