glib/gdatetime.c

   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   if (year < 1 || year > 9999 ||
 948       month < 1 || month > 12 ||
 949       day < 1 || day > 31 ||
 950       hour < 0 || hour > 23 ||
 951       minute < 0 || minute > 59 ||
 952       seconds < 0.0 || seconds >= 60.0)
 953     return NULL;
 954
 955   datetime = g_date_time_alloc (tz);
 956   datetime->days = ymd_to_days (year, month, day);
 957   datetime->usec = (hour   * USEC_PER_HOUR)
 958                  + (minute * USEC_PER_MINUTE)
 959                  + (gint64) (seconds * USEC_PER_SECOND);
 960
 961   full_time = SEC_PER_DAY *
 962                 (ymd_to_days (year, month, day) - UNIX_EPOCH_START) +
 963               SECS_PER_HOUR * hour +
 964               SECS_PER_MINUTE * minute +
 965               (int) seconds;
 966
 967   datetime->interval = g_time_zone_adjust_time (datetime->tz,
 968                                                 G_TIME_TYPE_STANDARD,
 969                                                 &full_time);
 970
 971   full_time += UNIX_EPOCH_START * SEC_PER_DAY;
 972   datetime->days = full_time / SEC_PER_DAY;
 973   datetime->usec = (full_time % SEC_PER_DAY) * USEC_PER_SECOND;
 974   datetime->usec += ((int) (seconds * USEC_PER_SECOND)) % USEC_PER_SECOND;
 975
 976   return datetime;
 977 }
 978
 979 /**
 980  * g_date_time_new_local:
 981  * @year: the year component of the date
 982  * @month: the month component of the date
 983  * @day: the day component of the date
 984  * @hour: the hour component of the date
 985  * @minute: the minute component of the date
 986  * @seconds: the number of seconds past the minute
 987  *
 988  * Creates a new #GDateTime corresponding to the given date and time in
 989  * the local time zone.
 990  *
 991  * This call is equivalent to calling g_date_time_new() with the time
 992  * zone returned by g_time_zone_new_local().
 993  *
 994  * Returns: a #GDateTime, or %NULL
 995  *
 996  * Since: 2.26
 997  **/
 998 GDateTime *
 999 g_date_time_new_local (gint    year,
1000                        gint    month,
1001                        gint    day,
1002                        gint    hour,
1003                        gint    minute,
1004                        gdouble seconds)
1005 {
1006   GDateTime *datetime;
1007   GTimeZone *local;
1008
1009   local = g_time_zone_new_local ();
1010   datetime = g_date_time_new (local, year, month, day, hour, minute, seconds);
1011   g_time_zone_unref (local);
1012
1013   return datetime;
1014 }
1015
1016 /**
1017  * g_date_time_new_utc:
1018  * @year: the year component of the date
1019  * @month: the month component of the date
1020  * @day: the day component of the date
1021  * @hour: the hour component of the date
1022  * @minute: the minute component of the date
1023  * @seconds: the number of seconds past the minute
1024  *
1025  * Creates a new #GDateTime corresponding to the given date and time in
1026  * UTC.
1027  *
1028  * This call is equivalent to calling g_date_time_new() with the time
1029  * zone returned by g_time_zone_new_utc().
1030  *
1031  * Returns: a #GDateTime, or %NULL
1032  *
1033  * Since: 2.26
1034  **/
1035 GDateTime *
1036 g_date_time_new_utc (gint    year,
1037                      gint    month,
1038                      gint    day,
1039                      gint    hour,
1040                      gint    minute,
1041                      gdouble seconds)
1042 {
1043   GDateTime *datetime;
1044   GTimeZone *utc;
1045
1046   utc = g_time_zone_new_utc ();
1047   datetime = g_date_time_new (utc, year, month, day, hour, minute, seconds);
1048   g_time_zone_unref (utc);
1049
1050   return datetime;
1051 }
1052
1053 /* Adders {{{1 */
1054
1055 /**
1056  * g_date_time_add:
1057  * @datetime: a #GDateTime
1058  * @timespan: a #GTimeSpan
1059  *
1060  * Creates a copy of @datetime and adds the specified timespan to the copy.
1061  *
1062  * Returns: the newly created #GDateTime which should be freed with
1063  *   g_date_time_unref().
1064  *
1065  * Since: 2.26
1066  */
1067 GDateTime*
1068 g_date_time_add (GDateTime *datetime,
1069                  GTimeSpan  timespan)
1070 {
1071   return g_date_time_from_instant (datetime->tz, timespan +
1072                                    g_date_time_to_instant (datetime));
1073 }
1074
1075 /**
1076  * g_date_time_add_years:
1077  * @datetime: a #GDateTime
1078  * @years: the number of years
1079  *
1080  * Creates a copy of @datetime and adds the specified number of years to the
1081  * copy. Add negative values to subtract years.
1082  *
1083  * Returns: the newly created #GDateTime which should be freed with
1084  *   g_date_time_unref().
1085  *
1086  * Since: 2.26
1087  */
1088 GDateTime *
1089 g_date_time_add_years (GDateTime *datetime,
1090                        gint       years)
1091 {
1092   gint year, month, day;
1093
1094   g_return_val_if_fail (datetime != NULL, NULL);
1095
1096   if (years < -10000 || years > 10000)
1097     return NULL;
1098
1099   g_date_time_get_ymd (datetime, &year, &month, &day);
1100   year += years;
1101
1102   /* only possible issue is if we've entered a year with no February 29
1103    */
1104   if (month == 2 && day == 29 && !GREGORIAN_LEAP (year))
1105     day = 28;
1106
1107   return g_date_time_replace_days (datetime, ymd_to_days (year, month, day));
1108 }
1109
1110 /**
1111  * g_date_time_add_months:
1112  * @datetime: a #GDateTime
1113  * @months: the number of months
1114  *
1115  * Creates a copy of @datetime and adds the specified number of months to the
1116  * copy. Add negative values to subtract months.
1117  *
1118  * Returns: the newly created #GDateTime which should be freed with
1119  *   g_date_time_unref().
1120  *
1121  * Since: 2.26
1122  */
1123 GDateTime*
1124 g_date_time_add_months (GDateTime *datetime,
1125                         gint       months)
1126 {
1127   gint year, month, day;
1128
1129   g_return_val_if_fail (datetime != NULL, NULL);
1130   g_date_time_get_ymd (datetime, &year, &month, &day);
1131
1132   if (months < -120000 || months > 120000)
1133     return NULL;
1134
1135   year += months / 12;
1136   month += months % 12;
1137   if (month < 1)
1138     {
1139       month += 12;
1140       year--;
1141     }
1142   else if (month > 12)
1143     {
1144       month -= 12;
1145       year++;
1146     }
1147
1148   day = MIN (day, days_in_months[GREGORIAN_LEAP (year)][month]);
1149
1150   return g_date_time_replace_days (datetime, ymd_to_days (year, month, day));
1151 }
1152
1153 /**
1154  * g_date_time_add_weeks:
1155  * @datetime: a #GDateTime
1156  * @weeks: the number of weeks
1157  *
1158  * Creates a copy of @datetime and adds the specified number of weeks to the
1159  * copy. Add negative values to subtract weeks.
1160  *
1161  * Returns: the newly created #GDateTime which should be freed with
1162  *   g_date_time_unref().
1163  *
1164  * Since: 2.26
1165  */
1166 GDateTime*
1167 g_date_time_add_weeks (GDateTime *datetime,
1168                        gint             weeks)
1169 {
1170   g_return_val_if_fail (datetime != NULL, NULL);
1171
1172   return g_date_time_add_days (datetime, weeks * 7);
1173 }
1174
1175 /**
1176  * g_date_time_add_days:
1177  * @datetime: a #GDateTime
1178  * @days: the number of days
1179  *
1180  * Creates a copy of @datetime and adds the specified number of days to the
1181  * copy. Add negative values to subtract days.
1182  *
1183  * Returns: the newly created #GDateTime which should be freed with
1184  *   g_date_time_unref().
1185  *
1186  * Since: 2.26
1187  */
1188 GDateTime*
1189 g_date_time_add_days (GDateTime *datetime,
1190                       gint       days)
1191 {
1192   g_return_val_if_fail (datetime != NULL, NULL);
1193
1194   if (days < -3660000 || days > 3660000)
1195     return NULL;
1196
1197   return g_date_time_replace_days (datetime, datetime->days + days);
1198 }
1199
1200 /**
1201  * g_date_time_add_hours:
1202  * @datetime: a #GDateTime
1203  * @hours: the number of hours to add
1204  *
1205  * Creates a copy of @datetime and adds the specified number of hours.
1206  * Add negative values to subtract hours.
1207  *
1208  * Returns: the newly created #GDateTime which should be freed with
1209  *   g_date_time_unref().
1210  *
1211  * Since: 2.26
1212  */
1213 GDateTime*
1214 g_date_time_add_hours (GDateTime *datetime,
1215                        gint       hours)
1216 {
1217   return g_date_time_add (datetime, hours * USEC_PER_HOUR);
1218 }
1219
1220 /**
1221  * g_date_time_add_minutes:
1222  * @datetime: a #GDateTime
1223  * @minutes: the number of minutes to add
1224  *
1225  * Creates a copy of @datetime adding the specified number of minutes.
1226  * Add negative values to subtract minutes.
1227  *
1228  * Returns: the newly created #GDateTime which should be freed with
1229  *   g_date_time_unref().
1230  *
1231  * Since: 2.26
1232  */
1233 GDateTime*
1234 g_date_time_add_minutes (GDateTime *datetime,
1235                          gint             minutes)
1236 {
1237   return g_date_time_add (datetime, minutes * USEC_PER_MINUTE);
1238 }
1239
1240
1241 /**
1242  * g_date_time_add_seconds:
1243  * @datetime: a #GDateTime
1244  * @seconds: the number of seconds to add
1245  *
1246  * Creates a copy of @datetime and adds the specified number of seconds.
1247  * Add negative values to subtract seconds.
1248  *
1249  * Returns: the newly created #GDateTime which should be freed with
1250  *   g_date_time_unref().
1251  *
1252  * Since: 2.26
1253  */
1254 GDateTime*
1255 g_date_time_add_seconds (GDateTime *datetime,
1256                          gdouble    seconds)
1257 {
1258   return g_date_time_add (datetime, seconds * USEC_PER_SECOND);
1259 }
1260
1261 /**
1262  * g_date_time_add_full:
1263  * @datetime: a #GDateTime
1264  * @years: the number of years to add
1265  * @months: the number of months to add
1266  * @days: the number of days to add
1267  * @hours: the number of hours to add
1268  * @minutes: the number of minutes to add
1269  * @seconds: the number of seconds to add
1270  *
1271  * Creates a new #GDateTime adding the specified values to the current date and
1272  * time in @datetime. Add negative values to subtract.
1273  *
1274  * Returns: the newly created #GDateTime that should be freed with
1275  *   g_date_time_unref().
1276  *
1277  * Since: 2.26
1278  */
1279 GDateTime *
1280 g_date_time_add_full (GDateTime *datetime,
1281                       gint       years,
1282                       gint       months,
1283                       gint       days,
1284                       gint       hours,
1285                       gint       minutes,
1286                       gdouble    seconds)
1287 {
1288   gint year, month, day;
1289   gint64 full_time;
1290   GDateTime *new;
1291   gint interval;
1292
1293   g_return_val_if_fail (datetime != NULL, NULL);
1294   g_date_time_get_ymd (datetime, &year, &month, &day);
1295
1296   months += years * 12;
1297
1298   if (months < -120000 || months > 120000)
1299     return NULL;
1300
1301   if (days < -3660000 || days > 3660000)
1302     return NULL;
1303
1304   year += months / 12;
1305   month += months % 12;
1306   if (month < 1)
1307     {
1308       month += 12;
1309       year--;
1310     }
1311   else if (month > 12)
1312     {
1313       month -= 12;
1314       year++;
1315     }
1316
1317   day = MIN (day, days_in_months[GREGORIAN_LEAP (year)][month]);
1318
1319   /* full_time is now in unix (local) time */
1320   full_time = datetime->usec / USEC_PER_SECOND + SEC_PER_DAY *
1321     (ymd_to_days (year, month, day) + days - UNIX_EPOCH_START);
1322
1323   interval = g_time_zone_adjust_time (datetime->tz,
1324                                       g_time_zone_is_dst (datetime->tz,
1325                                                           datetime->interval),
1326                                       &full_time);
1327
1328   /* move to UTC unix time */
1329   full_time -= g_time_zone_get_offset (datetime->tz, interval);
1330
1331   /* convert back to an instant, add back fractional seconds */
1332   full_time += UNIX_EPOCH_START * SEC_PER_DAY;
1333   full_time = full_time * USEC_PER_SECOND +
1334               datetime->usec % USEC_PER_SECOND;
1335
1336   /* do the actual addition now */
1337   full_time += (hours * USEC_PER_HOUR) +
1338                (minutes * USEC_PER_MINUTE) +
1339                (gint64) (seconds * USEC_PER_SECOND);
1340
1341   /* find the new interval */
1342   interval = g_time_zone_find_interval (datetime->tz,
1343                                         G_TIME_TYPE_UNIVERSAL,
1344                                         INSTANT_TO_UNIX (full_time));
1345
1346   /* convert back into local time */
1347   full_time += USEC_PER_SECOND *
1348                g_time_zone_get_offset (datetime->tz, interval);
1349
1350   /* split into days and usec of a new datetime */
1351   new = g_date_time_alloc (datetime->tz);
1352   new->interval = interval;
1353   new->days = full_time / USEC_PER_DAY;
1354   new->usec = full_time % USEC_PER_DAY;
1355
1356   /* XXX validate */
1357
1358   return new;
1359 }
1360
1361 /* Compare, difference, hash, equal {{{1 */
1362 /**
1363  * g_date_time_compare:
1364  * @dt1: first #GDateTime to compare
1365  * @dt2: second #GDateTime to compare
1366  *
1367  * A comparison function for #GDateTimes that is suitable
1368  * as a #GCompareFunc. Both #GDateTimes must be non-%NULL.
1369  *
1370  * Returns: -1, 0 or 1 if @dt1 is less than, equal to or greater
1371  *   than @dt2.
1372  *
1373  * Since: 2.26
1374  */
1375 gint
1376 g_date_time_compare (gconstpointer dt1,
1377                      gconstpointer dt2)
1378 {
1379   gint64 difference;
1380
1381   difference = g_date_time_difference ((GDateTime *) dt1, (GDateTime *) dt2);
1382
1383   if (difference < 0)
1384     return -1;
1385
1386   else if (difference > 0)
1387     return 1;
1388
1389   else
1390     return 0;
1391 }
1392
1393 /**
1394  * g_date_time_difference:
1395  * @end: a #GDateTime
1396  * @begin: a #GDateTime
1397  *
1398  * Calculates the difference in time between @end and @begin.  The
1399  * #GTimeSpan that is returned is effectively @end - @begin (ie:
1400  * positive if the first parameter is larger).
1401  *
1402  * Returns: the difference between the two #GDateTime, as a time
1403  *   span expressed in microseconds.
1404  *
1405  * Since: 2.26
1406  */
1407 GTimeSpan
1408 g_date_time_difference (GDateTime *end,
1409                         GDateTime *begin)
1410 {
1411   g_return_val_if_fail (begin != NULL, 0);
1412   g_return_val_if_fail (end != NULL, 0);
1413
1414   return g_date_time_to_instant (end) -
1415          g_date_time_to_instant (begin);
1416 }
1417
1418 /**
1419  * g_date_time_hash:
1420  * @datetime: a #GDateTime
1421  *
1422  * Hashes @datetime into a #guint, suitable for use within #GHashTable.
1423  *
1424  * Returns: a #guint containing the hash
1425  *
1426  * Since: 2.26
1427  */
1428 guint
1429 g_date_time_hash (gconstpointer datetime)
1430 {
1431   return g_date_time_to_instant ((GDateTime *) datetime);
1432 }
1433
1434 /**
1435  * g_date_time_equal:
1436  * @dt1: a #GDateTime
1437  * @dt2: a #GDateTime
1438  *
1439  * Checks to see if @dt1 and @dt2 are equal.
1440  *
1441  * Equal here means that they represent the same moment after converting
1442  * them to the same time zone.
1443  *
1444  * Returns: %TRUE if @dt1 and @dt2 are equal
1445  *
1446  * Since: 2.26
1447  */
1448 gboolean
1449 g_date_time_equal (gconstpointer dt1,
1450                    gconstpointer dt2)
1451 {
1452   return g_date_time_difference ((GDateTime *) dt1, (GDateTime *) dt2) == 0;
1453 }
1454
1455 /* Year, Month, Day Getters {{{1 */
1456 /**
1457  * g_date_time_get_ymd:
1458  * @datetime: a #GDateTime.
1459  * @year: (out) (allow-none): the return location for the gregorian year, or %NULL.
1460  * @month: (out) (allow-none): the return location for the month of the year, or %NULL.
1461  * @day: (out) (allow-none): the return location for the day of the month, or %NULL.
1462  *
1463  * Retrieves the Gregorian day, month, and year of a given #GDateTime.
1464  *
1465  * Since: 2.26
1466  **/
1467 void
1468 g_date_time_get_ymd (GDateTime *datetime,
1469                      gint      *year,
1470                      gint      *month,
1471                      gint      *day)
1472 {
1473   gint the_year;
1474   gint the_month;
1475   gint the_day;
1476   gint remaining_days;
1477   gint y100_cycles;
1478   gint y4_cycles;
1479   gint y1_cycles;
1480   gint preceding;
1481   gboolean leap;
1482
1483   g_return_if_fail (datetime != NULL);
1484
1485   remaining_days = datetime->days;
1486
1487   /*
1488    * We need to convert an offset in days to its year/month/day representation.
1489    * Leap years makes this a little trickier than it should be, so we use
1490    * 400, 100 and 4 years cycles here to get to the correct year.
1491    */
1492
1493   /* Our days offset starts sets 0001-01-01 as day 1, if it was day 0 our
1494    * math would be simpler, so let's do it */
1495   remaining_days--;
1496
1497   the_year = (remaining_days / DAYS_IN_400YEARS) * 400 + 1;
1498   remaining_days = remaining_days % DAYS_IN_400YEARS;
1499
1500   y100_cycles = remaining_days / DAYS_IN_100YEARS;
1501   remaining_days = remaining_days % DAYS_IN_100YEARS;
1502   the_year += y100_cycles * 100;
1503
1504   y4_cycles = remaining_days / DAYS_IN_4YEARS;
1505   remaining_days = remaining_days % DAYS_IN_4YEARS;
1506   the_year += y4_cycles * 4;
1507
1508   y1_cycles = remaining_days / 365;
1509   the_year += y1_cycles;
1510   remaining_days = remaining_days % 365;
1511
1512   if (y1_cycles == 4 || y100_cycles == 4) {
1513     g_assert (remaining_days == 0);
1514
1515     /* special case that indicates that the date is actually one year before,
1516      * in the 31th of December */
1517     the_year--;
1518     the_month = 12;
1519     the_day = 31;
1520     goto end;
1521   }
1522
1523   /* now get the month and the day */
1524   leap = y1_cycles == 3 && (y4_cycles != 24 || y100_cycles == 3);
1525
1526   g_assert (leap == GREGORIAN_LEAP(the_year));
1527
1528   the_month = (remaining_days + 50) >> 5;
1529   preceding = (days_in_year[0][the_month - 1] + (the_month > 2 && leap));
1530   if (preceding > remaining_days)
1531     {
1532       /* estimate is too large */
1533       the_month -= 1;
1534       preceding -= leap ? days_in_months[1][the_month]
1535                         : days_in_months[0][the_month];
1536     }
1537
1538   remaining_days -= preceding;
1539   g_assert(0 <= remaining_days);
1540
1541   the_day = remaining_days + 1;
1542
1543 end:
1544   if (year)
1545     *year = the_year;
1546   if (month)
1547     *month = the_month;
1548   if (day)
1549     *day = the_day;
1550 }
1551
1552 /**
1553  * g_date_time_get_year:
1554  * @datetime: A #GDateTime
1555  *
1556  * Retrieves the year represented by @datetime in the Gregorian calendar.
1557  *
1558  * Returns: the year represented by @datetime
1559  *
1560  * Since: 2.26
1561  */
1562 gint
1563 g_date_time_get_year (GDateTime *datetime)
1564 {
1565   gint year;
1566
1567   g_return_val_if_fail (datetime != NULL, 0);
1568
1569   g_date_time_get_ymd (datetime, &year, NULL, NULL);
1570
1571   return year;
1572 }
1573
1574 /**
1575  * g_date_time_get_month:
1576  * @datetime: a #GDateTime
1577  *
1578  * Retrieves the month of the year represented by @datetime in the Gregorian
1579  * calendar.
1580  *
1581  * Returns: the month represented by @datetime
1582  *
1583  * Since: 2.26
1584  */
1585 gint
1586 g_date_time_get_month (GDateTime *datetime)
1587 {
1588   gint month;
1589
1590   g_return_val_if_fail (datetime != NULL, 0);
1591
1592   g_date_time_get_ymd (datetime, NULL, &month, NULL);
1593
1594   return month;
1595 }
1596
1597 /**
1598  * g_date_time_get_day_of_month:
1599  * @datetime: a #GDateTime
1600  *
1601  * Retrieves the day of the month represented by @datetime in the gregorian
1602  * calendar.
1603  *
1604  * Returns: the day of the month
1605  *
1606  * Since: 2.26
1607  */
1608 gint
1609 g_date_time_get_day_of_month (GDateTime *datetime)
1610 {
1611   gint           day_of_year,
1612                  i;
1613   const guint16 *days;
1614   guint16        last = 0;
1615
1616   g_return_val_if_fail (datetime != NULL, 0);
1617
1618   days = days_in_year[GREGORIAN_LEAP (g_date_time_get_year (datetime)) ? 1 : 0];
1619   g_date_time_get_week_number (datetime, NULL, NULL, &day_of_year);
1620
1621   for (i = 1; i <= 12; i++)
1622     {
1623       if (days [i] >= day_of_year)
1624         return day_of_year - last;
1625       last = days [i];
1626     }
1627
1628   g_warn_if_reached ();
1629   return 0;
1630 }
1631
1632 /* Week of year / day of week getters {{{1 */
1633 /**
1634  * g_date_time_get_week_numbering_year:
1635  * @datetime: a #GDateTime
1636  *
1637  * Returns the ISO 8601 week-numbering year in which the week containing
1638  * @datetime falls.
1639  *
1640  * This function, taken together with g_date_time_get_week_of_year() and
1641  * g_date_time_get_day_of_week() can be used to determine the full ISO
1642  * week date on which @datetime falls.
1643  *
1644  * This is usually equal to the normal Gregorian year (as returned by
1645  * g_date_time_get_year()), except as detailed below:
1646  *
1647  * For Thursday, the week-numbering year is always equal to the usual
1648  * calendar year.  For other days, the number is such that every day
1649  * within a complete week (Monday to Sunday) is contained within the
1650  * same week-numbering year.
1651  *
1652  * For Monday, Tuesday and Wednesday occurring near the end of the year,
1653  * this may mean that the week-numbering year is one greater than the
1654  * calendar year (so that these days have the same week-numbering year
1655  * as the Thursday occurring early in the next year).
1656  *
1657  * For Friday, Saturaday and Sunday occurring near the start of the year,
1658  * this may mean that the week-numbering year is one less than the
1659  * calendar year (so that these days have the same week-numbering year
1660  * as the Thursday occurring late in the previous year).
1661  *
1662  * An equivalent description is that the week-numbering year is equal to
1663  * the calendar year containing the majority of the days in the current
1664  * week (Monday to Sunday).
1665  *
1666  * Note that January 1 0001 in the proleptic Gregorian calendar is a
1667  * Monday, so this function never returns 0.
1668  *
1669  * Returns: the ISO 8601 week-numbering year for @datetime
1670  *
1671  * Since: 2.26
1672  **/
1673 gint
1674 g_date_time_get_week_numbering_year (GDateTime *datetime)
1675 {
1676   gint year, month, day, weekday;
1677
1678   g_date_time_get_ymd (datetime, &year, &month, &day);
1679   weekday = g_date_time_get_day_of_week (datetime);
1680
1681   /* January 1, 2, 3 might be in the previous year if they occur after
1682    * Thursday.
1683    *
1684    *   Jan 1:  Friday, Saturday, Sunday    =>  day 1:  weekday 5, 6, 7
1685    *   Jan 2:  Saturday, Sunday            =>  day 2:  weekday 6, 7
1686    *   Jan 3:  Sunday                      =>  day 3:  weekday 7
1687    *
1688    * So we have a special case if (day - weekday) <= -4
1689    */
1690   if (month == 1 && (day - weekday) <= -4)
1691     return year - 1;
1692
1693   /* December 29, 30, 31 might be in the next year if they occur before
1694    * Thursday.
1695    *
1696    *   Dec 31: Monday, Tuesday, Wednesday  =>  day 31: weekday 1, 2, 3
1697    *   Dec 30: Monday, Tuesday             =>  day 30: weekday 1, 2
1698    *   Dec 29: Monday                      =>  day 29: weekday 1
1699    *
1700    * So we have a special case if (day - weekday) >= 28
1701    */
1702   else if (month == 12 && (day - weekday) >= 28)
1703     return year + 1;
1704
1705   else
1706     return year;
1707 }
1708
1709 /**
1710  * g_date_time_get_week_of_year:
1711  * @datetime: a #GDateTime
1712  *
1713  * Returns the ISO 8601 week number for the week containing @datetime.
1714  * The ISO 8601 week number is the same for every day of the week (from
1715  * Moday through Sunday).  That can produce some unusual results
1716  * (described below).
1717  *
1718  * The first week of the year is week 1.  This is the week that contains
1719  * the first Thursday of the year.  Equivalently, this is the first week
1720  * that has more than 4 of its days falling within the calendar year.
1721  *
1722  * The value 0 is never returned by this function.  Days contained
1723  * within a year but occurring before the first ISO 8601 week of that
1724  * year are considered as being contained in the last week of the
1725  * previous year.  Similarly, the final days of a calendar year may be
1726  * considered as being part of the first ISO 8601 week of the next year
1727  * if 4 or more days of that week are contained within the new year.
1728  *
1729  * Returns: the ISO 8601 week number for @datetime.
1730  *
1731  * Since: 2.26
1732  */
1733 gint
1734 g_date_time_get_week_of_year (GDateTime *datetime)
1735 {
1736   gint weeknum;
1737
1738   g_return_val_if_fail (datetime != NULL, 0);
1739
1740   g_date_time_get_week_number (datetime, &weeknum, NULL, NULL);
1741
1742   return weeknum;
1743 }
1744
1745 /**
1746  * g_date_time_get_day_of_week:
1747  * @datetime: a #GDateTime
1748  *
1749  * Retrieves the ISO 8601 day of the week on which @datetime falls (1 is
1750  * Monday, 2 is Tuesday... 7 is Sunday).
1751  *
1752  * Returns: the day of the week
1753  *
1754  * Since: 2.26
1755  */
1756 gint
1757 g_date_time_get_day_of_week (GDateTime *datetime)
1758 {
1759   g_return_val_if_fail (datetime != NULL, 0);
1760
1761   return (datetime->days - 1) % 7 + 1;
1762 }
1763
1764 /* Day of year getter {{{1 */
1765 /**
1766  * g_date_time_get_day_of_year:
1767  * @datetime: a #GDateTime
1768  *
1769  * Retrieves the day of the year represented by @datetime in the Gregorian
1770  * calendar.
1771  *
1772  * Returns: the day of the year
1773  *
1774  * Since: 2.26
1775  */
1776 gint
1777 g_date_time_get_day_of_year (GDateTime *datetime)
1778 {
1779   gint doy = 0;
1780
1781   g_return_val_if_fail (datetime != NULL, 0);
1782
1783   g_date_time_get_week_number (datetime, NULL, NULL, &doy);
1784   return doy;
1785 }
1786
1787 /* Time component getters {{{1 */
1788
1789 /**
1790  * g_date_time_get_hour:
1791  * @datetime: a #GDateTime
1792  *
1793  * Retrieves the hour of the day represented by @datetime
1794  *
1795  * Returns: the hour of the day
1796  *
1797  * Since: 2.26
1798  */
1799 gint
1800 g_date_time_get_hour (GDateTime *datetime)
1801 {
1802   g_return_val_if_fail (datetime != NULL, 0);
1803
1804   return (datetime->usec / USEC_PER_HOUR);
1805 }
1806
1807 /**
1808  * g_date_time_get_minute:
1809  * @datetime: a #GDateTime
1810  *
1811  * Retrieves the minute of the hour represented by @datetime
1812  *
1813  * Returns: the minute of the hour
1814  *
1815  * Since: 2.26
1816  */
1817 gint
1818 g_date_time_get_minute (GDateTime *datetime)
1819 {
1820   g_return_val_if_fail (datetime != NULL, 0);
1821
1822   return (datetime->usec % USEC_PER_HOUR) / USEC_PER_MINUTE;
1823 }
1824
1825 /**
1826  * g_date_time_get_second:
1827  * @datetime: a #GDateTime
1828  *
1829  * Retrieves the second of the minute represented by @datetime
1830  *
1831  * Returns: the second represented by @datetime
1832  *
1833  * Since: 2.26
1834  */
1835 gint
1836 g_date_time_get_second (GDateTime *datetime)
1837 {
1838   g_return_val_if_fail (datetime != NULL, 0);
1839
1840   return (datetime->usec % USEC_PER_MINUTE) / USEC_PER_SECOND;
1841 }
1842
1843 /**
1844  * g_date_time_get_microsecond:
1845  * @datetime: a #GDateTime
1846  *
1847  * Retrieves the microsecond of the date represented by @datetime
1848  *
1849  * Returns: the microsecond of the second
1850  *
1851  * Since: 2.26
1852  */
1853 gint
1854 g_date_time_get_microsecond (GDateTime *datetime)
1855 {
1856   g_return_val_if_fail (datetime != NULL, 0);
1857
1858   return (datetime->usec % USEC_PER_SECOND);
1859 }
1860
1861 /**
1862  * g_date_time_get_seconds:
1863  * @datetime: a #GDateTime
1864  *
1865  * Retrieves the number of seconds since the start of the last minute,
1866  * including the fractional part.
1867  *
1868  * Returns: the number of seconds
1869  *
1870  * Since: 2.26
1871  **/
1872 gdouble
1873 g_date_time_get_seconds (GDateTime *datetime)
1874 {
1875   g_return_val_if_fail (datetime != NULL, 0);
1876
1877   return (datetime->usec % USEC_PER_MINUTE) / 1000000.0;
1878 }
1879
1880 /* Exporters {{{1 */
1881 /**
1882  * g_date_time_to_unix:
1883  * @datetime: a #GDateTime
1884  *
1885  * Gives the Unix time corresponding to @datetime, rounding down to the
1886  * nearest second.
1887  *
1888  * Unix time is the number of seconds that have elapsed since 1970-01-01
1889  * 00:00:00 UTC, regardless of the time zone associated with @datetime.
1890  *
1891  * Returns: the Unix time corresponding to @datetime
1892  *
1893  * Since: 2.26
1894  **/
1895 gint64
1896 g_date_time_to_unix (GDateTime *datetime)
1897 {
1898   return INSTANT_TO_UNIX (g_date_time_to_instant (datetime));
1899 }
1900
1901 /**
1902  * g_date_time_to_timeval:
1903  * @datetime: a #GDateTime
1904  * @tv: a #GTimeVal to modify
1905  *
1906  * Stores the instant in time that @datetime represents into @tv.
1907  *
1908  * The time contained in a #GTimeVal is always stored in the form of
1909  * seconds elapsed since 1970-01-01 00:00:00 UTC, regardless of the time
1910  * zone associated with @datetime.
1911  *
1912  * On systems where 'long' is 32bit (ie: all 32bit systems and all
1913  * Windows systems), a #GTimeVal is incapable of storing the entire
1914  * range of values that #GDateTime is capable of expressing.  On those
1915  * systems, this function returns %FALSE to indicate that the time is
1916  * out of range.
1917  *
1918  * On systems where 'long' is 64bit, this function never fails.
1919  *
1920  * Returns: %TRUE if successful, else %FALSE
1921  *
1922  * Since: 2.26
1923  **/
1924 gboolean
1925 g_date_time_to_timeval (GDateTime *datetime,
1926                         GTimeVal  *tv)
1927 {
1928   tv->tv_sec = INSTANT_TO_UNIX (g_date_time_to_instant (datetime));
1929   tv->tv_usec = datetime->usec % USEC_PER_SECOND;
1930
1931   return TRUE;
1932 }
1933
1934 /* Timezone queries {{{1 */
1935 /**
1936  * g_date_time_get_utc_offset:
1937  * @datetime: a #GDateTime
1938  *
1939  * Determines the offset to UTC in effect at the time and in the time
1940  * zone of @datetime.
1941  *
1942  * The offset is the number of microseconds that you add to UTC time to
1943  * arrive at local time for the time zone (ie: negative numbers for time
1944  * zones west of GMT, positive numbers for east).
1945  *
1946  * If @datetime represents UTC time, then the offset is always zero.
1947  *
1948  * Returns: the number of microseconds that should be added to UTC to
1949  *          get the local time
1950  *
1951  * Since: 2.26
1952  **/
1953 GTimeSpan
1954 g_date_time_get_utc_offset (GDateTime *datetime)
1955 {
1956   gint offset;
1957
1958   g_return_val_if_fail (datetime != NULL, 0);
1959
1960   offset = g_time_zone_get_offset (datetime->tz, datetime->interval);
1961
1962   return (gint64) offset * USEC_PER_SECOND;
1963 }
1964
1965 /**
1966  * g_date_time_get_timezone_abbreviation:
1967  * @datetime: a #GDateTime
1968  *
1969  * Determines the time zone abbreviation to be used at the time and in
1970  * the time zone of @datetime.
1971  *
1972  * For example, in Toronto this is currently "EST" during the winter
1973  * months and "EDT" during the summer months when daylight savings
1974  * time is in effect.
1975  *
1976  * Returns: (transfer none): the time zone abbreviation. The returned
1977  *          string is owned by the #GDateTime and it should not be
1978  *          modified or freed
1979  *
1980  * Since: 2.26
1981  **/
1982 const gchar *
1983 g_date_time_get_timezone_abbreviation (GDateTime *datetime)
1984 {
1985   g_return_val_if_fail (datetime != NULL, NULL);
1986
1987   return g_time_zone_get_abbreviation (datetime->tz, datetime->interval);
1988 }
1989
1990 /**
1991  * g_date_time_is_daylight_savings:
1992  * @datetime: a #GDateTime
1993  *
1994  * Determines if daylight savings time is in effect at the time and in
1995  * the time zone of @datetime.
1996  *
1997  * Returns: %TRUE if daylight savings time is in effect
1998  *
1999  * Since: 2.26
2000  **/
2001 gboolean
2002 g_date_time_is_daylight_savings (GDateTime *datetime)
2003 {
2004   g_return_val_if_fail (datetime != NULL, FALSE);
2005
2006   return g_time_zone_is_dst (datetime->tz, datetime->interval);
2007 }
2008
2009 /* Timezone convert {{{1 */
2010 /**
2011  * g_date_time_to_timezone:
2012  * @datetime: a #GDateTime
2013  * @tz: the new #GTimeZone
2014  *
2015  * Create a new #GDateTime corresponding to the same instant in time as
2016  * @datetime, but in the time zone @tz.
2017  *
2018  * This call can fail in the case that the time goes out of bounds.  For
2019  * example, converting 0001-01-01 00:00:00 UTC to a time zone west of
2020  * Greenwich will fail (due to the year 0 being out of range).
2021  *
2022  * You should release the return value by calling g_date_time_unref()
2023  * when you are done with it.
2024  *
2025  * Returns: a new #GDateTime, or %NULL
2026  *
2027  * Since: 2.26
2028  **/
2029 GDateTime *
2030 g_date_time_to_timezone (GDateTime *datetime,
2031                          GTimeZone *tz)
2032 {
2033   return g_date_time_from_instant (tz, g_date_time_to_instant (datetime));
2034 }
2035
2036 /**
2037  * g_date_time_to_local:
2038  * @datetime: a #GDateTime
2039  *
2040  * Creates a new #GDateTime corresponding to the same instant in time as
2041  * @datetime, but in the local time zone.
2042  *
2043  * This call is equivalent to calling g_date_time_to_timezone() with the
2044  * time zone returned by g_time_zone_new_local().
2045  *
2046  * Returns: the newly created #GDateTime
2047  *
2048  * Since: 2.26
2049  **/
2050 GDateTime *
2051 g_date_time_to_local (GDateTime *datetime)
2052 {
2053   GDateTime *new;
2054   GTimeZone *local;
2055
2056   local = g_time_zone_new_local ();
2057   new = g_date_time_to_timezone (datetime, local);
2058   g_time_zone_unref (local);
2059
2060   return new;
2061 }
2062
2063 /**
2064  * g_date_time_to_utc:
2065  * @datetime: a #GDateTime
2066  *
2067  * Creates a new #GDateTime corresponding to the same instant in time as
2068  * @datetime, but in UTC.
2069  *
2070  * This call is equivalent to calling g_date_time_to_timezone() with the
2071  * time zone returned by g_time_zone_new_utc().
2072  *
2073  * Returns: the newly created #GDateTime
2074  *
2075  * Since: 2.26
2076  **/
2077 GDateTime *
2078 g_date_time_to_utc (GDateTime *datetime)
2079 {
2080   GDateTime *new;
2081   GTimeZone *utc;
2082
2083   utc = g_time_zone_new_utc ();
2084   new = g_date_time_to_timezone (datetime, utc);
2085   g_time_zone_unref (utc);
2086
2087   return new;
2088 }
2089
2090 /* Format {{{1 */
2091
2092 static gboolean
2093 format_z (GString *outstr,
2094           gint     offset,
2095           guint    colons)
2096 {
2097   gint hours;
2098   gint minutes;
2099   gint seconds;
2100
2101   hours = offset / 3600;
2102   minutes = ABS (offset) / 60 % 60;
2103   seconds = ABS (offset) % 60;
2104
2105   switch (colons)
2106     {
2107     case 0:
2108       g_string_append_printf (outstr, "%+03d%02d",
2109                               hours,
2110                               minutes);
2111       break;
2112
2113     case 1:
2114       g_string_append_printf (outstr, "%+03d:%02d",
2115                               hours,
2116                               minutes);
2117       break;
2118
2119     case 2:
2120       g_string_append_printf (outstr, "%+03d:%02d:%02d",
2121                               hours,
2122                               minutes,
2123                               seconds);
2124       break;
2125
2126     case 3:
2127       g_string_append_printf (outstr, "%+03d", hours);
2128
2129       if (minutes != 0 || seconds != 0)
2130         {
2131           g_string_append_printf (outstr, ":%02d", minutes);
2132
2133           if (seconds != 0)
2134             g_string_append_printf (outstr, ":%02d", seconds);
2135         }
2136       break;
2137
2138     default:
2139       return FALSE;
2140     }
2141
2142   return TRUE;
2143 }
2144
2145 static void
2146 format_number (GString  *str,
2147                gboolean  use_alt_digits,
2148                gchar    *pad,
2149                gint      width,
2150                guint32   number)
2151 {
2152   const gchar *ascii_digits[10] = {
2153     "0", "1", "2", "3", "4", "5", "6", "7", "8", "9"
2154   };
2155   const gchar **digits = ascii_digits;
2156   const gchar *tmp[10];
2157   gint i = 0;
2158
2159   g_return_if_fail (width <= 10);
2160
2161 #ifdef HAVE_LANGINFO_OUTDIGIT
2162   if (use_alt_digits)
2163     {
2164       static const gchar *alt_digits[10];
2165       static gsize initialised;
2166       /* 2^32 has 10 digits */
2167
2168       if G_UNLIKELY (g_once_init_enter (&initialised))
2169         {
2170 #define DO_DIGIT(n) \
2171         alt_digits[n] = nl_langinfo (_NL_CTYPE_OUTDIGIT## n ##_MB)
2172           DO_DIGIT(0); DO_DIGIT(1); DO_DIGIT(2); DO_DIGIT(3); DO_DIGIT(4);
2173           DO_DIGIT(5); DO_DIGIT(6); DO_DIGIT(7); DO_DIGIT(8); DO_DIGIT(9);
2174 #undef DO_DIGIT
2175           g_once_init_leave (&initialised, TRUE);
2176         }
2177
2178       digits = alt_digits;
2179     }
2180 #endif /* HAVE_LANGINFO_OUTDIGIT */
2181
2182   do
2183     {
2184       tmp[i++] = digits[number % 10];
2185       number /= 10;
2186     }
2187   while (number);
2188
2189   while (pad && i < width)
2190     tmp[i++] = *pad == '0' ? digits[0] : pad;
2191
2192   /* should really be impossible */
2193   g_assert (i <= 10);
2194
2195   while (i)
2196     g_string_append (str, tmp[--i]);
2197 }
2198
2199 static gboolean g_date_time_format_locale (GDateTime   *datetime,
2200                                            const gchar *format,
2201                                            GString     *outstr,
2202                                            gboolean     locale_is_utf8);
2203
2204 /* g_date_time_format() subroutine that takes a locale-encoded format
2205  * string and produces a locale-encoded date/time string.
2206  */
2207 static gboolean
2208 g_date_time_locale_format_locale (GDateTime   *datetime,
2209                                   const gchar *format,
2210                                   GString     *outstr,
2211                                   gboolean     locale_is_utf8)
2212 {
2213   gchar *utf8_format;
2214   gboolean success;
2215
2216   if (locale_is_utf8)
2217     return g_date_time_format_locale (datetime, format, outstr,
2218                                       locale_is_utf8);
2219
2220   utf8_format = g_locale_to_utf8 (format, -1, NULL, NULL, NULL);
2221   if (!utf8_format)
2222     return FALSE;
2223
2224   success = g_date_time_format_locale (datetime, utf8_format, outstr,
2225                                        locale_is_utf8);
2226   g_free (utf8_format);
2227   return success;
2228 }
2229
2230 /* g_date_time_format() subroutine that takes a UTF-8 format
2231  * string and produces a locale-encoded date/time string.
2232  */
2233 static gboolean
2234 g_date_time_format_locale (GDateTime   *datetime,
2235                            const gchar *format,
2236                            GString     *outstr,
2237                            gboolean     locale_is_utf8)
2238 {
2239   guint     len;
2240   guint     colons;
2241   gchar    *tmp;
2242   gunichar  c;
2243   gboolean  alt_digits = FALSE;
2244   gboolean  pad_set = FALSE;
2245   gchar    *pad = "";
2246   gchar    *ampm;
2247   const gchar *tz;
2248
2249   while (*format)
2250     {
2251       len = strcspn (format, "%");
2252       if (len)
2253         {
2254           if (locale_is_utf8)
2255             g_string_append_len (outstr, format, len);
2256           else
2257             {
2258               tmp = g_locale_from_utf8 (format, len, NULL, NULL, NULL);
2259               if (!tmp)
2260                 return FALSE;
2261               g_string_append (outstr, tmp);
2262               g_free (tmp);
2263             }
2264         }
2265
2266       format += len;
2267       if (!*format)
2268         break;
2269
2270       g_assert (*format == '%');
2271       format++;
2272       if (!*format)
2273         break;
2274
2275       colons = 0;
2276       alt_digits = FALSE;
2277       pad_set = FALSE;
2278
2279     next_mod:
2280       c = g_utf8_get_char (format);
2281       format = g_utf8_next_char (format);
2282       switch (c)
2283         {
2284         case 'a':
2285           g_string_append (outstr, WEEKDAY_ABBR (datetime));
2286           break;
2287         case 'A':
2288           g_string_append (outstr, WEEKDAY_FULL (datetime));
2289           break;
2290         case 'b':
2291           g_string_append (outstr, MONTH_ABBR (datetime));
2292           break;
2293         case 'B':
2294           g_string_append (outstr, MONTH_FULL (datetime));
2295           break;
2296         case 'c':
2297           {
2298             if (!g_date_time_locale_format_locale (datetime, PREFERRED_DATE_TIME_FMT,
2299                                                    outstr, locale_is_utf8))
2300               return FALSE;
2301           }
2302           break;
2303         case 'C':
2304           format_number (outstr, alt_digits, pad_set ? pad : "0", 2,
2305                          g_date_time_get_year (datetime) / 100);
2306           break;
2307         case 'd':
2308           format_number (outstr, alt_digits, pad_set ? pad : "0", 2,
2309                          g_date_time_get_day_of_month (datetime));
2310           break;
2311         case 'e':
2312           format_number (outstr, alt_digits, pad_set ? pad : " ", 2,
2313                          g_date_time_get_day_of_month (datetime));
2314           break;
2315         case 'F':
2316           g_string_append_printf (outstr, "%d-%02d-%02d",
2317                                   g_date_time_get_year (datetime),
2318                                   g_date_time_get_month (datetime),
2319                                   g_date_time_get_day_of_month (datetime));
2320           break;
2321         case 'g':
2322           format_number (outstr, alt_digits, pad_set ? pad : "0", 2,
2323                          g_date_time_get_week_numbering_year (datetime) % 100);
2324           break;
2325         case 'G':
2326           format_number (outstr, alt_digits, pad_set ? pad : 0, 0,
2327                          g_date_time_get_week_numbering_year (datetime));
2328           break;
2329         case 'h':
2330           g_string_append (outstr, MONTH_ABBR (datetime));
2331           break;
2332         case 'H':
2333           format_number (outstr, alt_digits, pad_set ? pad : "0", 2,
2334                          g_date_time_get_hour (datetime));
2335           break;
2336         case 'I':
2337           format_number (outstr, alt_digits, pad_set ? pad : "0", 2,
2338                          (g_date_time_get_hour (datetime) + 11) % 12 + 1);
2339           break;
2340         case 'j':
2341           format_number (outstr, alt_digits, pad_set ? pad : "0", 3,
2342                          g_date_time_get_day_of_year (datetime));
2343           break;
2344         case 'k':
2345           format_number (outstr, alt_digits, pad_set ? pad : " ", 2,
2346                          g_date_time_get_hour (datetime));
2347           break;
2348         case 'l':
2349           format_number (outstr, alt_digits, pad_set ? pad : " ", 2,
2350                          (g_date_time_get_hour (datetime) + 11) % 12 + 1);
2351           break;
2352         case 'n':
2353           g_string_append_c (outstr, '\n');
2354           break;
2355         case 'm':
2356           format_number (outstr, alt_digits, pad_set ? pad : "0", 2,
2357                          g_date_time_get_month (datetime));
2358           break;
2359         case 'M':
2360           format_number (outstr, alt_digits, pad_set ? pad : "0", 2,
2361                          g_date_time_get_minute (datetime));
2362           break;
2363         case 'O':
2364           alt_digits = TRUE;
2365           goto next_mod;
2366         case 'p':
2367           ampm = (gchar *) GET_AMPM (datetime);
2368           if (!locale_is_utf8)
2369             {
2370               ampm = tmp = g_locale_to_utf8 (ampm, -1, NULL, NULL, NULL);
2371               if (!tmp)
2372                 return FALSE;
2373             }
2374           ampm = g_utf8_strup (ampm, -1);
2375           if (!locale_is_utf8)
2376             {
2377               g_free (tmp);
2378               tmp = g_locale_from_utf8 (ampm, -1, NULL, NULL, NULL);
2379               g_free (ampm);
2380               if (!tmp)
2381                 return FALSE;
2382               ampm = tmp;
2383             }
2384           g_string_append (outstr, ampm);
2385           g_free (ampm);
2386           break;
2387         case 'P':
2388           ampm = (gchar *) GET_AMPM (datetime);
2389           if (!locale_is_utf8)
2390             {
2391               ampm = tmp = g_locale_to_utf8 (ampm, -1, NULL, NULL, NULL);
2392               if (!tmp)
2393                 return FALSE;
2394             }
2395           ampm = g_utf8_strdown (ampm, -1);
2396           if (!locale_is_utf8)
2397             {
2398               g_free (tmp);
2399               tmp = g_locale_from_utf8 (ampm, -1, NULL, NULL, NULL);
2400               g_free (ampm);
2401               if (!tmp)
2402                 return FALSE;
2403               ampm = tmp;
2404             }
2405           g_string_append (outstr, ampm);
2406           g_free (ampm);
2407           break;
2408         case 'r':
2409           {
2410             if (!g_date_time_locale_format_locale (datetime, PREFERRED_12HR_TIME_FMT,
2411                                                    outstr, locale_is_utf8))
2412               return FALSE;
2413           }
2414           break;
2415         case 'R':
2416           g_string_append_printf (outstr, "%02d:%02d",
2417                                   g_date_time_get_hour (datetime),
2418                                   g_date_time_get_minute (datetime));
2419           break;
2420         case 's':
2421           g_string_append_printf (outstr, "%" G_GINT64_FORMAT, g_date_time_to_unix (datetime));
2422           break;
2423         case 'S':
2424           format_number (outstr, alt_digits, pad_set ? pad : "0", 2,
2425                          g_date_time_get_second (datetime));
2426           break;
2427         case 't':
2428           g_string_append_c (outstr, '\t');
2429           break;
2430         case 'T':
2431           g_string_append_printf (outstr, "%02d:%02d:%02d",
2432                                   g_date_time_get_hour (datetime),
2433                                   g_date_time_get_minute (datetime),
2434                                   g_date_time_get_second (datetime));
2435           break;
2436         case 'u':
2437           format_number (outstr, alt_digits, 0, 0,
2438                          g_date_time_get_day_of_week (datetime));
2439           break;
2440         case 'V':
2441           format_number (outstr, alt_digits, pad_set ? pad : "0", 2,
2442                          g_date_time_get_week_of_year (datetime));
2443           break;
2444         case 'w':
2445           format_number (outstr, alt_digits, 0, 0,
2446                          g_date_time_get_day_of_week (datetime) % 7);
2447           break;
2448         case 'x':
2449           {
2450             if (!g_date_time_locale_format_locale (datetime, PREFERRED_DATE_FMT,
2451                                                    outstr, locale_is_utf8))
2452               return FALSE;
2453           }
2454           break;
2455         case 'X':
2456           {
2457             if (!g_date_time_locale_format_locale (datetime, PREFERRED_TIME_FMT,
2458                                                    outstr, locale_is_utf8))
2459               return FALSE;
2460           }
2461           break;
2462         case 'y':
2463           format_number (outstr, alt_digits, pad_set ? pad : "0", 2,
2464                          g_date_time_get_year (datetime) % 100);
2465           break;
2466         case 'Y':
2467           format_number (outstr, alt_digits, 0, 0,
2468                          g_date_time_get_year (datetime));
2469           break;
2470         case 'z':
2471           {
2472             gint64 offset;
2473             if (datetime->tz != NULL)
2474               offset = g_date_time_get_utc_offset (datetime) / USEC_PER_SECOND;
2475             else
2476               offset = 0;
2477             if (!format_z (outstr, (int) offset, colons))
2478               return FALSE;
2479           }
2480           break;
2481         case 'Z':
2482           tz = g_date_time_get_timezone_abbreviation (datetime);
2483           if (!locale_is_utf8)
2484             {
2485               tz = tmp = g_locale_from_utf8 (tz, -1, NULL, NULL, NULL);
2486               if (!tmp)
2487                 return FALSE;
2488             }
2489           g_string_append (outstr, tz);
2490           if (!locale_is_utf8)
2491             g_free (tmp);
2492           break;
2493         case '%':
2494           g_string_append_c (outstr, '%');
2495           break;
2496         case '-':
2497           pad_set = TRUE;
2498           pad = "";
2499           goto next_mod;
2500         case '_':
2501           pad_set = TRUE;
2502           pad = " ";
2503           goto next_mod;
2504         case '0':
2505           pad_set = TRUE;
2506           pad = "0";
2507           goto next_mod;
2508         case ':':
2509           /* Colons are only allowed before 'z' */
2510           if (*format && *format != 'z' && *format != ':')
2511             return FALSE;
2512           colons++;
2513           goto next_mod;
2514         default:
2515           return FALSE;
2516         }
2517     }
2518
2519   return TRUE;
2520 }
2521
2522 /**
2523  * g_date_time_format:
2524  * @datetime: A #GDateTime
2525  * @format: a valid UTF-8 string, containing the format for the
2526  *          #GDateTime
2527  *
2528  * Creates a newly allocated string representing the requested @format.
2529  *
2530  * The format strings understood by this function are a subset of the
2531  * strftime() format language as specified by C99.  The \%D, \%U and \%W
2532  * conversions are not supported, nor is the 'E' modifier.  The GNU
2533  * extensions \%k, \%l, \%s and \%P are supported, however, as are the
2534  * '0', '_' and '-' modifiers.
2535  *
2536  * In contrast to strftime(), this function always produces a UTF-8
2537  * string, regardless of the current locale.  Note that the rendering of
2538  * many formats is locale-dependent and may not match the strftime()
2539  * output exactly.
2540  *
2541  * The following format specifiers are supported:
2542  *
2543  * - \%a: the abbreviated weekday name according to the current locale
2544  * - \%A: the full weekday name according to the current locale
2545  * - \%b: the abbreviated month name according to the current locale
2546  * - \%B: the full month name according to the current locale
2547  * - \%c: the  preferred date and time rpresentation for the current locale
2548  * - \%C: the century number (year/100) as a 2-digit integer (00-99)
2549  * - \%d: the day of the month as a decimal number (range 01 to 31)
2550  * - \%e: the day of the month as a decimal number (range  1 to 31)
2551  * - \%F: equivalent to `%Y-%m-%d` (the ISO 8601 date format)
2552  * - \%g: the last two digits of the ISO 8601 week-based year as a
2553  *   decimal number (00-99). This works well with \%V and \%u.
2554  * - \%G: the ISO 8601 week-based year as a decimal number. This works
2555  *   well with \%V and \%u.
2556  * - \%h: equivalent to \%b
2557  * - \%H: the hour as a decimal number using a 24-hour clock (range 00 to 23)
2558  * - \%I: the hour as a decimal number using a 12-hour clock (range 01 to 12)
2559  * - \%j: the day of the year as a decimal number (range 001 to 366)
2560  * - \%k: the hour (24-hour clock) as a decimal number (range 0 to 23);
2561  *   single digits are preceded by a blank
2562  * - \%l: the hour (12-hour clock) as a decimal number (range 1 to 12);
2563  *   single digits are preceded by a blank
2564  * - \%m: the month as a decimal number (range 01 to 12)
2565  * - \%M: the minute as a decimal number (range 00 to 59)
2566  * - \%p: either "AM" or "PM" according to the given time value, or the
2567  *   corresponding  strings for the current locale.  Noon is treated as
2568  *   "PM" and midnight as "AM".
2569  * - \%P: like \%p but lowercase: "am" or "pm" or a corresponding string for
2570  *   the current locale
2571  * - \%r: the time in a.m. or p.m. notation
2572  * - \%R: the time in 24-hour notation (\%H:\%M)
2573  * - \%s: the number of seconds since the Epoch, that is, since 1970-01-01
2574  *   00:00:00 UTC
2575  * - \%S: the second as a decimal number (range 00 to 60)
2576  * - \%t: a tab character
2577  * - \%T: the time in 24-hour notation with seconds (\%H:\%M:\%S)
2578  * - \%u: the ISO 8601 standard day of the week as a decimal, range 1 to 7,
2579  *    Monday being 1. This works well with \%G and \%V.
2580  * - \%V: the ISO 8601 standard week number of the current year as a decimal
2581  *   number, range 01 to 53, where week 1 is the first week that has at
2582  *   least 4 days in the new year. See g_date_time_get_week_of_year().
2583  *   This works well with \%G and \%u.
2584  * - \%w: the day of the week as a decimal, range 0 to 6, Sunday being 0.
2585  *   This is not the ISO 8601 standard format -- use \%u instead.
2586  * - \%x: the preferred date representation for the current locale without
2587  *   the time
2588  * - \%X: the preferred time representation for the current locale without
2589  *   the date
2590  * - \%y: the year as a decimal number without the century
2591  * - \%Y: the year as a decimal number including the century
2592  * - \%z: the time zone as an offset from UTC (+hhmm)
2593  * - \%:z: the time zone as an offset from UTC (+hh:mm).
2594  *   This is a gnulib strftime() extension. Since: 2.38
2595  * - \%::z: the time zone as an offset from UTC (+hh:mm:ss). This is a
2596  *   gnulib strftime() extension. Since: 2.38
2597  * - \%:::z: the time zone as an offset from UTC, with : to necessary
2598  *   precision (e.g., -04, +05:30). This is a gnulib strftime() extension. Since: 2.38
2599  * - \%Z: the time zone or name or abbreviation
2600  * - \%\%: a literal \% character
2601  *
2602  * Some conversion specifications can be modified by preceding the
2603  * conversion specifier by one or more modifier characters. The
2604  * following modifiers are supported for many of the numeric
2605  * conversions:
2606  *
2607  * - O: Use alternative numeric symbols, if the current locale supports those.
2608  * - _: Pad a numeric result with spaces. This overrides the default padding
2609  *   for the specifier.
2610  * - -: Do not pad a numeric result. This overrides the default padding
2611  *   for the specifier.
2612  * - 0: Pad a numeric result with zeros. This overrides the default padding
2613  *   for the specifier.
2614  *
2615  * Returns: a newly allocated string formatted to the requested format
2616  *     or %NULL in the case that there was an error. The string
2617  *     should be freed with g_free().
2618  *
2619  * Since: 2.26
2620  */
2621 gchar *
2622 g_date_time_format (GDateTime   *datetime,
2623                     const gchar *format)
2624 {
2625   GString  *outstr;
2626   gchar *utf8;
2627   gboolean locale_is_utf8 = g_get_charset (NULL);
2628
2629   g_return_val_if_fail (datetime != NULL, NULL);
2630   g_return_val_if_fail (format != NULL, NULL);
2631   g_return_val_if_fail (g_utf8_validate (format, -1, NULL), NULL);
2632
2633   outstr = g_string_sized_new (strlen (format) * 2);
2634
2635   if (!g_date_time_format_locale (datetime, format, outstr, locale_is_utf8))
2636     {
2637       g_string_free (outstr, TRUE);
2638       return NULL;
2639     }
2640
2641   if (locale_is_utf8)
2642     return g_string_free (outstr, FALSE);
2643
2644   utf8 = g_locale_to_utf8 (outstr->str, outstr->len, NULL, NULL, NULL);
2645   g_string_free (outstr, TRUE);
2646   return utf8;
2647 }
2648
2649
2650 /* Epilogue {{{1 */
2651 /* vim:set foldmethod=marker: */