procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Improve format-time-string doc

Browse source 
* doc/lispref/os.texi (Time Parsing): Fix some errors in the
documentation for format-time-string.  Document ^, #, %s, and %z
with colons.  Say that unrecognized sequences are output as-is.
* src/editfns.c (Fformat_time_string): %S can stand for 60.
Also mention unrecognized sequences.
This commit is contained in:
Paul Eggert 2017-10-17 18:25:18 -07:00
parent 2e1b3522b8
commit 8ca6fa585a
2 changed files with 33 additions and 15 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

37
doc/lispref/os.texi
View file

@ -1486,8 +1486,8 @@ This stands for the full name of the month.
@item %c @item %c
This is a synonym for @samp{%x %X}. This is a synonym for @samp{%x %X}.
@item %C @item %C
This has a locale-specific meaning. In the default locale (named C), it This stands for the century, that is, the year divided by 100,
is equivalent to @samp{%A, %B %e, %Y}. truncated toward zero.
@item %d @item %d
This stands for the day of month, zero-padded. This stands for the day of month, zero-padded.
@item %D @item %D
@ -1530,8 +1530,11 @@ This stands for the calendar quarter (1--4).
This is a synonym for @samp{%I:%M:%S %p}. This is a synonym for @samp{%I:%M:%S %p}.
@item %R @item %R
This is a synonym for @samp{%H:%M}. This is a synonym for @samp{%H:%M}.
@item %s
This stands for the integer number of seconds since the epoch.
@item %S @item %S
This stands for the seconds (00--59). This stands for the second (00--59, or 00--60 on platforms
that support leap seconds).
@item %t @item %t
This stands for a tab character. This stands for a tab character.
@item %T @item %T
@ -1561,22 +1564,31 @@ This stands for the year with century.
@item %Z @item %Z
This stands for the time zone abbreviation (e.g., @samp{EST}). This stands for the time zone abbreviation (e.g., @samp{EST}).
@item %z @item %z
This stands for the time zone numerical offset (e.g., @samp{-0500}). This stands for the time zone numerical offset. The @samp{z} can be
preceded by one, two, or three colons; if plain @samp{%z} stands for
@samp{-0500}, then @samp{%:z} stands for @samp{-05:00}, @samp{%::z}
stands for @samp{-05:00:00}, and @samp{%:::z} is like @samp{%::z}
except it suppresses trailing instances of @samp{:00} so it stands for
@samp{-05} in the same example.
@item %%
This stands for a single @samp{%}.
@end table @end table
One or more flag characters can appear immediately after the @samp{%}.
@samp{0} pads with zeros, @samp{_} pads with blanks, @samp{-}
suppresses padding, @samp{^} upper-cases letters, and @samp{#}
reverses the case of letters.
You can also specify the field width and type of padding for any of You can also specify the field width and type of padding for any of
these @samp{%}-sequences. This works as in @code{printf}: you write these @samp{%}-sequences. This works as in @code{printf}: you write
the field width as digits in the middle of a @samp{%}-sequences. If you the field width as digits in a @samp{%}-sequence, after any flags.
start the field width with @samp{0}, it means to pad with zeros. If you
start the field width with @samp{_}, it means to pad with spaces.
For example, @samp{%S} specifies the number of seconds since the minute; For example, @samp{%S} specifies the number of seconds since the minute;
@samp{%03S} means to pad this with zeros to 3 positions, @samp{%_3S} to @samp{%03S} means to pad this with zeros to 3 positions, @samp{%_3S} to
pad with spaces to 3 positions. Plain @samp{%3S} pads with zeros, pad with spaces to 3 positions. Plain @samp{%3S} pads with zeros,
because that is how @samp{%S} normally pads to two positions. because that is how @samp{%S} normally pads to two positions.
The characters @samp{E} and @samp{O} act as modifiers when used between The characters @samp{E} and @samp{O} act as modifiers when used after
@samp{%} and one of the letters in the table above. @samp{E} specifies any flags and field widths in a @samp{%}-sequence. @samp{E} specifies
using the current locale's alternative version of the date and time. using the current locale's alternative version of the date and time.
In a Japanese locale, for example, @code{%Ex} might yield a date format In a Japanese locale, for example, @code{%Ex} might yield a date format
based on the Japanese Emperors' reigns. @samp{E} is allowed in based on the Japanese Emperors' reigns. @samp{E} is allowed in
@ -1587,6 +1599,11 @@ based on the Japanese Emperors' reigns. @samp{E} is allowed in
representation of numbers, instead of the ordinary decimal digits. This representation of numbers, instead of the ordinary decimal digits. This
is allowed with most letters, all the ones that output numbers. is allowed with most letters, all the ones that output numbers.
To help debug programs, unrecognized @samp{%}-sequences stand for
themselves and are output as-is. Programs should not rely on this
behavior, as future versions of Emacs may recognize new
@samp{%}-sequences as extensions.
This function uses the C library function @code{strftime} This function uses the C library function @code{strftime}
(@pxref{Formatting Calendar Time,,, libc, The GNU C Library Reference (@pxref{Formatting Calendar Time,,, libc, The GNU C Library Reference
Manual}) to do most of the work. In order to communicate with that Manual}) to do most of the work. In order to communicate with that

11
src/editfns.c
View file

@ -2038,11 +2038,11 @@ by text that describes the specified date and time in TIME:
only blank-padded, %l is like %I blank-padded. only blank-padded, %l is like %I blank-padded.
%p is the locale's equivalent of either AM or PM. %p is the locale's equivalent of either AM or PM.
%q is the calendar quarter (1–4). %q is the calendar quarter (1–4).
%M is the minute. %M is the minute (00-59).
%S is the second. %S is the second (00-59; 00-60 on platforms with leap seconds)
%N is the nanosecond, %6N the microsecond, %3N the millisecond, etc.
%Z is the time zone name, %z is the numeric form.
%s is the number of seconds since 1970-01-01 00:00:00 +0000. %s is the number of seconds since 1970-01-01 00:00:00 +0000.
%N is the nanosecond, %6N the microsecond, %3N the millisecond, etc.
%Z is the time zone abbreviation, %z is the numeric form.
%c is the locale's date and time format. %c is the locale's date and time format.
%x is the locale's "preferred" date format. %x is the locale's "preferred" date format.
@ -2052,7 +2052,8 @@ by text that describes the specified date and time in TIME:
%R is like "%H:%M", %T is like "%H:%M:%S", %r is like "%I:%M:%S %p". %R is like "%H:%M", %T is like "%H:%M:%S", %r is like "%I:%M:%S %p".
%X is the locale's "preferred" time format. %X is the locale's "preferred" time format.
Finally, %n is a newline, %t is a tab, %% is a literal %. Finally, %n is a newline, %t is a tab, %% is a literal %, and
unrecognized %-sequences stand for themselves.
Certain flags and modifiers are available with some format controls. Certain flags and modifiers are available with some format controls.
The flags are `_', `-', `^' and `#'. For certain characters X, The flags are `_', `-', `^' and `#'. For certain characters X,