diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/lispref/buffers.texi | 10 | ||||
| -rw-r--r-- | doc/lispref/os.texi | 157 | ||||
| -rw-r--r-- | doc/lispref/processes.texi | 19 | ||||
| -rw-r--r-- | doc/lispref/text.texi | 5 | ||||
| -rw-r--r-- | doc/misc/emacs-mime.texi | 69 |
5 files changed, 156 insertions, 104 deletions
diff --git a/doc/lispref/buffers.texi b/doc/lispref/buffers.texi index 1acf4baedba..8789a8d56f6 100644 --- a/doc/lispref/buffers.texi +++ b/doc/lispref/buffers.texi @@ -648,10 +648,7 @@ file should not be done. @defun visited-file-modtime This function returns the current buffer's recorded last file -modification time, as a list of the form @code{(@var{high} @var{low} -@var{microsec} @var{picosec})}. (This is the same format that -@code{file-attributes} uses to return time values; @pxref{File -Attributes}.) +modification time, as a Lisp timestamp (@pxref{Time of Day}). If the buffer has no recorded last modification time, this function returns zero. This case occurs, for instance, if the buffer is not @@ -671,9 +668,8 @@ is not @code{nil}, and otherwise to the last modification time of the visited file. If @var{time} is neither @code{nil} nor an integer flag returned -by @code{visited-file-modtime}, it should have the form -@code{(@var{high} @var{low} @var{microsec} @var{picosec})}, -the format used by @code{current-time} (@pxref{Time of Day}). +by @code{visited-file-modtime}, it should be a Lisp time value +(@pxref{Time of Day}). This function is useful if the buffer was not read from the file normally, or if the file itself has been changed for some known benign diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi index 8ce5a5ed6d8..ea6915350e8 100644 --- a/doc/lispref/os.texi +++ b/doc/lispref/os.texi @@ -1233,11 +1233,44 @@ return value is @code{nil}. This section explains how to determine the current time and time zone. +@cindex Lisp timestamp +@cindex timestamp, Lisp + Many functions like @code{current-time} and @code{file-attributes} +return @dfn{Lisp timestamp} values that count seconds, and that can +represent absolute time by counting seconds since the @dfn{epoch} of +1970-01-01 00:00:00 UTC. + + Although traditionally Lisp timestamps were integer pairs, their +form has evolved and programs ordinarily should not depend on the +current default form. If your program needs a particular timestamp +form, you can use the @code{encode-time} function to convert it to the +needed form. @xref{Time Conversion}. + @cindex epoch - Most of these functions represent time as a list of four integers -@code{(@var{sec-high} @var{sec-low} @var{microsec} @var{picosec})}. -This represents the number of seconds from the @dfn{epoch} (January -1, 1970 at 00:00 UTC), using the formula: + There are currently three forms of Lisp timestamps, each of +which represents a number of seconds: + +@itemize @bullet +@item +An integer. Although this is the simplest form, it cannot represent +subsecond timestamps. + +@item +A pair of integers @code{(@var{ticks} . @var{hz})}, where @var{hz} is +positive. This represents @var{ticks}/@var{hz} seconds, which is the +same time as plain @var{ticks} if @var{hz} is 1. A common value for +@var{hz} is 1000000000, for a nanosecond-resolution +clock.@footnote{Currently @var{hz} should be at least 65536 to avoid +compatibility warnings when the timestamp is passed to standard +functions, as previous versions of Emacs would interpret such a +timestamps differently due to backward-compatibility concerns. These +warnings are intended to be removed in a future Emacs version.} + +@item +A list of four integers @code{(@var{high} @var{low} @var{micro} +@var{pico})}, where 0 @leq{} @var{low} < 65536, 0 @leq{} @var{micro} < +1000000, and 0 @leq{} @var{pico} < 1000000. +This represents the number of seconds using the formula: @ifnottex @var{high} * 2**16 + @var{low} + @var{micro} * 10**@minus{}6 + @var{pico} * 10**@minus{}12. @@ -1245,21 +1278,23 @@ This represents the number of seconds from the @dfn{epoch} (January @tex $high*2^{16} + low + micro*10^{-6} + pico*10^{-12}$. @end tex -The return value of @code{current-time} represents time using this -form, as do the timestamps in the return values of other functions -such as @code{file-attributes} (@pxref{Definition of -file-attributes}). In some cases, functions may return two- or +In some cases, functions may default to returning two- or three-element lists, with omitted @var{microsec} and @var{picosec} components defaulting to zero. +On all current machines @var{picosec} is a multiple of 1000, but this +may change as higher-resolution clocks become available. +@end itemize @cindex time value Function arguments, e.g., the @var{time} argument to @code{current-time-string}, accept a more-general @dfn{time value} -format, which can be a list of integers as above, or a single number -for seconds since the epoch, or @code{nil} for the current time. You -can convert a time value into a human-readable string using -@code{current-time-string} and @code{format-time-string}, into a list -of integers using @code{seconds-to-time}, and into other forms using +format, which can be a Lisp timestamp, @code{nil} for the current +time, a single floating-point number for seconds, or a list +@code{(@var{high} @var{low} @var{micro})} or @code{(@var{high} +@var{low})} that is a truncated list timestamp with missing elements +taken to be zero. You can convert a time value into +a human-readable string using @code{format-time-string}, into a Lisp +timestamp using @code{encode-time}, and into other forms using @code{decode-time} and @code{float-time}. These functions are described in the following sections. @@ -1287,12 +1322,7 @@ defaults to the current time zone rule. @xref{Time Zone Rules}. @end defun @defun current-time -This function returns the current time, represented as a list of four -integers @code{(@var{sec-high} @var{sec-low} @var{microsec} @var{picosec})}. -These integers have trailing zeros on systems that return time with -lower resolutions. On all current machines @var{picosec} is a -multiple of 1000, but this may change as higher-resolution clocks -become available. +This function returns the current time as a Lisp timestamp. @end defun @defun float-time &optional time @@ -1306,13 +1336,6 @@ exact. Do not use this function if precise time stamps are required. @code{time-to-seconds} is an alias for this function. @end defun -@defun seconds-to-time time -This function converts a time value to list-of-integer form. -For example, if @var{time} is a number, @code{(time-to-seconds -(seconds-to-time @var{time}))} equals the number unless overflow -or rounding errors occur. -@end defun - @node Time Zone Rules @section Time Zone Rules @cindex time zone rules @@ -1434,32 +1457,63 @@ seconds east of Greenwich. @var{dow} and @var{utcoff}. @end defun -@defun encode-time seconds minutes hour day month year &optional zone -This function is the inverse of @code{decode-time}. It converts seven -items of calendrical data into a list-of-integer time value. For the -meanings of the arguments, see the table above under -@code{decode-time}. +@defun encode-time time &optional form +This function converts @var{time} to a Lisp timestamp. +It can act as the inverse of @code{decode-time}. + +The first argument can be a Lisp time value such as @code{nil} for the +current time, a number of seconds, a pair @code{(@var{ticks} +. @var{hz})}, or a list @code{(@var{high} @var{low} @var{micro} +@var{pico})} (@pxref{Time of Day}). It can also be a list +@code{(@var{second} @var{minute} @var{hour} @var{day} @var{month} +@var{year} @var{ignored} @var{dst} @var{zone})} that specifies a +decoded time in the style of @code{decode-time}, so that +@code{(encode-time (decode-time ...))} works. For the meanings of +these list members, see the table under @code{decode-time}. + +The optional @var{form} argument specifies the desired timestamp form +to be returned. If @var{form} is the symbol @code{integer}, this +function returns an integer count of seconds. If @var{form} is a +positive integer, it specifies a clock frequency and this function +returns an integer-pair timestamp @code{(@var{ticks} +. @var{form})}.@footnote{Currently a positive integer @var{form} +should be at least 65536 if the returned value is intended to be given +to standard functions expecting Lisp timestamps.} If @var{form} is +@code{t}, this function treats it as a positive integer suitable for +representing the timestamp; for example, it is treated as 1000000000 +if the platform timestamp has nanosecond resolution. If @var{form} is +@code{list}, this function returns an integer list @code{(@var{high} +@var{low} @var{micro} @var{pico})}. Although an omitted or @code{nil} +@var{form} currently acts like @code{list}, this is planned to change +in a future Emacs version, so callers requiring list timestamps should +pass @code{list} explicitly. + +As an obsolescent calling convention, this function can be given six +or more arguments. The first six arguments @var{second}, +@var{minute}, @var{hour}, @var{day}, @var{month}, and @var{year} +specify most of the components of a decoded time. If there are more +than six arguments the @emph{last} argument is used as @var{zone} and +any other extra arguments are ignored, so that @code{(apply +'encode-time (decode-time ...))} works; otherwise @var{zone} defaults +to the current time zone rule (@pxref{Time Zone Rules}). The decoded +time's @var{dst} component is treated as if it was @minus{}1, and +@var{form} so it takes its default value. Year numbers less than 100 are not treated specially. If you want them to stand for years above 1900, or years above 2000, you must alter them yourself before you call @code{encode-time}. -The optional argument @var{zone} defaults to the current time zone rule. -@xref{Time Zone Rules}. - -If you pass more than seven arguments to @code{encode-time}, the first -six are used as @var{seconds} through @var{year}, the last argument is -used as @var{zone}, and the arguments in between are ignored. This -feature makes it possible to use the elements of a list returned by -@code{decode-time} as the arguments to @code{encode-time}, like this: +The @code{encode-time} function acts as a rough inverse to +@code{decode-time}. For example, you can pass the output of +the latter to the former as follows: @example -(apply 'encode-time (decode-time @dots{})) +(encode-time (decode-time @dots{})) @end example You can perform simple date arithmetic by using out-of-range values for -the @var{seconds}, @var{minutes}, @var{hour}, @var{day}, and @var{month} -arguments; for example, day 0 means the day preceding the given month. +@var{seconds}, @var{minutes}, @var{hour}, @var{day}, and @var{month}; +for example, day 0 means the day preceding the given month. The operating system puts limits on the range of possible time values; if you try to encode a time that is out of range, an error results. @@ -1474,12 +1528,12 @@ on others, years as early as 1901 do work. @cindex formatting time values These functions convert time values to text in a string, and vice versa. -Time values include @code{nil}, numbers, and lists of two to four -integers (@pxref{Time of Day}). +Time values include @code{nil}, numbers, and Lisp timestamps +(@pxref{Time of Day}). @defun date-to-time string This function parses the time-string @var{string} and returns the -corresponding time value. +corresponding Lisp timestamp. @end defun @defun format-time-string format-string &optional time zone @@ -1701,10 +1755,8 @@ When called interactively, it prints the uptime in the echo area. @end deffn @defun get-internal-run-time -This function returns the processor run time used by Emacs as a list -of four integers: @code{(@var{sec-high} @var{sec-low} @var{microsec} -@var{picosec})}, using the same format as @code{current-time} -(@pxref{Time of Day}). +This function returns the processor run time used by Emacs, as a Lisp +timestamp (@pxref{Time of Day}). Note that the time returned by this function excludes the time Emacs was not using the processor, and if the Emacs process has several @@ -1729,9 +1781,10 @@ interactively, it prints the duration in the echo area. @cindex calendrical computations These functions perform calendrical computations using time values -(@pxref{Time of Day}). A value of @code{nil} for any of their +(@pxref{Time of Day}). As with any time value, 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. +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 @@ -1757,7 +1810,7 @@ float-time}) to convert the result into seconds. This returns the sum of two time values, as a time value. However, the result is a float if either argument is a float infinity or NaN@. 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. +as a time value that is often just a single number of elapsed seconds. Here is how to add a number of seconds to a time value: @example diff --git a/doc/lispref/processes.texi b/doc/lispref/processes.texi index 89ad1cf8381..e1113e37f10 100644 --- a/doc/lispref/processes.texi +++ b/doc/lispref/processes.texi @@ -2158,19 +2158,17 @@ faults for all the child processes of the given process. @item utime Time spent by the process in the user context, for running the -application's code. The corresponding @var{value} is in the -@w{@code{(@var{high} @var{low} @var{microsec} @var{picosec})}} format, the same -format used by functions @code{current-time} (@pxref{Time of Day, -current-time}) and @code{file-attributes} (@pxref{File Attributes}). +application's code. The corresponding @var{value} is a Lisp +timestamp (@pxref{Time of Day}). @item stime Time spent by the process in the system (kernel) context, for -processing system calls. The corresponding @var{value} is in the same -format as for @code{utime}. +processing system calls. The corresponding @var{value} is a Lisp +timestamp. @item time The sum of @code{utime} and @code{stime}. The corresponding -@var{value} is in the same format as for @code{utime}. +@var{value} is a Lisp timestamp. @item cutime @itemx cstime @@ -2189,13 +2187,10 @@ nice values get scheduled more favorably.) The number of threads in the process. @item start -The time when the process was started, in the same -@code{(@var{high} @var{low} @var{microsec} @var{picosec})} format used by -@code{file-attributes} and @code{current-time}. +The time when the process was started, as a Lisp timestamp. @item etime -The time elapsed since the process started, in the format @code{(@var{high} -@var{low} @var{microsec} @var{picosec})}. +The time elapsed since the process started, as a Lisp timestamp. @item vsize The virtual memory size of the process, measured in kilobytes. diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi index 825827095b4..6c38d8eed09 100644 --- a/doc/lispref/text.texi +++ b/doc/lispref/text.texi @@ -1327,9 +1327,8 @@ elements follow immediately after this element. @item (t . @var{time-flag}) This kind of element indicates that an unmodified buffer became -modified. A @var{time-flag} of the form -@code{(@var{sec-high} @var{sec-low} @var{microsec} -@var{picosec})} represents the visited file's modification time as of +modified. A @var{time-flag} that is a non-integer Lisp timestamp +represents the visited file's modification time as of when it was previously visited or saved, using the same format as @code{current-time}; see @ref{Time of Day}. A @var{time-flag} of 0 means the buffer does not correspond to any file; diff --git a/doc/misc/emacs-mime.texi b/doc/misc/emacs-mime.texi index 9280311b5c9..f46b2a7fc1d 100644 --- a/doc/misc/emacs-mime.texi +++ b/doc/misc/emacs-mime.texi @@ -1524,12 +1524,12 @@ many mailers don't support it. @xref{rfc2231}. @section time-date While not really a part of the @acronym{MIME} library, it is convenient to -document this library here. It deals with parsing @code{Date} headers +document time conversion functions often used when parsing @code{Date} headers and manipulating time. (Not by using tesseracts, though, I'm sorry to say.) -These functions convert between five formats: A date string, an Emacs -time structure, a decoded time list, a second number, and a day number. +These functions convert between five formats: A date string, a Lisp +timestamp, a decoded time list, a second number, and a day number. Here's a bunch of time/date/second/day examples: @@ -1537,35 +1537,41 @@ Here's a bunch of time/date/second/day examples: (parse-time-string "Sat Sep 12 12:21:54 1998 +0200") @result{} (54 21 12 12 9 1998 6 -1 7200) -(date-to-time "Sat Sep 12 12:21:54 1998 +0200") -@result{} (13818 19266) +(encode-time (date-to-time "Sat Sep 12 12:21:54 1998 +0200") + 1000000) +@result{} (905595714000000 . 1000000) -(parse-iso8601-time-string "1998-09-12T12:21:54+0200") -@result{} (13818 19266) +(encode-time (parse-iso8601-time-string "1998-09-12T12:21:54+0200") + 1000000) +@result{} (905595714000000 . 1000000) -(float-time '(13818 19266)) +(float-time '(905595714000000 . 1000000)) @result{} 905595714.0 -(seconds-to-time 905595714.0) -@result{} (13818 19266 0 0) +(encode-time 905595714.0 1000000) +@result{} (905595714000000 . 1000000) -(time-to-days '(13818 19266)) +(time-to-days '(905595714000000 . 1000000)) @result{} 729644 -(days-to-time 729644) -@result{} (961933 512) +(encode-time (days-to-time 729644) 1000000) +@result{} (63041241600000000 . 1000000) -(time-since '(13818 19266)) -@result{} (6797 9607 984839 247000) +(encode-time (time-since '(905595714000000 . 1000000)) + 1000000) +@result{} (631963244775642171 . 1000000000) -(time-less-p '(13818 19266) '(13818 19145)) +(time-less-p '(905595714000000 . 1000000) + '(905595593000000000 . 1000000000)) @result{} nil -(time-equal-p '(13818 19266) '(13818 19145)) -@result{} nil +(time-equal-p '(905595593000000000 . 1000000000) + '(905595593000000 . 1000000 )) +@result{} t -(time-subtract '(13818 19266) '(13818 19145)) -@result{} (0 121) +(time-subtract '(905595714000000 . 1000000) + '(905595593000000000 . 1000000000)) +@result{} (121000000000 . 1000000000) (days-between "Sat Sep 12 12:21:54 1998 +0200" "Sat Sep 07 12:21:54 1998 +0200") @@ -1574,13 +1580,13 @@ Here's a bunch of time/date/second/day examples: (date-leap-year-p 2000) @result{} t -(time-to-day-in-year '(13818 19266)) +(time-to-day-in-year '(905595714000000 . 1000000)) @result{} 255 (time-to-number-of-days (time-since (date-to-time "Mon, 01 Jan 2001 02:22:26 GMT"))) -@result{} 4314.095589286675 +@result{} 6472.722661506652 @end example And finally, we have @code{safe-date-to-time}, which does the same as @@ -1595,22 +1601,24 @@ An RFC822 (or similar) date string. For instance: @code{"Sat Sep 12 12:21:54 1998 +0200"}. @item time -An internal Emacs time. For instance: @code{(13818 26466 0 0)}. +A Lisp timestamp. +For instance: @code{(905595714000000 . 1000000)}. @item seconds -A floating point representation of the internal Emacs time. For -instance: @code{905595714.0}. +An integer or floating point count of seconds. For instance: +@code{905595714.0}, @code{905595714}. @item days An integer number representing the number of days since 00000101. For instance: @code{729644}. @item decoded time -A list of decoded time. For instance: @code{(54 21 12 12 9 1998 6 t +A list of decoded time. For instance: @code{(54 21 12 12 9 1998 6 nil 7200)}. @end table -All the examples above represent the same moment. +All the examples above represent the same moment, except that +@var{days} represents the day containing the moment. These are the functions available: @@ -1621,8 +1629,9 @@ Take a date and return a time. @item float-time Take a time and return seconds. (This is a built-in function.) -@item seconds-to-time -Take seconds and return a time. +@item encode-time +Take seconds (and other ways to represent time, notably decoded time +lists), and return a time. @item time-to-days Take a time and return days. @@ -1645,7 +1654,7 @@ Take two times and say whether the first time is less (i.e., earlier) than the second time. (This is a built-in function.) @item time-equal-p -Check, whether two time values are equal. The time values must not be +Check whether two time values are equal. The time values need not be in the same format. (This is a built-in function.) @item time-since |