# HG changeset patch # User Richard M. Stallman # Date 1123789630 0 # Node ID 6ed6c1b79d36f8bc6c8e80b81da84c2bdea1c9a9 # Parent 989a5fc8da03a1d9ed81c6da2b6cc2684046e41d (Time Parsing): New node split out of Time Conversion. diff -r 989a5fc8da03 -r 6ed6c1b79d36 lispref/os.texi --- a/lispref/os.texi Thu Aug 11 19:46:35 2005 +0000 +++ b/lispref/os.texi Thu Aug 11 19:47:10 2005 +0000 @@ -21,8 +21,10 @@ * System Environment:: Distinguish the name and kind of system. * User Identification:: Finding the name and user id of the user. * Time of Day:: Getting the current time. -* Time Conversion:: Converting a time from numeric form to a string, or - to calendrical data (or vice versa). +* Time Conversion:: Converting a time from numeric form + to calendrical data, and vice versa). +* Time Parsing:: Converting a time from numeric form to text + and vice versa. * Processor Run Time:: Getting the run time used by Emacs. * Time Calculations:: Adding, subtracting, comparing times, etc. * Timers:: Setting a timer to call a function at a certain time. @@ -1071,22 +1073,102 @@ @section Time Conversion These functions convert time values (lists of two or three integers) -to strings or to calendrical information. There is also a function to -convert calendrical information to a time value. You can get time -values from the functions @code{current-time} (@pxref{Time of Day}) and +to calendrical information and vice versa. You can get time values +from the functions @code{current-time} (@pxref{Time of Day}) and @code{file-attributes} (@pxref{Definition of file-attributes}). -Many operating systems are limited to time values that contain 32 bits + Many operating systems are limited to time values that contain 32 bits of information; these systems typically handle only the times from 1901-12-13 20:45:52 UTC through 2038-01-19 03:14:07 UTC. However, some operating systems have larger time values, and can represent times far in the past or future. -Time conversion functions always use the Gregorian calendar, even for -dates before the Gregorian calendar was introduced. Year numbers count -the number of years since the year 1 B.C., and do not skip zero as -traditional Gregorian years do; for example, the year number @minus{}37 -represents the Gregorian year 38 B.C@. + Time conversion functions always use the Gregorian calendar, even +for dates before the Gregorian calendar was introduced. Year numbers +count the number of years since the year 1 B.C., and do not skip zero +as traditional Gregorian years do; for example, the year number +@minus{}37 represents the Gregorian year 38 B.C@. + +@defun decode-time &optional time +This function converts a time value into calendrical information. If +you don't specify @var{time}, it decodes the current time. The return +value is a list of nine elements, as follows: + +@example +(@var{seconds} @var{minutes} @var{hour} @var{day} @var{month} @var{year} @var{dow} @var{dst} @var{zone}) +@end example + +Here is what the elements mean: + +@table @var +@item seconds +The number of seconds past the minute, as an integer between 0 and 59. +On some operating systems, this is 60 for leap seconds. +@item minutes +The number of minutes past the hour, as an integer between 0 and 59. +@item hour +The hour of the day, as an integer between 0 and 23. +@item day +The day of the month, as an integer between 1 and 31. +@item month +The month of the year, as an integer between 1 and 12. +@item year +The year, an integer typically greater than 1900. +@item dow +The day of week, as an integer between 0 and 6, where 0 stands for +Sunday. +@item dst +@code{t} if daylight savings time is effect, otherwise @code{nil}. +@item zone +An integer indicating the time zone, as the number of seconds east of +Greenwich. +@end table + +@strong{Common Lisp Note:} Common Lisp has different meanings for +@var{dow} and @var{zone}. +@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 time value. For the meanings of the +arguments, see the table above under @code{decode-time}. + +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 and +its daylight savings time rules. If specified, it can be either a list +(as you would get from @code{current-time-zone}), a string as in the +@code{TZ} environment variable, @code{t} for Universal Time, or an +integer (as you would get from @code{decode-time}). The specified +zone is used without any further alteration for daylight savings time. + +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: + +@example +(apply '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. + +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. +For instance, years before 1970 do not work on some systems; +on others, years as early as 1901 do work. +@end defun + +@node Time Parsing +@section Parsing and Formatting Times + + These functions convert time values (lists of two or three integers) +to text in a string, and vice versa. @defun date-to-time string This function parses the time-string @var{string} and returns the @@ -1213,81 +1295,6 @@ the inverse conversion, use @code{float-time}. @end defun -@defun decode-time &optional time -This function converts a time value into calendrical information. If -you don't specify @var{time}, it decodes the current time. The return -value is a list of nine elements, as follows: - -@example -(@var{seconds} @var{minutes} @var{hour} @var{day} @var{month} @var{year} @var{dow} @var{dst} @var{zone}) -@end example - -Here is what the elements mean: - -@table @var -@item seconds -The number of seconds past the minute, as an integer between 0 and 59. -On some operating systems, this is 60 for leap seconds. -@item minutes -The number of minutes past the hour, as an integer between 0 and 59. -@item hour -The hour of the day, as an integer between 0 and 23. -@item day -The day of the month, as an integer between 1 and 31. -@item month -The month of the year, as an integer between 1 and 12. -@item year -The year, an integer typically greater than 1900. -@item dow -The day of week, as an integer between 0 and 6, where 0 stands for -Sunday. -@item dst -@code{t} if daylight savings time is effect, otherwise @code{nil}. -@item zone -An integer indicating the time zone, as the number of seconds east of -Greenwich. -@end table - -@strong{Common Lisp Note:} Common Lisp has different meanings for -@var{dow} and @var{zone}. -@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 time value. For the meanings of the -arguments, see the table above under @code{decode-time}. - -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 and -its daylight savings time rules. If specified, it can be either a list -(as you would get from @code{current-time-zone}), a string as in the -@code{TZ} environment variable, @code{t} for Universal Time, or an -integer (as you would get from @code{decode-time}). The specified -zone is used without any further alteration for daylight savings time. - -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: - -@example -(apply '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. - -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. -For instance, years before 1970 do not work on some systems; -on others, years as early as 1901 do work. -@end defun - @node Processor Run Time @section Processor Run time