DateTime.format

Creates a newly allocated string representing the requested @format.

The format strings understood by this function are a subset of the strftime() format language as specified by C99. The \%D, \%U and \%W conversions are not supported, nor is the 'E' modifier. The GNU extensions \%k, \%l, \%s and \%P are supported, however, as are the '0', '_' and '-' modifiers.

In contrast to strftime(), this function always produces a UTF-8 string, regardless of the current locale. Note that the rendering of many formats is locale-dependent and may not match the strftime() output exactly.

The following format specifiers are supported:

- \%a: the abbreviated weekday name according to the current locale - \%A: the full weekday name according to the current locale - \%b: the abbreviated month name according to the current locale - \%B: the full month name according to the current locale - \%c: the preferred date and time representation for the current locale - \%C: the century number (year/100) as a 2-digit integer (00-99) - \%d: the day of the month as a decimal number (range 01 to 31) - \%e: the day of the month as a decimal number (range 1 to 31) - \%F: equivalent to %Y-%m-%d (the ISO 8601 date format) - \%g: the last two digits of the ISO 8601 week-based year as a decimal number (00-99). This works well with \%V and \%u. - \%G: the ISO 8601 week-based year as a decimal number. This works well with \%V and \%u. - \%h: equivalent to \%b - \%H: the hour as a decimal number using a 24-hour clock (range 00 to 23) - \%I: the hour as a decimal number using a 12-hour clock (range 01 to 12) - \%j: the day of the year as a decimal number (range 001 to 366) - \%k: the hour (24-hour clock) as a decimal number (range 0 to 23); single digits are preceded by a blank - \%l: the hour (12-hour clock) as a decimal number (range 1 to 12); single digits are preceded by a blank - \%m: the month as a decimal number (range 01 to 12) - \%M: the minute as a decimal number (range 00 to 59) - \%p: either "AM" or "PM" according to the given time value, or the corresponding strings for the current locale. Noon is treated as "PM" and midnight as "AM". - \%P: like \%p but lowercase: "am" or "pm" or a corresponding string for the current locale - \%r: the time in a.m. or p.m. notation - \%R: the time in 24-hour notation (\%H:\%M) - \%s: the number of seconds since the Epoch, that is, since 1970-01-01 00:00:00 UTC - \%S: the second as a decimal number (range 00 to 60) - \%t: a tab character - \%T: the time in 24-hour notation with seconds (\%H:\%M:\%S) - \%u: the ISO 8601 standard day of the week as a decimal, range 1 to 7, Monday being 1. This works well with \%G and \%V. - \%V: the ISO 8601 standard week number of the current year as a decimal number, range 01 to 53, where week 1 is the first week that has at least 4 days in the new year. See g_date_time_get_week_of_year(). This works well with \%G and \%u. - \%w: the day of the week as a decimal, range 0 to 6, Sunday being 0. This is not the ISO 8601 standard format -- use \%u instead. - \%x: the preferred date representation for the current locale without the time - \%X: the preferred time representation for the current locale without the date - \%y: the year as a decimal number without the century - \%Y: the year as a decimal number including the century - \%z: the time zone as an offset from UTC (+hhmm) - \%:z: the time zone as an offset from UTC (+hh:mm). This is a gnulib strftime() extension. Since: 2.38 - \%::z: the time zone as an offset from UTC (+hh:mm:ss). This is a gnulib strftime() extension. Since: 2.38 - \%:::z: the time zone as an offset from UTC, with : to necessary precision (e.g., -04, +05:30). This is a gnulib strftime() extension. Since: 2.38 - \%Z: the time zone or name or abbreviation - \%\%: a literal \% character

Some conversion specifications can be modified by preceding the conversion specifier by one or more modifier characters. The following modifiers are supported for many of the numeric conversions:

- O: Use alternative numeric symbols, if the current locale supports those. - _: Pad a numeric result with spaces. This overrides the default padding for the specifier. - -: Do not pad a numeric result. This overrides the default padding for the specifier. - 0: Pad a numeric result with zeros. This overrides the default padding for the specifier.

Additionally, when O is used with B, b, or h, it produces the alternative form of a month name. The alternative form should be used when the month name is used without a day number (e.g., standalone). It is required in some languages (Baltic, Slavic, Greek, and more) due to their grammatical rules. For other languages there is no difference. \%OB is a GNU and BSD strftime() extension expected to be added to the future POSIX specification, \%Ob and \%Oh are GNU strftime() extensions. Since: 2.56