[Emacs-diffs] Changes to emacs/lispref/os.texi

[Richard M . Stallman]

Index: emacs/lispref/os.texi
diff -c emacs/lispref/os.texi:1.76 emacs/lispref/os.texi:1.77
*** emacs/lispref/os.texi:1.76  Wed Aug 10 14:29:00 2005
--- emacs/lispref/os.texi       Thu Aug 11 19:47:10 2005
***************
*** 21,28 ****
  * 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).
  * 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.
--- 21,30 ----
  * 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 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,1092 ****
  @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
  @code{file-attributes} (@pxref{Definition of file-attributes}).
  
! 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 address@hidden
  
  @defun date-to-time string
  This function parses the time-string @var{string} and returns the
--- 1073,1174 ----
  @section Time Conversion
  
    These functions convert time values (lists of two or three integers)
! 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
  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 address@hidden
! 
! @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
***************
*** 1211,1291 ****
  This function converts @var{seconds}, a floating point number of
  seconds since the epoch, to a time value and returns that.  To perform
  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
--- 1293,1298 ----