Improve documentation of functions that accept time values
* doc/lispref/os.texi (Time Calculations): Mention the meaning of 'nil' or a scalar number as the time-value argument. Add a cross-reference to 'float-time' for computing a time difference as a scalar number of seconds. * src/editfns.c (Fformat_time_string, Ftime_less_p) (Ftime_subtract, Ftime_add, Fdecode_time, Fcurrent_time_string) (Fcurrent_time_zone): Mention in the doc strings the meaning of nil argument and the fact that a time value can be a scalar number of seconds since the epoch. (Ftime_subtract): Mention 'float-time'.
This commit is contained in:
Eli Zaretskii
parent
a37c08d524
commit
36bafc9cee
2 changed files with 35 additions and 16 deletions
|
|
@ -1472,7 +1472,7 @@ corresponding time value.
|
|||
@defun format-time-string format-string &optional time zone
|
||||
|
||||
This function converts @var{time} (or the current time, if
|
||||
@var{time} is omitted) to a string according to
|
||||
@var{time} is omitted or @code{nil}) to a string according to
|
||||
@var{format-string}. The conversion uses the time zone rule @var{zone}, which
|
||||
defaults to the current time zone rule. @xref{Time Zone Rules}. The argument
|
||||
@var{format-string} may contain @samp{%}-sequences which say to
|
||||
|
|
@ -1690,7 +1690,9 @@ interactively, it prints the duration in the echo area.
|
|||
@cindex calendrical computations
|
||||
|
||||
These functions perform calendrical computations using time values
|
||||
(@pxref{Time of Day}).
|
||||
(@pxref{Time of Day}). A value of @code{nil} for any of their
|
||||
time-value arguments stands for the current system time, and a single
|
||||
integer number stands for the number of seconds since the epoch.
|
||||
|
||||
@defun time-less-p t1 t2
|
||||
This returns @code{t} if time value @var{t1} is less than time value
|
||||
|
|
@ -1699,12 +1701,15 @@ This returns @code{t} if time value @var{t1} is less than time value
|
|||
|
||||
@defun time-subtract t1 t2
|
||||
This returns the time difference @var{t1} @minus{} @var{t2} between
|
||||
two time values, as a time value.
|
||||
two time values, as a time value. If you need the difference in units
|
||||
of elapsed seconds, use @code{float-time} (@pxref{Time of Day,
|
||||
float-time}) to convert the result into seconds.
|
||||
@end defun
|
||||
|
||||
@defun time-add t1 t2
|
||||
This returns the sum of two time values, as a time value.
|
||||
One argument should represent a time difference rather than a point in time.
|
||||
One argument should represent a time difference rather than a point in time,
|
||||
either as a list or as a single number of elapsed seconds.
|
||||
Here is how to add a number of seconds to a time value:
|
||||
|
||||
@example
|
||||
|
|
|
|||
|
|
@ -1581,21 +1581,28 @@ time_arith (Lisp_Object a, Lisp_Object b,
|
|||
}
|
||||
|
||||
DEFUN ("time-add", Ftime_add, Stime_add, 2, 2, 0,
|
||||
doc: /* Return the sum of two time values A and B, as a time value. */)
|
||||
doc: /* Return the sum of two time values A and B, as a time value.
|
||||
A nil value for either argument stands for the current time.
|
||||
See `current-time-string' for the various forms of a time value. */)
|
||||
(Lisp_Object a, Lisp_Object b)
|
||||
{
|
||||
return time_arith (a, b, time_add);
|
||||
}
|
||||
|
||||
DEFUN ("time-subtract", Ftime_subtract, Stime_subtract, 2, 2, 0,
|
||||
doc: /* Return the difference between two time values A and B, as a time value. */)
|
||||
doc: /* Return the difference between two time values A and B, as a time value.
|
||||
Use `float-time' to convert the difference into elapsed seconds.
|
||||
A nil value for either argument stands for the current time.
|
||||
See `current-time-string' for the various forms of a time value. */)
|
||||
(Lisp_Object a, Lisp_Object b)
|
||||
{
|
||||
return time_arith (a, b, time_subtract);
|
||||
}
|
||||
|
||||
DEFUN ("time-less-p", Ftime_less_p, Stime_less_p, 2, 2, 0,
|
||||
doc: /* Return non-nil if time value T1 is earlier than time value T2. */)
|
||||
doc: /* Return non-nil if time value T1 is earlier than time value T2.
|
||||
A nil value for either argument stands for the current time.
|
||||
See `current-time-string' for the various forms of a time value. */)
|
||||
(Lisp_Object t1, Lisp_Object t2)
|
||||
{
|
||||
int t1len, t2len;
|
||||
|
|
@ -1973,11 +1980,13 @@ emacs_nmemftime (char *s, size_t maxsize, const char *format,
|
|||
}
|
||||
|
||||
DEFUN ("format-time-string", Fformat_time_string, Sformat_time_string, 1, 3, 0,
|
||||
doc: /* Use FORMAT-STRING to format the time TIME, or now if omitted.
|
||||
doc: /* Use FORMAT-STRING to format the time TIME, or now if omitted or nil.
|
||||
TIME is specified as (HIGH LOW USEC PSEC), as returned by
|
||||
`current-time' or `file-attributes'. The obsolete form (HIGH . LOW)
|
||||
is also still accepted. The optional ZONE is omitted or nil for Emacs
|
||||
local time, t for Universal Time, `wall' for system wall clock time,
|
||||
`current-time' or `file-attributes'.
|
||||
It can also be a single integer number of seconds since the epoch.
|
||||
The obsolete form (HIGH . LOW) is also still accepted.
|
||||
The optional ZONE is omitted or nil for Emacs local time,
|
||||
t for Universal Time, `wall' for system wall clock time,
|
||||
or a string as in the TZ environment variable.
|
||||
|
||||
The value is a copy of FORMAT-STRING, but with certain constructs replaced
|
||||
|
|
@ -2094,7 +2103,9 @@ DEFUN ("decode-time", Fdecode_time, Sdecode_time, 0, 2, 0,
|
|||
doc: /* Decode a time value as (SEC MINUTE HOUR DAY MONTH YEAR DOW DST UTCOFF).
|
||||
The optional SPECIFIED-TIME should be a list of (HIGH LOW . IGNORED),
|
||||
as from `current-time' and `file-attributes', or nil to use the
|
||||
current time. The obsolete form (HIGH . LOW) is also still accepted.
|
||||
current time.
|
||||
It can also be a single integer number of seconds since the epoch.
|
||||
The obsolete form (HIGH . LOW) is also still accepted.
|
||||
The optional ZONE is omitted or nil for Emacs local time, t for
|
||||
Universal Time, `wall' for system wall clock time, or a string as in
|
||||
the TZ environment variable.
|
||||
|
|
@ -2219,8 +2230,10 @@ which provide a much more powerful and general facility.
|
|||
If SPECIFIED-TIME is given, it is a time to format instead of the
|
||||
current time. The argument should have the form (HIGH LOW . IGNORED).
|
||||
Thus, you can use times obtained from `current-time' and from
|
||||
`file-attributes'. SPECIFIED-TIME can also have the form (HIGH . LOW),
|
||||
but this is considered obsolete.
|
||||
`file-attributes'. SPECIFIED-TIME can also be a single integer
|
||||
number of seconds since the epoch.
|
||||
SPECIFIED-TIME can also have the form (HIGH . LOW), but this is
|
||||
considered obsolete.
|
||||
|
||||
The optional ZONE is omitted or nil for Emacs local time, t for
|
||||
Universal Time, `wall' for system wall clock time, or a string as in
|
||||
|
|
@ -2298,8 +2311,9 @@ NAME is a string giving the name of the time zone.
|
|||
If SPECIFIED-TIME is given, the time zone offset is determined from it
|
||||
instead of using the current time. The argument should have the form
|
||||
\(HIGH LOW . IGNORED). Thus, you can use times obtained from
|
||||
`current-time' and from `file-attributes'. SPECIFIED-TIME can also
|
||||
have the form (HIGH . LOW), but this is considered obsolete.
|
||||
`current-time' and from `file-attributes'. SPECIFIED-TIME can also be
|
||||
a single integer number of seconds since the epoch. SPECIFIED-TIME can
|
||||
also have the form (HIGH . LOW), but this is considered obsolete.
|
||||
Optional second arg ZONE is omitted or nil for the local time zone, or
|
||||
a string as in the TZ environment variable.
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue