mirror/emacs
1
0
Fork 0
mirror of https://git.savannah.gnu.org/git/emacs.git synced 2025-01-07 15:06:22 +00:00
Code Issues Releases Activity

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
This is a synonym for @samp{%x %X}.
@item %C
This has a locale-specific meaning. In the default locale (named C), it
is equivalent to @samp{%A, %B %e, %Y}.
This stands for the century, that is, the year divided by 100,
truncated toward zero.
@item %d
This stands for the day of month, zero-padded.
@item %D
@ -1530,8 +1530,11 @@ This stands for the calendar quarter (1--4).
This is a synonym for @samp{%I:%M:%S %p}.
@item %R
This is a synonym for @samp{%H:%M}.
@item %s
This stands for the integer number of seconds since the epoch.
@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
This stands for a tab character.
@item %T
@ -1561,22 +1564,31 @@ This stands for the year with century.
@item %Z
This stands for the time zone abbreviation (e.g., @samp{EST}).
@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
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
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
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.
the field width as digits in a @samp{%}-sequence, after any flags.
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
pad with spaces to 3 positions. Plain @samp{%3S} pads with zeros,
because that is how @samp{%S} normally pads to two positions.
The characters @samp{E} and @samp{O} act as modifiers when used between
@samp{%} and one of the letters in the table above. @samp{E} specifies
The characters @samp{E} and @samp{O} act as modifiers when used after
any flags and field widths in a @samp{%}-sequence. @samp{E} specifies
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
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
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}
(@pxref{Formatting Calendar Time,,, libc, The GNU C Library Reference
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.
%p is the locale's equivalent of either AM or PM.
%q is the calendar quarter (1–4).
%M is the minute.
%S is the second.
%N is the nanosecond, %6N the microsecond, %3N the millisecond, etc.
%Z is the time zone name, %z is the numeric form.
%M is the minute (00-59).
%S is the second (00-59; 00-60 on platforms with leap seconds)
%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.
%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".
%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.
The flags are `_', `-', `^' and `#'. For certain characters X,