## GstDateTime

GstDateTime — A date, time and timezone structure

## Functions

#define | GST_TYPE_DATE_TIME
gint | gst_date_time_get_day ()
gint | gst_date_time_get_month ()
gint | gst_date_time_get_hour ()
gint | gst_date_time_get_microsecond ()
gint | gst_date_time_get_minute ()
gfloat | gst_date_time_get_time_zone_offset ()
gint | gst_date_time_get_second ()
gint | gst_date_time_get_year ()
GstDateTime * | gst_date_time_new ()
GstDateTime * | gst_date_time_new_ymd ()
GstDateTime * | gst_date_time_new_ym ()
GstDateTime * | gst_date_time_new_y ()
GstDateTime * | gst_date_time_new_from_unix_epoch_local_time ()
GstDateTime * | gst_date_time_new_from_unix_epoch_utc ()
GstDateTime * | gst_date_time_new_local_time ()
GstDateTime * | gst_date_time_new_now_local_time ()
GstDateTime * | gst_date_time_new_now_utc ()
GstDateTime * | gst_date_time_ref ()
void | gst_date_time_unref ()
gboolean | gst_date_time_has_day ()
gboolean | gst_date_time_has_month ()
gboolean | gst_date_time_has_second ()
gboolean | gst_date_time_has_time ()
gboolean | gst_date_time_has_year ()
GstDateTime * | gst_date_time_new_from_iso8601_string ()
gchar * | gst_date_time_to_iso8601_string ()
GstDateTime * | gst_date_time_new_from_g_date_time ()
GDateTime * | gst_date_time_to_g_date_time ()

## Types and Values

| GstDateTime

## Object Hierarchy

        GBoxed
        ╰── GstDateTime

## 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_TYPE_DATE_TIME

    #define GST_TYPE_DATE_TIME (_gst_date_time_type)

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

#### Returns

the GType of GstDateTime

### 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 representing 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][nullable]

### 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()`.

[nullable]

### 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][nullable]

### 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][nullable]

## 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 accessor functions to get the stored values.