These functions convert time values to text in a string, and vice versa. Time values are either represented as a Lisp timestamp (see Time of Day) or a decoded time structure (see Time Conversion).
This function parses the time-string string and returns the
corresponding Lisp timestamp. The argument string should represent
a date-time, and should be in one of the forms recognized by
parse-time-string (see below). This function assumes Universal
Time if string lacks explicit time zone information,
and assumes earliest values if string lacks month, day, or time.
The operating system limits the range of time and zone values.
This function parses the time-string string into a decoded time structure (see Time Conversion). The argument string should resemble an RFC 822 (or later) or ISO 8601 string, like “Fri, 25 Mar 2016 16:24:56 +0100” or “1998-09-12T12:21:54-0200”, but this function will attempt to parse less well-formed time strings as well.
For a more strict function (that will error out upon invalid input),
this function can be used instead. It can parse all variants of
the ISO 8601 standard, so in addition to the formats mentioned above,
it also parses things like “1998W45-3” (week number) and
“1998-245” (ordinal day number). To parse durations, there’s
iso8601-parse-duration, and to parse intervals, there’s
iso8601-parse-interval. All these functions return decoded
time structures, except the final one, which returns three of them
(the start, the end, and the duration).
This function converts time (which should be a Lisp timestamp,
and defaults to the current time if time is omitted or
nil) to a string according to format-string. The
conversion uses the time zone rule zone, which defaults to the
current time zone rule. See Time Zone Rules. The argument
format-string may contain ‘%’-sequences which say to
substitute parts of the time. Here is a table of what the
‘%’-sequences mean:
This stands for the abbreviated name of the day of week.
This stands for the full name of the day of week.
This stands for the abbreviated name of the month.
This stands for the full name of the month.
This is a synonym for ‘%x %X’.
This stands for the century, that is, the year divided by 100, truncated toward zero. The default field width is 2.
This stands for the day of month, zero-padded.
This is a synonym for ‘%m/%d/%y’.
This stands for the day of month, blank-padded.
This stands for the ISO 8601 date format, which is like ‘%+4Y-%m-%d’ except that any flags or field width override the ‘+’ and (after subtracting 6) the ‘4’.
This stands for the year without century (00–99) corresponding to the current ISO week number. ISO weeks start on Monday and end on Sunday. If an ISO week begins in one year and ends in another, the rules regarding which year ‘%g’ will produce are complex and will not be described here; however, in general, if most of the week’s days are in the ending year, ‘%g’ will produce that year.
This stands for the year with century corresponding to the current ISO week number.
This is a synonym for ‘%b’.
This stands for the hour (00–23).
This stands for the hour (01–12).
This stands for the day of the year (001–366).
This stands for the hour (0–23), blank padded.
This stands for the hour (1–12), blank padded.
This stands for the month (01–12).
This stands for the minute (00–59).
This stands for a newline.
This stands for the nanoseconds (000000000–999999999). To ask for fewer digits, use ‘%3N’ for milliseconds, ‘%6N’ for microseconds, etc. Any excess digits are discarded, without rounding.
This stands for ‘AM’ or ‘PM’, as appropriate.
This stands for the calendar quarter (1–4).
This is a synonym for ‘%I:%M:%S %p’.
This is a synonym for ‘%H:%M’.
This stands for the integer number of seconds since the epoch.
This stands for the second (00–59, or 00–60 on platforms that support leap seconds).
This stands for a tab character.
This is a synonym for ‘%H:%M:%S’.
This stands for the numeric day of week (1–7). Monday is day 1.
This stands for the week of the year (01–52), assuming that weeks start on Sunday.
This stands for the week of the year according to ISO 8601.
This stands for the numeric day of week (0–6). Sunday is day 0.
This stands for the week of the year (01–52), assuming that weeks start on Monday.
This has a locale-specific meaning. In the default locale (named ‘C’), it is equivalent to ‘%D’.
This has a locale-specific meaning. In the default locale (named ‘C’), it is equivalent to ‘%T’.
This stands for the year without century (00–99).
This stands for the year with century.
This stands for the time zone abbreviation (e.g., ‘EST’).
This stands for the time zone numerical offset. The ‘z’ can be preceded by one, two, or three colons; if plain ‘%z’ stands for ‘-0500’, then ‘%:z’ stands for ‘-05:00’, ‘%::z’ stands for ‘-05:00:00’, and ‘%:::z’ is like ‘%::z’ except it suppresses trailing instances of ‘:00’ so it stands for ‘-05’ in the same example.
This stands for a single ‘%’.
One or more flag characters can appear immediately after the ‘%’. ‘0’ pads with zeros, ‘+’ pads with zeros and also puts ‘+’ before nonnegative year numbers with more than four digits, ‘_’ pads with blanks, ‘-’ suppresses padding, ‘^’ upper-cases letters, and ‘#’ reverses the case of letters.
You can also specify the field width and type of padding for any of
these ‘%’-sequences. This works as in printf: you write
the field width as digits in a ‘%’-sequence, after any flags.
For example, ‘%S’ specifies the number of seconds since the minute;
‘%03S’ means to pad this with zeros to 3 positions, ‘%_3S’ to
pad with spaces to 3 positions. Plain ‘%3S’ pads with zeros,
because that is how ‘%S’ normally pads to two positions.
The characters ‘E’ and ‘O’ act as modifiers when used after
any flags and field widths in a ‘%’-sequence. ‘E’ specifies
using the current locale’s alternative version of the date and time.
In a Japanese locale, for example, %Ex might yield a date format
based on the Japanese Emperors’ reigns. ‘E’ is allowed in
‘%Ec’, ‘%EC’, ‘%Ex’, ‘%EX’, ‘%Ey’, and
‘%EY’.
‘O’ means to use the current locale’s alternative representation of numbers, instead of the ordinary decimal digits. This is allowed with most letters, all the ones that output numbers.
To help debug programs, unrecognized ‘%’-sequences stand for themselves and are output as-is. Programs should not rely on this behavior, as future versions of Emacs may recognize new ‘%’-sequences as extensions.
This function uses the C library function strftime
(see Formatting Calendar Time in The GNU C Library Reference
Manual) to do most of the work. In order to communicate with that
function, it first converts time and zone to internal form;
the operating system limits the range of time and zone values.
This function also encodes format-string using the coding system
specified by locale-coding-system (see Locales); after
strftime returns the resulting string,
this function decodes the string using that same coding
system.
This function converts its argument seconds into a string of years, days, hours, etc., according to format-string. The argument format-string may contain ‘%’-sequences which control the conversion. Here is a table of what the ‘%’-sequences mean:
The integer number of 365-day years.
The integer number of days.
The integer number of hours.
The integer number of minutes.
The number of seconds. If the optional ‘,’ parameter is used, it’s a floating point number, and the number after the ‘,’ specifies how many decimals to be used. ‘%,2s’ means “use two decimals”.
Non-printing control flag. When it is used, other specifiers must be
given in the order of decreasing size, i.e., years before days, hours
before minutes, etc. Nothing will be produced in the result string to
the left of ‘%z’ until the first non-zero conversion is
encountered. For example, the default format used by
emacs-uptime (see emacs-uptime)
"%Y, %D, %H, %M, %z%S" means that the number of seconds
will always be produced, but years, days, hours, and minutes will only
be shown if they are non-zero.
Non-printing control flag that works along the same lines as ‘%z’, but instead suppresses printing of trailing zero-value time elements.
Produces a literal ‘%’.
Upper-case format sequences produce the units in addition to the numbers, lower-case formats produce only the numbers.
You can also specify the field width by following the ‘%’ with a
number; shorter numbers will be padded with blanks. An optional
period before the width requests zero-padding instead. For example,
"%.3Y" might produce "004 years".