38.7 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 (see 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 universal

This function converts time (or the current time, if time is omitted) to a string according to format-string. 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.

‘%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 week of the year (01–52), assuming that weeks start on Sunday.

‘%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.

If universal is non-nil, that means to describe the time as Universal Time; nil means describe it using what Emacs believes is the local time zone (see current-time-zone).

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 encodes its argument using the coding system specified by locale-coding-system (see Locales); after strftime returns the resulting string, format-time-string decodes the string using that same coding system.

Function: seconds-to-time seconds

This function converts seconds, the number of seconds since the epoch, to a time value and returns that. To convert back, use float-time (see Time of Day).

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 (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.

‘%%’

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 (see most-positive-fixnum).