since: 2.56


g_date_time_new_from_iso8601 (
  const gchar* text,
  GTimeZone* default_tz


Creates a GDateTime corresponding to the given ISO 8601 formatted string text. ISO 8601 strings of the form

Note that as GDateTime is oblivious to leap seconds”, leap seconds information in an ISO-8601 string will be ignored, so a 23:59:60 time would be parsed as 23:59:59.

is the separator and can be either ‘T’, ‘t’ or ‘ ‘. The latter two separators are an extension from RFC 3339.

is in the form:

  • YYYY-MM-DD - Year/month/day, e.g. 2016-08-24.
  • YYYYMMDD - Same as above without dividers.
  • YYYY-DDD - Ordinal day where DDD is from 001 to 366, e.g. 2016-237.
  • YYYYDDD - Same as above without dividers.
  • YYYY-Www-D - Week day where ww is from 01 to 52 and D from 1-7, e.g. 2016-W34-3.
  • YYYYWwwD - Same as above without dividers.

  • hh:mm:ss(.sss) - Hours, minutes, seconds (subseconds), e.g. 22:10:42.123.
  • hhmmss(.sss) - Same as above without dividers.

is an optional timezone suffix of the form:

  • Z - UTC.
  • +hh:mm or -hh:mm - Offset from UTC in hours and minutes, e.g. +12:00.
  • +hh or -hh - Offset from UTC in hours, e.g. +12.

If the timezone is not provided in text it must be provided in default_tz (this field is otherwise ignored).

This call can fail (returning NULL) if text is not a valid ISO 8601 formatted string.

You should release the return value by calling g_date_time_unref() when you are done with it.

Available since: 2.56



Type: const gchar*

An ISO 8601 formatted time string.

The data is owned by the caller of the function.
The value is a NUL terminated UTF-8 string.

Type: GTimeZone

A GTimeZone to use if the text doesn’t contain a timezone, or NULL.

The argument can be NULL.
The data is owned by the caller of the function.

Return value

Type: GDateTime

A new GDateTime, or NULL.

The caller of the function takes ownership of the data, and is responsible for freeing it.
The return value can be NULL.