Document `localtime` and `strflocaltime`

diff --git a/docs/content/3.manual/manual.yml b/docs/content/3.manual/manual.yml
index 74f06613aec9260289743392a56416b92089d8e7..ae2b7f914fc0053f9b080a9061f9d541f75e6764 100644 (file)
--- a/docs/content/3.manual/manual.yml
+++ b/docs/content/3.manual/manual.yml
@@ -1846,19 +1846,23 @@ sections:
           the Unix epoch.
 
           Low-level jq interfaces to the C-library time functions are
-          also provided: `strptime`, `strftime`, `mktime`, and `gmtime`.
-          Refer to your host operating system's documentation for the
-          format strings used by `strptime` and `strftime`.  Note: these
-          are not necessarily stable interfaces in jq, particularly as
-          to their localization functionality.
+          also provided: `strptime`, `strftime`, `strflocaltime`,
+          `mktime`, `gmtime`, and `localtime`.  Refer to your host
+          operating system's documentation for the format strings used
+          by `strptime` and `strftime`.  Note: these are not necessarily
+          stable interfaces in jq, particularly as to their localization
+          functionality.
 
           The `gmtime` builtin consumes a number of seconds since the
           Unix epoch and outputs a "broken down time" representation of
-          time as an array of numbers representing (in this order): the
-          year, the month (zero-based), the day of the month, the hour
-          of the day, the minute of the hour, the second of the minute,
-          the day of the week, and the day of the year -- all one-based
-          unless otherwise stated.
+          Greenwhich Meridian time as an array of numbers representing
+          (in this order): the year, the month (zero-based), the day of
+          the month, the hour of the day, the minute of the hour, the
+          second of the minute, the day of the week, and the day of the
+          year -- all one-based unless otherwise stated.
+
+          The `localtime` builtin works like the `gmtime` builtin, but
+          using the local timezone setting.
 
           The `mktime` builtin consumes "broken down time"
           representations of time output by `gmtime` and `strptime`.
@@ -1867,8 +1871,9 @@ sections:
           `fmt` argument.  The output is in the "broken down time"
           representation consumed by `gmtime` and output by `mktime`.
 
-          The `strftime(fmt)` builtin formats a time with the given
-          format.
+          The `strftime(fmt)` builtin formats a time (GMT) with the
+          given format.  The `strflocaltime` does the same, but using
+          the local timezone setting.
 
           The format strings for `strptime` and `strftime` are described
           in typical C library documentation.  The format string for ISO

diff --git a/jq.1.prebuilt b/jq.1.prebuilt
index 1503f39b633c3c5d81431c4faa18a62208f52655..e07a14287a69b3afd02b99dafb265c734ef452c7 100644 (file)
--- a/jq.1.prebuilt
+++ b/jq.1.prebuilt
@@ -2032,10 +2032,13 @@ The \fBtodate\fR builtin is an alias for \fBtodateiso8601\fR\.
 The \fBnow\fR builtin outputs the current time, in seconds since the Unix epoch\.
 .
 .P
-Low\-level jq interfaces to the C\-library time functions are also provided: \fBstrptime\fR, \fBstrftime\fR, \fBmktime\fR, and \fBgmtime\fR\. Refer to your host operating system\'s documentation for the format strings used by \fBstrptime\fR and \fBstrftime\fR\. Note: these are not necessarily stable interfaces in jq, particularly as to their localization functionality\.
+Low\-level jq interfaces to the C\-library time functions are also provided: \fBstrptime\fR, \fBstrftime\fR, \fBstrflocaltime\fR, \fBmktime\fR, \fBgmtime\fR, and \fBlocaltime\fR\. Refer to your host operating system\'s documentation for the format strings used by \fBstrptime\fR and \fBstrftime\fR\. Note: these are not necessarily stable interfaces in jq, particularly as to their localization functionality\.
 .
 .P
-The \fBgmtime\fR builtin consumes a number of seconds since the Unix epoch and outputs a "broken down time" representation of time as an array of numbers representing (in this order): the year, the month (zero\-based), the day of the month, the hour of the day, the minute of the hour, the second of the minute, the day of the week, and the day of the year \-\- all one\-based unless otherwise stated\.
+The \fBgmtime\fR builtin consumes a number of seconds since the Unix epoch and outputs a "broken down time" representation of Greenwhich Meridian time as an array of numbers representing (in this order): the year, the month (zero\-based), the day of the month, the hour of the day, the minute of the hour, the second of the minute, the day of the week, and the day of the year \-\- all one\-based unless otherwise stated\.
+.
+.P
+The \fBlocaltime\fR builtin works like the \fBgmtime\fR builtin, but using the local timezone setting\.
 .
 .P
 The \fBmktime\fR builtin consumes "broken down time" representations of time output by \fBgmtime\fR and \fBstrptime\fR\.
@@ -2044,7 +2047,7 @@ The \fBmktime\fR builtin consumes "broken down time" representations of time out
 The \fBstrptime(fmt)\fR builtin parses input strings matching the \fBfmt\fR argument\. The output is in the "broken down time" representation consumed by \fBgmtime\fR and output by \fBmktime\fR\.
 .
 .P
-The \fBstrftime(fmt)\fR builtin formats a time with the given format\.
+The \fBstrftime(fmt)\fR builtin formats a time (GMT) with the given format\. The \fBstrflocaltime\fR does the same, but using the local timezone setting\.
 .
 .P
 The format strings for \fBstrptime\fR and \fBstrftime\fR are described in typical C library documentation\. The format string for ISO 8601 datetime is \fB"%Y\-%m\-%dT%H:%M:%SZ"\fR\.