From: Tim-Philipp Müller Date: Tue, 12 Jun 2012 22:52:02 +0000 (+0100) Subject: datetime: clean-ups and new API adjustments X-Git-Tag: RELEASE-0.11.93~342 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=5b37641cbcdec1ad744404800fca87fa8a7d60e9;p=platform%2Fupstream%2Fgstreamer.git datetime: clean-ups and new API adjustments Remove constructors we don't want: gst_date_time_new_ymd_h() because we don't want to support hour-only for now; gst_date_time_new_ymd_hm() because we don't want to add constructors with time info where the caller doesn't have to think about what timezone the time is in. Lots of compulsive clean-up. Docs fixes. Replace has_minute() and has_hour() with has_time(). --- diff --git a/gst/gstdatetime.c b/gst/gstdatetime.c index a8a6c3407e..2045a11b72 100644 --- a/gst/gstdatetime.c +++ b/gst/gstdatetime.c @@ -42,29 +42,21 @@ * 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; + GST_DATE_TIME_FIELDS_INVALID = 0, + GST_DATE_TIME_FIELDS_Y, /* have year */ + GST_DATE_TIME_FIELDS_YM, /* have year and month */ + GST_DATE_TIME_FIELDS_YMD, /* have year, month and day */ + GST_DATE_TIME_FIELDS_YMD_HM, + GST_DATE_TIME_FIELDS_YMD_HMS +} GstDateTimeFields; struct _GstDateTime { GDateTime *datetime; - DateTimeFields fields; + GstDateTimeFields fields; volatile gint ref_count; }; @@ -78,6 +70,7 @@ gst_date_time_new_from_gdatetime (GDateTime * dt) gst_dt = g_slice_new (GstDateTime); gst_dt->datetime = dt; + gst_dt->fields = GST_DATE_TIME_FIELDS_YMD_HMS; gst_dt->ref_count = 1; return gst_dt; } @@ -86,84 +79,72 @@ gst_date_time_new_from_gdatetime (GDateTime * dt) * gst_date_time_has_year: * @datetime: a #GstDateTime * - * Returns the TRUE if year exist - * - * Since: + * Returns: TRUE if @datetime's year field is set (which should always + * be the case), otherwise FALSE */ gboolean gst_date_time_has_year (const GstDateTime * datetime) { - return (datetime->fields >= HAS_Y) ? 1 : 0; + g_return_val_if_fail (datetime != NULL, FALSE); + + return (datetime->fields >= GST_DATE_TIME_FIELDS_Y); } /** * gst_date_time_has_month: * @datetime: a #GstDateTime * - * Returns the TRUE if month exist - * - * Since: + * Returns: TRUE if @datetime's month field is set, otherwise FALSE */ gboolean gst_date_time_has_month (const GstDateTime * datetime) { - return (datetime->fields >= HAS_YM) ? 1 : 0; + g_return_val_if_fail (datetime != NULL, FALSE); + + return (datetime->fields >= GST_DATE_TIME_FIELDS_YM); } /** * gst_date_time_has_day: * @datetime: a #GstDateTime * - * Returns the TRUE if day exist - * - * Since: + * Returns: TRUE if @datetime's day field is set, otherwise FALSE */ gboolean gst_date_time_has_day (const GstDateTime * datetime) { - return (datetime->fields >= HAS_YMD) ? 1 : 0; -} + g_return_val_if_fail (datetime != NULL, FALSE); -/** - * 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; + return (datetime->fields >= GST_DATE_TIME_FIELDS_YMD); } /** - * gst_date_time_has_minute: + * gst_date_time_has_time: * @datetime: a #GstDateTime * - * Returns the TRUE if minute exist - * - * Since: + * Returns: TRUE if @datetime's hour and minute fields are set, + * otherwise FALSE */ gboolean -gst_date_time_has_minute (const GstDateTime * datetime) +gst_date_time_has_time (const GstDateTime * datetime) { - return (datetime->fields >= HAS_YMD_HM) ? 1 : 0; + g_return_val_if_fail (datetime != NULL, FALSE); + + return (datetime->fields >= GST_DATE_TIME_FIELDS_YMD_HM); } /** * gst_date_time_has_second: * @datetime: a #GstDateTime * - * Returns the TRUE if second exist - * - * Since: + * Returns: TRUE if @datetime's second field is set, otherwise FALSE */ gboolean gst_date_time_has_second (const GstDateTime * datetime) { - return (datetime->fields >= HAS_YMD_HMS) ? 1 : 0; + g_return_val_if_fail (datetime != NULL, FALSE); + + return (datetime->fields >= GST_DATE_TIME_FIELDS_YMD_HMS); } /** @@ -179,7 +160,8 @@ gst_date_time_has_second (const GstDateTime * datetime) gint gst_date_time_get_year (const GstDateTime * datetime) { - g_return_val_if_fail (gst_date_time_has_year (datetime), 0); + g_return_val_if_fail (datetime != NULL, 0); + return g_date_time_get_year (datetime->datetime); } @@ -196,7 +178,9 @@ gst_date_time_get_year (const GstDateTime * datetime) gint gst_date_time_get_month (const GstDateTime * datetime) { + g_return_val_if_fail (datetime != NULL, 0); g_return_val_if_fail (gst_date_time_has_month (datetime), 0); + return g_date_time_get_month (datetime->datetime); } @@ -213,7 +197,9 @@ gst_date_time_get_month (const GstDateTime * datetime) gint gst_date_time_get_day (const GstDateTime * datetime) { + g_return_val_if_fail (datetime != NULL, 0); g_return_val_if_fail (gst_date_time_has_day (datetime), 0); + return g_date_time_get_day_of_month (datetime->datetime); } @@ -232,7 +218,9 @@ gst_date_time_get_day (const GstDateTime * datetime) gint gst_date_time_get_hour (const GstDateTime * datetime) { - g_return_val_if_fail (gst_date_time_has_hour (datetime), 0); + g_return_val_if_fail (datetime != NULL, 0); + g_return_val_if_fail (gst_date_time_has_time (datetime), 0); + return g_date_time_get_hour (datetime->datetime); } @@ -251,7 +239,9 @@ gst_date_time_get_hour (const GstDateTime * datetime) gint gst_date_time_get_minute (const GstDateTime * datetime) { - g_return_val_if_fail (gst_date_time_has_minute (datetime), 0); + g_return_val_if_fail (datetime != NULL, 0); + g_return_val_if_fail (gst_date_time_has_time (datetime), 0); + return g_date_time_get_minute (datetime->datetime); } @@ -270,7 +260,9 @@ gst_date_time_get_minute (const GstDateTime * datetime) gint gst_date_time_get_second (const GstDateTime * datetime) { + g_return_val_if_fail (datetime != NULL, 0); g_return_val_if_fail (gst_date_time_has_second (datetime), 0); + return g_date_time_get_second (datetime->datetime); } @@ -288,6 +280,9 @@ gst_date_time_get_second (const GstDateTime * datetime) gint gst_date_time_get_microsecond (const GstDateTime * datetime) { + g_return_val_if_fail (datetime != NULL, 0); + g_return_val_if_fail (gst_date_time_has_second (datetime), 0); + return g_date_time_get_microsecond (datetime->datetime); } @@ -306,6 +301,9 @@ gst_date_time_get_microsecond (const GstDateTime * datetime) gfloat gst_date_time_get_time_zone_offset (const GstDateTime * datetime) { + g_return_val_if_fail (datetime != NULL, 0.0); + g_return_val_if_fail (gst_date_time_has_time (datetime), 0.0); + return (g_date_time_get_utc_offset (datetime->datetime) / G_USEC_PER_SEC) / 3600.0; } @@ -328,10 +326,7 @@ gst_date_time_get_time_zone_offset (const GstDateTime * datetime) 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; + return gst_date_time_new (0.0, year, -1, -1, -1, -1, -1); } /** @@ -356,10 +351,7 @@ gst_date_time_new_y (gint year) 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; + return gst_date_time_new (0.0, year, month, -1, -1, -1, -1); } /** @@ -388,78 +380,7 @@ gst_date_time_new_ym (gint year, gint month) 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; + return gst_date_time_new (0.0, year, month, day, -1, -1, -1); } /** @@ -481,7 +402,6 @@ 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; } @@ -504,41 +424,39 @@ 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 +static GstDateTimeFields 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; + *month = *day = 1; + *hour = *minute = *seconds = 0; + return GST_DATE_TIME_FIELDS_Y; } else if (*day == -1) { - *day = *hour = *minute = *seconds = 1; - return HAS_YM; + *day = 1; + *hour = *minute = *seconds = 0; + return GST_DATE_TIME_FIELDS_YM; } else if (*hour == -1) { - *hour = *minute = *seconds = 1; - return HAS_YMD; - } else if (*minute == -1) { - *minute = *seconds = 1; - return HAS_YMD_H; + *hour = *minute = *seconds = 0; + return GST_DATE_TIME_FIELDS_YMD; } else if (*seconds == -1) { - *seconds = 1; - return HAS_YMD_HM; + *seconds = 0; + return GST_DATE_TIME_FIELDS_YMD_HM; } else - return HAS_YMD_HMS; + return GST_DATE_TIME_FIELDS_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 + * @month: the gregorian month, or -1 + * @day: the day of the gregorian month, or -1 + * @hour: the hour of the day, or -1 + * @minute: the minute of the hour, or -1 + * @seconds: the second of the minute, or -1 * * Creates a new #GstDateTime using the date and times in the gregorian calendar * in the local timezone. @@ -546,10 +464,15 @@ gst_date_time_check_fields (gint * year, gint * month, gint * day, * @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. + * If @month is -1, then the #GstDateTime created will only contain @year, + * and all other fields will be considered not set. + * + * If @day is -1, then the #GstDateTime created will only contain @year and + * @month and all other fields will be considered not set. + * + * If @hour is -1, then the #GstDateTime created will only contain @year and + * @month and @day, and the time fields will be considered not set. In this + * case @minute and @seconds should also be -1. * * Free-function: gst_date_time_unref * @@ -561,8 +484,8 @@ GstDateTime * gst_date_time_new_local_time (gint year, gint month, gint day, gint hour, gint minute, gdouble seconds) { + GstDateTimeFields fields; 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); @@ -596,11 +519,7 @@ gst_date_time_new_local_time (gint year, gint month, gint day, gint hour, 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; + return gst_date_time_new_from_gdatetime (g_date_time_new_now_local ()); } /** @@ -619,11 +538,7 @@ gst_date_time_new_now_local_time (void) 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; + return gst_date_time_new_from_gdatetime (g_date_time_new_now_utc ()); } gint @@ -669,12 +584,12 @@ GstDateTime * gst_date_time_new (gfloat tzoffset, gint year, gint month, gint day, gint hour, gint minute, gdouble seconds) { + GstDateTimeFields fields; 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); @@ -683,6 +598,8 @@ gst_date_time_new (gfloat tzoffset, gint year, gint month, gint day, gint hour, 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); + g_return_val_if_fail ((hour >= 0 && minute >= 0) || + (hour == -1 && minute == -1 && seconds == -1 && tzoffset == 0.0), NULL); tzhour = (gint) ABS (tzoffset); tzminute = (gint) ((ABS (tzoffset) - tzhour) * 60); diff --git a/gst/gstdatetime.h b/gst/gstdatetime.h index d613571b85..04c8299bcd 100644 --- a/gst/gstdatetime.h +++ b/gst/gstdatetime.h @@ -36,47 +36,63 @@ G_BEGIN_DECLS */ typedef struct _GstDateTime GstDateTime; -gboolean gst_date_time_has_year (const GstDateTime * datetime); -gboolean gst_date_time_has_month (const GstDateTime * datetime); -gboolean gst_date_time_has_day (const GstDateTime * datetime); -gboolean gst_date_time_has_hour (const GstDateTime * datetime); -gboolean gst_date_time_has_minute (const GstDateTime * datetime); -gboolean gst_date_time_has_second (const GstDateTime * datetime); - -gint gst_date_time_get_year (const GstDateTime * datetime); -gint gst_date_time_get_month (const GstDateTime * datetime); -gint gst_date_time_get_day (const GstDateTime * datetime); -gint gst_date_time_get_hour (const GstDateTime * datetime); -gint gst_date_time_get_minute (const GstDateTime * datetime); -gint gst_date_time_get_second (const GstDateTime * datetime); -gint gst_date_time_get_microsecond (const GstDateTime * datetime); -gfloat gst_date_time_get_time_zone_offset (const GstDateTime * datetime); +/* query which fields are set */ + +gboolean gst_date_time_has_year (const GstDateTime * datetime); +gboolean gst_date_time_has_month (const GstDateTime * datetime); +gboolean gst_date_time_has_day (const GstDateTime * datetime); +gboolean gst_date_time_has_time (const GstDateTime * datetime); +gboolean gst_date_time_has_second (const GstDateTime * datetime); + +/* field getters */ + +gint gst_date_time_get_year (const GstDateTime * datetime); +gint gst_date_time_get_month (const GstDateTime * datetime); +gint gst_date_time_get_day (const GstDateTime * datetime); +gint gst_date_time_get_hour (const GstDateTime * datetime); +gint gst_date_time_get_minute (const GstDateTime * datetime); +gint gst_date_time_get_second (const GstDateTime * datetime); +gint gst_date_time_get_microsecond (const GstDateTime * datetime); +gfloat gst_date_time_get_time_zone_offset (const GstDateTime * datetime); + +/* constructors */ GstDateTime * gst_date_time_new_from_unix_epoch_local_time (gint64 secs) G_GNUC_MALLOC; + GstDateTime * gst_date_time_new_from_unix_epoch_utc (gint64 secs) G_GNUC_MALLOC; -GstDateTime * gst_date_time_new_local_time (gint year, gint month, - gint day, gint hour, + +GstDateTime * gst_date_time_new_local_time (gint year, + gint month, + gint day, + gint hour, gint minute, gdouble seconds) G_GNUC_MALLOC; + GstDateTime * gst_date_time_new_y (gint year) G_GNUC_MALLOC; -GstDateTime * gst_date_time_new_ym (gint year, gint month) G_GNUC_MALLOC; -GstDateTime * gst_date_time_new_ymd (gint year, gint month, + +GstDateTime * gst_date_time_new_ym (gint year, + gint month) G_GNUC_MALLOC; + +GstDateTime * gst_date_time_new_ymd (gint year, + gint month, gint day) G_GNUC_MALLOC; -GstDateTime * gst_date_time_new_ymd_h (gint year, gint month, - gint day, gint hour) G_GNUC_MALLOC; -GstDateTime * gst_date_time_new_ymd_hm (gint year, gint month, - gint day, gint hour, - gint minute) G_GNUC_MALLOC; + GstDateTime * gst_date_time_new (gfloat tzoffset, gint year, gint month, gint day, gint hour, gint minute, gdouble seconds) G_GNUC_MALLOC; + GstDateTime * gst_date_time_new_now_local_time (void) G_GNUC_MALLOC; + GstDateTime * gst_date_time_new_now_utc (void) G_GNUC_MALLOC; +/* refcounting */ + GstDateTime * gst_date_time_ref (GstDateTime * datetime); + void gst_date_time_unref (GstDateTime * datetime); G_END_DECLS + #endif /* __GST_DATE_TIME_H__ */