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"
33 * @short_description: A date, time and timezone structure
35 * Struct to store date, time and timezone information altogether.
36 * #GstDateTime is refcounted and immutable.
38 * Date information is handled using the proleptic Gregorian calendar.
40 * Provides basic creation functions and accessor functions to its fields.
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
59 GstDateTimeFields fields;
60 volatile gint ref_count;
64 gst_date_time_new_from_gdatetime (GDateTime * dt)
71 gst_dt = g_slice_new (GstDateTime);
72 gst_dt->datetime = dt;
73 gst_dt->fields = GST_DATE_TIME_FIELDS_YMD_HMS;
74 gst_dt->ref_count = 1;
79 * gst_date_time_has_year:
80 * @datetime: a #GstDateTime
82 * Returns: TRUE if @datetime<!-- -->'s year field is set (which should always
83 * be the case), otherwise FALSE
86 gst_date_time_has_year (const GstDateTime * datetime)
88 g_return_val_if_fail (datetime != NULL, FALSE);
90 return (datetime->fields >= GST_DATE_TIME_FIELDS_Y);
94 * gst_date_time_has_month:
95 * @datetime: a #GstDateTime
97 * Returns: TRUE if @datetime<!-- -->'s month field is set, otherwise FALSE
100 gst_date_time_has_month (const GstDateTime * datetime)
102 g_return_val_if_fail (datetime != NULL, FALSE);
104 return (datetime->fields >= GST_DATE_TIME_FIELDS_YM);
108 * gst_date_time_has_day:
109 * @datetime: a #GstDateTime
111 * Returns: TRUE if @datetime<!-- -->'s day field is set, otherwise FALSE
114 gst_date_time_has_day (const GstDateTime * datetime)
116 g_return_val_if_fail (datetime != NULL, FALSE);
118 return (datetime->fields >= GST_DATE_TIME_FIELDS_YMD);
122 * gst_date_time_has_time:
123 * @datetime: a #GstDateTime
125 * Returns: TRUE if @datetime<!-- -->'s hour and minute fields are set,
129 gst_date_time_has_time (const GstDateTime * datetime)
131 g_return_val_if_fail (datetime != NULL, FALSE);
133 return (datetime->fields >= GST_DATE_TIME_FIELDS_YMD_HM);
137 * gst_date_time_has_second:
138 * @datetime: a #GstDateTime
140 * Returns: TRUE if @datetime<!-- -->'s second field is set, otherwise FALSE
143 gst_date_time_has_second (const GstDateTime * datetime)
145 g_return_val_if_fail (datetime != NULL, FALSE);
147 return (datetime->fields >= GST_DATE_TIME_FIELDS_YMD_HMS);
151 * gst_date_time_get_year:
152 * @datetime: a #GstDateTime
154 * Returns the year of this #GstDateTime
155 * Call gst_date_time_has_year before, to avoid warnings.
157 * Return value: The year of this #GstDateTime
161 gst_date_time_get_year (const GstDateTime * datetime)
163 g_return_val_if_fail (datetime != NULL, 0);
165 return g_date_time_get_year (datetime->datetime);
169 * gst_date_time_get_month:
170 * @datetime: a #GstDateTime
172 * Returns the month of this #GstDateTime. January is 1, February is 2, etc..
173 * Call gst_date_time_has_month before, to avoid warnings.
175 * Return value: The month of this #GstDateTime
179 gst_date_time_get_month (const GstDateTime * datetime)
181 g_return_val_if_fail (datetime != NULL, 0);
182 g_return_val_if_fail (gst_date_time_has_month (datetime), 0);
184 return g_date_time_get_month (datetime->datetime);
188 * gst_date_time_get_day:
189 * @datetime: a #GstDateTime
191 * Returns the day of this #GstDateTime.
192 * Call gst_date_time_has_day before, to avoid warnings.
194 * Return value: The day of this #GstDateTime
198 gst_date_time_get_day (const GstDateTime * datetime)
200 g_return_val_if_fail (datetime != NULL, 0);
201 g_return_val_if_fail (gst_date_time_has_day (datetime), 0);
203 return g_date_time_get_day_of_month (datetime->datetime);
207 * gst_date_time_get_hour:
208 * @datetime: a #GstDateTime
210 * Retrieves the hour of the day represented by @datetime in the gregorian
211 * calendar. The return is in the range of 0 to 23.
212 * Call gst_date_time_has_haur before, to avoid warnings.
214 * Return value: the hour of the day
219 gst_date_time_get_hour (const GstDateTime * datetime)
221 g_return_val_if_fail (datetime != NULL, 0);
222 g_return_val_if_fail (gst_date_time_has_time (datetime), 0);
224 return g_date_time_get_hour (datetime->datetime);
228 * gst_date_time_get_minute:
229 * @datetime: a #GstDateTime
231 * Retrieves the minute of the hour represented by @datetime in the gregorian
233 * Call gst_date_time_has_minute before, to avoid warnings.
235 * Return value: the minute of the hour
240 gst_date_time_get_minute (const GstDateTime * datetime)
242 g_return_val_if_fail (datetime != NULL, 0);
243 g_return_val_if_fail (gst_date_time_has_time (datetime), 0);
245 return g_date_time_get_minute (datetime->datetime);
249 * gst_date_time_get_second:
250 * @datetime: a #GstDateTime
252 * Retrieves the second of the minute represented by @datetime in the gregorian
254 * Call gst_date_time_has_second before, to avoid warnings.
256 * Return value: the second represented by @datetime
261 gst_date_time_get_second (const GstDateTime * datetime)
263 g_return_val_if_fail (datetime != NULL, 0);
264 g_return_val_if_fail (gst_date_time_has_second (datetime), 0);
266 return g_date_time_get_second (datetime->datetime);
270 * gst_date_time_get_microsecond:
271 * @datetime: a #GstDateTime
273 * Retrieves the fractional part of the seconds in microseconds represented by
274 * @datetime in the gregorian calendar.
276 * Return value: the microsecond of the second
281 gst_date_time_get_microsecond (const GstDateTime * datetime)
283 g_return_val_if_fail (datetime != NULL, 0);
284 g_return_val_if_fail (gst_date_time_has_second (datetime), 0);
286 return g_date_time_get_microsecond (datetime->datetime);
290 * gst_date_time_get_time_zone_offset:
291 * @datetime: a #GstDateTime
293 * Retrieves the offset from UTC in hours that the timezone specified
294 * by @datetime represents. Timezones ahead (to the east) of UTC have positive
295 * values, timezones before (to the west) of UTC have negative values.
296 * If @datetime represents UTC time, then the offset is zero.
298 * Return value: the offset from UTC in hours
302 gst_date_time_get_time_zone_offset (const GstDateTime * datetime)
304 g_return_val_if_fail (datetime != NULL, 0.0);
305 g_return_val_if_fail (gst_date_time_has_time (datetime), 0.0);
307 return (g_date_time_get_utc_offset (datetime->datetime) /
308 G_USEC_PER_SEC) / 3600.0;
312 * gst_date_time_new_y:
313 * @year: the gregorian year
315 * Creates a new #GstDateTime using the date and times in the gregorian calendar
316 * in the local timezone.
318 * @year should be from 1 to 9999.
320 * Free-function: gst_date_time_unref
322 * Return value: (transfer full): the newly created #GstDateTime
327 gst_date_time_new_y (gint year)
329 return gst_date_time_new (0.0, year, -1, -1, -1, -1, -1);
333 * gst_date_time_new_ym:
334 * @year: the gregorian year
335 * @month: the gregorian month
337 * Creates a new #GstDateTime using the date and times in the gregorian calendar
338 * in the local timezone.
340 * @year should be from 1 to 9999, @month should be from 1 to 12.
342 * If value is -1 then all over value will be ignored. For example
343 * if @month == -1, then #GstDateTime will created only for @year.
345 * Free-function: gst_date_time_unref
347 * Return value: (transfer full): the newly created #GstDateTime
352 gst_date_time_new_ym (gint year, gint month)
354 return gst_date_time_new (0.0, year, month, -1, -1, -1, -1);
358 * gst_date_time_new_ymd:
359 * @year: the gregorian year
360 * @month: the gregorian month
361 * @day: the day of the gregorian month
363 * Creates a new #GstDateTime using the date and times in the gregorian calendar
364 * in the local timezone.
366 * @year should be from 1 to 9999, @month should be from 1 to 12, @day from
369 * If value is -1 then all over value will be ignored. For example
370 * if @month == -1, then #GstDateTime will created only for @year. If
371 * @day == -1, then #GstDateTime will created for @year and @month and
374 * Free-function: gst_date_time_unref
376 * Return value: (transfer full): the newly created #GstDateTime
381 gst_date_time_new_ymd (gint year, gint month, gint day)
383 return gst_date_time_new (0.0, year, month, day, -1, -1, -1);
387 * gst_date_time_new_from_unix_epoch_local_time:
388 * @secs: seconds from the Unix epoch
390 * Creates a new #GstDateTime using the time since Jan 1, 1970 specified by
391 * @secs. The #GstDateTime is in the local timezone.
393 * Free-function: gst_date_time_unref
395 * Return value: (transfer full): the newly created #GstDateTime
400 gst_date_time_new_from_unix_epoch_local_time (gint64 secs)
402 GstDateTime *datetime;
404 gst_date_time_new_from_gdatetime (g_date_time_new_from_unix_local (secs));
409 * gst_date_time_new_from_unix_epoch_utc:
410 * @secs: seconds from the Unix epoch
412 * Creates a new #GstDateTime using the time since Jan 1, 1970 specified by
413 * @secs. The #GstDateTime is in the UTC timezone.
415 * Free-function: gst_date_time_unref
417 * Return value: (transfer full): the newly created #GstDateTime
422 gst_date_time_new_from_unix_epoch_utc (gint64 secs)
424 GstDateTime *datetime;
426 gst_date_time_new_from_gdatetime (g_date_time_new_from_unix_utc (secs));
430 static GstDateTimeFields
431 gst_date_time_check_fields (gint * year, gint * month, gint * day,
432 gint * hour, gint * minute, gdouble * seconds)
436 *hour = *minute = *seconds = 0;
437 return GST_DATE_TIME_FIELDS_Y;
438 } else if (*day == -1) {
440 *hour = *minute = *seconds = 0;
441 return GST_DATE_TIME_FIELDS_YM;
442 } else if (*hour == -1) {
443 *hour = *minute = *seconds = 0;
444 return GST_DATE_TIME_FIELDS_YMD;
445 } else if (*seconds == -1) {
447 return GST_DATE_TIME_FIELDS_YMD_HM;
449 return GST_DATE_TIME_FIELDS_YMD_HMS;
453 * gst_date_time_new_local_time:
454 * @year: the gregorian year
455 * @month: the gregorian month, or -1
456 * @day: the day of the gregorian month, or -1
457 * @hour: the hour of the day, or -1
458 * @minute: the minute of the hour, or -1
459 * @seconds: the second of the minute, or -1
461 * Creates a new #GstDateTime using the date and times in the gregorian calendar
462 * in the local timezone.
464 * @year should be from 1 to 9999, @month should be from 1 to 12, @day from
465 * 1 to 31, @hour from 0 to 23, @minutes and @seconds from 0 to 59.
467 * If @month is -1, then the #GstDateTime created will only contain @year,
468 * and all other fields will be considered not set.
470 * If @day is -1, then the #GstDateTime created will only contain @year and
471 * @month and all other fields will be considered not set.
473 * If @hour is -1, then the #GstDateTime created will only contain @year and
474 * @month and @day, and the time fields will be considered not set. In this
475 * case @minute and @seconds should also be -1.
477 * Free-function: gst_date_time_unref
479 * Return value: (transfer full): the newly created #GstDateTime
484 gst_date_time_new_local_time (gint year, gint month, gint day, gint hour,
485 gint minute, gdouble seconds)
487 GstDateTimeFields fields;
488 GstDateTime *datetime;
490 g_return_val_if_fail (year > 0 && year <= 9999, NULL);
491 g_return_val_if_fail ((month > 0 && month <= 12) || month == -1, NULL);
492 g_return_val_if_fail ((day > 0 && day <= 31) || day == -1, NULL);
493 g_return_val_if_fail ((hour >= 0 && hour < 24) || hour == -1, NULL);
494 g_return_val_if_fail ((minute >= 0 && minute < 60) || minute == -1, NULL);
495 g_return_val_if_fail ((seconds >= 0 && seconds < 60) || seconds == -1, NULL);
497 fields = gst_date_time_check_fields (&year, &month, &day,
498 &hour, &minute, &seconds);
500 datetime = gst_date_time_new_from_gdatetime (g_date_time_new_local (year,
501 month, day, hour, minute, seconds));
503 datetime->fields = fields;
508 * gst_date_time_new_now_local_time:
510 * Creates a new #GstDateTime representing the current date and time.
512 * Free-function: gst_date_time_unref
514 * Return value: (transfer full): the newly created #GstDateTime which should
515 * be freed with gst_date_time_unref().
520 gst_date_time_new_now_local_time (void)
522 return gst_date_time_new_from_gdatetime (g_date_time_new_now_local ());
526 * gst_date_time_new_now_utc:
528 * Creates a new #GstDateTime that represents the current instant at Universal
531 * Free-function: gst_date_time_unref
533 * Return value: (transfer full): the newly created #GstDateTime which should
534 * be freed with gst_date_time_unref().
539 gst_date_time_new_now_utc (void)
541 return gst_date_time_new_from_gdatetime (g_date_time_new_now_utc ());
545 priv_gst_date_time_compare (gconstpointer dt1, gconstpointer dt2)
547 const GstDateTime *datetime1 = dt1;
548 const GstDateTime *datetime2 = dt2;
549 return g_date_time_compare (datetime1->datetime, datetime2->datetime);
554 * @tzoffset: Offset from UTC in hours.
555 * @year: the gregorian year
556 * @month: the gregorian month
557 * @day: the day of the gregorian month
558 * @hour: the hour of the day
559 * @minute: the minute of the hour
560 * @seconds: the second of the minute
562 * Creates a new #GstDateTime using the date and times in the gregorian calendar
563 * in the supplied timezone.
565 * @year should be from 1 to 9999, @month should be from 1 to 12, @day from
566 * 1 to 31, @hour from 0 to 23, @minutes and @seconds from 0 to 59.
568 * Note that @tzoffset is a float and was chosen so for being able to handle
569 * some fractional timezones, while it still keeps the readability of
570 * represeting it in hours for most timezones.
572 * If value is -1 then all over value will be ignored. For example
573 * if @month == -1, then #GstDateTime will created only for @year. If
574 * @day == -1, then #GstDateTime will created for @year and @month and
577 * Free-function: gst_date_time_unref
579 * Return value: (transfer full): the newly created #GstDateTime
584 gst_date_time_new (gfloat tzoffset, gint year, gint month, gint day, gint hour,
585 gint minute, gdouble seconds)
587 GstDateTimeFields fields;
591 GstDateTime *datetime;
592 gint tzhour, tzminute;
594 g_return_val_if_fail (year > 0 && year <= 9999, NULL);
595 g_return_val_if_fail ((month > 0 && month <= 12) || month == -1, NULL);
596 g_return_val_if_fail ((day > 0 && day <= 31) || day == -1, NULL);
597 g_return_val_if_fail ((hour >= 0 && hour < 24) || hour == -1, NULL);
598 g_return_val_if_fail ((minute >= 0 && minute < 60) || minute == -1, NULL);
599 g_return_val_if_fail ((seconds >= 0 && seconds < 60) || seconds == -1, NULL);
600 g_return_val_if_fail (tzoffset >= -12.0 && tzoffset <= 12.0, NULL);
601 g_return_val_if_fail ((hour >= 0 && minute >= 0) ||
602 (hour == -1 && minute == -1 && seconds == -1 && tzoffset == 0.0), NULL);
604 tzhour = (gint) ABS (tzoffset);
605 tzminute = (gint) ((ABS (tzoffset) - tzhour) * 60);
607 g_snprintf (buf, 6, "%c%02d%02d", tzoffset >= 0 ? '+' : '-', tzhour,
610 tz = g_time_zone_new (buf);
612 fields = gst_date_time_check_fields (&year, &month, &day,
613 &hour, &minute, &seconds);
615 dt = g_date_time_new (tz, year, month, day, hour, minute, seconds);
616 g_time_zone_unref (tz);
618 datetime = gst_date_time_new_from_gdatetime (dt);
619 datetime->fields = fields;
625 gst_date_time_free (GstDateTime * datetime)
627 g_date_time_unref (datetime->datetime);
628 g_slice_free (GstDateTime, datetime);
633 * @datetime: a #GstDateTime
635 * Atomically increments the reference count of @datetime by one.
637 * Return value: (transfer full): the reference @datetime
642 gst_date_time_ref (GstDateTime * datetime)
644 g_return_val_if_fail (datetime != NULL, NULL);
645 g_return_val_if_fail (datetime->ref_count > 0, NULL);
646 g_atomic_int_inc (&datetime->ref_count);
651 * gst_date_time_unref:
652 * @datetime: (transfer full): a #GstDateTime
654 * Atomically decrements the reference count of @datetime by one. When the
655 * reference count reaches zero, the structure is freed.
660 gst_date_time_unref (GstDateTime * datetime)
662 g_return_if_fail (datetime != NULL);
663 g_return_if_fail (datetime->ref_count > 0);
665 if (g_atomic_int_dec_and_test (&datetime->ref_count))
666 gst_date_time_free (datetime);