time: improved convenience in time functions.

* time.c (time_str_local, time_str_utc): New static functions.
(time_fields_local, time_fields_utc, time_struct_local,
time_struct_utc): Time argument
becomes optional, defaulted to current time.
(time_init): Use time_s symbol instead of interning
twice. Register new time-str-local and time-str-utc
intrinsics. Fix registration of functions that take
optional args.

* txr.1: New functions documented; optional arguments
documented; existing documentation revised.

* stdlib/doc-syms.tl: Updated.

3 files changed, 80 insertions, 29 deletions

diff --git a/stdlib/doc-syms.tl b/stdlib/doc-syms.tl
index 57ccce7f..2c9c14b1 100644
--- a/stdlib/doc-syms.tl
+++ b/stdlib/doc-syms.tl
@@ -2010,6 +2010,8 @@
       ("time-parse" "D-0066")
       ("time-parse-local" "N-00207C99")
       ("time-parse-utc" "N-00207C99")
+      ("time-str-local" "N-01711783")
+      ("time-str-utc" "N-01711783")
       ("time-string" "N-007B1819")
       ("time-string-local" "N-00F192AD")
       ("time-string-utc" "N-00F192AD")
diff --git a/time.c b/time.c
index 8f4017a1..b53fa37f 100644
--- a/time.c
+++ b/time.c
@@ -151,6 +151,19 @@ val time_string_utc(val time, val format)
   return timestr;
 }
 
+static val time_str_local(val format, val time_in)
+{
+  val time = default_arg_strict(time_in, time_sec());
+  return time_string_local(time, format);
+}
+
+static val time_str_utc(val format, val time_in)
+{
+  val time = default_arg_strict(time_in, time_sec());
+  return time_string_utc(time, format);
+}
+
+
 static val broken_time_list(struct tm *tms)
 {
   return list(num(tms->tm_year + 1900),
@@ -192,10 +205,11 @@ static val broken_time_struct(struct tm *tms)
   return ts;
 }
 
-val time_fields_local(val time)
+val time_fields_local(val time_in)
 {
   val self = lit("time-fields-local");
   struct tm tms;
+  val time = default_arg_strict(time_in, time_sec());
   time_t secs = c_time(time, self);
 
   if (localtime_r(&secs, &tms) == 0)
@@ -204,10 +218,11 @@ val time_fields_local(val time)
   return broken_time_list(&tms);
 }
 
-val time_fields_utc(val time)
+val time_fields_utc(val time_in)
 {
   val self = lit("time-fields-utc");
   struct tm tms;
+  val time = default_arg_strict(time_in, time_sec());
   time_t secs = c_time(time, self);
 
   if (gmtime_r(&secs, &tms) == 0)
@@ -216,10 +231,11 @@ val time_fields_utc(val time)
   return broken_time_list(&tms);
 }
 
-val time_struct_local(val time)
+val time_struct_local(val time_in)
 {
   val self = lit("time-struct-local");
   struct tm tms;
+  val time = default_arg_strict(time_in, time_sec());
   time_t secs = c_time(time, self);
 
   if (localtime_r(&secs, &tms) == 0)
@@ -228,10 +244,11 @@ val time_struct_local(val time)
   return broken_time_struct(&tms);
 }
 
-val time_struct_utc(val time)
+val time_struct_utc(val time_in)
 {
   val self = lit("time-struct-utc");
   struct tm tms;
+  val time = default_arg_strict(time_in, time_sec());
   time_t secs = c_time(time, self);
 
   if (gmtime_r(&secs, &tms) == 0)
@@ -552,15 +569,17 @@ void time_init(void)
   static_slot_set(time_st, time_parse_s, func_n3(time_parse_meth));
 #endif
 
-  reg_fun(intern(lit("time"), user_package), func_n0(time_sec));
+  reg_fun(time_s, func_n0(time_sec));
   reg_fun(intern(lit("time-usec"), user_package), func_n0(time_sec_usec));
   reg_fun(intern(lit("time-nsec"), user_package), func_n0(time_sec_nsec));
   reg_fun(intern(lit("time-string-local"), user_package), func_n2(time_string_local));
   reg_fun(intern(lit("time-string-utc"), user_package), func_n2(time_string_utc));
-  reg_fun(intern(lit("time-fields-local"), user_package), func_n1(time_fields_local));
-  reg_fun(intern(lit("time-fields-utc"), user_package), func_n1(time_fields_utc));
-  reg_fun(intern(lit("time-struct-local"), user_package), func_n1(time_struct_local));
-  reg_fun(intern(lit("time-struct-utc"), user_package), func_n1(time_struct_utc));
+  reg_fun(intern(lit("time-str-local"), user_package), func_n2o(time_str_local, 1));
+  reg_fun(intern(lit("time-str-utc"), user_package), func_n2o(time_str_utc, 1));
+  reg_fun(intern(lit("time-fields-local"), user_package), func_n1o(time_fields_local, 0));
+  reg_fun(intern(lit("time-fields-utc"), user_package), func_n1o(time_fields_utc, 0));
+  reg_fun(intern(lit("time-struct-local"), user_package), func_n1o(time_struct_local, 0));
+  reg_fun(intern(lit("time-struct-utc"), user_package), func_n1o(time_struct_utc, 0));
   reg_fun(intern(lit("make-time"), user_package), func_n7(make_time));
 #if HAVE_TIMEGM || HAVE_SETENV
   reg_fun(intern(lit("make-time-utc"), user_package), func_n7(make_time_utc));
diff --git a/txr.1 b/txr.1
index e4044901..232c174a 100644
--- a/txr.1
+++ b/txr.1
@@ -66900,20 +66900,49 @@ field of the cons returned by the
 .code time-usec
 function.
 
+.coNP Functions @ time-str-local and @ time-str-utc
+.synb
+.mets (time-str-local < format <> [ time ])
+.mets (time-str-utc < format <> [ time ])
+.syne
+.desc
+The functions
+.code time-str-local
+and
+.code time-str-utc
+are equivalent, respectively, to
+.code time-string-local
+and
+.code time-string-utc
+with the arguments reversed. Thus the following
+equivalences hold:
+
+.verb
+  (time-str-local F T)   <-->  (time-string-local T F)
+  (time-str-utc F T)     <-->  (time-string-utc T F)
+.brev
+
+Additionally, if no argument is supplied to the
+.code time
+parameter, its value is obtained by invoking the
+.code time
+function.
+
 .coNP Functions @ time-fields-local and @ time-fields-utc
 .synb
-.mets (time-fields-local << time )
-.mets (time-fields-utc << time )
+.mets (time-fields-local <> [ time ])
+.mets (time-fields-utc <> [ time ])
 .syne
 .desc
-These functions take the numeric time returned by the time function,
-and convert it to a list of seven fields.
+These functions take numeric time in the format returned by the
+.code time
+function and convert it to a list of seven fields.
 
 The
-.code time-string-local
+.code time-fields-local
 function converts the time to the local timezone of
-the host system. The
-.code time-string-utc
+the host system, whereas the
+.code time-fields-utc
 function produces time in UTC.
 
 The fields returned as a list consist of six integers, and a Boolean value.
@@ -66926,11 +66955,11 @@ in the case of
 
 The
 .meta time
-argument is an integer representing seconds obtained from the
+parameter is an integer representing seconds obtained from the
 .code time
-function or from the
-.code time-usec
-function.
+function. If the argument is absent, the value is obtained by
+calling
+.codn time .
 
 .coNP Structure @ time
 .synb
@@ -67010,29 +67039,30 @@ structure as a source of input values.
 
 .coNP Functions @ time-struct-local and @ time-struct-utc
 .synb
-.mets (time-struct-local << time )
-.mets (time-struct-utc << time )
+.mets (time-struct-local <> [ time ])
+.mets (time-struct-utc <> [ time ])
 .syne
 .desc
-These functions take the numeric time returned by the time function,
-and convert it to an instance of the
+These functions take numeric time in the format returned by the
+.code time
+function and convert it to an instance of the
 .code time
 structure.
 
 The
 .code time-struct-local
 function converts the time to the local timezone of
-the host system. The
+the host system, whereas
 .code time-struct-utc
 function produces time in UTC.
 
 The
 .meta time
-argument is an integer representing seconds obtained from the
+parameter is an integer representing seconds obtained from the
 .code time
-function or from the
-.code time-usec
-function.
+function. If the argument is absent, the value is obtained by
+calling
+.codn time .
 
 .coNP Functions @, time-parse @ time-parse-local and @ time-parse-utc
 .synb