gst/gstdatetime.c

   1 /* GStreamer
   2  * Copyright (C) 2010 Thiago Santos <thiago.sousa.santos@collabora.co.uk>
   3  *
   4  * This library is free software; you can redistribute it and/or
   5  * modify it under the terms of the GNU Library General Public
   6  * License as published by the Free Software Foundation; either
   7  * version 2 of the License, or (at your option) any later version.
   8  *
   9  * This library is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12  * Library General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU Library General Public
  15  * License along with this library; if not, write to the
  16  * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
  17  * Boston, MA 02110-1301, USA.
  18  */
  19
  20 #ifdef HAVE_CONFIG_H
  21 #include "config.h"
  22 #endif
  23
  24 #include "gst_private.h"
  25 #include "glib-compat-private.h"
  26 #include "gstdatetime.h"
  27 #include "gstvalue.h"
  28 #include <glib.h>
  29 #include <math.h>
  30 #include <stdio.h>
  31
  32 /**
  33  * SECTION:gstdatetime
  34  * @title: GstDateTime
  35  * @short_description: A date, time and timezone structure
  36  *
  37  * Struct to store date, time and timezone information altogether.
  38  * #GstDateTime is refcounted and immutable.
  39  *
  40  * Date information is handled using the proleptic Gregorian calendar.
  41  *
  42  * Provides basic creation functions and accessor functions to its fields.
  43  */
  44
  45 typedef enum
  46 {
  47   GST_DATE_TIME_FIELDS_INVALID = 0,
  48   GST_DATE_TIME_FIELDS_Y,       /* have year                */
  49   GST_DATE_TIME_FIELDS_YM,      /* have year and month      */
  50   GST_DATE_TIME_FIELDS_YMD,     /* have year, month and day */
  51   GST_DATE_TIME_FIELDS_YMD_HM,
  52   GST_DATE_TIME_FIELDS_YMD_HMS
  53       /* Note: if we ever add more granularity here, e.g. for microsecs,
  54        * the compare function will need updating */
  55 } GstDateTimeFields;
  56
  57 struct _GstDateTime
  58 {
  59   GDateTime *datetime;
  60
  61   GstDateTimeFields fields;
  62   volatile gint ref_count;
  63 };
  64
  65 /**
  66  * gst_date_time_new_from_g_date_time:
  67  * @dt: (transfer full): the #GDateTime. The new #GstDateTime takes ownership.
  68  *
  69  * Creates a new #GstDateTime from a #GDateTime object.
  70  *
  71  * Free-function: gst_date_time_unref
  72  *
  73  * Returns: (transfer full): a newly created #GstDateTime, or %NULL on error
  74  */
  75 GstDateTime *
  76 gst_date_time_new_from_g_date_time (GDateTime * dt)
  77 {
  78   GstDateTime *gst_dt;
  79
  80   if (!dt)
  81     return NULL;
  82
  83   gst_dt = g_slice_new (GstDateTime);
  84   gst_dt->datetime = dt;
  85   gst_dt->fields = GST_DATE_TIME_FIELDS_YMD_HMS;
  86   gst_dt->ref_count = 1;
  87   return gst_dt;
  88 }
  89
  90 /**
  91  * gst_date_time_to_g_date_time:
  92  * @datetime: GstDateTime.
  93  *
  94  * Creates a new #GDateTime from a fully defined #GstDateTime object.
  95  *
  96  * Free-function: g_date_time_unref
  97  *
  98  * Returns: (transfer full): a newly created #GDateTime, or %NULL on error
  99  */
 100 GDateTime *
 101 gst_date_time_to_g_date_time (GstDateTime * datetime)
 102 {
 103   g_return_val_if_fail (datetime != NULL, NULL);
 104
 105   if (datetime->fields != GST_DATE_TIME_FIELDS_YMD_HMS)
 106     return NULL;
 107
 108   return g_date_time_add (datetime->datetime, 0);
 109 }
 110
 111 /**
 112  * gst_date_time_has_year:
 113  * @datetime: a #GstDateTime
 114  *
 115  * Returns: %TRUE if @datetime<!-- -->'s year field is set (which should always
 116  *     be the case), otherwise %FALSE
 117  */
 118 gboolean
 119 gst_date_time_has_year (const GstDateTime * datetime)
 120 {
 121   g_return_val_if_fail (datetime != NULL, FALSE);
 122
 123   return (datetime->fields >= GST_DATE_TIME_FIELDS_Y);
 124 }
 125
 126 /**
 127  * gst_date_time_has_month:
 128  * @datetime: a #GstDateTime
 129  *
 130  * Returns: %TRUE if @datetime<!-- -->'s month field is set, otherwise %FALSE
 131  */
 132 gboolean
 133 gst_date_time_has_month (const GstDateTime * datetime)
 134 {
 135   g_return_val_if_fail (datetime != NULL, FALSE);
 136
 137   return (datetime->fields >= GST_DATE_TIME_FIELDS_YM);
 138 }
 139
 140 /**
 141  * gst_date_time_has_day:
 142  * @datetime: a #GstDateTime
 143  *
 144  * Returns: %TRUE if @datetime<!-- -->'s day field is set, otherwise %FALSE
 145  */
 146 gboolean
 147 gst_date_time_has_day (const GstDateTime * datetime)
 148 {
 149   g_return_val_if_fail (datetime != NULL, FALSE);
 150
 151   return (datetime->fields >= GST_DATE_TIME_FIELDS_YMD);
 152 }
 153
 154 /**
 155  * gst_date_time_has_time:
 156  * @datetime: a #GstDateTime
 157  *
 158  * Returns: %TRUE if @datetime<!-- -->'s hour and minute fields are set,
 159  *     otherwise %FALSE
 160  */
 161 gboolean
 162 gst_date_time_has_time (const GstDateTime * datetime)
 163 {
 164   g_return_val_if_fail (datetime != NULL, FALSE);
 165
 166   return (datetime->fields >= GST_DATE_TIME_FIELDS_YMD_HM);
 167 }
 168
 169 /**
 170  * gst_date_time_has_second:
 171  * @datetime: a #GstDateTime
 172  *
 173  * Returns: %TRUE if @datetime<!-- -->'s second field is set, otherwise %FALSE
 174  */
 175 gboolean
 176 gst_date_time_has_second (const GstDateTime * datetime)
 177 {
 178   g_return_val_if_fail (datetime != NULL, FALSE);
 179
 180   return (datetime->fields >= GST_DATE_TIME_FIELDS_YMD_HMS);
 181 }
 182
 183 /**
 184  * gst_date_time_get_year:
 185  * @datetime: a #GstDateTime
 186  *
 187  * Returns the year of this #GstDateTime
 188  * Call gst_date_time_has_year before, to avoid warnings.
 189  *
 190  * Return value: The year of this #GstDateTime
 191  */
 192 gint
 193 gst_date_time_get_year (const GstDateTime * datetime)
 194 {
 195   g_return_val_if_fail (datetime != NULL, 0);
 196
 197   return g_date_time_get_year (datetime->datetime);
 198 }
 199
 200 /**
 201  * gst_date_time_get_month:
 202  * @datetime: a #GstDateTime
 203  *
 204  * Returns the month of this #GstDateTime. January is 1, February is 2, etc..
 205  * Call gst_date_time_has_month before, to avoid warnings.
 206  *
 207  * Return value: The month of this #GstDateTime
 208  */
 209 gint
 210 gst_date_time_get_month (const GstDateTime * datetime)
 211 {
 212   g_return_val_if_fail (datetime != NULL, 0);
 213   g_return_val_if_fail (gst_date_time_has_month (datetime), 0);
 214
 215   return g_date_time_get_month (datetime->datetime);
 216 }
 217
 218 /**
 219  * gst_date_time_get_day:
 220  * @datetime: a #GstDateTime
 221  *
 222  * Returns the day of the month of this #GstDateTime.
 223  * Call gst_date_time_has_day before, to avoid warnings.
 224  *
 225  * Return value: The day of this #GstDateTime
 226  */
 227 gint
 228 gst_date_time_get_day (const GstDateTime * datetime)
 229 {
 230   g_return_val_if_fail (datetime != NULL, 0);
 231   g_return_val_if_fail (gst_date_time_has_day (datetime), 0);
 232
 233   return g_date_time_get_day_of_month (datetime->datetime);
 234 }
 235
 236 /**
 237  * gst_date_time_get_hour:
 238  * @datetime: a #GstDateTime
 239  *
 240  * Retrieves the hour of the day represented by @datetime in the gregorian
 241  * calendar. The return is in the range of 0 to 23.
 242  * Call gst_date_time_has_haur before, to avoid warnings.
 243  *
 244  * Return value: the hour of the day
 245  */
 246 gint
 247 gst_date_time_get_hour (const GstDateTime * datetime)
 248 {
 249   g_return_val_if_fail (datetime != NULL, 0);
 250   g_return_val_if_fail (gst_date_time_has_time (datetime), 0);
 251
 252   return g_date_time_get_hour (datetime->datetime);
 253 }
 254
 255 /**
 256  * gst_date_time_get_minute:
 257  * @datetime: a #GstDateTime
 258  *
 259  * Retrieves the minute of the hour represented by @datetime in the gregorian
 260  * calendar.
 261  * Call gst_date_time_has_minute before, to avoid warnings.
 262  *
 263  * Return value: the minute of the hour
 264  */
 265 gint
 266 gst_date_time_get_minute (const GstDateTime * datetime)
 267 {
 268   g_return_val_if_fail (datetime != NULL, 0);
 269   g_return_val_if_fail (gst_date_time_has_time (datetime), 0);
 270
 271   return g_date_time_get_minute (datetime->datetime);
 272 }
 273
 274 /**
 275  * gst_date_time_get_second:
 276  * @datetime: a #GstDateTime
 277  *
 278  * Retrieves the second of the minute represented by @datetime in the gregorian
 279  * calendar.
 280  * Call gst_date_time_has_second before, to avoid warnings.
 281  *
 282  * Return value: the second represented by @datetime
 283  */
 284 gint
 285 gst_date_time_get_second (const GstDateTime * datetime)
 286 {
 287   g_return_val_if_fail (datetime != NULL, 0);
 288   g_return_val_if_fail (gst_date_time_has_second (datetime), 0);
 289
 290   return g_date_time_get_second (datetime->datetime);
 291 }
 292
 293 /**
 294  * gst_date_time_get_microsecond:
 295  * @datetime: a #GstDateTime
 296  *
 297  * Retrieves the fractional part of the seconds in microseconds represented by
 298  * @datetime in the gregorian calendar.
 299  *
 300  * Return value: the microsecond of the second
 301  */
 302 gint
 303 gst_date_time_get_microsecond (const GstDateTime * datetime)
 304 {
 305   g_return_val_if_fail (datetime != NULL, 0);
 306   g_return_val_if_fail (gst_date_time_has_second (datetime), 0);
 307
 308   return g_date_time_get_microsecond (datetime->datetime);
 309 }
 310
 311 /**
 312  * gst_date_time_get_time_zone_offset:
 313  * @datetime: a #GstDateTime
 314  *
 315  * Retrieves the offset from UTC in hours that the timezone specified
 316  * by @datetime represents. Timezones ahead (to the east) of UTC have positive
 317  * values, timezones before (to the west) of UTC have negative values.
 318  * If @datetime represents UTC time, then the offset is zero.
 319  *
 320  * Return value: the offset from UTC in hours
 321  */
 322 gfloat
 323 gst_date_time_get_time_zone_offset (const GstDateTime * datetime)
 324 {
 325   g_return_val_if_fail (datetime != NULL, 0.0);
 326   g_return_val_if_fail (gst_date_time_has_time (datetime), 0.0);
 327
 328   return (g_date_time_get_utc_offset (datetime->datetime) /
 329       G_USEC_PER_SEC) / 3600.0;
 330 }
 331
 332 /**
 333  * gst_date_time_new_y:
 334  * @year: the gregorian year
 335  *
 336  * Creates a new #GstDateTime using the date and times in the gregorian calendar
 337  * in the local timezone.
 338  *
 339  * @year should be from 1 to 9999.
 340  *
 341  * Free-function: gst_date_time_unref
 342  *
 343  * Return value: (transfer full): the newly created #GstDateTime
 344  */
 345 GstDateTime *
 346 gst_date_time_new_y (gint year)
 347 {
 348   return gst_date_time_new (0.0, year, -1, -1, -1, -1, -1);
 349 }
 350
 351 /**
 352  * gst_date_time_new_ym:
 353  * @year: the gregorian year
 354  * @month: the gregorian month
 355  *
 356  * Creates a new #GstDateTime using the date and times in the gregorian calendar
 357  * in the local timezone.
 358  *
 359  * @year should be from 1 to 9999, @month should be from 1 to 12.
 360  *
 361  * If value is -1 then all over value will be ignored. For example
 362  * if @month == -1, then #GstDateTime will created only for @year.
 363  *
 364  * Free-function: gst_date_time_unref
 365  *
 366  * Return value: (transfer full): the newly created #GstDateTime
 367  */
 368 GstDateTime *
 369 gst_date_time_new_ym (gint year, gint month)
 370 {
 371   return gst_date_time_new (0.0, year, month, -1, -1, -1, -1);
 372 }
 373
 374 /**
 375  * gst_date_time_new_ymd:
 376  * @year: the gregorian year
 377  * @month: the gregorian month
 378  * @day: the day of the gregorian month
 379  *
 380  * Creates a new #GstDateTime using the date and times in the gregorian calendar
 381  * in the local timezone.
 382  *
 383  * @year should be from 1 to 9999, @month should be from 1 to 12, @day from
 384  * 1 to 31.
 385  *
 386  * If value is -1 then all over value will be ignored. For example
 387  * if @month == -1, then #GstDateTime will created only for @year. If
 388  * @day == -1, then #GstDateTime will created for @year and @month and
 389  * so on.
 390  *
 391  * Free-function: gst_date_time_unref
 392  *
 393  * Return value: (transfer full): the newly created #GstDateTime
 394  */
 395 GstDateTime *
 396 gst_date_time_new_ymd (gint year, gint month, gint day)
 397 {
 398   return gst_date_time_new (0.0, year, month, day, -1, -1, -1);
 399 }
 400
 401 /**
 402  * gst_date_time_new_from_unix_epoch_local_time:
 403  * @secs: seconds from the Unix epoch
 404  *
 405  * Creates a new #GstDateTime using the time since Jan 1, 1970 specified by
 406  * @secs. The #GstDateTime is in the local timezone.
 407  *
 408  * Free-function: gst_date_time_unref
 409  *
 410  * Return value: (transfer full): the newly created #GstDateTime
 411  */
 412 GstDateTime *
 413 gst_date_time_new_from_unix_epoch_local_time (gint64 secs)
 414 {
 415   GDateTime *datetime;
 416
 417   datetime = g_date_time_new_from_unix_local (secs);
 418   return gst_date_time_new_from_g_date_time (datetime);
 419 }
 420
 421 /**
 422  * gst_date_time_new_from_unix_epoch_utc:
 423  * @secs: seconds from the Unix epoch
 424  *
 425  * Creates a new #GstDateTime using the time since Jan 1, 1970 specified by
 426  * @secs. The #GstDateTime is in the UTC timezone.
 427  *
 428  * Free-function: gst_date_time_unref
 429  *
 430  * Return value: (transfer full): the newly created #GstDateTime
 431  */
 432 GstDateTime *
 433 gst_date_time_new_from_unix_epoch_utc (gint64 secs)
 434 {
 435   GstDateTime *datetime;
 436   datetime =
 437       gst_date_time_new_from_g_date_time (g_date_time_new_from_unix_utc (secs));
 438   return datetime;
 439 }
 440
 441 static GstDateTimeFields
 442 gst_date_time_check_fields (gint * year, gint * month, gint * day,
 443     gint * hour, gint * minute, gdouble * seconds)
 444 {
 445   if (*month == -1) {
 446     *month = *day = 1;
 447     *hour = *minute = *seconds = 0;
 448     return GST_DATE_TIME_FIELDS_Y;
 449   } else if (*day == -1) {
 450     *day = 1;
 451     *hour = *minute = *seconds = 0;
 452     return GST_DATE_TIME_FIELDS_YM;
 453   } else if (*hour == -1) {
 454     *hour = *minute = *seconds = 0;
 455     return GST_DATE_TIME_FIELDS_YMD;
 456   } else if (*seconds == -1) {
 457     *seconds = 0;
 458     return GST_DATE_TIME_FIELDS_YMD_HM;
 459   } else
 460     return GST_DATE_TIME_FIELDS_YMD_HMS;
 461 }
 462
 463 /**
 464  * gst_date_time_new_local_time:
 465  * @year: the gregorian year
 466  * @month: the gregorian month, or -1
 467  * @day: the day of the gregorian month, or -1
 468  * @hour: the hour of the day, or -1
 469  * @minute: the minute of the hour, or -1
 470  * @seconds: the second of the minute, or -1
 471  *
 472  * Creates a new #GstDateTime using the date and times in the gregorian calendar
 473  * in the local timezone.
 474  *
 475  * @year should be from 1 to 9999, @month should be from 1 to 12, @day from
 476  * 1 to 31, @hour from 0 to 23, @minutes and @seconds from 0 to 59.
 477  *
 478  * If @month is -1, then the #GstDateTime created will only contain @year,
 479  * and all other fields will be considered not set.
 480  *
 481  * If @day is -1, then the #GstDateTime created will only contain @year and
 482  * @month and all other fields will be considered not set.
 483  *
 484  * If @hour is -1, then the #GstDateTime created will only contain @year and
 485  * @month and @day, and the time fields will be considered not set. In this
 486  * case @minute and @seconds should also be -1.
 487  *
 488  * Free-function: gst_date_time_unref
 489  *
 490  * Return value: (transfer full): the newly created #GstDateTime
 491  */
 492 GstDateTime *
 493 gst_date_time_new_local_time (gint year, gint month, gint day, gint hour,
 494     gint minute, gdouble seconds)
 495 {
 496   GstDateTimeFields fields;
 497   GstDateTime *datetime;
 498
 499   g_return_val_if_fail (year > 0 && year <= 9999, NULL);
 500   g_return_val_if_fail ((month > 0 && month <= 12) || month == -1, NULL);
 501   g_return_val_if_fail ((day > 0 && day <= 31) || day == -1, NULL);
 502   g_return_val_if_fail ((hour >= 0 && hour < 24) || hour == -1, NULL);
 503   g_return_val_if_fail ((minute >= 0 && minute < 60) || minute == -1, NULL);
 504   g_return_val_if_fail ((seconds >= 0 && seconds < 60) || seconds == -1, NULL);
 505
 506   fields = gst_date_time_check_fields (&year, &month, &day,
 507       &hour, &minute, &seconds);
 508
 509   datetime = gst_date_time_new_from_g_date_time (g_date_time_new_local (year,
 510           month, day, hour, minute, seconds));
 511
 512   datetime->fields = fields;
 513   return datetime;
 514 }
 515
 516 /**
 517  * gst_date_time_new_now_local_time:
 518  *
 519  * Creates a new #GstDateTime representing the current date and time.
 520  *
 521  * Free-function: gst_date_time_unref
 522  *
 523  * Return value: (transfer full): the newly created #GstDateTime which should
 524  *     be freed with gst_date_time_unref().
 525  */
 526 GstDateTime *
 527 gst_date_time_new_now_local_time (void)
 528 {
 529   return gst_date_time_new_from_g_date_time (g_date_time_new_now_local ());
 530 }
 531
 532 /**
 533  * gst_date_time_new_now_utc:
 534  *
 535  * Creates a new #GstDateTime that represents the current instant at Universal
 536  * coordinated time.
 537  *
 538  * Free-function: gst_date_time_unref
 539  *
 540  * Return value: (transfer full): the newly created #GstDateTime which should
 541  *   be freed with gst_date_time_unref().
 542  */
 543 GstDateTime *
 544 gst_date_time_new_now_utc (void)
 545 {
 546   return gst_date_time_new_from_g_date_time (g_date_time_new_now_utc ());
 547 }
 548
 549 gint
 550 __gst_date_time_compare (const GstDateTime * dt1, const GstDateTime * dt2)
 551 {
 552   gint64 diff;
 553
 554   /* we assume here that GST_DATE_TIME_FIELDS_YMD_HMS is the highest
 555    * resolution, and ignore microsecond differences on purpose for now */
 556   if (dt1->fields != dt2->fields)
 557     return GST_VALUE_UNORDERED;
 558
 559   /* This will round down to nearest second, which is what we want. We're
 560    * not comparing microseconds on purpose here, since we're not
 561    * serialising them when doing new_utc_now() + to_string() */
 562   diff =
 563       g_date_time_to_unix (dt1->datetime) - g_date_time_to_unix (dt2->datetime);
 564   if (diff < 0)
 565     return GST_VALUE_LESS_THAN;
 566   else if (diff > 0)
 567     return GST_VALUE_GREATER_THAN;
 568   else
 569     return GST_VALUE_EQUAL;
 570 }
 571
 572 /**
 573  * gst_date_time_new:
 574  * @tzoffset: Offset from UTC in hours.
 575  * @year: the gregorian year
 576  * @month: the gregorian month
 577  * @day: the day of the gregorian month
 578  * @hour: the hour of the day
 579  * @minute: the minute of the hour
 580  * @seconds: the second of the minute
 581  *
 582  * Creates a new #GstDateTime using the date and times in the gregorian calendar
 583  * in the supplied timezone.
 584  *
 585  * @year should be from 1 to 9999, @month should be from 1 to 12, @day from
 586  * 1 to 31, @hour from 0 to 23, @minutes and @seconds from 0 to 59.
 587  *
 588  * Note that @tzoffset is a float and was chosen so for being able to handle
 589  * some fractional timezones, while it still keeps the readability of
 590  * representing it in hours for most timezones.
 591  *
 592  * If value is -1 then all over value will be ignored. For example
 593  * if @month == -1, then #GstDateTime will created only for @year. If
 594  * @day == -1, then #GstDateTime will created for @year and @month and
 595  * so on.
 596  *
 597  * Free-function: gst_date_time_unref
 598  *
 599  * Return value: (transfer full): the newly created #GstDateTime
 600  */
 601 GstDateTime *
 602 gst_date_time_new (gfloat tzoffset, gint year, gint month, gint day, gint hour,
 603     gint minute, gdouble seconds)
 604 {
 605   GstDateTimeFields fields;
 606   gchar buf[6];
 607   GTimeZone *tz;
 608   GDateTime *dt;
 609   GstDateTime *datetime;
 610   gint tzhour, tzminute;
 611
 612   g_return_val_if_fail (year > 0 && year <= 9999, NULL);
 613   g_return_val_if_fail ((month > 0 && month <= 12) || month == -1, NULL);
 614   g_return_val_if_fail ((day > 0 && day <= 31) || day == -1, NULL);
 615   g_return_val_if_fail ((hour >= 0 && hour < 24) || hour == -1, NULL);
 616   g_return_val_if_fail ((minute >= 0 && minute < 60) || minute == -1, NULL);
 617   g_return_val_if_fail ((seconds >= 0 && seconds < 60) || seconds == -1, NULL);
 618   g_return_val_if_fail (tzoffset >= -12.0 && tzoffset <= 12.0, NULL);
 619   g_return_val_if_fail ((hour >= 0 && minute >= 0) ||
 620       (hour == -1 && minute == -1 && seconds == -1 && tzoffset == 0.0), NULL);
 621
 622   tzhour = (gint) ABS (tzoffset);
 623   tzminute = (gint) ((ABS (tzoffset) - tzhour) * 60);
 624
 625   g_snprintf (buf, 6, "%c%02d%02d", tzoffset >= 0 ? '+' : '-', tzhour,
 626       tzminute);
 627
 628   tz = g_time_zone_new (buf);
 629
 630   fields = gst_date_time_check_fields (&year, &month, &day,
 631       &hour, &minute, &seconds);
 632
 633   dt = g_date_time_new (tz, year, month, day, hour, minute, seconds);
 634   g_time_zone_unref (tz);
 635
 636   datetime = gst_date_time_new_from_g_date_time (dt);
 637   datetime->fields = fields;
 638
 639   return datetime;
 640 }
 641
 642 gchar *
 643 __gst_date_time_serialize (GstDateTime * datetime, gboolean serialize_usecs)
 644 {
 645   GString *s;
 646   gfloat gmt_offset;
 647   guint msecs;
 648
 649   /* we always have at least the year */
 650   s = g_string_new (NULL);
 651   g_string_append_printf (s, "%04u", gst_date_time_get_year (datetime));
 652
 653   if (datetime->fields == GST_DATE_TIME_FIELDS_Y)
 654     goto done;
 655
 656   /* add month */
 657   g_string_append_printf (s, "-%02u", gst_date_time_get_month (datetime));
 658
 659   if (datetime->fields == GST_DATE_TIME_FIELDS_YM)
 660     goto done;
 661
 662   /* add day of month */
 663   g_string_append_printf (s, "-%02u", gst_date_time_get_day (datetime));
 664
 665   if (datetime->fields == GST_DATE_TIME_FIELDS_YMD)
 666     goto done;
 667
 668   /* add time */
 669   g_string_append_printf (s, "T%02u:%02u", gst_date_time_get_hour (datetime),
 670       gst_date_time_get_minute (datetime));
 671
 672   if (datetime->fields == GST_DATE_TIME_FIELDS_YMD_HM)
 673     goto add_timezone;
 674
 675   /* add seconds */
 676   g_string_append_printf (s, ":%02u", gst_date_time_get_second (datetime));
 677
 678   /* add microseconds */
 679   if (serialize_usecs) {
 680     msecs = gst_date_time_get_microsecond (datetime);
 681     if (msecs != 0) {
 682       g_string_append_printf (s, ".%06u", msecs);
 683       /* trim trailing 0s */
 684       while (s->str[s->len - 1] == '0')
 685         g_string_truncate (s, s->len - 1);
 686     }
 687   }
 688
 689   /* add timezone */
 690
 691 add_timezone:
 692
 693   gmt_offset = gst_date_time_get_time_zone_offset (datetime);
 694   if (gmt_offset == 0) {
 695     g_string_append_c (s, 'Z');
 696   } else {
 697     guint tzhour, tzminute;
 698
 699     tzhour = (guint) ABS (gmt_offset);
 700     tzminute = (guint) ((ABS (gmt_offset) - tzhour) * 60);
 701
 702     g_string_append_c (s, (gmt_offset >= 0) ? '+' : '-');
 703     g_string_append_printf (s, "%02u%02u", tzhour, tzminute);
 704   }
 705
 706 done:
 707
 708   return g_string_free (s, FALSE);
 709 }
 710
 711 /**
 712  * gst_date_time_to_iso8601_string:
 713  * @datetime: GstDateTime.
 714  *
 715  * Create a minimal string compatible with ISO-8601. Possible output formats
 716  * are (for example): 2012, 2012-06, 2012-06-23, 2012-06-23T23:30Z,
 717  * 2012-06-23T23:30+0100, 2012-06-23T23:30:59Z, 2012-06-23T23:30:59+0100
 718  *
 719  * Returns: a newly allocated string formatted according to ISO 8601 and
 720  *     only including the datetime fields that are valid, or %NULL in case
 721  *     there was an error. The string should be freed with g_free().
 722  */
 723 gchar *
 724 gst_date_time_to_iso8601_string (GstDateTime * datetime)
 725 {
 726   g_return_val_if_fail (datetime != NULL, NULL);
 727
 728   if (datetime->fields == GST_DATE_TIME_FIELDS_INVALID)
 729     return NULL;
 730
 731   return __gst_date_time_serialize (datetime, FALSE);
 732 }
 733
 734 /**
 735  * gst_date_time_new_from_iso8601_string:
 736  * @string: ISO 8601-formatted datetime string.
 737  *
 738  * Tries to parse common variants of ISO-8601 datetime strings into a
 739  * #GstDateTime.
 740  *
 741  * Free-function: gst_date_time_unref
 742  *
 743  * Returns: (transfer full): a newly created #GstDateTime, or %NULL on error
 744  */
 745 GstDateTime *
 746 gst_date_time_new_from_iso8601_string (const gchar * string)
 747 {
 748   gint year = -1, month = -1, day = -1, hour = -1, minute = -1;
 749   gdouble second = -1.0;
 750   gfloat tzoffset = 0.0;
 751   guint64 usecs;
 752   gint len, ret;
 753
 754   g_return_val_if_fail (string != NULL, NULL);
 755
 756   GST_DEBUG ("Parsing '%s' into a datetime", string);
 757
 758   len = strlen (string);
 759
 760   if (len < 4 || !g_ascii_isdigit (string[0]) || !g_ascii_isdigit (string[1])
 761       || !g_ascii_isdigit (string[2]) || !g_ascii_isdigit (string[3]))
 762     return NULL;
 763
 764   ret = sscanf (string, "%04d-%02d-%02d", &year, &month, &day);
 765
 766   if (ret == 0)
 767     return NULL;
 768
 769   if (ret == 3 && day <= 0) {
 770     ret = 2;
 771     day = -1;
 772   }
 773
 774   if (ret >= 2 && month <= 0) {
 775     ret = 1;
 776     month = day = -1;
 777   }
 778
 779   if (ret >= 1 && year <= 0)
 780     return NULL;
 781
 782   else if (ret >= 1 && len < 16)
 783     /* YMD is 10 chars. XMD + HM will be 16 chars. if it is less,
 784      * it make no sense to continue. We will stay with YMD. */
 785     goto ymd;
 786
 787   string += 10;
 788   /* Exit if there is no expeceted value on this stage */
 789   if (!(*string == 'T' || *string == '-' || *string == ' '))
 790     goto ymd;
 791
 792   /* if hour or minute fails, then we will use onlly ymd. */
 793   hour = g_ascii_strtoull (string + 1, (gchar **) & string, 10);
 794   if (hour > 24 || *string != ':')
 795     goto ymd;
 796
 797   /* minute */
 798   minute = g_ascii_strtoull (string + 1, (gchar **) & string, 10);
 799   if (minute > 59)
 800     goto ymd;
 801
 802   /* second */
 803   if (*string == ':') {
 804     second = g_ascii_strtoull (string + 1, (gchar **) & string, 10);
 805     /* if we fail here, we still can reuse hour and minute. We
 806      * will still attempt to parse any timezone information */
 807     if (second > 59) {
 808       second = -1.0;
 809     } else {
 810       /* microseconds */
 811       if (*string == '.' || *string == ',') {
 812         const gchar *usec_start = string + 1;
 813         guint digits;
 814
 815         usecs = g_ascii_strtoull (string + 1, (gchar **) & string, 10);
 816         if (usecs != G_MAXUINT64 && string > usec_start) {
 817           digits = (guint) (string - usec_start);
 818           second += (gdouble) usecs / pow (10.0, digits);
 819         }
 820       }
 821     }
 822   }
 823
 824   if (*string == 'Z')
 825     goto ymd_hms;
 826   else {
 827     /* reuse some code from gst-plugins-base/gst-libs/gst/tag/gstxmptag.c */
 828     gint gmt_offset_hour = -1, gmt_offset_min = -1, gmt_offset = -1;
 829     gchar *plus_pos = NULL;
 830     gchar *neg_pos = NULL;
 831     gchar *pos = NULL;
 832
 833     GST_LOG ("Checking for timezone information");
 834
 835     /* check if there is timezone info */
 836     plus_pos = strrchr (string, '+');
 837     neg_pos = strrchr (string, '-');
 838     if (plus_pos)
 839       pos = plus_pos + 1;
 840     else if (neg_pos)
 841       pos = neg_pos + 1;
 842
 843     if (pos) {
 844       gint ret_tz;
 845       if (pos[2] == ':')
 846         ret_tz = sscanf (pos, "%d:%d", &gmt_offset_hour, &gmt_offset_min);
 847       else
 848         ret_tz = sscanf (pos, "%02d%02d", &gmt_offset_hour, &gmt_offset_min);
 849
 850       GST_DEBUG ("Parsing timezone: %s", pos);
 851
 852       if (ret_tz == 2) {
 853         gmt_offset = gmt_offset_hour * 60 + gmt_offset_min;
 854         if (neg_pos != NULL && neg_pos + 1 == pos)
 855           gmt_offset *= -1;
 856
 857         tzoffset = gmt_offset / 60.0;
 858
 859         GST_LOG ("Timezone offset: %f (%d minutes)", tzoffset, gmt_offset);
 860       } else
 861         GST_WARNING ("Failed to parse timezone information");
 862     }
 863   }
 864
 865 ymd_hms:
 866   return gst_date_time_new (tzoffset, year, month, day, hour, minute, second);
 867 ymd:
 868   return gst_date_time_new_ymd (year, month, day);
 869 }
 870
 871
 872 static void
 873 gst_date_time_free (GstDateTime * datetime)
 874 {
 875   g_date_time_unref (datetime->datetime);
 876   g_slice_free (GstDateTime, datetime);
 877 }
 878
 879 /**
 880  * gst_date_time_ref:
 881  * @datetime: a #GstDateTime
 882  *
 883  * Atomically increments the reference count of @datetime by one.
 884  *
 885  * Return value: (transfer full): the reference @datetime
 886  */
 887 GstDateTime *
 888 gst_date_time_ref (GstDateTime * datetime)
 889 {
 890   g_return_val_if_fail (datetime != NULL, NULL);
 891   g_return_val_if_fail (datetime->ref_count > 0, NULL);
 892   g_atomic_int_inc (&datetime->ref_count);
 893   return datetime;
 894 }
 895
 896 /**
 897  * gst_date_time_unref:
 898  * @datetime: (transfer full): a #GstDateTime
 899  *
 900  * Atomically decrements the reference count of @datetime by one.  When the
 901  * reference count reaches zero, the structure is freed.
 902  */
 903 void
 904 gst_date_time_unref (GstDateTime * datetime)
 905 {
 906   g_return_if_fail (datetime != NULL);
 907   g_return_if_fail (datetime->ref_count > 0);
 908
 909   if (g_atomic_int_dec_and_test (&datetime->ref_count))
 910     gst_date_time_free (datetime);
 911 }