GstDateTime

GstDateTime — A date, time and timezone structure

Functions

Types and Values

Object Hierarchy


Includes

#include <gst/gst.h>

Description

Struct to store date, time and timezone information altogether. GstDateTime is refcounted and immutable.

Date information is handled using the proleptic Gregorian calendar.

Provides basic creation functions and accessor functions to its fields.

Functions

gst_date_time_get_day ()

gint
gst_date_time_get_day (const GstDateTime *datetime);

Returns the day of the month of this GstDateTime. Call gst_date_time_has_day before, to avoid warnings.

Parameters

datetime

a GstDateTime

 

Returns

The day of this GstDateTime


gst_date_time_get_month ()

gint
gst_date_time_get_month (const GstDateTime *datetime);

Returns the month of this GstDateTime. January is 1, February is 2, etc.. Call gst_date_time_has_month before, to avoid warnings.

Parameters

datetime

a GstDateTime

 

Returns

The month of this GstDateTime


gst_date_time_get_hour ()

gint
gst_date_time_get_hour (const GstDateTime *datetime);

Retrieves the hour of the day represented by datetime in the gregorian calendar. The return is in the range of 0 to 23. Call gst_date_time_has_haur before, to avoid warnings.

Parameters

datetime

a GstDateTime

 

Returns

the hour of the day


gst_date_time_get_microsecond ()

gint
gst_date_time_get_microsecond (const GstDateTime *datetime);

Retrieves the fractional part of the seconds in microseconds represented by datetime in the gregorian calendar.

Parameters

datetime

a GstDateTime

 

Returns

the microsecond of the second


gst_date_time_get_minute ()

gint
gst_date_time_get_minute (const GstDateTime *datetime);

Retrieves the minute of the hour represented by datetime in the gregorian calendar. Call gst_date_time_has_minute before, to avoid warnings.

Parameters

datetime

a GstDateTime

 

Returns

the minute of the hour


gst_date_time_get_time_zone_offset ()

gfloat
gst_date_time_get_time_zone_offset (const GstDateTime *datetime);

Retrieves the offset from UTC in hours that the timezone specified by datetime represents. Timezones ahead (to the east) of UTC have positive values, timezones before (to the west) of UTC have negative values. If datetime represents UTC time, then the offset is zero.

Parameters

datetime

a GstDateTime

 

Returns

the offset from UTC in hours


gst_date_time_get_second ()

gint
gst_date_time_get_second (const GstDateTime *datetime);

Retrieves the second of the minute represented by datetime in the gregorian calendar. Call gst_date_time_has_second before, to avoid warnings.

Parameters

datetime

a GstDateTime

 

Returns

the second represented by datetime


gst_date_time_get_year ()

gint
gst_date_time_get_year (const GstDateTime *datetime);

Returns the year of this GstDateTime Call gst_date_time_has_year before, to avoid warnings.

Parameters

datetime

a GstDateTime

 

Returns

The year of this GstDateTime


gst_date_time_new ()

GstDateTime *
gst_date_time_new (gfloat tzoffset,
                   gint year,
                   gint month,
                   gint day,
                   gint hour,
                   gint minute,
                   gdouble seconds);

Creates a new GstDateTime using the date and times in the gregorian calendar in the supplied 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 and seconds from 0 to 59.

Note that tzoffset is a float and was chosen so for being able to handle some fractional timezones, while it still keeps the readability of represeting it in hours for most timezones.

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

Parameters

tzoffset

Offset from UTC in hours.

 

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

 

Returns

the newly created GstDateTime.

[transfer full]


gst_date_time_new_ymd ()

GstDateTime *
gst_date_time_new_ymd (gint year,
                       gint month,
                       gint 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.

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

Parameters

year

the gregorian year

 

month

the gregorian month

 

day

the day of the gregorian month

 

Returns

the newly created GstDateTime.

[transfer full]


gst_date_time_new_ym ()

GstDateTime *
gst_date_time_new_ym (gint year,
                      gint month);

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.

If value is -1 then all over value will be ignored. For example if month == -1, then GstDateTime will created only for year .

Free-function: gst_date_time_unref

Parameters

year

the gregorian year

 

month

the gregorian month

 

Returns

the newly created GstDateTime.

[transfer full]


gst_date_time_new_y ()

GstDateTime *
gst_date_time_new_y (gint year);

Creates a new GstDateTime using the date and times in the gregorian calendar in the local timezone.

year should be from 1 to 9999.

Free-function: gst_date_time_unref

Parameters

year

the gregorian year

 

Returns

the newly created GstDateTime.

[transfer full]


gst_date_time_new_from_unix_epoch_local_time ()

GstDateTime *
gst_date_time_new_from_unix_epoch_local_time
                               (gint64 secs);

Creates a new GstDateTime using the time since Jan 1, 1970 specified by secs . The GstDateTime is in the local timezone.

Free-function: gst_date_time_unref

Parameters

secs

seconds from the Unix epoch

 

Returns

the newly created GstDateTime.

[transfer full]


gst_date_time_new_from_unix_epoch_utc ()

GstDateTime *
gst_date_time_new_from_unix_epoch_utc (gint64 secs);

Creates a new GstDateTime using the time since Jan 1, 1970 specified by secs . The GstDateTime is in the UTC timezone.

Free-function: gst_date_time_unref

Parameters

secs

seconds from the Unix epoch

 

Returns

the newly created GstDateTime.

[transfer full]


gst_date_time_new_local_time ()

GstDateTime *
gst_date_time_new_local_time (gint year,
                              gint month,
                              gint day,
                              gint hour,
                              gint minute,
                              gdouble seconds);

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 and seconds from 0 to 59.

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

Parameters

year

the gregorian year

 

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

 

Returns

the newly created GstDateTime.

[transfer full]


gst_date_time_new_now_local_time ()

GstDateTime *
gst_date_time_new_now_local_time (void);

Creates a new GstDateTime representing the current date and time.

Free-function: gst_date_time_unref

Returns

the newly created GstDateTime which should be freed with gst_date_time_unref().

[transfer full]


gst_date_time_new_now_utc ()

GstDateTime *
gst_date_time_new_now_utc (void);

Creates a new GstDateTime that represents the current instant at Universal coordinated time.

Free-function: gst_date_time_unref

Returns

the newly created GstDateTime which should be freed with gst_date_time_unref().

[transfer full]


gst_date_time_ref ()

GstDateTime *
gst_date_time_ref (GstDateTime *datetime);

Atomically increments the reference count of datetime by one.

Parameters

datetime

a GstDateTime

 

Returns

the reference datetime .

[transfer full]


gst_date_time_unref ()

void
gst_date_time_unref (GstDateTime *datetime);

Atomically decrements the reference count of datetime by one. When the reference count reaches zero, the structure is freed.

Parameters

datetime

a GstDateTime.

[transfer full]

gst_date_time_has_day ()

gboolean
gst_date_time_has_day (const GstDateTime *datetime);

Parameters

datetime

a GstDateTime

 

Returns

TRUE if datetime 's day field is set, otherwise FALSE


gst_date_time_has_month ()

gboolean
gst_date_time_has_month (const GstDateTime *datetime);

Parameters

datetime

a GstDateTime

 

Returns

TRUE if datetime 's month field is set, otherwise FALSE


gst_date_time_has_second ()

gboolean
gst_date_time_has_second (const GstDateTime *datetime);

Parameters

datetime

a GstDateTime

 

Returns

TRUE if datetime 's second field is set, otherwise FALSE


gst_date_time_has_time ()

gboolean
gst_date_time_has_time (const GstDateTime *datetime);

Parameters

datetime

a GstDateTime

 

Returns

TRUE if datetime 's hour and minute fields are set, otherwise FALSE


gst_date_time_has_year ()

gboolean
gst_date_time_has_year (const GstDateTime *datetime);

Parameters

datetime

a GstDateTime

 

Returns

TRUE if datetime 's year field is set (which should always be the case), otherwise FALSE


gst_date_time_new_from_iso8601_string ()

GstDateTime *
gst_date_time_new_from_iso8601_string (const gchar *string);

Tries to parse common variants of ISO-8601 datetime strings into a GstDateTime.

Free-function: gst_date_time_unref

Parameters

string

ISO 8601-formatted datetime string.

 

Returns

a newly created GstDateTime, or NULL on error.

[transfer full]


gst_date_time_to_iso8601_string ()

gchar *
gst_date_time_to_iso8601_string (GstDateTime *datetime);

Create a minimal string compatible with ISO-8601. Possible output formats are (for example): 2012, 2012-06, 2012-06-23, 2012-06-23T23:30Z, 2012-06-23T23:30+0100, 2012-06-23T23:30:59Z, 2012-06-23T23:30:59+0100

Parameters

datetime

GstDateTime.

 

Returns

a newly allocated string formatted according to ISO 8601 and only including the datetime fields that are valid, or NULL in case there was an error. The string should be freed with g_free().


gst_date_time_new_from_g_date_time ()

GstDateTime *
gst_date_time_new_from_g_date_time (GDateTime *dt);

Creates a new GstDateTime from a GDateTime object.

Free-function: gst_date_time_unref

Parameters

dt

the GDateTime. The new GstDateTime takes ownership.

[transfer full]

Returns

a newly created GstDateTime, or NULL on error.

[transfer full]


gst_date_time_to_g_date_time ()

GDateTime *
gst_date_time_to_g_date_time (GstDateTime *datetime);

Creates a new GDateTime from a fully defined GstDateTime object.

Free-function: g_date_time_unref

Parameters

datetime

GstDateTime.

 

Returns

a newly created GDateTime, or NULL on error.

[transfer full]

Types and Values

GstDateTime

typedef struct _GstDateTime GstDateTime;

Opaque, immutable, refcounted struct that stores date, time and timezone information. It currently supports ranges from 0001-01-01 to 9999-12-31 in the Gregorian proleptic calendar.

Use the acessor functions to get the stored values.


GST_TYPE_DATE_TIME

#define GST_TYPE_DATE_TIME               gst_date_time_get_type ()

a boxed GValue type for GstDateTime that represents a date and time.

Returns

the GType of GstDateTime