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_g_date_time:
69 * @dt: (transfer full): the #GDateTime. The new #GstDateTime takes ownership.
71 * Creates a new #GstDateTime from a #GDateTime object.
73 * Free-function: gst_date_time_unref
75 * Returns: (transfer full): a newly created #GstDateTime, or NULL on error
78 gst_date_time_new_from_g_date_time (GDateTime * dt)
85 gst_dt = g_slice_new (GstDateTime);
86 gst_dt->datetime = dt;
87 gst_dt->fields = GST_DATE_TIME_FIELDS_YMD_HMS;
88 gst_dt->ref_count = 1;
93 * gst_date_time_to_g_date_time:
94 * @datetime: GstDateTime.
96 * Creates a new #GDateTime from a fully defined #GstDateTime object.
98 * Free-function: g_date_time_unref
100 * Returns: (transfer full): a newly created #GDateTime, or NULL on error
103 gst_date_time_to_g_date_time (GstDateTime * datetime)
105 g_return_val_if_fail (datetime != NULL, NULL);
107 if (datetime->fields != GST_DATE_TIME_FIELDS_YMD_HMS)
110 return g_date_time_add (datetime->datetime, 0);
114 * gst_date_time_has_year:
115 * @datetime: a #GstDateTime
117 * Returns: TRUE if @datetime<!-- -->'s year field is set (which should always
118 * be the case), otherwise FALSE
121 gst_date_time_has_year (const GstDateTime * datetime)
123 g_return_val_if_fail (datetime != NULL, FALSE);
125 return (datetime->fields >= GST_DATE_TIME_FIELDS_Y);
129 * gst_date_time_has_month:
130 * @datetime: a #GstDateTime
132 * Returns: TRUE if @datetime<!-- -->'s month field is set, otherwise FALSE
135 gst_date_time_has_month (const GstDateTime * datetime)
137 g_return_val_if_fail (datetime != NULL, FALSE);
139 return (datetime->fields >= GST_DATE_TIME_FIELDS_YM);
143 * gst_date_time_has_day:
144 * @datetime: a #GstDateTime
146 * Returns: TRUE if @datetime<!-- -->'s day field is set, otherwise FALSE
149 gst_date_time_has_day (const GstDateTime * datetime)
151 g_return_val_if_fail (datetime != NULL, FALSE);
153 return (datetime->fields >= GST_DATE_TIME_FIELDS_YMD);
157 * gst_date_time_has_time:
158 * @datetime: a #GstDateTime
160 * Returns: TRUE if @datetime<!-- -->'s hour and minute fields are set,
164 gst_date_time_has_time (const GstDateTime * datetime)
166 g_return_val_if_fail (datetime != NULL, FALSE);
168 return (datetime->fields >= GST_DATE_TIME_FIELDS_YMD_HM);
172 * gst_date_time_has_second:
173 * @datetime: a #GstDateTime
175 * Returns: TRUE if @datetime<!-- -->'s second field is set, otherwise FALSE
178 gst_date_time_has_second (const GstDateTime * datetime)
180 g_return_val_if_fail (datetime != NULL, FALSE);
182 return (datetime->fields >= GST_DATE_TIME_FIELDS_YMD_HMS);
186 * gst_date_time_get_year:
187 * @datetime: a #GstDateTime
189 * Returns the year of this #GstDateTime
190 * Call gst_date_time_has_year before, to avoid warnings.
192 * Return value: The year of this #GstDateTime
196 gst_date_time_get_year (const GstDateTime * datetime)
198 g_return_val_if_fail (datetime != NULL, 0);
200 return g_date_time_get_year (datetime->datetime);
204 * gst_date_time_get_month:
205 * @datetime: a #GstDateTime
207 * Returns the month of this #GstDateTime. January is 1, February is 2, etc..
208 * Call gst_date_time_has_month before, to avoid warnings.
210 * Return value: The month of this #GstDateTime
214 gst_date_time_get_month (const GstDateTime * datetime)
216 g_return_val_if_fail (datetime != NULL, 0);
217 g_return_val_if_fail (gst_date_time_has_month (datetime), 0);
219 return g_date_time_get_month (datetime->datetime);
223 * gst_date_time_get_day:
224 * @datetime: a #GstDateTime
226 * Returns the day of the month of this #GstDateTime.
227 * Call gst_date_time_has_day before, to avoid warnings.
229 * Return value: The day of this #GstDateTime
233 gst_date_time_get_day (const GstDateTime * datetime)
235 g_return_val_if_fail (datetime != NULL, 0);
236 g_return_val_if_fail (gst_date_time_has_day (datetime), 0);
238 return g_date_time_get_day_of_month (datetime->datetime);
242 * gst_date_time_get_hour:
243 * @datetime: a #GstDateTime
245 * Retrieves the hour of the day represented by @datetime in the gregorian
246 * calendar. The return is in the range of 0 to 23.
247 * Call gst_date_time_has_haur before, to avoid warnings.
249 * Return value: the hour of the day
254 gst_date_time_get_hour (const GstDateTime * datetime)
256 g_return_val_if_fail (datetime != NULL, 0);
257 g_return_val_if_fail (gst_date_time_has_time (datetime), 0);
259 return g_date_time_get_hour (datetime->datetime);
263 * gst_date_time_get_minute:
264 * @datetime: a #GstDateTime
266 * Retrieves the minute of the hour represented by @datetime in the gregorian
268 * Call gst_date_time_has_minute before, to avoid warnings.
270 * Return value: the minute of the hour
275 gst_date_time_get_minute (const GstDateTime * datetime)
277 g_return_val_if_fail (datetime != NULL, 0);
278 g_return_val_if_fail (gst_date_time_has_time (datetime), 0);
280 return g_date_time_get_minute (datetime->datetime);
284 * gst_date_time_get_second:
285 * @datetime: a #GstDateTime
287 * Retrieves the second of the minute represented by @datetime in the gregorian
289 * Call gst_date_time_has_second before, to avoid warnings.
291 * Return value: the second represented by @datetime
296 gst_date_time_get_second (const GstDateTime * datetime)
298 g_return_val_if_fail (datetime != NULL, 0);
299 g_return_val_if_fail (gst_date_time_has_second (datetime), 0);
301 return g_date_time_get_second (datetime->datetime);
305 * gst_date_time_get_microsecond:
306 * @datetime: a #GstDateTime
308 * Retrieves the fractional part of the seconds in microseconds represented by
309 * @datetime in the gregorian calendar.
311 * Return value: the microsecond of the second
316 gst_date_time_get_microsecond (const GstDateTime * datetime)
318 g_return_val_if_fail (datetime != NULL, 0);
319 g_return_val_if_fail (gst_date_time_has_second (datetime), 0);
321 return g_date_time_get_microsecond (datetime->datetime);
325 * gst_date_time_get_time_zone_offset:
326 * @datetime: a #GstDateTime
328 * Retrieves the offset from UTC in hours that the timezone specified
329 * by @datetime represents. Timezones ahead (to the east) of UTC have positive
330 * values, timezones before (to the west) of UTC have negative values.
331 * If @datetime represents UTC time, then the offset is zero.
333 * Return value: the offset from UTC in hours
337 gst_date_time_get_time_zone_offset (const GstDateTime * datetime)
339 g_return_val_if_fail (datetime != NULL, 0.0);
340 g_return_val_if_fail (gst_date_time_has_time (datetime), 0.0);
342 return (g_date_time_get_utc_offset (datetime->datetime) /
343 G_USEC_PER_SEC) / 3600.0;
347 * gst_date_time_new_y:
348 * @year: the gregorian year
350 * Creates a new #GstDateTime using the date and times in the gregorian calendar
351 * in the local timezone.
353 * @year should be from 1 to 9999.
355 * Free-function: gst_date_time_unref
357 * Return value: (transfer full): the newly created #GstDateTime
362 gst_date_time_new_y (gint year)
364 return gst_date_time_new (0.0, year, -1, -1, -1, -1, -1);
368 * gst_date_time_new_ym:
369 * @year: the gregorian year
370 * @month: the gregorian month
372 * Creates a new #GstDateTime using the date and times in the gregorian calendar
373 * in the local timezone.
375 * @year should be from 1 to 9999, @month should be from 1 to 12.
377 * If value is -1 then all over value will be ignored. For example
378 * if @month == -1, then #GstDateTime will created only for @year.
380 * Free-function: gst_date_time_unref
382 * Return value: (transfer full): the newly created #GstDateTime
387 gst_date_time_new_ym (gint year, gint month)
389 return gst_date_time_new (0.0, year, month, -1, -1, -1, -1);
393 * gst_date_time_new_ymd:
394 * @year: the gregorian year
395 * @month: the gregorian month
396 * @day: the day of the gregorian month
398 * Creates a new #GstDateTime using the date and times in the gregorian calendar
399 * in the local timezone.
401 * @year should be from 1 to 9999, @month should be from 1 to 12, @day from
404 * If value is -1 then all over value will be ignored. For example
405 * if @month == -1, then #GstDateTime will created only for @year. If
406 * @day == -1, then #GstDateTime will created for @year and @month and
409 * Free-function: gst_date_time_unref
411 * Return value: (transfer full): the newly created #GstDateTime
416 gst_date_time_new_ymd (gint year, gint month, gint day)
418 return gst_date_time_new (0.0, year, month, day, -1, -1, -1);
422 * gst_date_time_new_from_unix_epoch_local_time:
423 * @secs: seconds from the Unix epoch
425 * Creates a new #GstDateTime using the time since Jan 1, 1970 specified by
426 * @secs. The #GstDateTime is in the local timezone.
428 * Free-function: gst_date_time_unref
430 * Return value: (transfer full): the newly created #GstDateTime
435 gst_date_time_new_from_unix_epoch_local_time (gint64 secs)
439 datetime = g_date_time_new_from_unix_local (secs);
440 return gst_date_time_new_from_g_date_time (datetime);
444 * gst_date_time_new_from_unix_epoch_utc:
445 * @secs: seconds from the Unix epoch
447 * Creates a new #GstDateTime using the time since Jan 1, 1970 specified by
448 * @secs. The #GstDateTime is in the UTC timezone.
450 * Free-function: gst_date_time_unref
452 * Return value: (transfer full): the newly created #GstDateTime
457 gst_date_time_new_from_unix_epoch_utc (gint64 secs)
459 GstDateTime *datetime;
461 gst_date_time_new_from_g_date_time (g_date_time_new_from_unix_utc (secs));
465 static GstDateTimeFields
466 gst_date_time_check_fields (gint * year, gint * month, gint * day,
467 gint * hour, gint * minute, gdouble * seconds)
471 *hour = *minute = *seconds = 0;
472 return GST_DATE_TIME_FIELDS_Y;
473 } else if (*day == -1) {
475 *hour = *minute = *seconds = 0;
476 return GST_DATE_TIME_FIELDS_YM;
477 } else if (*hour == -1) {
478 *hour = *minute = *seconds = 0;
479 return GST_DATE_TIME_FIELDS_YMD;
480 } else if (*seconds == -1) {
482 return GST_DATE_TIME_FIELDS_YMD_HM;
484 return GST_DATE_TIME_FIELDS_YMD_HMS;
488 * gst_date_time_new_local_time:
489 * @year: the gregorian year
490 * @month: the gregorian month, or -1
491 * @day: the day of the gregorian month, or -1
492 * @hour: the hour of the day, or -1
493 * @minute: the minute of the hour, or -1
494 * @seconds: the second of the minute, or -1
496 * Creates a new #GstDateTime using the date and times in the gregorian calendar
497 * in the local timezone.
499 * @year should be from 1 to 9999, @month should be from 1 to 12, @day from
500 * 1 to 31, @hour from 0 to 23, @minutes and @seconds from 0 to 59.
502 * If @month is -1, then the #GstDateTime created will only contain @year,
503 * and all other fields will be considered not set.
505 * If @day is -1, then the #GstDateTime created will only contain @year and
506 * @month and all other fields will be considered not set.
508 * If @hour is -1, then the #GstDateTime created will only contain @year and
509 * @month and @day, and the time fields will be considered not set. In this
510 * case @minute and @seconds should also be -1.
512 * Free-function: gst_date_time_unref
514 * Return value: (transfer full): the newly created #GstDateTime
519 gst_date_time_new_local_time (gint year, gint month, gint day, gint hour,
520 gint minute, gdouble seconds)
522 GstDateTimeFields fields;
523 GstDateTime *datetime;
525 g_return_val_if_fail (year > 0 && year <= 9999, NULL);
526 g_return_val_if_fail ((month > 0 && month <= 12) || month == -1, NULL);
527 g_return_val_if_fail ((day > 0 && day <= 31) || day == -1, NULL);
528 g_return_val_if_fail ((hour >= 0 && hour < 24) || hour == -1, NULL);
529 g_return_val_if_fail ((minute >= 0 && minute < 60) || minute == -1, NULL);
530 g_return_val_if_fail ((seconds >= 0 && seconds < 60) || seconds == -1, NULL);
532 fields = gst_date_time_check_fields (&year, &month, &day,
533 &hour, &minute, &seconds);
535 datetime = gst_date_time_new_from_g_date_time (g_date_time_new_local (year,
536 month, day, hour, minute, seconds));
538 datetime->fields = fields;
543 * gst_date_time_new_now_local_time:
545 * Creates a new #GstDateTime representing the current date and time.
547 * Free-function: gst_date_time_unref
549 * Return value: (transfer full): the newly created #GstDateTime which should
550 * be freed with gst_date_time_unref().
555 gst_date_time_new_now_local_time (void)
557 return gst_date_time_new_from_g_date_time (g_date_time_new_now_local ());
561 * gst_date_time_new_now_utc:
563 * Creates a new #GstDateTime that represents the current instant at Universal
566 * Free-function: gst_date_time_unref
568 * Return value: (transfer full): the newly created #GstDateTime which should
569 * be freed with gst_date_time_unref().
574 gst_date_time_new_now_utc (void)
576 return gst_date_time_new_from_g_date_time (g_date_time_new_now_utc ());
580 __gst_date_time_compare (const GstDateTime * dt1, const GstDateTime * dt2)
584 /* we assume here that GST_DATE_TIME_FIELDS_YMD_HMS is the highest
585 * resolution, and ignore microsecond differences on purpose for now */
586 if (dt1->fields != dt2->fields)
587 return GST_VALUE_UNORDERED;
589 /* This will round down to nearest second, which is what we want. We're
590 * not comparing microseconds on purpose here, since we're not
591 * serialising them when doing new_utc_now() + to_string() */
593 g_date_time_to_unix (dt1->datetime) - g_date_time_to_unix (dt2->datetime);
595 return GST_VALUE_LESS_THAN;
597 return GST_VALUE_GREATER_THAN;
599 return GST_VALUE_EQUAL;
604 * @tzoffset: Offset from UTC in hours.
605 * @year: the gregorian year
606 * @month: the gregorian month
607 * @day: the day of the gregorian month
608 * @hour: the hour of the day
609 * @minute: the minute of the hour
610 * @seconds: the second of the minute
612 * Creates a new #GstDateTime using the date and times in the gregorian calendar
613 * in the supplied timezone.
615 * @year should be from 1 to 9999, @month should be from 1 to 12, @day from
616 * 1 to 31, @hour from 0 to 23, @minutes and @seconds from 0 to 59.
618 * Note that @tzoffset is a float and was chosen so for being able to handle
619 * some fractional timezones, while it still keeps the readability of
620 * represeting it in hours for most timezones.
622 * If value is -1 then all over value will be ignored. For example
623 * if @month == -1, then #GstDateTime will created only for @year. If
624 * @day == -1, then #GstDateTime will created for @year and @month and
627 * Free-function: gst_date_time_unref
629 * Return value: (transfer full): the newly created #GstDateTime
634 gst_date_time_new (gfloat tzoffset, gint year, gint month, gint day, gint hour,
635 gint minute, gdouble seconds)
637 GstDateTimeFields fields;
641 GstDateTime *datetime;
642 gint tzhour, tzminute;
644 g_return_val_if_fail (year > 0 && year <= 9999, NULL);
645 g_return_val_if_fail ((month > 0 && month <= 12) || month == -1, NULL);
646 g_return_val_if_fail ((day > 0 && day <= 31) || day == -1, NULL);
647 g_return_val_if_fail ((hour >= 0 && hour < 24) || hour == -1, NULL);
648 g_return_val_if_fail ((minute >= 0 && minute < 60) || minute == -1, NULL);
649 g_return_val_if_fail ((seconds >= 0 && seconds < 60) || seconds == -1, NULL);
650 g_return_val_if_fail (tzoffset >= -12.0 && tzoffset <= 12.0, NULL);
651 g_return_val_if_fail ((hour >= 0 && minute >= 0) ||
652 (hour == -1 && minute == -1 && seconds == -1 && tzoffset == 0.0), NULL);
654 tzhour = (gint) ABS (tzoffset);
655 tzminute = (gint) ((ABS (tzoffset) - tzhour) * 60);
657 g_snprintf (buf, 6, "%c%02d%02d", tzoffset >= 0 ? '+' : '-', tzhour,
660 tz = g_time_zone_new (buf);
662 fields = gst_date_time_check_fields (&year, &month, &day,
663 &hour, &minute, &seconds);
665 dt = g_date_time_new (tz, year, month, day, hour, minute, seconds);
666 g_time_zone_unref (tz);
668 datetime = gst_date_time_new_from_g_date_time (dt);
669 datetime->fields = fields;
676 * gst_date_time_to_iso8601_string:
677 * @datetime: GstDateTime.
679 * Create a minimal string compatible with ISO-8601. Possible output formats
680 * are (for example): 2012, 2012-06, 2012-06-23, 2012-06-23T23:30Z,
681 * 2012-06-23T23:30+0100, 2012-06-23T23:30:59Z, 2012-06-23T23:30:59+0100
683 * Returns: a newly allocated string formatted according to ISO 8601 and
684 * only including the datetime fields that are valid, or NULL in case
685 * there was an error. The string should be freed with g_free().
688 gst_date_time_to_iso8601_string (GstDateTime * datetime)
692 switch (datetime->fields) {
693 case GST_DATE_TIME_FIELDS_Y:
694 return g_date_time_format (datetime->datetime, "%Y");
695 case GST_DATE_TIME_FIELDS_YM:
696 return g_date_time_format (datetime->datetime, "%Y-%m");
697 case GST_DATE_TIME_FIELDS_YMD:
698 return g_date_time_format (datetime->datetime, "%F");
699 case GST_DATE_TIME_FIELDS_YMD_HM:
700 gmt_offset = gst_date_time_get_time_zone_offset (datetime);
702 return g_date_time_format (datetime->datetime, "%FT%RZ");
704 return g_date_time_format (datetime->datetime, "%FT%R%z");
705 case GST_DATE_TIME_FIELDS_YMD_HMS:
706 gmt_offset = gst_date_time_get_time_zone_offset (datetime);
708 return g_date_time_format (datetime->datetime, "%FT%TZ");
710 return g_date_time_format (datetime->datetime, "%FT%T%z");
717 * gst_date_time_new_from_iso8601_string:
718 * @string: ISO 8601-formatted datetime string.
720 * Tries to parse common variants of ISO-8601 datetime strings into a
723 * Free-function: gst_date_time_unref
725 * Returns: (transfer full): a newly created #GstDateTime, or NULL on error
728 gst_date_time_new_from_iso8601_string (const gchar * string)
730 gint year = -1, month = -1, day = -1, hour = -1, minute = -1, second = -1;
731 gfloat tzoffset = 0.0;
734 len = strlen (string);
736 g_return_val_if_fail (len >= 4, NULL);
737 g_return_val_if_fail (g_ascii_isdigit (*string), NULL);
739 GST_DEBUG ("Parsing %s into a datetime", string);
741 ret = sscanf (string, "%04d-%02d-%02d", &year, &month, &day);
746 if (ret == 3 && day <= 0) {
751 if (ret >= 2 && month <= 0) {
756 if (ret >= 1 && year <= 0)
759 else if (ret >= 1 && len < 16)
760 /* YMD is 10 chars. XMD + HM will be 16 chars. if it is less,
761 * it make no sense to continue. We will stay with YMD. */
765 /* Exit if there is no expeceted value on this stage */
766 if (!(*string == 'T' || *string == '-' || *string == ' '))
769 /* if hour or minute fails, then we will use onlly ymd. */
770 hour = g_ascii_strtoull (string + 1, (gchar **) & string, 10);
771 if (hour > 24 || *string != ':')
775 minute = g_ascii_strtoull (string + 1, (gchar **) & string, 10);
780 if (*string == ':') {
781 second = g_ascii_strtoull (string + 1, (gchar **) & string, 10);
782 /* if we fail here, we still can reuse hour and minute. We
783 * will still attempt to parse any timezone information */
792 /* reuse some code from gst-plugins-base/gst-libs/gst/tag/gstxmptag.c */
793 gint gmt_offset_hour = -1, gmt_offset_min = -1, gmt_offset = -1;
794 gchar *plus_pos = NULL;
795 gchar *neg_pos = NULL;
798 GST_LOG ("Checking for timezone information");
800 /* check if there is timezone info */
801 plus_pos = strrchr (string, '+');
802 neg_pos = strrchr (string, '-');
811 ret_tz = sscanf (pos, "%d:%d", &gmt_offset_hour, &gmt_offset_min);
813 ret_tz = sscanf (pos, "%02d%02d", &gmt_offset_hour, &gmt_offset_min);
815 GST_DEBUG ("Parsing timezone: %s", pos);
818 gmt_offset = gmt_offset_hour * 60 + gmt_offset_min;
819 if (neg_pos != NULL && neg_pos + 1 == pos)
822 tzoffset = gmt_offset / 60.0;
824 GST_LOG ("Timezone offset: %f (%d minutes)", tzoffset, gmt_offset);
826 GST_WARNING ("Failed to parse timezone information");
831 return gst_date_time_new (tzoffset, year, month, day, hour, minute, second);
833 return gst_date_time_new_ymd (year, month, day);
838 gst_date_time_free (GstDateTime * datetime)
840 g_date_time_unref (datetime->datetime);
841 g_slice_free (GstDateTime, datetime);
846 * @datetime: a #GstDateTime
848 * Atomically increments the reference count of @datetime by one.
850 * Return value: (transfer full): the reference @datetime
855 gst_date_time_ref (GstDateTime * datetime)
857 g_return_val_if_fail (datetime != NULL, NULL);
858 g_return_val_if_fail (datetime->ref_count > 0, NULL);
859 g_atomic_int_inc (&datetime->ref_count);
864 * gst_date_time_unref:
865 * @datetime: (transfer full): a #GstDateTime
867 * Atomically decrements the reference count of @datetime by one. When the
868 * reference count reaches zero, the structure is freed.
873 gst_date_time_unref (GstDateTime * datetime)
875 g_return_if_fail (datetime != NULL);
876 g_return_if_fail (datetime->ref_count > 0);
878 if (g_atomic_int_dec_and_test (&datetime->ref_count))
879 gst_date_time_free (datetime);