From: Paul Eggert <eggert@cs.ucla.edu>
Date: Mon, 25 Feb 2019 19:33:51 +0000 (-0800)
Subject: format-time-string: document new '+' flag
X-Git-Tag: emacs-27.0.90~3541
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=e3bb6f90e999a6d71537806573c48b9ceb3fb413;p=emacs.git

format-time-string: document new '+' flag

* doc/lispref/os.texi (Time Parsing), etc/NEWS:
* src/timefns.c (Fformat_time_string): Document the new
behavior, added for compatibility with POSIX.1-2017.
---

diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi
index cb8f25df0a3..59cd5a8fe8a 100644
--- a/doc/lispref/os.texi
+++ b/doc/lispref/os.texi
@@ -1600,7 +1600,9 @@ This is a synonym for @samp{%m/%d/%y}.
 @item %e
 This stands for the day of month, blank-padded.
 @item %F
-This stands for the ISO 8601 date format, i.e., @samp{"%Y-%m-%d"}.
+This stands for the ISO 8601 date format, which is like
+@samp{%+4Y-%m-%d} except that any flags or field width override the
+@samp{+} and (after subtracting 6) the @samp{4}.
 @item %g
 This stands for the year corresponding to the ISO week within the century.
 @item %G
@@ -1680,7 +1682,9 @@ 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{-}
+@samp{0} pads with zeros, @samp{+} pads with zeros and also puts
+@samp{+} before nonnegative year numbers with more than four digits,
+@samp{_} pads with blanks, @samp{-}
 suppresses padding, @samp{^} upper-cases letters, and @samp{#}
 reverses the case of letters.
 
diff --git a/etc/NEWS b/etc/NEWS
index 8acbf6d3a7f..587d20cce35 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1343,6 +1343,12 @@ floating-point operators do.
 +++
 ** New function 'time-equal-p' compares time values for equality.
 
++++
+** 'format-time-string' supports a new conversion specifier flag '+'
+that acts like the '0' flag but also puts a '+' before nonnegative
+years containing more than four digits.  This is for compatibility
+with POSIX.1-2017.
+
 ** 'define-minor-mode' automatically documents the meaning of ARG.
 
 +++
diff --git a/src/timefns.c b/src/timefns.c
index 7e061228e2c..5beeaf57a25 100644
--- a/src/timefns.c
+++ b/src/timefns.c
@@ -1267,7 +1267,7 @@ by text that describes the specified date and time in TIME:
 %c is the locale's date and time format.
 %x is the locale's "preferred" date format.
 %D is like "%m/%d/%y".
-%F is the ISO 8601 date format (like "%Y-%m-%d").
+%F is the ISO 8601 date format (like "%+4Y-%m-%d").
 
 %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.
@@ -1275,17 +1275,23 @@ by text that describes the specified date and time in TIME:
 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,
-%_X is like %X, but padded with blanks; %-X is like %X,
-but without padding.  %^X is like %X, but with all textual
-characters up-cased; %#X is like %X, but with letter-case of
-all textual characters reversed.
-%NX (where N stands for an integer) is like %X,
-but takes up at least N (a number) positions.
-The modifiers are `E' and `O'.  For certain characters X,
-%EX is a locale's alternative version of %X;
-%OX is like %X, but uses the locale's number symbols.
+A %-sequence can contain optional flags, field width, and a modifier
+(in that order) after the `%'.  The flags are:
+
+`-' Do not pad the field.
+`_' Pad with spaces.
+`0' Pad with zeros.
+`+' Pad with zeros and put `+' before nonnegative year numbers with >4 digits.
+`^' Use upper case characters if possible.
+`#' Use opposite case characters if possible.
+
+A field width N is an unsigned decimal integer with a leading digit nonzero.
+%NX is like %X, but takes up at least N positions.
+
+The modifiers are:
+
+`E' Use the locale's alternative version.
+`O' Use the locale's number symbols.
 
 For example, to produce full ISO 8601 format, use "%FT%T%z".