elisp: Time Parsing
38.8 Parsing and Formatting Times
=================================
These functions convert time values to text in a string, and vice versa.
Time values are lists of two to four integers (
Time of Day).
-- Function: date-to-time string
This function parses the time-string STRING and returns the
corresponding time value.
-- Function: format-time-string format-string &optional time zone
This function converts TIME (or 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. 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:
‘%a’
This stands for the abbreviated name of the day of week.
‘%A’
This stands for the full name of the day of week.
‘%b’
This stands for the abbreviated name of the month.
‘%B’
This stands for the full name of the month.
‘%c’
This is a synonym for ‘%x %X’.
‘%C’
This has a locale-specific meaning. In the default locale
(named C), it is equivalent to ‘%A, %B %e, %Y’.
‘%d’
This stands for the day of month, zero-padded.
‘%D’
This is a synonym for ‘%m/%d/%y’.
‘%e’
This stands for the day of month, blank-padded.
‘%F’
This stands for the ISO 8601 date format, i.e., ‘"%Y-%m-%d"’.
‘%g’
This stands for the year corresponding to the ISO week within
the century.
‘%G’
This stands for the year corresponding to the ISO week.
‘%h’
This is a synonym for ‘%b’.
‘%H’
This stands for the hour (00–23).
‘%I’
This stands for the hour (01–12).
‘%j’
This stands for the day of the year (001–366).
‘%k’
This stands for the hour (0–23), blank padded.
‘%l’
This stands for the hour (1–12), blank padded.
‘%m’
This stands for the month (01–12).
‘%M’
This stands for the minute (00–59).
‘%n’
This stands for a newline.
‘%N’
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.
‘%p’
This stands for ‘AM’ or ‘PM’, as appropriate.
‘%r’
This is a synonym for ‘%I:%M:%S %p’.
‘%R’
This is a synonym for ‘%H:%M’.
‘%S’
This stands for the seconds (00–59).
‘%t’
This stands for a tab character.
‘%T’
This is a synonym for ‘%H:%M:%S’.
‘%u’
This stands for the numeric day of week (1–7). Monday is day
1.
‘%U’
This stands for the week of the year (01–52), assuming that
weeks start on Sunday.
‘%V’
This stands for the week of the year according to ISO 8601.
‘%w’
This stands for the numeric day of week (0–6). Sunday is day
0.
‘%W’
This stands for the week of the year (01–52), assuming that
weeks start on Monday.
‘%x’
This has a locale-specific meaning. In the default locale
(named ‘C’), it is equivalent to ‘%D’.
‘%X’
This has a locale-specific meaning. In the default locale
(named ‘C’), it is equivalent to ‘%T’.
‘%y’
This stands for the year without century (00–99).
‘%Y’
This stands for the year with century.
‘%Z’
This stands for the time zone abbreviation (e.g., ‘EST’).
‘%z’
This stands for the time zone numerical offset (e.g.,
‘-0500’).
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 the middle of a ‘%’-sequences. If you
start the field width with ‘0’, it means to pad with zeros. If you
start the field width with ‘_’, it means to pad with spaces.
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 between ‘%’
and one of the letters in the table above. ‘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.
This function uses the C library function ‘strftime’ (
(libc)Formatting Calendar Time) to do most of the work. In order
to communicate with that function, it first encodes its argument
using the coding system specified by ‘locale-coding-system’ (
Locales); after ‘strftime’ returns the resulting string,
‘format-time-string’ decodes the string using that same coding
system.
-- Function: format-seconds format-string seconds
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:
‘%y’
‘%Y’
The integer number of 365-day years.
‘%d’
‘%D’
The integer number of days.
‘%h’
‘%H’
The integer number of hours.
‘%m’
‘%M’
The integer number of minutes.
‘%s’
‘%S’
The integer number of seconds.
‘%z’
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’ (emacs-uptime
Processor Run Time.) ‘"%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.
‘%%’
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"’.
_Warning:_ This function works only with values of SECONDS that
don’t exceed ‘most-positive-fixnum’ (most-positive-fixnum
Integer Basics.).
Info Catalog
elisp: Time Conversion
elisp: System Interface
elisp: Processor Run Time