[glib/wip/date-time-fixes] GDateTime: fill in and improve docs
- From: Ryan Lortie <ryanl src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [glib/wip/date-time-fixes] GDateTime: fill in and improve docs
- Date: Fri, 17 Sep 2010 06:29:36 +0000 (UTC)
commit 5e2dd40c7d56e3984e42af9f325faa83f866cc27
Author: Ryan Lortie <desrt desrt ca>
Date: Fri Sep 17 02:29:16 2010 -0400
GDateTime: fill in and improve docs
docs/reference/glib/glib-sections.txt | 81 +++-
glib/gdatetime.c | 881 +++++++++++++++++++++------------
glib/gdatetime.h | 88 ++--
3 files changed, 671 insertions(+), 379 deletions(-)
---
diff --git a/docs/reference/glib/glib-sections.txt b/docs/reference/glib/glib-sections.txt
index 0b2a056..e4b1b85 100644
--- a/docs/reference/glib/glib-sections.txt
+++ b/docs/reference/glib/glib-sections.txt
@@ -1429,64 +1429,101 @@ g_time_zone_is_dst
<SECTION>
<FILE>date-time</FILE>
+GTimeSpan
G_TIME_SPAN_DAY
G_TIME_SPAN_HOUR
G_TIME_SPAN_MINUTE
G_TIME_SPAN_SECOND
-G_TIME_SPAN_MILLISECONT
-GTimeSpan
+G_TIME_SPAN_MILLISECOND
+
<SUBSECTION>
GDateTime
-g_date_time_new_full
-g_date_time_new_from_date
-g_date_time_new_from_epoch
-g_date_time_new_from_timeval
-g_date_time_new_now
-g_date_time_new_utc_now
-g_date_time_new_today
-g_date_time_ref
g_date_time_unref
+g_date_time_ref
+
+<SUBSECTION>
+g_date_time_new_now
+g_date_time_new_now_local
+g_date_time_new_now_utc
+
+<SUBSECTION>
+g_date_time_new_from_unix
+g_date_time_new_from_unix_local
+g_date_time_new_from_unix_utc
+
+<SUBSECTION>
+g_date_time_new_from_timeval
+g_date_time_new_from_timeval_local
+g_date_time_new_from_timeval_utc
+
+<SUBSECTION>
+g_date_time_new
+g_date_time_new_full
+g_date_time_new_local
+g_date_time_new_local_full
+g_date_time_new_utc
+
<SUBSECTION>
g_date_time_add
+
+<SUBSECTION>
g_date_time_add_years
g_date_time_add_months
g_date_time_add_weeks
g_date_time_add_days
+
+<SUBSECTION>
g_date_time_add_hours
g_date_time_add_minutes
g_date_time_add_seconds
-g_date_time_add_milliseconds
+
+<SUBSECTION>
g_date_time_add_full
+
<SUBSECTION>
-g_date_time_difference
g_date_time_compare
-g_date_time_equal
+g_date_time_difference
g_date_time_hash
+g_date_time_equal
+
+<SUBSECTION>
+g_date_time_get_ymd
+
<SUBSECTION>
-g_date_time_get_dmy
g_date_time_get_year
g_date_time_get_month
-g_date_time_get_week_of_year
g_date_time_get_day_of_month
+
+<SUBSECTION>
+g_date_time_get_week_of_year
g_date_time_get_day_of_week
+
+<SUBSECTION>
g_date_time_get_day_of_year
+
+<SUBSECTION>
g_date_time_get_hour
g_date_time_get_minute
g_date_time_get_second
-g_date_time_get_millisecond
g_date_time_get_microsecond
-g_date_time_get_julian
+g_date_time_get_seconds
+
+<SUBSECTION>
+g_date_time_to_unix
+g_date_time_to_timeval
+
+<SUBSECTION>
g_date_time_get_utc_offset
g_date_time_get_timezone_abbreviation
g_date_time_is_daylight_savings
-g_date_time_is_leap_year
+
<SUBSECTION>
-g_date_time_day
-g_date_time_to_epoch
+g_date_time_to_timezone
g_date_time_to_local
-g_date_time_to_timeval
g_date_time_to_utc
-g_date_time_printf
+
+<SUBSECTION>
+g_date_time_format
</SECTION>
<SECTION>
diff --git a/glib/gdatetime.c b/glib/gdatetime.c
index 29896bf..a6f43b8 100644
--- a/glib/gdatetime.c
+++ b/glib/gdatetime.c
@@ -76,6 +76,7 @@
* SECTION:date-time
* @title: GDateTime
* @short_description: A structure representing Date and Time
+ * @see_also: #GTimeZone
*
* #GDateTime is a structure that combines a Gregorian date and time
* into a single structure. It provides many conversion and methods to
@@ -329,59 +330,54 @@ ymd_to_days (gint year,
return days;
}
-/* Internal state transformers {{{1 */
-
-/*< internal >
- * g_date_time_deal_with_date_change:
- * @datetime: a #GDateTime
- *
- * This function should be called whenever the date changes by adding
- * days, months or years. It does three things.
- *
- * First, we ensure that the date falls between 0001-01-01 and
- * 9999-12-31 and return %FALSE if it does not.
- *
- * Next we update the ->interval field.
- *
- * Finally, we ensure that the resulting date and time pair exists (by
- * ensuring that our timezone has an interval containing it) and
- * adjusting as required. For example, if we have the time 02:30:00 on
- * March 13 2010 in Toronto and we add 1 day to it, we would end up with
- * 2:30am on March 14th, which doesn't exist. In that case, we bump the
- * time up to 3:00am.
- */
-static gboolean
-g_date_time_deal_with_date_change (GDateTime *datetime)
+static void
+g_date_time_get_week_number (GDateTime *datetime,
+ gint *week_number,
+ gint *day_of_week,
+ gint *day_of_year)
{
- GTimeType was_dst;
- gint64 full_time;
- gint64 usec;
-
- if (datetime->days < 1 || datetime->days > 3652059)
- return FALSE;
-
- was_dst = g_time_zone_is_dst (datetime->tz, datetime->interval);
+ gint a, b, c, d, e, f, g, n, s, month, day, year;
- full_time = datetime->days * USEC_PER_DAY + datetime->usec;
+ g_date_time_get_ymd (datetime, &year, &month, &day);
+ if (month <= 2)
+ {
+ a = g_date_time_get_year (datetime) - 1;
+ b = (a / 4) - (a / 100) + (a / 400);
+ c = ((a - 1) / 4) - ((a - 1) / 100) + ((a - 1) / 400);
+ s = b - c;
+ e = 0;
+ f = day - 1 + (31 * (month - 1));
+ }
+ else
+ {
+ a = year;
+ b = (a / 4) - (a / 100) + (a / 400);
+ c = ((a - 1) / 4) - ((a - 1) / 100) + ((a - 1) / 400);
+ s = b - c;
+ e = s + 1;
+ f = day + (((153 * (month - 3)) + 2) / 5) + 58 + s;
+ }
- usec = full_time % USEC_PER_SECOND;
- full_time /= USEC_PER_SECOND;
- full_time -= UNIX_EPOCH_START * SEC_PER_DAY;
+ g = (a + b) % 7;
+ d = (f + g - e) % 7;
+ n = f + 3 - d;
- datetime->interval = g_time_zone_adjust_time (datetime->tz,
- was_dst,
- &full_time);
- full_time += UNIX_EPOCH_START * SEC_PER_DAY;
- full_time *= USEC_PER_SECOND;
- full_time += usec;
+ if (week_number)
+ {
+ if (n < 0)
+ *week_number = 53 - ((g - s) / 5);
+ else if (n > 364 + s)
+ *week_number = 1;
+ else
+ *week_number = (n / 7) + 1;
+ }
- datetime->days = full_time / USEC_PER_DAY;
- datetime->usec = full_time % USEC_PER_DAY;
+ if (day_of_week)
+ *day_of_week = d + 1;
- /* maybe daylight time caused us to shift to a different day,
- * but it definitely didn't push us into a different year */
- return TRUE;
+ if (day_of_year)
+ *day_of_year = f + 1;
}
/* Lifecycle {{{1 */
@@ -443,8 +439,7 @@ g_date_time_unref (GDateTime *datetime)
}
}
-/* Constructors {{{1 */
-
+/* Internal state transformers {{{1 */
/*< internal >
* g_date_time_to_instant:
* @datetime: a #GDateTime
@@ -452,7 +447,7 @@ g_date_time_unref (GDateTime *datetime)
* Convert a @datetime into an instant.
*
* An instant is a number that uniquely describes a particular
- * microsecond in time, taking timezone considerations into account.
+ * microsecond in time, taking time zone considerations into account.
* (ie: "03:00 -0400" is the same instant as "02:00 -0500").
*
* An instant is always positive but we use a signed return value to
@@ -474,7 +469,7 @@ g_date_time_to_instant (GDateTime *datetime)
* @tz: a #GTimeZone
* @instant: a instant in time
*
- * Creates a #GDateTime from a timezone and an instant.
+ * Creates a #GDateTime from a time zone and an instant.
*
* This might fail if the time ends up being out of range.
*/
@@ -509,6 +504,101 @@ g_date_time_from_instant (GTimeZone *tz,
return datetime;
}
+
+/*< internal >
+ * g_date_time_deal_with_date_change:
+ * @datetime: a #GDateTime
+ *
+ * This function should be called whenever the date changes by adding
+ * days, months or years. It does three things.
+ *
+ * First, we ensure that the date falls between 0001-01-01 and
+ * 9999-12-31 and return %FALSE if it does not.
+ *
+ * Next we update the ->interval field.
+ *
+ * Finally, we ensure that the resulting date and time pair exists (by
+ * ensuring that our time zone has an interval containing it) and
+ * adjusting as required. For example, if we have the time 02:30:00 on
+ * March 13 2010 in Toronto and we add 1 day to it, we would end up with
+ * 2:30am on March 14th, which doesn't exist. In that case, we bump the
+ * time up to 3:00am.
+ */
+static gboolean
+g_date_time_deal_with_date_change (GDateTime *datetime)
+{
+ GTimeType was_dst;
+ gint64 full_time;
+ gint64 usec;
+
+ if (datetime->days < 1 || datetime->days > 3652059)
+ return FALSE;
+
+ was_dst = g_time_zone_is_dst (datetime->tz, datetime->interval);
+
+ full_time = datetime->days * USEC_PER_DAY + datetime->usec;
+
+
+ usec = full_time % USEC_PER_SECOND;
+ full_time /= USEC_PER_SECOND;
+ full_time -= UNIX_EPOCH_START * SEC_PER_DAY;
+
+ datetime->interval = g_time_zone_adjust_time (datetime->tz,
+ was_dst,
+ &full_time);
+ full_time += UNIX_EPOCH_START * SEC_PER_DAY;
+ full_time *= USEC_PER_SECOND;
+ full_time += usec;
+
+ datetime->days = full_time / USEC_PER_DAY;
+ datetime->usec = full_time % USEC_PER_DAY;
+
+ /* maybe daylight time caused us to shift to a different day,
+ * but it definitely didn't push us into a different year */
+ return TRUE;
+}
+
+static GDateTime *
+g_date_time_replace_days (GDateTime *datetime,
+ gint days)
+{
+ GDateTime *new;
+
+ new = g_date_time_alloc (datetime->tz);
+ new->interval = datetime->interval;
+ new->usec = datetime->usec;
+ new->days = days;
+
+ if (!g_date_time_deal_with_date_change (new))
+ {
+ g_date_time_unref (new);
+ new = NULL;
+ }
+
+ return new;
+}
+
+/* now/unix/timeval Constructors {{{1 */
+
+/**
+ * g_date_time_new_now:
+ * @tz: a #GTimeZone
+ *
+ * Creates a #GDateTime corresponding to this exact instant in the given
+ * time zone @tz. The time is as accurate as the system allows, to a
+ * maximum accuracy of 1 microsecond.
+ *
+ * This function will always succeed unless the system clock is set to
+ * truly insane values (or unless GLib is still being used after the
+ * year 9999).
+ *
+ * The should release the return value by calling g_date_time_unref()
+ * when you are done with it.
+ *
+ * Returns: a new #GDateTime, or %NULL
+ *
+ * Since: 2.26
+ **/
GDateTime *
g_date_time_new_now (GTimeZone *tz)
{
@@ -519,6 +609,19 @@ g_date_time_new_now (GTimeZone *tz)
return g_date_time_new_from_timeval (tz, &tv);
}
+/**
+ * g_date_time_new_now_local:
+ *
+ * Creates a #GDateTime corresponding to this exact instant in the local
+ * time zone.
+ *
+ * This is equivalent to calling g_date_time_new_now() with the time
+ * zone returned by g_time_zone_new_local().
+ *
+ * Returns: a new #GDateTime, or %NULL
+ *
+ * Since: 2.26
+ **/
GDateTime *
g_date_time_new_now_local (void)
{
@@ -532,6 +635,18 @@ g_date_time_new_now_local (void)
return datetime;
}
+/**
+ * g_date_time_new_now_utc:
+ *
+ * Creates a #GDateTime corresponding to this exact instant in UTC.
+ *
+ * This is equivalent to calling g_date_time_new_now() with the time
+ * zone returned by g_time_zone_new_utc().
+ *
+ * Returns: a new #GDateTime, or %NULL
+ *
+ * Since: 2.26
+ **/
GDateTime *
g_date_time_new_now_utc (void)
{
@@ -545,6 +660,27 @@ g_date_time_new_now_utc (void)
return datetime;
}
+/**
+ * g_date_time_new_from_unix:
+ * @tz: a #GTimeZone
+ * @t: the Unix time
+ *
+ * Creates a #GDateTime corresponding to the given Unix time @t in the
+ * given time zone @tz.
+ *
+ * Unix time is the number of seconds that have elapsed since 1970-01-01
+ * 00:00:00 UTC, regardless of the time zone given.
+ *
+ * This call can fail (returning %NULL) if @t represents a time outside
+ * of the supported range of #GDateTime.
+ *
+ * The should release the return value by calling g_date_time_unref()
+ * when you are done with it.
+ *
+ * Returns: a new #GDateTime, or %NULL
+ *
+ * Since: 2.26
+ **/
GDateTime *
g_date_time_new_from_unix (GTimeZone *tz,
gint64 secs)
@@ -552,6 +688,20 @@ g_date_time_new_from_unix (GTimeZone *tz,
return g_date_time_from_instant (tz, UNIX_TO_INSTANT (secs));
}
+/**
+ * g_date_time_new_from_unix_local:
+ * @t: the Unix time
+ *
+ * Creates a #GDateTime corresponding to the given Unix time @t in the
+ * local time zone.
+ *
+ * This is equivalent to calling g_date_time_new_from_unix() with the
+ * time zone returned by g_time_zone_new_local().
+ *
+ * Returns: a new #GDateTime, or %NULL
+ *
+ * Since: 2.26
+ **/
GDateTime *
g_date_time_new_from_unix_local (gint64 t)
{
@@ -565,6 +715,19 @@ g_date_time_new_from_unix_local (gint64 t)
return datetime;
}
+/**
+ * g_date_time_new_from_unix_utc:
+ * @t: the Unix time
+ *
+ * Creates a #GDateTime corresponding to the given Unix time @t in UTC.
+ *
+ * This is equivalent to calling g_date_time_new_from_unix() with the
+ * time zone returned by g_time_zone_new_utc().
+ *
+ * Returns: a new #GDateTime, or %NULL
+ *
+ * Since: 2.26
+ **/
GDateTime *
g_date_time_new_from_unix_utc (gint64 t)
{
@@ -578,6 +741,28 @@ g_date_time_new_from_unix_utc (gint64 t)
return datetime;
}
+/**
+ * g_date_time_new_from_timeval:
+ * @tz: a #GTimeZone
+ * @tv: a #GTimeVal
+ *
+ * Creates a #GDateTime corresponding to the given #GTimeVal @tv in the
+ * given time zone @tz.
+ *
+ * The time contained in a #GTimeVal is always stored in the form of
+ * seconds elapsed since 1970-01-01 00:00:00 UTC, regardless of the
+ * given time zone.
+ *
+ * This call can fail (returning %NULL) if @tv represents a time outside
+ * of the supported range of #GDateTime.
+ *
+ * The should release the return value by calling g_date_time_unref()
+ * when you are done with it.
+ *
+ * Returns: a new #GDateTime, or %NULL
+ *
+ * Since: 2.26
+ **/
GDateTime *
g_date_time_new_from_timeval (GTimeZone *tz,
const GTimeVal *tv)
@@ -586,6 +771,20 @@ g_date_time_new_from_timeval (GTimeZone *tz,
UNIX_TO_INSTANT (tv->tv_sec));
}
+/**
+ * g_date_time_new_from_timeval_local:
+ * @tv: a #GTimeVal
+ *
+ * Creates a #GDateTime corresponding to the given #GTimeVal @tv in the
+ * local time zone.
+ *
+ * This is equivalent to calling g_date_time_new_from_timeval() with the
+ * time zone returned by g_time_zone_new_local().
+ *
+ * Returns: a new #GDateTime, or %NULL
+ *
+ * Since: 2.26
+ **/
GDateTime *
g_date_time_new_from_timeval_local (const GTimeVal *tv)
{
@@ -599,6 +798,19 @@ g_date_time_new_from_timeval_local (const GTimeVal *tv)
return datetime;
}
+/**
+ * g_date_time_new_from_timeval_utc:
+ * @tv: a #GTimeVal
+ *
+ * Creates a #GDateTime corresponding to the given #GTimeVal @tv in UTC.
+ *
+ * This is equivalent to calling g_date_time_new_from_timeval() with the
+ * time zone returned by g_time_zone_new_utc().
+ *
+ * Returns: a new #GDateTime, or %NULL
+ *
+ * Since: 2.26
+ **/
GDateTime *
g_date_time_new_from_timeval_utc (const GTimeVal *tv)
{
@@ -612,6 +824,8 @@ g_date_time_new_from_timeval_utc (const GTimeVal *tv)
return datetime;
}
+/* full new functions {{{1 */
+
GDateTime *
g_date_time_new (GTimeZone *tz,
gint year,
@@ -647,42 +861,6 @@ g_date_time_new (GTimeZone *tz,
}
GDateTime *
-g_date_time_new_local (gint year,
- gint month,
- gint day,
- gint hour,
- gint minute,
- gdouble seconds)
-{
- GDateTime *datetime;
- GTimeZone *local;
-
- local = g_time_zone_new_local ();
- datetime = g_date_time_new (local, year, month, day, hour, minute, seconds);
- g_time_zone_unref (local);
-
- return datetime;
-}
-
-GDateTime *
-g_date_time_new_utc (gint year,
- gint month,
- gint day,
- gint hour,
- gint minute,
- gdouble seconds)
-{
- GDateTime *datetime;
- GTimeZone *utc;
-
- utc = g_time_zone_new_utc ();
- datetime = g_date_time_new (utc, year, month, day, hour, minute, seconds);
- g_time_zone_unref (utc);
-
- return datetime;
-}
-
-GDateTime *
g_date_time_new_full (GTimeZone *tz,
gint year,
gint month,
@@ -720,6 +898,24 @@ g_date_time_new_full (GTimeZone *tz,
}
GDateTime *
+g_date_time_new_local (gint year,
+ gint month,
+ gint day,
+ gint hour,
+ gint minute,
+ gdouble seconds)
+{
+ GDateTime *datetime;
+ GTimeZone *local;
+
+ local = g_time_zone_new_local ();
+ datetime = g_date_time_new (local, year, month, day, hour, minute, seconds);
+ g_time_zone_unref (local);
+
+ return datetime;
+}
+
+GDateTime *
g_date_time_new_local_full (gint year,
gint month,
gint day,
@@ -741,58 +937,26 @@ g_date_time_new_local_full (gint year,
return datetime;
}
-/* Adders {{{1 */
-
-static void
-g_date_time_get_week_number (GDateTime *datetime,
- gint *week_number,
- gint *day_of_week,
- gint *day_of_year)
+GDateTime *
+g_date_time_new_utc (gint year,
+ gint month,
+ gint day,
+ gint hour,
+ gint minute,
+ gdouble seconds)
{
- gint a, b, c, d, e, f, g, n, s, month, day, year;
-
- g_date_time_get_ymd (datetime, &year, &month, &day);
-
- if (month <= 2)
- {
- a = g_date_time_get_year (datetime) - 1;
- b = (a / 4) - (a / 100) + (a / 400);
- c = ((a - 1) / 4) - ((a - 1) / 100) + ((a - 1) / 400);
- s = b - c;
- e = 0;
- f = day - 1 + (31 * (month - 1));
- }
- else
- {
- a = year;
- b = (a / 4) - (a / 100) + (a / 400);
- c = ((a - 1) / 4) - ((a - 1) / 100) + ((a - 1) / 400);
- s = b - c;
- e = s + 1;
- f = day + (((153 * (month - 3)) + 2) / 5) + 58 + s;
- }
-
- g = (a + b) % 7;
- d = (f + g - e) % 7;
- n = f + 3 - d;
-
- if (week_number)
- {
- if (n < 0)
- *week_number = 53 - ((g - s) / 5);
- else if (n > 364 + s)
- *week_number = 1;
- else
- *week_number = (n / 7) + 1;
- }
+ GDateTime *datetime;
+ GTimeZone *utc;
- if (day_of_week)
- *day_of_week = d + 1;
+ utc = g_time_zone_new_utc ();
+ datetime = g_date_time_new (utc, year, month, day, hour, minute, seconds);
+ g_time_zone_unref (utc);
- if (day_of_year)
- *day_of_year = f + 1;
+ return datetime;
}
+/* Adders {{{1 */
+
/**
* g_date_time_add:
* @datetime: a #GDateTime
@@ -813,26 +977,6 @@ g_date_time_add (GDateTime *datetime,
g_date_time_to_instant (datetime));
}
-static GDateTime *
-g_date_time_replace_days (GDateTime *datetime,
- gint days)
-{
- GDateTime *new;
-
- new = g_date_time_alloc (datetime->tz);
- new->interval = datetime->interval;
- new->usec = datetime->usec;
- new->days = days;
-
- if (!g_date_time_deal_with_date_change (new))
- {
- g_date_time_unref (new);
- new = NULL;
- }
-
- return new;
-}
-
/**
* g_date_time_add_years:
* @datetime: a #GDateTime
@@ -978,11 +1122,11 @@ g_date_time_add_hours (GDateTime *datetime,
}
/**
- * g_date_time_add_seconds:
+ * g_date_time_add_minutes:
* @datetime: a #GDateTime
- * @seconds: the number of seconds to add
+ * @minutes: the number of minutes to add
*
- * Creates a copy of @datetime and adds the specified number of seconds.
+ * Creates a copy of @datetime adding the specified number of minutes.
*
* Return value: the newly created #GDateTime which should be freed with
* g_date_time_unref().
@@ -990,18 +1134,19 @@ g_date_time_add_hours (GDateTime *datetime,
* Since: 2.26
*/
GDateTime*
-g_date_time_add_seconds (GDateTime *datetime,
- gdouble seconds)
+g_date_time_add_minutes (GDateTime *datetime,
+ gint minutes)
{
- return g_date_time_add (datetime, seconds * USEC_PER_SECOND);
+ return g_date_time_add (datetime, minutes * USEC_PER_MINUTE);
}
+
/**
- * g_date_time_add_minutes:
+ * g_date_time_add_seconds:
* @datetime: a #GDateTime
- * @minutes: the number of minutes to add
+ * @seconds: the number of seconds to add
*
- * Creates a copy of @datetime adding the specified number of minutes.
+ * Creates a copy of @datetime and adds the specified number of seconds.
*
* Return value: the newly created #GDateTime which should be freed with
* g_date_time_unref().
@@ -1009,10 +1154,10 @@ g_date_time_add_seconds (GDateTime *datetime,
* Since: 2.26
*/
GDateTime*
-g_date_time_add_minutes (GDateTime *datetime,
- gint minutes)
+g_date_time_add_seconds (GDateTime *datetime,
+ gdouble seconds)
{
- return g_date_time_add (datetime, minutes * USEC_PER_MINUTE);
+ return g_date_time_add (datetime, seconds * USEC_PER_SECOND);
}
/**
@@ -1115,7 +1260,7 @@ g_date_time_add_full (GDateTime *datetime,
return new;
}
-/* Compare, equal, hash, difference {{{1 */
+/* Compare, difference, hash, equal {{{1 */
/**
* g_date_time_compare:
* @dt1: first #GDateTime to compare
@@ -1196,7 +1341,7 @@ g_date_time_hash (gconstpointer datetime)
* Checks to see if @dt1 and @dt2 are equal.
*
* Equal here means that they represent the same moment after converting
- * them to the same timezone.
+ * them to the same time zone.
*
* Return value: %TRUE if @dt1 and @dt2 are equal
*
@@ -1209,101 +1354,7 @@ g_date_time_equal (gconstpointer dt1,
return g_date_time_difference ((GDateTime *) dt1, (GDateTime *) dt2) == 0;
}
-/* Getters {{{1 */
-/**
- * g_date_time_get_day_of_week:
- * @datetime: a #GDateTime
- *
- * Retrieves the day of the week represented by @datetime within the gregorian
- * calendar. 1 is Sunday, 2 is Monday, etc.
- *
- * Return value: the day of the week
- *
- * Since: 2.26
- */
-gint
-g_date_time_get_day_of_week (GDateTime *datetime)
-{
- gint a, y, m,
- year = 0,
- month = 0,
- day = 0,
- dow;
-
- g_return_val_if_fail (datetime != NULL, 0);
-
- /*
- * See Calendar FAQ Section 2.6 for algorithm information
- * http://www.tondering.dk/claus/cal/calendar29.txt
- */
-
- g_date_time_get_ymd (datetime, &year, &month, &day);
- a = (14 - month) / 12;
- y = year - a;
- m = month + (12 * a) - 2;
- dow = ((day + y + (y / 4) - (y / 100) + (y / 400) + (31 * m) / 12) % 7);
-
- /* 1 is Monday and 7 is Sunday */
- return (dow == 0) ? 7 : dow;
-}
-
-/**
- * g_date_time_get_day_of_month:
- * @datetime: a #GDateTime
- *
- * Retrieves the day of the month represented by @datetime in the gregorian
- * calendar.
- *
- * Return value: the day of the month
- *
- * Since: 2.26
- */
-gint
-g_date_time_get_day_of_month (GDateTime *datetime)
-{
- gint day_of_year,
- i;
- const guint16 *days;
- guint16 last = 0;
-
- g_return_val_if_fail (datetime != NULL, 0);
-
- days = days_in_year[GREGORIAN_LEAP (g_date_time_get_year (datetime)) ? 1 : 0];
- g_date_time_get_week_number (datetime, NULL, NULL, &day_of_year);
-
- for (i = 1; i <= 12; i++)
- {
- if (days [i] >= day_of_year)
- return day_of_year - last;
- last = days [i];
- }
-
- g_warn_if_reached ();
- return 0;
-}
-
-/**
- * g_date_time_get_day_of_year:
- * @datetime: a #GDateTime
- *
- * Retrieves the day of the year represented by @datetime in the Gregorian
- * calendar.
- *
- * Return value: the day of the year
- *
- * Since: 2.26
- */
-gint
-g_date_time_get_day_of_year (GDateTime *datetime)
-{
- gint doy = 0;
-
- g_return_val_if_fail (datetime != NULL, 0);
-
- g_date_time_get_week_number (datetime, NULL, NULL, &doy);
- return doy;
-}
-
+/* Year, Month, Day Getters {{{1 */
/**
* g_date_time_get_ymd:
* @datetime: a #GDateTime.
@@ -1314,7 +1365,7 @@ g_date_time_get_day_of_year (GDateTime *datetime)
* Retrieves the Gregorian day, month, and year of a given #GDateTime.
*
* Since: 2.26
- */
+ **/
void
g_date_time_get_ymd (GDateTime *datetime,
gint *year,
@@ -1401,61 +1452,89 @@ end:
}
/**
- * g_date_time_get_hour:
- * @datetime: a #GDateTime
+ * g_date_time_get_year:
+ * @datetime: A #GDateTime
*
- * Retrieves the hour of the day represented by @datetime
+ * Retrieves the year represented by @datetime in the Gregorian calendar.
*
- * Return value: the hour of the day
+ * Return value: the year represented by @datetime
*
* Since: 2.26
*/
gint
-g_date_time_get_hour (GDateTime *datetime)
+g_date_time_get_year (GDateTime *datetime)
{
+ gint year;
+
g_return_val_if_fail (datetime != NULL, 0);
- return (datetime->usec / USEC_PER_HOUR);
+ g_date_time_get_ymd (datetime, &year, NULL, NULL);
+
+ return year;
}
/**
- * g_date_time_get_microsecond:
+ * g_date_time_get_month:
* @datetime: a #GDateTime
*
- * Retrieves the microsecond of the date represented by @datetime
+ * Retrieves the month of the year represented by @datetime in the Gregorian
+ * calendar.
*
- * Return value: the microsecond of the second
+ * Return value: the month represented by @datetime
*
* Since: 2.26
*/
gint
-g_date_time_get_microsecond (GDateTime *datetime)
+g_date_time_get_month (GDateTime *datetime)
{
+ gint month;
+
g_return_val_if_fail (datetime != NULL, 0);
- return (datetime->usec % USEC_PER_SECOND);
+ g_date_time_get_ymd (datetime, NULL, &month, NULL);
+
+ return month;
}
/**
- * g_date_time_get_minute:
+ * g_date_time_get_day_of_month:
* @datetime: a #GDateTime
*
- * Retrieves the minute of the hour represented by @datetime
+ * Retrieves the day of the month represented by @datetime in the gregorian
+ * calendar.
*
- * Return value: the minute of the hour
+ * Return value: the day of the month
*
* Since: 2.26
*/
gint
-g_date_time_get_minute (GDateTime *datetime)
+g_date_time_get_day_of_month (GDateTime *datetime)
{
+ gint day_of_year,
+ i;
+ const guint16 *days;
+ guint16 last = 0;
+
g_return_val_if_fail (datetime != NULL, 0);
- return (datetime->usec % USEC_PER_HOUR) / USEC_PER_MINUTE;
+ days = days_in_year[GREGORIAN_LEAP (g_date_time_get_year (datetime)) ? 1 : 0];
+ g_date_time_get_week_number (datetime, NULL, NULL, &day_of_year);
+
+ for (i = 1; i <= 12; i++)
+ {
+ if (days [i] >= day_of_year)
+ return day_of_year - last;
+ last = days [i];
+ }
+
+ g_warn_if_reached ();
+ return 0;
}
+/* Week of year / day of week getters {{{1 */
/**
* g_date_time_get_week_of_year:
+ * @datetime: a #GDateTime
*
* Returns the numeric week of the respective year.
*
@@ -1476,49 +1555,101 @@ g_date_time_get_week_of_year (GDateTime *datetime)
}
/**
- * g_date_time_get_year:
- * @datetime: A #GDateTime
+ * g_date_time_get_day_of_week:
+ * @datetime: a #GDateTime
*
- * Retrieves the year represented by @datetime in the Gregorian calendar.
+ * Retrieves the day of the week represented by @datetime within the gregorian
+ * calendar. 1 is Sunday, 2 is Monday, etc.
*
- * Return value: the year represented by @datetime
+ * Return value: the day of the week
*
* Since: 2.26
*/
gint
-g_date_time_get_year (GDateTime *datetime)
+g_date_time_get_day_of_week (GDateTime *datetime)
{
- gint year;
+ gint a, y, m,
+ year = 0,
+ month = 0,
+ day = 0,
+ dow;
g_return_val_if_fail (datetime != NULL, 0);
- g_date_time_get_ymd (datetime, &year, NULL, NULL);
+ /*
+ * See Calendar FAQ Section 2.6 for algorithm information
+ * http://www.tondering.dk/claus/cal/calendar29.txt
+ */
- return year;
-}
+ g_date_time_get_ymd (datetime, &year, &month, &day);
+ a = (14 - month) / 12;
+ y = year - a;
+ m = month + (12 * a) - 2;
+ dow = ((day + y + (y / 4) - (y / 100) + (y / 400) + (31 * m) / 12) % 7);
+ /* 1 is Monday and 7 is Sunday */
+ return (dow == 0) ? 7 : dow;
+}
+/* Day of year getter {{{1 */
/**
- * g_date_time_get_month:
+ * g_date_time_get_day_of_year:
* @datetime: a #GDateTime
*
- * Retrieves the month of the year represented by @datetime in the Gregorian
+ * Retrieves the day of the year represented by @datetime in the Gregorian
* calendar.
*
- * Return value: the month represented by @datetime
+ * Return value: the day of the year
*
* Since: 2.26
*/
gint
-g_date_time_get_month (GDateTime *datetime)
+g_date_time_get_day_of_year (GDateTime *datetime)
{
- gint month;
+ gint doy = 0;
g_return_val_if_fail (datetime != NULL, 0);
- g_date_time_get_ymd (datetime, NULL, &month, NULL);
+ g_date_time_get_week_number (datetime, NULL, NULL, &doy);
+ return doy;
+}
- return month;
+/* Time component getters {{{1 */
+
+/**
+ * g_date_time_get_hour:
+ * @datetime: a #GDateTime
+ *
+ * Retrieves the hour of the day represented by @datetime
+ *
+ * Return value: the hour of the day
+ *
+ * Since: 2.26
+ */
+gint
+g_date_time_get_hour (GDateTime *datetime)
+{
+ g_return_val_if_fail (datetime != NULL, 0);
+
+ return (datetime->usec / USEC_PER_HOUR);
+}
+
+/**
+ * g_date_time_get_minute:
+ * @datetime: a #GDateTime
+ *
+ * Retrieves the minute of the hour represented by @datetime
+ *
+ * Return value: the minute of the hour
+ *
+ * Since: 2.26
+ */
+gint
+g_date_time_get_minute (GDateTime *datetime)
+{
+ g_return_val_if_fail (datetime != NULL, 0);
+
+ return (datetime->usec % USEC_PER_HOUR) / USEC_PER_MINUTE;
}
/**
@@ -1539,13 +1670,87 @@ g_date_time_get_second (GDateTime *datetime)
return (datetime->usec % USEC_PER_MINUTE) / USEC_PER_SECOND;
}
+/**
+ * g_date_time_get_microsecond:
+ * @datetime: a #GDateTime
+ *
+ * Retrieves the microsecond of the date represented by @datetime
+ *
+ * Return value: the microsecond of the second
+ *
+ * Since: 2.26
+ */
+gint
+g_date_time_get_microsecond (GDateTime *datetime)
+{
+ g_return_val_if_fail (datetime != NULL, 0);
+
+ return (datetime->usec % USEC_PER_SECOND);
+}
+
+/**
+ * g_date_time_get_seconds:
+ * @datetime: a #GDateTime
+ *
+ * Retrieves the number of seconds since the start of the last minute,
+ * including the fractional part.
+ *
+ * Returns: the number of seconds
+ *
+ * Since: 2.26
+ **/
+gdouble
+g_date_time_get_seconds (GDateTime *datetime)
+{
+ g_return_val_if_fail (datetime != NULL, 0);
+
+ return (datetime->usec % USEC_PER_MINUTE) / 1000000.0;
+}
+
/* Exporters {{{1 */
+/**
+ * g_date_time_to_unix:
+ * @datetime: a #GDateTime
+ *
+ * Gives the Unix time corresponding to @datetime, rounding down to the
+ * nearest second.
+ *
+ * Unix time is the number of seconds that have elapsed since 1970-01-01
+ * 00:00:00 UTC, regardless of the time zone associated with @datetime.
+ *
+ * Returns: the Unix time corresponding to @datetime
+ *
+ * Since: 2.26
+ **/
gint64
g_date_time_to_unix (GDateTime *datetime)
{
return INSTANT_TO_UNIX (g_date_time_to_instant (datetime));
}
+/**
+ * g_date_time_to_timeval:
+ * @datetime: a #GDateTime
+ * @tv: a #GTimeVal to modify
+ *
+ * Stores the instant in time that @datetime represents into @tv.
+ *
+ * The time contained in a #GTimeVal is always stored in the form of
+ * seconds elapsed since 1970-01-01 00:00:00 UTC, regardless of the time
+ * zone associated with @datetime.
+ *
+ * On systems where 'long' is 32bit (ie: all 32bit systems and all
+ * Windows systems), a #GTimeVal is incapable of storing the entire
+ * range of values that #GDateTime is capable of expressing. On those
+ * systems, this function returns %FALSE to indicate that the time is
+ * out of range.
+ *
+ * On systems where 'long' is 64bit, this function never fails.
+ *
+ * Returns: %TRUE if successful, else %FALSE
+ *
+ * Since: 2.26
+ **/
gboolean
g_date_time_to_timeval (GDateTime *datetime,
GTimeVal *tv)
@@ -1561,16 +1766,20 @@ g_date_time_to_timeval (GDateTime *datetime,
* g_date_time_get_utc_offset:
* @datetime: a #GDateTime
*
- * Retrieves the offset from UTC that the local timezone specified by
- * @datetime represents.
+ * Determines the offset to UTC in effect at the time and in the time
+ * zone of @datetime.
+ *
+ * The offset is the number of microseconds that you add to UTC time to
+ * arrive at local time for the time zone (ie: negative numbers for time
+ * zones west of GMT, positive numbers for east).
*
- * If @datetime represents UTC time, then the offset is zero.
+ * If @datetime represents UTC time, then the offset is always zero.
*
- * Return value: the offset, expressed as a time span expressed in
- * microseconds.
+ * Returns: the number of microseconds that should be added to UTC to
+ * get the local time
*
* Since: 2.26
- */
+ **/
GTimeSpan
g_date_time_get_utc_offset (GDateTime *datetime)
{
@@ -1587,14 +1796,19 @@ g_date_time_get_utc_offset (GDateTime *datetime)
* g_date_time_get_timezone_abbreviation:
* @datetime: a #GDateTime
*
- * Retrieves the timezone abbreviation for the date specified by @datetime, if any.
+ * Determines the time zone abbreviation to be used at the time and in
+ * the time zone of @datetime.
+ *
+ * For example, in Toronto this is currently "EST" during the winter
+ * months and "EDT" during the summer months when daylight savings
+ * time is in effect.
*
- * Return value: (transfer none): the timezone abbreviation. The returned
- * string is owned by the #GDateTime and it should not be modified or
- * freed
+ * Returns: (transfer none): the time zone abbreviation. The returned
+ * string is owned by the #GDateTime and it should not be
+ * modified or freed
*
* Since: 2.26
- */
+ **/
const gchar *
g_date_time_get_timezone_abbreviation (GDateTime *datetime)
{
@@ -1607,13 +1821,13 @@ g_date_time_get_timezone_abbreviation (GDateTime *datetime)
* g_date_time_is_daylight_savings:
* @datetime: a #GDateTime
*
- * Determines if @datetime represents a date known to fall within daylight
- * savings time in the gregorian calendar.
+ * Determines if daylight savings time is in effect at the time and in
+ * the time zone of @datetime.
*
- * Return value: %TRUE if @datetime falls within daylight savings time.
+ * Returns: %TRUE if daylight savings time is in effect
*
* Since: 2.26
- */
+ **/
gboolean
g_date_time_is_daylight_savings (GDateTime *datetime)
{
@@ -1623,6 +1837,25 @@ g_date_time_is_daylight_savings (GDateTime *datetime)
}
/* Timezone convert {{{1 */
+/**
+ * g_date_time_to_timezone:
+ * @datetime: a #GDateTime
+ * @tz: the new #GTimeZone
+ *
+ * Create a new #GDateTime corresponding to the same instant in time as
+ * @datetime, but in the time zone @tz.
+ *
+ * This call can fail in the case that the time goes out of bounds. For
+ * example, converting 0001-01-01 00:00:00 UTC to a time zone west of
+ * Greenwich will fail (due to the year 0 being out of range).
+ *
+ * The should release the return value by calling g_date_time_unref()
+ * when you are done with it.
+ *
+ * Returns: a new #GDateTime, or %NULL
+ *
+ * Since: 2.26
+ **/
GDateTime *
g_date_time_to_timezone (GDateTime *datetime,
GTimeZone *tz)
@@ -1630,18 +1863,20 @@ g_date_time_to_timezone (GDateTime *datetime,
return g_date_time_from_instant (tz, g_date_time_to_instant (datetime));
}
-
-
/**
* g_date_time_to_local:
* @datetime: a #GDateTime
*
- * Creates a new #GDateTime with @datetime converted to local time.
+ * Creates a new #GDateTime corresponding to the same instant in time as
+ * @datetime, but in the local time zone.
+ *
+ * This call is equivalent to calling g_date_time_to_timezone() with the
+ * time zone returned by g_time_zone_new_local().
*
- * Return value: the newly created #GDateTime
+ * Returns: the newly created #GDateTime
*
* Since: 2.26
- */
+ **/
GDateTime *
g_date_time_to_local (GDateTime *datetime)
{
@@ -1655,6 +1890,20 @@ g_date_time_to_local (GDateTime *datetime)
return new;
}
+/**
+ * g_date_time_to_utc:
+ * @datetime: a #GDateTime
+ *
+ * Creates a new #GDateTime corresponding to the same instant in time as
+ * @datetime, but in UTC.
+ *
+ * This call is equivalent to calling g_date_time_to_timezone() with the
+ * time zone returned by g_time_zone_new_utc().
+ *
+ * Returns: the newly created #GDateTime
+ *
+ * Since: 2.26
+ **/
GDateTime *
g_date_time_to_utc (GDateTime *datetime)
{
@@ -1716,7 +1965,7 @@ g_date_time_to_utc (GDateTime *datetime)
* %%y The year as a decimal number without the century.
* %%Y The year as a decimal number including the century.
* %%z The time-zone as hour offset from UTC
- * %%Z The timezone or name or abbreviation
+ * %%Z The time zone or name or abbreviation
* %%% A literal %% character.
*
* Return value: a newly allocated string formatted to the requested format or
diff --git a/glib/gdatetime.h b/glib/gdatetime.h
index 210f13a..32d5cc3 100644
--- a/glib/gdatetime.h
+++ b/glib/gdatetime.h
@@ -98,73 +98,78 @@ typedef gint64 GTimeSpan;
*/
typedef struct _GDateTime GDateTime;
-GDateTime * g_date_time_ref (GDateTime *datetime);
void g_date_time_unref (GDateTime *datetime);
+GDateTime * g_date_time_ref (GDateTime *datetime);
+GDateTime * g_date_time_new_now (GTimeZone *tz);
GDateTime * g_date_time_new_now_local (void);
GDateTime * g_date_time_new_now_utc (void);
-GDateTime * g_date_time_new_now (GTimeZone *tz);
-GDateTime * g_date_time_new_from_unix_local (gint64 secs);
-GDateTime * g_date_time_new_from_unix_utc (gint64 secs);
-GDateTime * g_date_time_new_from_unix (GTimeZone *timezone,
- gint64 secs);
+GDateTime * g_date_time_new_from_unix (GTimeZone *tz,
+ gint64 t);
+GDateTime * g_date_time_new_from_unix_local (gint64 t);
+GDateTime * g_date_time_new_from_unix_utc (gint64 t);
+
+GDateTime * g_date_time_new_from_timeval (GTimeZone *tz,
+ const GTimeVal *tv);
GDateTime * g_date_time_new_from_timeval_local (const GTimeVal *tv);
GDateTime * g_date_time_new_from_timeval_utc (const GTimeVal *tv);
-GDateTime * g_date_time_new_from_timeval (GTimeZone *timezone,
- const GTimeVal *tv);
-GDateTime * g_date_time_new_local (gint year,
+GDateTime * g_date_time_new (GTimeZone *tz,
+ gint year,
gint month,
gint day,
gint hour,
gint minute,
gdouble second);
-GDateTime * g_date_time_new_local_full (gint year,
+GDateTime * g_date_time_new_full (GTimeZone *tz,
+ gint year,
gint month,
gint day,
gint hour,
gint minute,
gdouble second,
gboolean is_dst);
-GDateTime * g_date_time_new_utc (gint year,
+
+GDateTime * g_date_time_new_local (gint year,
gint month,
gint day,
gint hour,
gint minute,
gdouble second);
-GDateTime * g_date_time_new (GTimeZone *tz,
- gint year,
+GDateTime * g_date_time_new_local_full (gint year,
gint month,
gint day,
gint hour,
gint minute,
- gdouble second);
-GDateTime * g_date_time_new_full (GTimeZone *tz,
- gint year,
+ gdouble second,
+ gboolean is_dst);
+GDateTime * g_date_time_new_utc (gint year,
gint month,
gint day,
gint hour,
gint minute,
- gdouble second,
- gboolean is_dst);
+ gdouble second);
GDateTime * g_date_time_add (GDateTime *datetime,
GTimeSpan timespan);
+
+GDateTime * g_date_time_add_years (GDateTime *datetime,
+ gint years);
+GDateTime * g_date_time_add_months (GDateTime *datetime,
+ gint months);
+GDateTime * g_date_time_add_weeks (GDateTime *datetime,
+ gint weeks);
GDateTime * g_date_time_add_days (GDateTime *datetime,
gint days);
+
GDateTime * g_date_time_add_hours (GDateTime *datetime,
gint hours);
GDateTime * g_date_time_add_minutes (GDateTime *datetime,
gint minutes);
-GDateTime * g_date_time_add_months (GDateTime *datetime,
- gint months);
GDateTime * g_date_time_add_seconds (GDateTime *datetime,
gdouble seconds);
-GDateTime * g_date_time_add_weeks (GDateTime *datetime,
- gint weeks);
-GDateTime * g_date_time_add_years (GDateTime *datetime,
- gint years);
+
GDateTime * g_date_time_add_full (GDateTime *datetime,
gint years,
gint months,
@@ -175,28 +180,31 @@ GDateTime * g_date_time_add_full (GDateTi
gint g_date_time_compare (gconstpointer dt1,
gconstpointer dt2);
+GTimeSpan g_date_time_difference (GDateTime *begin,
+ GDateTime *end);
+guint g_date_time_hash (gconstpointer datetime);
gboolean g_date_time_equal (gconstpointer dt1,
gconstpointer dt2);
-guint g_date_time_hash (gconstpointer datetime);
-GTimeSpan g_date_time_difference (GDateTime *begin,
- GDateTime *end);
+void g_date_time_get_ymd (GDateTime *datetime,
+ gint *year,
+ gint *month,
+ gint *day);
+
+gint g_date_time_get_year (GDateTime *datetime);
+gint g_date_time_get_month (GDateTime *datetime);
+gint g_date_time_get_day_of_month (GDateTime *datetime);
+
+gint g_date_time_get_week_of_year (GDateTime *datetime);
+gint g_date_time_get_day_of_week (GDateTime *datetime);
+
+gint g_date_time_get_day_of_year (GDateTime *datetime);
gint g_date_time_get_hour (GDateTime *datetime);
gint g_date_time_get_minute (GDateTime *datetime);
gint g_date_time_get_second (GDateTime *datetime);
gint g_date_time_get_microsecond (GDateTime *datetime);
gdouble g_date_time_get_seconds (GDateTime *datetime);
-gint g_date_time_get_day_of_week (GDateTime *datetime);
-gint g_date_time_get_day_of_month (GDateTime *datetime);
-gint g_date_time_get_week_of_year (GDateTime *datetime);
-gint g_date_time_get_day_of_year (GDateTime *datetime);
-gint g_date_time_get_month (GDateTime *datetime);
-gint g_date_time_get_year (GDateTime *datetime);
-void g_date_time_get_ymd (GDateTime *datetime,
- gint *year,
- gint *month,
- gint *day);
gint64 g_date_time_to_unix (GDateTime *datetime);
gboolean g_date_time_to_timeval (GDateTime *datetime,
@@ -206,12 +214,10 @@ GTimeSpan g_date_time_get_utc_offset (GDateTi
const gchar * g_date_time_get_timezone_abbreviation (GDateTime *datetime);
gboolean g_date_time_is_daylight_savings (GDateTime *datetime);
-gboolean g_date_time_is_leap_year (GDateTime *datetime);
-
-GDateTime * g_date_time_to_local (GDateTime *datetime);
-GDateTime * g_date_time_to_utc (GDateTime *datetime);
GDateTime * g_date_time_to_timezone (GDateTime *datetime,
GTimeZone *tz);
+GDateTime * g_date_time_to_local (GDateTime *datetime);
+GDateTime * g_date_time_to_utc (GDateTime *datetime);
gchar * g_date_time_format (GDateTime *datetime,
const gchar *format) G_GNUC_MALLOC;
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
