gstreamer/gst/gstdatetime.c

/* GStreamer
 * Copyright (C) 2010 Thiago Santos <thiago.sousa.santos@collabora.co.uk>
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Library General Public
 * License as published by the Free Software Foundation; either
 * version 2 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Library General Public License for more details.
 *
 * You should have received a copy of the GNU Library General Public
 * License along with this library; if not, write to the
 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 * Boston, MA 02111-1307, USA.
 */

#ifdef HAVE_CONFIG_H
#include "config.h"
#endif

#include "glib-compat-private.h"
#include "gst_private.h"
#include "gstdatetime.h"
#include <glib.h>
#include <math.h>

/**
 * SECTION:gstdatetime
 * @title: GstDateTime
 * @short_description: A date, time and timezone structure
 *
 * Struct to store date, time and timezone information altogether.
 * #GstDateTime is refcounted and immutable.
 *
 * Date information is handled using the proleptic Gregorian calendar.
 *
 * Provides basic creation functions and accessor functions to its fields.
 *
 * Since: 0.10.31
 */

#define GST_DATE_TIME_SEC_PER_DAY          (G_GINT64_CONSTANT (86400))
#define GST_DATE_TIME_USEC_PER_DAY         (G_GINT64_CONSTANT (86400000000))
#define GST_DATE_TIME_USEC_PER_HOUR        (G_GINT64_CONSTANT (3600000000))
#define GST_DATE_TIME_USEC_PER_MINUTE      (G_GINT64_CONSTANT (60000000))
#define GST_DATE_TIME_USEC_PER_SECOND      (G_GINT64_CONSTANT (1000000))
#define GST_DATE_TIME_USEC_PER_MILLISECOND (G_GINT64_CONSTANT (1000))

typedef enum
{
  BAD_DATE,
  HAS_Y,                        /* has year */
  HAS_YM,                       /* has year and month */
  HAS_YMD,                      /* has year mont and day */
  HAS_YMD_H,
  HAS_YMD_HM,
  HAS_YMD_HMS
} DateTimeFields;

struct _GstDateTime
{
  GDateTime *datetime;

  DateTimeFields fields;
  volatile gint ref_count;
};

static GstDateTime *
gst_date_time_new_from_gdatetime (GDateTime * dt)
{
  GstDateTime *gst_dt;

  if (!dt)
    return NULL;

  gst_dt = g_slice_new (GstDateTime);
  gst_dt->datetime = dt;
  gst_dt->ref_count = 1;
  return gst_dt;
}

/**
 * gst_date_time_has_year:
 * @datetime: a #GstDateTime
 *
 * Returns the TRUE if year exist
 *
 * Since:
 */
gboolean
gst_date_time_has_year (const GstDateTime * datetime)
{
  return (datetime->fields >= HAS_Y) ? 1 : 0;
}

/**
 * gst_date_time_has_month:
 * @datetime: a #GstDateTime
 *
 * Returns the TRUE if month exist
 *
 * Since:
 */
gboolean
gst_date_time_has_month (const GstDateTime * datetime)
{
  return (datetime->fields >= HAS_YM) ? 1 : 0;
}

/**
 * gst_date_time_has_day:
 * @datetime: a #GstDateTime
 *
 * Returns the TRUE if day exist
 *
 * Since:
 */
gboolean
gst_date_time_has_day (const GstDateTime * datetime)
{
  return (datetime->fields >= HAS_YMD) ? 1 : 0;
}

/**
 * gst_date_time_has_hour:
 * @datetime: a #GstDateTime
 *
 * Returns the TRUE if hour exist
 *
 * Since:
 */
gboolean
gst_date_time_has_hour (const GstDateTime * datetime)
{
  return (datetime->fields >= HAS_YMD_H) ? 1 : 0;
}

/**
 * gst_date_time_has_minute:
 * @datetime: a #GstDateTime
 *
 * Returns the TRUE if minute exist
 *
 * Since:
 */
gboolean
gst_date_time_has_minute (const GstDateTime * datetime)
{
  return (datetime->fields >= HAS_YMD_HM) ? 1 : 0;
}

/**
 * gst_date_time_has_second:
 * @datetime: a #GstDateTime
 *
 * Returns the TRUE if second exist
 *
 * Since:
 */
gboolean
gst_date_time_has_second (const GstDateTime * datetime)
{
  return (datetime->fields >= HAS_YMD_HMS) ? 1 : 0;
}

/**
 * gst_date_time_get_year:
 * @datetime: a #GstDateTime
 *
 * Returns the year of this #GstDateTime
 * Call gst_date_time_has_year before, to avoid warnings.
 *
 * Return value: The year of this #GstDateTime
 * Since: 0.10.31
 */
gint
gst_date_time_get_year (const GstDateTime * datetime)
{
  g_return_val_if_fail (gst_date_time_has_year (datetime), 0);
  return g_date_time_get_year (datetime->datetime);
}

/**
 * gst_date_time_get_month:
 * @datetime: a #GstDateTime
 *
 * Returns the month of this #GstDateTime. January is 1, February is 2, etc..
 * Call gst_date_time_has_month before, to avoid warnings.
 *
 * Return value: The month of this #GstDateTime
 * Since: 0.10.31
 */
gint
gst_date_time_get_month (const GstDateTime * datetime)
{
  g_return_val_if_fail (gst_date_time_has_month (datetime), 0);
  return g_date_time_get_month (datetime->datetime);
}

/**
 * gst_date_time_get_day:
 * @datetime: a #GstDateTime
 *
 * Returns the day of this #GstDateTime.
 * Call gst_date_time_has_day before, to avoid warnings.
 *
 * Return value: The day of this #GstDateTime
 * Since: 0.10.31
 */
gint
gst_date_time_get_day (const GstDateTime * datetime)
{
  g_return_val_if_fail (gst_date_time_has_day (datetime), 0);
  return g_date_time_get_day_of_month (datetime->datetime);
}

/**
 * gst_date_time_get_hour:
 * @datetime: a #GstDateTime
 *
 * Retrieves the hour of the day represented by @datetime in the gregorian
 * calendar. The return is in the range of 0 to 23.
 * Call gst_date_time_has_haur before, to avoid warnings.
 *
 * Return value: the hour of the day
 *
 * Since: 0.10.31
 */
gint
gst_date_time_get_hour (const GstDateTime * datetime)
{
  g_return_val_if_fail (gst_date_time_has_hour (datetime), 0);
  return g_date_time_get_hour (datetime->datetime);
}

/**
 * gst_date_time_get_minute:
 * @datetime: a #GstDateTime
 *
 * Retrieves the minute of the hour represented by @datetime in the gregorian
 * calendar.
 * Call gst_date_time_has_minute before, to avoid warnings.
 *
 * Return value: the minute of the hour
 *
 * Since: 0.10.31
 */
gint
gst_date_time_get_minute (const GstDateTime * datetime)
{
  g_return_val_if_fail (gst_date_time_has_minute (datetime), 0);
  return g_date_time_get_minute (datetime->datetime);
}

/**
 * gst_date_time_get_second:
 * @datetime: a #GstDateTime
 *
 * Retrieves the second of the minute represented by @datetime in the gregorian
 * calendar.
 * Call gst_date_time_has_second before, to avoid warnings.
 *
 * Return value: the second represented by @datetime
 *
 * Since: 0.10.31
 */
gint
gst_date_time_get_second (const GstDateTime * datetime)
{
  g_return_val_if_fail (gst_date_time_has_second (datetime), 0);
  return g_date_time_get_second (datetime->datetime);
}

/**
 * gst_date_time_get_microsecond:
 * @datetime: a #GstDateTime
 *
 * Retrieves the fractional part of the seconds in microseconds represented by
 * @datetime in the gregorian calendar.
 *
 * Return value: the microsecond of the second
 *
 * Since: 0.10.31
 */
gint
gst_date_time_get_microsecond (const GstDateTime * datetime)
{
  return g_date_time_get_microsecond (datetime->datetime);
}

/**
 * gst_date_time_get_time_zone_offset:
 * @datetime: a #GstDateTime
 *
 * Retrieves the offset from UTC in hours that the timezone specified
 * by @datetime represents. Timezones ahead (to the east) of UTC have positive
 * values, timezones before (to the west) of UTC have negative values.
 * If @datetime represents UTC time, then the offset is zero.
 *
 * Return value: the offset from UTC in hours
 * Since: 0.10.31
 */
gfloat
gst_date_time_get_time_zone_offset (const GstDateTime * datetime)
{
  return (g_date_time_get_utc_offset (datetime->datetime) /
      G_USEC_PER_SEC) / 3600.0;
}

/**
 * gst_date_time_new_y:
 * @year: the gregorian year
 *
 * Creates a new #GstDateTime using the date and times in the gregorian calendar
 * in the local timezone.
 *
 * @year should be from 1 to 9999.
 *
 * Free-function: gst_date_time_unref
 *
 * Return value: (transfer full): the newly created #GstDateTime
 *
 * Since:
 */
GstDateTime *
gst_date_time_new_y (gint year)
{
  GstDateTime *datetime;
  datetime = gst_date_time_new_local_time (year, 1, 1, 1, 1, 1);
  datetime->fields = HAS_Y;
  return datetime;
}

/**
 * gst_date_time_new_ym:
 * @year: the gregorian year
 * @month: the gregorian month
 *
 * Creates a new #GstDateTime using the date and times in the gregorian calendar
 * in the local timezone.
 *
 * @year should be from 1 to 9999, @month should be from 1 to 12.
 *
 * If value is -1 then all over value will be ignored. For example
 * if @month == -1, then #GstDateTime will created only for @year.
 *
 * Free-function: gst_date_time_unref
 *
 * Return value: (transfer full): the newly created #GstDateTime
 *
 * Since:
 */
GstDateTime *
gst_date_time_new_ym (gint year, gint month)
{
  GstDateTime *datetime;
  datetime = gst_date_time_new_local_time (year, month, 1, 1, 1, 1);
  datetime->fields = HAS_YM;
  return datetime;
}

/**
 * gst_date_time_new_ymd:
 * @year: the gregorian year
 * @month: the gregorian month
 * @day: the day of the gregorian month
 *
 * Creates a new #GstDateTime using the date and times in the gregorian calendar
 * in the local timezone.
 *
 * @year should be from 1 to 9999, @month should be from 1 to 12, @day from
 * 1 to 31.
 *
 * If value is -1 then all over value will be ignored. For example
 * if @month == -1, then #GstDateTime will created only for @year. If
 * @day == -1, then #GstDateTime will created for @year and @month and
 * so on.
 *
 * Free-function: gst_date_time_unref
 *
 * Return value: (transfer full): the newly created #GstDateTime
 *
 * Since:
 */
GstDateTime *
gst_date_time_new_ymd (gint year, gint month, gint day)
{
  GstDateTime *datetime;
  datetime = gst_date_time_new_local_time (year, month, day, 1, 1, 1);
  datetime->fields = HAS_YMD;
  return datetime;
}

/**
 * gst_date_time_new_ymd_h:
 * @year: the gregorian year
 * @month: the gregorian month
 * @day: the day of the gregorian month
 * @hour: the hour of the day
 *
 * Creates a new #GstDateTime using the date and times in the gregorian calendar
 * in the local timezone.
 *
 * @year should be from 1 to 9999, @month should be from 1 to 12, @day from
 * 1 to 31, @hour from 0 to 23.
 *
 * If value is -1 then all over value will be ignored. For example
 * if @month == -1, then #GstDateTime will created only for @year. If
 * @day == -1, then #GstDateTime will created for @year and @month and
 * so on.
 *
 * Free-function: gst_date_time_unref
 *
 * Return value: (transfer full): the newly created #GstDateTime
 *
 * Since:
 */
GstDateTime *
gst_date_time_new_ymd_h (gint year, gint month, gint day, gint hour)
{
  GstDateTime *datetime;
  datetime = gst_date_time_new_local_time (year, month, day, hour, 1, 1);
  datetime->fields = HAS_YMD_H;
  return datetime;
}

/**
 * gst_date_time_new_ymd_hm:
 * @year: the gregorian year
 * @month: the gregorian month
 * @day: the day of the gregorian month
 * @hour: the hour of the day
 * @minute: the minute of the hour
 *
 * Creates a new #GstDateTime using the date and times in the gregorian calendar
 * in the local timezone.
 *
 * @year should be from 1 to 9999, @month should be from 1 to 12, @day from
 * 1 to 31, @hour from 0 to 23, @minutes from 0 to 59.
 *
 * If value is -1 then all over value will be ignored. For example
 * if @month == -1, then #GstDateTime will created only for @year. If
 * @day == -1, then #GstDateTime will created for @year and @month and
 * so on.
 *
 * Free-function: gst_date_time_unref
 *
 * Return value: (transfer full): the newly created #GstDateTime
 *
 * Since:
 */
GstDateTime *
gst_date_time_new_ymd_hm (gint year, gint month, gint day, gint hour,
    gint minute)
{
  GstDateTime *datetime;
  datetime = gst_date_time_new_local_time (year, month, day, hour, minute, 1);
  datetime->fields = HAS_YMD_HM;
  return datetime;
}

/**
 * gst_date_time_new_from_unix_epoch_local_time:
 * @secs: seconds from the Unix epoch
 *
 * Creates a new #GstDateTime using the time since Jan 1, 1970 specified by
 * @secs. The #GstDateTime is in the local timezone.
 *
 * Free-function: gst_date_time_unref
 *
 * Return value: (transfer full): the newly created #GstDateTime
 *
 * Since: 0.10.31
 */
GstDateTime *
gst_date_time_new_from_unix_epoch_local_time (gint64 secs)
{
  GstDateTime *datetime;
  datetime =
      gst_date_time_new_from_gdatetime (g_date_time_new_from_unix_local (secs));
  datetime->fields = HAS_YMD_HMS;
  return datetime;
}

/**
 * gst_date_time_new_from_unix_epoch_utc:
 * @secs: seconds from the Unix epoch
 *
 * Creates a new #GstDateTime using the time since Jan 1, 1970 specified by
 * @secs. The #GstDateTime is in the UTC timezone.
 *
 * Free-function: gst_date_time_unref
 *
 * Return value: (transfer full): the newly created #GstDateTime
 *
 * Since: 0.10.31
 */
GstDateTime *
gst_date_time_new_from_unix_epoch_utc (gint64 secs)
{
  GstDateTime *datetime;
  datetime =
      gst_date_time_new_from_gdatetime (g_date_time_new_from_unix_utc (secs));
  datetime->fields = HAS_YMD_HMS;
  return datetime;
}

static DateTimeFields
gst_date_time_check_fields (gint * year, gint * month, gint * day,
    gint * hour, gint * minute, gdouble * seconds)
{
  if (*month == -1) {
    *month = *day = *hour = *minute = *seconds = 1;
    return HAS_Y;
  } else if (*day == -1) {
    *day = *hour = *minute = *seconds = 1;
    return HAS_YM;
  } else if (*hour == -1) {
    *hour = *minute = *seconds = 1;
    return HAS_YMD;
  } else if (*minute == -1) {
    *minute = *seconds = 1;
    return HAS_YMD_H;
  } else if (*seconds == -1) {
    *seconds = 1;
    return HAS_YMD_HM;
  } else
    return HAS_YMD_HMS;
}

/**
 * gst_date_time_new_local_time:
 * @year: the gregorian year
 * @month: the gregorian month
 * @day: the day of the gregorian month
 * @hour: the hour of the day
 * @minute: the minute of the hour
 * @seconds: the second of the minute
 *
 * Creates a new #GstDateTime using the date and times in the gregorian calendar
 * in the local timezone.
 *
 * @year should be from 1 to 9999, @month should be from 1 to 12, @day from
 * 1 to 31, @hour from 0 to 23, @minutes and @seconds from 0 to 59.
 *
 * If value is -1 then all over value will be ignored. For example
 * if @month == -1, then #GstDateTime will created only for @year. If
 * @day == -1, then #GstDateTime will created for @year and @month and
 * so on.
 *
 * Free-function: gst_date_time_unref
 *
 * Return value: (transfer full): the newly created #GstDateTime
 *
 * Since: 0.10.31
 */
GstDateTime *
gst_date_time_new_local_time (gint year, gint month, gint day, gint hour,
    gint minute, gdouble seconds)
{
  GstDateTime *datetime;
  DateTimeFields fields;

  g_return_val_if_fail (year > 0 && year <= 9999, NULL);
  g_return_val_if_fail ((month > 0 && month <= 12) || month == -1, NULL);
  g_return_val_if_fail ((day > 0 && day <= 31) || day == -1, NULL);
  g_return_val_if_fail ((hour >= 0 && hour < 24) || hour == -1, NULL);
  g_return_val_if_fail ((minute >= 0 && minute < 60) || minute == -1, NULL);
  g_return_val_if_fail ((seconds >= 0 && seconds < 60) || seconds == -1, NULL);

  fields = gst_date_time_check_fields (&year, &month, &day,
      &hour, &minute, &seconds);

  datetime = gst_date_time_new_from_gdatetime (g_date_time_new_local (year,
          month, day, hour, minute, seconds));

  datetime->fields = fields;
  return datetime;
}

/**
 * gst_date_time_new_now_local_time:
 *
 * Creates a new #GstDateTime representing the current date and time.
 *
 * Free-function: gst_date_time_unref
 *
 * Return value: (transfer full): the newly created #GstDateTime which should
 *     be freed with gst_date_time_unref().
 *
 * Since: 0.10.31
 */
GstDateTime *
gst_date_time_new_now_local_time (void)
{
  GstDateTime *datetime;

  datetime = gst_date_time_new_from_gdatetime (g_date_time_new_now_local ());
  datetime->fields = HAS_YMD_HMS;
  return datetime;
}

/**
 * gst_date_time_new_now_utc:
 *
 * Creates a new #GstDateTime that represents the current instant at Universal
 * coordinated time.
 *
 * Free-function: gst_date_time_unref
 *
 * Return value: (transfer full): the newly created #GstDateTime which should
 *   be freed with gst_date_time_unref().
 *
 * Since: 0.10.31
 */
GstDateTime *
gst_date_time_new_now_utc (void)
{
  GstDateTime *datetime;

  datetime = gst_date_time_new_from_gdatetime (g_date_time_new_now_utc ());
  datetime->fields = HAS_YMD_HMS;
  return datetime;
}

gint
priv_gst_date_time_compare (gconstpointer dt1, gconstpointer dt2)
{
  const GstDateTime *datetime1 = dt1;
  const GstDateTime *datetime2 = dt2;
  return g_date_time_compare (datetime1->datetime, datetime2->datetime);
}

/**
 * gst_date_time_new:
 * @tzoffset: Offset from UTC in hours.
 * @year: the gregorian year
 * @month: the gregorian month
 * @day: the day of the gregorian month
 * @hour: the hour of the day
 * @minute: the minute of the hour
 * @seconds: the second of the minute
 *
 * Creates a new #GstDateTime using the date and times in the gregorian calendar
 * in the supplied timezone.
 *
 * @year should be from 1 to 9999, @month should be from 1 to 12, @day from
 * 1 to 31, @hour from 0 to 23, @minutes and @seconds from 0 to 59.
 *
 * Note that @tzoffset is a float and was chosen so for being able to handle
 * some fractional timezones, while it still keeps the readability of
 * represeting it in hours for most timezones.
 *
 * If value is -1 then all over value will be ignored. For example
 * if @month == -1, then #GstDateTime will created only for @year. If
 * @day == -1, then #GstDateTime will created for @year and @month and
 * so on.
 *
 * Free-function: gst_date_time_unref
 *
 * Return value: (transfer full): the newly created #GstDateTime
 *
 * Since: 0.10.31
 */
GstDateTime *
gst_date_time_new (gfloat tzoffset, gint year, gint month, gint day, gint hour,
    gint minute, gdouble seconds)
{
  gchar buf[6];
  GTimeZone *tz;
  GDateTime *dt;
  GstDateTime *datetime;
  gint tzhour, tzminute;
  DateTimeFields fields;

  g_return_val_if_fail (year > 0 && year <= 9999, NULL);
  g_return_val_if_fail ((month > 0 && month <= 12) || month == -1, NULL);
  g_return_val_if_fail ((day > 0 && day <= 31) || day == -1, NULL);
  g_return_val_if_fail ((hour >= 0 && hour < 24) || hour == -1, NULL);
  g_return_val_if_fail ((minute >= 0 && minute < 60) || minute == -1, NULL);
  g_return_val_if_fail ((seconds >= 0 && seconds < 60) || seconds == -1, NULL);
  g_return_val_if_fail (tzoffset >= -12.0 && tzoffset <= 12.0, NULL);

  tzhour = (gint) ABS (tzoffset);
  tzminute = (gint) ((ABS (tzoffset) - tzhour) * 60);

  g_snprintf (buf, 6, "%c%02d%02d", tzoffset >= 0 ? '+' : '-', tzhour,
      tzminute);

  tz = g_time_zone_new (buf);

  fields = gst_date_time_check_fields (&year, &month, &day,
      &hour, &minute, &seconds);

  dt = g_date_time_new (tz, year, month, day, hour, minute, seconds);
  g_time_zone_unref (tz);

  datetime = gst_date_time_new_from_gdatetime (dt);
  datetime->fields = fields;

  return datetime;
}

static void
gst_date_time_free (GstDateTime * datetime)
{
  g_date_time_unref (datetime->datetime);
  g_slice_free (GstDateTime, datetime);
}

/**
 * gst_date_time_ref:
 * @datetime: a #GstDateTime
 *
 * Atomically increments the reference count of @datetime by one.
 *
 * Return value: (transfer full): the reference @datetime
 *
 * Since: 0.10.31
 */
GstDateTime *
gst_date_time_ref (GstDateTime * datetime)
{
  g_return_val_if_fail (datetime != NULL, NULL);
  g_return_val_if_fail (datetime->ref_count > 0, NULL);
  g_atomic_int_inc (&datetime->ref_count);
  return datetime;
}

/**
 * gst_date_time_unref:
 * @datetime: (transfer full): a #GstDateTime
 *
 * Atomically decrements the reference count of @datetime by one.  When the
 * reference count reaches zero, the structure is freed.
 *
 * Since: 0.10.31
 */
void
gst_date_time_unref (GstDateTime * datetime)
{
  g_return_if_fail (datetime != NULL);
  g_return_if_fail (datetime->ref_count > 0);

  if (g_atomic_int_dec_and_test (&datetime->ref_count))
    gst_date_time_free (datetime);
}