2 * Copyright (C) 2010 Thiago Santos <thiago.sousa.santos@collabora.co.uk>
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.
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.
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., 59 Temple Place - Suite 330,
17 * Boston, MA 02111-1307, USA.
24 #include "glib-compat-private.h"
25 #include "gst_private.h"
26 #include "gstdatetime.h"
35 * @short_description: A date, time and timezone structure
37 * Struct to store date, time and timezone information altogether.
38 * #GstDateTime is refcounted and immutable.
40 * Date information is handled using the proleptic Gregorian calendar.
42 * Provides basic creation functions and accessor functions to its fields.
49 GST_DATE_TIME_FIELDS_INVALID = 0,
50 GST_DATE_TIME_FIELDS_Y, /* have year */
51 GST_DATE_TIME_FIELDS_YM, /* have year and month */
52 GST_DATE_TIME_FIELDS_YMD, /* have year, month and day */
53 GST_DATE_TIME_FIELDS_YMD_HM,
54 GST_DATE_TIME_FIELDS_YMD_HMS
55 /* Note: if we ever add more granularity here, e.g. for microsecs,
56 * the compare function will need updating */
63 GstDateTimeFields fields;
64 volatile gint ref_count;
68 gst_date_time_new_from_gdatetime (GDateTime * dt)
75 gst_dt = g_slice_new (GstDateTime);
76 gst_dt->datetime = dt;
77 gst_dt->fields = GST_DATE_TIME_FIELDS_YMD_HMS;
78 gst_dt->ref_count = 1;
83 * gst_date_time_has_year:
84 * @datetime: a #GstDateTime
86 * Returns: TRUE if @datetime<!-- -->'s year field is set (which should always
87 * be the case), otherwise FALSE
90 gst_date_time_has_year (const GstDateTime * datetime)
92 g_return_val_if_fail (datetime != NULL, FALSE);
94 return (datetime->fields >= GST_DATE_TIME_FIELDS_Y);
98 * gst_date_time_has_month:
99 * @datetime: a #GstDateTime
101 * Returns: TRUE if @datetime<!-- -->'s month field is set, otherwise FALSE
104 gst_date_time_has_month (const GstDateTime * datetime)
106 g_return_val_if_fail (datetime != NULL, FALSE);
108 return (datetime->fields >= GST_DATE_TIME_FIELDS_YM);
112 * gst_date_time_has_day:
113 * @datetime: a #GstDateTime
115 * Returns: TRUE if @datetime<!-- -->'s day field is set, otherwise FALSE
118 gst_date_time_has_day (const GstDateTime * datetime)
120 g_return_val_if_fail (datetime != NULL, FALSE);
122 return (datetime->fields >= GST_DATE_TIME_FIELDS_YMD);
126 * gst_date_time_has_time:
127 * @datetime: a #GstDateTime
129 * Returns: TRUE if @datetime<!-- -->'s hour and minute fields are set,
133 gst_date_time_has_time (const GstDateTime * datetime)
135 g_return_val_if_fail (datetime != NULL, FALSE);
137 return (datetime->fields >= GST_DATE_TIME_FIELDS_YMD_HM);
141 * gst_date_time_has_second:
142 * @datetime: a #GstDateTime
144 * Returns: TRUE if @datetime<!-- -->'s second field is set, otherwise FALSE
147 gst_date_time_has_second (const GstDateTime * datetime)
149 g_return_val_if_fail (datetime != NULL, FALSE);
151 return (datetime->fields >= GST_DATE_TIME_FIELDS_YMD_HMS);
155 * gst_date_time_get_year:
156 * @datetime: a #GstDateTime
158 * Returns the year of this #GstDateTime
159 * Call gst_date_time_has_year before, to avoid warnings.
161 * Return value: The year of this #GstDateTime
165 gst_date_time_get_year (const GstDateTime * datetime)
167 g_return_val_if_fail (datetime != NULL, 0);
169 return g_date_time_get_year (datetime->datetime);
173 * gst_date_time_get_month:
174 * @datetime: a #GstDateTime
176 * Returns the month of this #GstDateTime. January is 1, February is 2, etc..
177 * Call gst_date_time_has_month before, to avoid warnings.
179 * Return value: The month of this #GstDateTime
183 gst_date_time_get_month (const GstDateTime * datetime)
185 g_return_val_if_fail (datetime != NULL, 0);
186 g_return_val_if_fail (gst_date_time_has_month (datetime), 0);
188 return g_date_time_get_month (datetime->datetime);
192 * gst_date_time_get_day:
193 * @datetime: a #GstDateTime
195 * Returns the day of this #GstDateTime.
196 * Call gst_date_time_has_day before, to avoid warnings.
198 * Return value: The day of this #GstDateTime
202 gst_date_time_get_day (const GstDateTime * datetime)
204 g_return_val_if_fail (datetime != NULL, 0);
205 g_return_val_if_fail (gst_date_time_has_day (datetime), 0);
207 return g_date_time_get_day_of_month (datetime->datetime);
211 * gst_date_time_get_hour:
212 * @datetime: a #GstDateTime
214 * Retrieves the hour of the day represented by @datetime in the gregorian
215 * calendar. The return is in the range of 0 to 23.
216 * Call gst_date_time_has_haur before, to avoid warnings.
218 * Return value: the hour of the day
223 gst_date_time_get_hour (const GstDateTime * datetime)
225 g_return_val_if_fail (datetime != NULL, 0);
226 g_return_val_if_fail (gst_date_time_has_time (datetime), 0);
228 return g_date_time_get_hour (datetime->datetime);
232 * gst_date_time_get_minute:
233 * @datetime: a #GstDateTime
235 * Retrieves the minute of the hour represented by @datetime in the gregorian
237 * Call gst_date_time_has_minute before, to avoid warnings.
239 * Return value: the minute of the hour
244 gst_date_time_get_minute (const GstDateTime * datetime)
246 g_return_val_if_fail (datetime != NULL, 0);
247 g_return_val_if_fail (gst_date_time_has_time (datetime), 0);
249 return g_date_time_get_minute (datetime->datetime);
253 * gst_date_time_get_second:
254 * @datetime: a #GstDateTime
256 * Retrieves the second of the minute represented by @datetime in the gregorian
258 * Call gst_date_time_has_second before, to avoid warnings.
260 * Return value: the second represented by @datetime
265 gst_date_time_get_second (const GstDateTime * datetime)
267 g_return_val_if_fail (datetime != NULL, 0);
268 g_return_val_if_fail (gst_date_time_has_second (datetime), 0);
270 return g_date_time_get_second (datetime->datetime);
274 * gst_date_time_get_microsecond:
275 * @datetime: a #GstDateTime
277 * Retrieves the fractional part of the seconds in microseconds represented by
278 * @datetime in the gregorian calendar.
280 * Return value: the microsecond of the second
285 gst_date_time_get_microsecond (const GstDateTime * datetime)
287 g_return_val_if_fail (datetime != NULL, 0);
288 g_return_val_if_fail (gst_date_time_has_second (datetime), 0);
290 return g_date_time_get_microsecond (datetime->datetime);
294 * gst_date_time_get_time_zone_offset:
295 * @datetime: a #GstDateTime
297 * Retrieves the offset from UTC in hours that the timezone specified
298 * by @datetime represents. Timezones ahead (to the east) of UTC have positive
299 * values, timezones before (to the west) of UTC have negative values.
300 * If @datetime represents UTC time, then the offset is zero.
302 * Return value: the offset from UTC in hours
306 gst_date_time_get_time_zone_offset (const GstDateTime * datetime)
308 g_return_val_if_fail (datetime != NULL, 0.0);
309 g_return_val_if_fail (gst_date_time_has_time (datetime), 0.0);
311 return (g_date_time_get_utc_offset (datetime->datetime) /
312 G_USEC_PER_SEC) / 3600.0;
316 * gst_date_time_new_y:
317 * @year: the gregorian year
319 * Creates a new #GstDateTime using the date and times in the gregorian calendar
320 * in the local timezone.
322 * @year should be from 1 to 9999.
324 * Free-function: gst_date_time_unref
326 * Return value: (transfer full): the newly created #GstDateTime
331 gst_date_time_new_y (gint year)
333 return gst_date_time_new (0.0, year, -1, -1, -1, -1, -1);
337 * gst_date_time_new_ym:
338 * @year: the gregorian year
339 * @month: the gregorian month
341 * Creates a new #GstDateTime using the date and times in the gregorian calendar
342 * in the local timezone.
344 * @year should be from 1 to 9999, @month should be from 1 to 12.
346 * If value is -1 then all over value will be ignored. For example
347 * if @month == -1, then #GstDateTime will created only for @year.
349 * Free-function: gst_date_time_unref
351 * Return value: (transfer full): the newly created #GstDateTime
356 gst_date_time_new_ym (gint year, gint month)
358 return gst_date_time_new (0.0, year, month, -1, -1, -1, -1);
362 * gst_date_time_new_ymd:
363 * @year: the gregorian year
364 * @month: the gregorian month
365 * @day: the day of the gregorian month
367 * Creates a new #GstDateTime using the date and times in the gregorian calendar
368 * in the local timezone.
370 * @year should be from 1 to 9999, @month should be from 1 to 12, @day from
373 * If value is -1 then all over value will be ignored. For example
374 * if @month == -1, then #GstDateTime will created only for @year. If
375 * @day == -1, then #GstDateTime will created for @year and @month and
378 * Free-function: gst_date_time_unref
380 * Return value: (transfer full): the newly created #GstDateTime
385 gst_date_time_new_ymd (gint year, gint month, gint day)
387 return gst_date_time_new (0.0, year, month, day, -1, -1, -1);
391 * gst_date_time_new_from_unix_epoch_local_time:
392 * @secs: seconds from the Unix epoch
394 * Creates a new #GstDateTime using the time since Jan 1, 1970 specified by
395 * @secs. The #GstDateTime is in the local timezone.
397 * Free-function: gst_date_time_unref
399 * Return value: (transfer full): the newly created #GstDateTime
404 gst_date_time_new_from_unix_epoch_local_time (gint64 secs)
406 GstDateTime *datetime;
408 gst_date_time_new_from_gdatetime (g_date_time_new_from_unix_local (secs));
413 * gst_date_time_new_from_unix_epoch_utc:
414 * @secs: seconds from the Unix epoch
416 * Creates a new #GstDateTime using the time since Jan 1, 1970 specified by
417 * @secs. The #GstDateTime is in the UTC timezone.
419 * Free-function: gst_date_time_unref
421 * Return value: (transfer full): the newly created #GstDateTime
426 gst_date_time_new_from_unix_epoch_utc (gint64 secs)
428 GstDateTime *datetime;
430 gst_date_time_new_from_gdatetime (g_date_time_new_from_unix_utc (secs));
434 static GstDateTimeFields
435 gst_date_time_check_fields (gint * year, gint * month, gint * day,
436 gint * hour, gint * minute, gdouble * seconds)
440 *hour = *minute = *seconds = 0;
441 return GST_DATE_TIME_FIELDS_Y;
442 } else if (*day == -1) {
444 *hour = *minute = *seconds = 0;
445 return GST_DATE_TIME_FIELDS_YM;
446 } else if (*hour == -1) {
447 *hour = *minute = *seconds = 0;
448 return GST_DATE_TIME_FIELDS_YMD;
449 } else if (*seconds == -1) {
451 return GST_DATE_TIME_FIELDS_YMD_HM;
453 return GST_DATE_TIME_FIELDS_YMD_HMS;
457 * gst_date_time_new_local_time:
458 * @year: the gregorian year
459 * @month: the gregorian month, or -1
460 * @day: the day of the gregorian month, or -1
461 * @hour: the hour of the day, or -1
462 * @minute: the minute of the hour, or -1
463 * @seconds: the second of the minute, or -1
465 * Creates a new #GstDateTime using the date and times in the gregorian calendar
466 * in the local timezone.
468 * @year should be from 1 to 9999, @month should be from 1 to 12, @day from
469 * 1 to 31, @hour from 0 to 23, @minutes and @seconds from 0 to 59.
471 * If @month is -1, then the #GstDateTime created will only contain @year,
472 * and all other fields will be considered not set.
474 * If @day is -1, then the #GstDateTime created will only contain @year and
475 * @month and all other fields will be considered not set.
477 * If @hour is -1, then the #GstDateTime created will only contain @year and
478 * @month and @day, and the time fields will be considered not set. In this
479 * case @minute and @seconds should also be -1.
481 * Free-function: gst_date_time_unref
483 * Return value: (transfer full): the newly created #GstDateTime
488 gst_date_time_new_local_time (gint year, gint month, gint day, gint hour,
489 gint minute, gdouble seconds)
491 GstDateTimeFields fields;
492 GstDateTime *datetime;
494 g_return_val_if_fail (year > 0 && year <= 9999, NULL);
495 g_return_val_if_fail ((month > 0 && month <= 12) || month == -1, NULL);
496 g_return_val_if_fail ((day > 0 && day <= 31) || day == -1, NULL);
497 g_return_val_if_fail ((hour >= 0 && hour < 24) || hour == -1, NULL);
498 g_return_val_if_fail ((minute >= 0 && minute < 60) || minute == -1, NULL);
499 g_return_val_if_fail ((seconds >= 0 && seconds < 60) || seconds == -1, NULL);
501 fields = gst_date_time_check_fields (&year, &month, &day,
502 &hour, &minute, &seconds);
504 datetime = gst_date_time_new_from_gdatetime (g_date_time_new_local (year,
505 month, day, hour, minute, seconds));
507 datetime->fields = fields;
512 * gst_date_time_new_now_local_time:
514 * Creates a new #GstDateTime representing the current date and time.
516 * Free-function: gst_date_time_unref
518 * Return value: (transfer full): the newly created #GstDateTime which should
519 * be freed with gst_date_time_unref().
524 gst_date_time_new_now_local_time (void)
526 return gst_date_time_new_from_gdatetime (g_date_time_new_now_local ());
530 * gst_date_time_new_now_utc:
532 * Creates a new #GstDateTime that represents the current instant at Universal
535 * Free-function: gst_date_time_unref
537 * Return value: (transfer full): the newly created #GstDateTime which should
538 * be freed with gst_date_time_unref().
543 gst_date_time_new_now_utc (void)
545 return gst_date_time_new_from_gdatetime (g_date_time_new_now_utc ());
549 __gst_date_time_compare (const GstDateTime * dt1, const GstDateTime * dt2)
553 /* we assume here that GST_DATE_TIME_FIELDS_YMD_HMS is the highest
554 * resolution, and ignore microsecond differences on purpose for now */
555 if (dt1->fields != dt2->fields)
556 return GST_VALUE_UNORDERED;
558 /* This will round down to nearest second, which is what we want. We're
559 * not comparing microseconds on purpose here, since we're not
560 * serialising them when doing new_utc_now() + to_string() */
562 g_date_time_to_unix (dt1->datetime) - g_date_time_to_unix (dt2->datetime);
564 return GST_VALUE_LESS_THAN;
566 return GST_VALUE_GREATER_THAN;
568 return GST_VALUE_EQUAL;
573 * @tzoffset: Offset from UTC in hours.
574 * @year: the gregorian year
575 * @month: the gregorian month
576 * @day: the day of the gregorian month
577 * @hour: the hour of the day
578 * @minute: the minute of the hour
579 * @seconds: the second of the minute
581 * Creates a new #GstDateTime using the date and times in the gregorian calendar
582 * in the supplied timezone.
584 * @year should be from 1 to 9999, @month should be from 1 to 12, @day from
585 * 1 to 31, @hour from 0 to 23, @minutes and @seconds from 0 to 59.
587 * Note that @tzoffset is a float and was chosen so for being able to handle
588 * some fractional timezones, while it still keeps the readability of
589 * represeting it in hours for most timezones.
591 * If value is -1 then all over value will be ignored. For example
592 * if @month == -1, then #GstDateTime will created only for @year. If
593 * @day == -1, then #GstDateTime will created for @year and @month and
596 * Free-function: gst_date_time_unref
598 * Return value: (transfer full): the newly created #GstDateTime
603 gst_date_time_new (gfloat tzoffset, gint year, gint month, gint day, gint hour,
604 gint minute, gdouble seconds)
606 GstDateTimeFields fields;
610 GstDateTime *datetime;
611 gint tzhour, tzminute;
613 g_return_val_if_fail (year > 0 && year <= 9999, NULL);
614 g_return_val_if_fail ((month > 0 && month <= 12) || month == -1, NULL);
615 g_return_val_if_fail ((day > 0 && day <= 31) || day == -1, NULL);
616 g_return_val_if_fail ((hour >= 0 && hour < 24) || hour == -1, NULL);
617 g_return_val_if_fail ((minute >= 0 && minute < 60) || minute == -1, NULL);
618 g_return_val_if_fail ((seconds >= 0 && seconds < 60) || seconds == -1, NULL);
619 g_return_val_if_fail (tzoffset >= -12.0 && tzoffset <= 12.0, NULL);
620 g_return_val_if_fail ((hour >= 0 && minute >= 0) ||
621 (hour == -1 && minute == -1 && seconds == -1 && tzoffset == 0.0), NULL);
623 tzhour = (gint) ABS (tzoffset);
624 tzminute = (gint) ((ABS (tzoffset) - tzhour) * 60);
626 g_snprintf (buf, 6, "%c%02d%02d", tzoffset >= 0 ? '+' : '-', tzhour,
629 tz = g_time_zone_new (buf);
631 fields = gst_date_time_check_fields (&year, &month, &day,
632 &hour, &minute, &seconds);
634 dt = g_date_time_new (tz, year, month, day, hour, minute, seconds);
635 g_time_zone_unref (tz);
637 datetime = gst_date_time_new_from_gdatetime (dt);
638 datetime->fields = fields;
645 * gst_date_time_to_iso8601_string:
646 * @datetime: GstDateTime.
648 * Create a minimal string compatible with ISO-8601. Possible output formats
649 * are (for example): 2012, 2012-06, 2012-06-23, 2012-06-23T23:30Z,
650 * 2012-06-23T23:30+0100, 2012-06-23T23:30:59Z, 2012-06-23T23:30:59+0100
652 * Returns: a newly allocated string formatted according to ISO 8601 and
653 * only including the datetime fields that are valid, or NULL in case
654 * there was an error. The string should be freed with g_free().
657 gst_date_time_to_iso8601_string (GstDateTime * datetime)
661 switch (datetime->fields) {
662 case GST_DATE_TIME_FIELDS_Y:
663 return g_date_time_format (datetime->datetime, "%Y");
664 case GST_DATE_TIME_FIELDS_YM:
665 return g_date_time_format (datetime->datetime, "%Y-%m");
666 case GST_DATE_TIME_FIELDS_YMD:
667 return g_date_time_format (datetime->datetime, "%F");
668 case GST_DATE_TIME_FIELDS_YMD_HM:
669 gmt_offset = gst_date_time_get_time_zone_offset (datetime);
671 return g_date_time_format (datetime->datetime, "%FT%RZ");
673 return g_date_time_format (datetime->datetime, "%FT%R%z");
674 case GST_DATE_TIME_FIELDS_YMD_HMS:
675 gmt_offset = gst_date_time_get_time_zone_offset (datetime);
677 return g_date_time_format (datetime->datetime, "%FT%TZ");
679 return g_date_time_format (datetime->datetime, "%FT%T%z");
686 * gst_date_time_new_from_iso8601_string:
687 * @string: ISO 8601-formatted datetime string.
689 * Tries to parse common variants of ISO-8601 datetime strings into a
692 * Free-function: gst_date_time_unref
694 * Returns: (transfer full): a newly created #GstDateTime, or NULL on error
697 gst_date_time_new_from_iso8601_string (const gchar * string)
699 gint year = -1, month = -1, day = -1, hour = -1, minute = -1, second = -1;
700 gfloat tzoffset = 0.0;
703 len = strlen (string);
705 g_return_val_if_fail (len >= 4, NULL);
706 g_return_val_if_fail (g_ascii_isdigit (*string), NULL);
708 GST_DEBUG ("Parsing %s into a datetime", string);
710 ret = sscanf (string, "%04d-%02d-%02d", &year, &month, &day);
714 else if (ret >= 1 && len < 16)
715 /* YMD is 10 chars. XMD + HM will be 16 chars. if it is less,
716 * it make no sense to continue. We will stay with YMD. */
720 /* Exit if there is no expeceted value on this stage */
721 if (!(*string == 'T' || *string == '-' || *string == ' '))
724 /* if hour or minute fails, then we will use onlly ymd. */
725 hour = g_ascii_strtoull (string + 1, (gchar **) & string, 10);
726 if (hour > 24 || *string != ':')
729 minute = g_ascii_strtoull (string + 1, (gchar **) & string, 10);
733 if (*string == ':') {
734 second = g_ascii_strtoull (string + 1, (gchar **) & string, 10);
735 /* if we fail here, we still can reuse hour and minute. We
736 * will also fall of to tzoffset = 0.0 */
744 /* reuse some code from gst-plugins-base/gst-libs/gst/tag/gstxmptag.c */
745 gint gmt_offset_hour = -1, gmt_offset_min = -1, gmt_offset = -1;
746 gchar *plus_pos = NULL;
747 gchar *neg_pos = NULL;
750 GST_LOG ("Checking for timezone information");
752 /* check if there is timezone info */
753 plus_pos = strrchr (string, '+');
754 neg_pos = strrchr (string, '-');
763 ret_tz = sscanf (pos, "%d:%d", &gmt_offset_hour, &gmt_offset_min);
765 ret_tz = sscanf (pos, "%02d%02d", &gmt_offset_hour, &gmt_offset_min);
767 GST_DEBUG ("Parsing timezone: %s", pos);
770 gmt_offset = gmt_offset_hour * 60 + gmt_offset_min;
771 if (neg_pos != NULL && neg_pos + 1 == pos)
774 tzoffset = gmt_offset / 60.0;
776 GST_LOG ("Timezone offset: %f (%d minutes)", tzoffset, gmt_offset);
778 GST_WARNING ("Failed to parse timezone information");
783 return gst_date_time_new (tzoffset, year, month, day, hour, minute, second);
785 return gst_date_time_new_ymd (year, month, day);
790 gst_date_time_free (GstDateTime * datetime)
792 g_date_time_unref (datetime->datetime);
793 g_slice_free (GstDateTime, datetime);
798 * @datetime: a #GstDateTime
800 * Atomically increments the reference count of @datetime by one.
802 * Return value: (transfer full): the reference @datetime
807 gst_date_time_ref (GstDateTime * datetime)
809 g_return_val_if_fail (datetime != NULL, NULL);
810 g_return_val_if_fail (datetime->ref_count > 0, NULL);
811 g_atomic_int_inc (&datetime->ref_count);
816 * gst_date_time_unref:
817 * @datetime: (transfer full): a #GstDateTime
819 * Atomically decrements the reference count of @datetime by one. When the
820 * reference count reaches zero, the structure is freed.
825 gst_date_time_unref (GstDateTime * datetime)
827 g_return_if_fail (datetime != NULL);
828 g_return_if_fail (datetime->ref_count > 0);
830 if (g_atomic_int_dec_and_test (&datetime->ref_count))
831 gst_date_time_free (datetime);