# HG changeset patch # User Luc Teirlinck # Date 1089416068 0 # Node ID 4f00fbfe3c1e04560f1419be71ebc3aad9e88b29 # Parent eef1aaabd6751457e6351997cdebf6dcdf56ec07 (Ffloat_time, Fformat_time_string, Fdecode_time) (Fcurrent_time_string, Fcurrent_time_zone): Mention in docstrings that time values of the type (HIGH . LOW) are considered obsolete. diff -r eef1aaabd675 -r 4f00fbfe3c1e src/editfns.c --- a/src/editfns.c Fri Jul 09 21:50:42 2004 +0000 +++ b/src/editfns.c Fri Jul 09 23:34:28 2004 +0000 @@ -1431,10 +1431,10 @@ DEFUN ("float-time", Ffloat_time, Sfloat_time, 0, 1, 0, doc: /* Return the current time, as a float number of seconds since the epoch. If SPECIFIED-TIME is given, it is the time to convert to float -instead of the current time. The argument should have the forms: - (HIGH . LOW) or (HIGH LOW USEC) or (HIGH LOW . USEC). -Thus, you can use times obtained from `current-time' -and from `file-attributes'. +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. WARNING: Since the result is floating point, it may not be exact. Do not use this function if precise time stamps are required. */) @@ -1506,8 +1506,9 @@ 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. -TIME is specified as (HIGH LOW . IGNORED) or (HIGH . LOW), as returned by -`current-time' or `file-attributes'. +TIME is specified as (HIGH LOW . IGNORED), as returned by +`current-time' or `file-attributes'. The obsolete form (HIGH . LOW) +is also still accepted. The third, optional, argument UNIVERSAL, if non-nil, means describe TIME as Universal Time; nil means describe TIME in the local time zone. The value is a copy of FORMAT-STRING, but with certain constructs replaced @@ -1603,17 +1604,19 @@ DEFUN ("decode-time", Fdecode_time, Sdecode_time, 0, 1, 0, doc: /* Decode a time value as (SEC MINUTE HOUR DAY MONTH YEAR DOW DST ZONE). -The optional SPECIFIED-TIME should be a list of (HIGH LOW . IGNORED) -or (HIGH . LOW), as from `current-time' and `file-attributes', or `nil' -to use the current time. The list has the following nine members: -SEC is an integer between 0 and 60; SEC is 60 for a leap second, which -only some operating systems support. MINUTE is an integer between 0 and 59. -HOUR is an integer between 0 and 23. DAY is an integer between 1 and 31. -MONTH is an integer between 1 and 12. YEAR is an integer indicating the -four-digit year. DOW is the day of week, an integer between 0 and 6, where -0 is Sunday. DST is t if daylight savings time is effect, otherwise nil. -ZONE is an integer indicating the number of seconds east of Greenwich. -(Note that Common Lisp has different meanings for DOW and ZONE.) */) +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. +The list has the following nine members: SEC is an integer between 0 +and 60; SEC is 60 for a leap second, which only some operating systems +support. MINUTE is an integer between 0 and 59. HOUR is an integer +between 0 and 23. DAY is an integer between 1 and 31. MONTH is an +integer between 1 and 12. YEAR is an integer indicating the +four-digit year. DOW is the day of week, an integer between 0 and 6, +where 0 is Sunday. DST is t if daylight savings time is effect, +otherwise nil. ZONE is an integer indicating the number of seconds +east of Greenwich. (Note that Common Lisp has different meanings for +DOW and ZONE.) */) (specified_time) Lisp_Object specified_time; { @@ -1745,13 +1748,11 @@ However, see also the functions `decode-time' and `format-time-string' 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) -or the form: - (HIGH LOW . IGNORED). -Thus, you can use times obtained from `current-time' -and from `file-attributes'. */) +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. */) (specified_time) Lisp_Object specified_time; { @@ -1802,12 +1803,10 @@ A negative value means west of Greenwich. 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) -or the form: - (HIGH LOW . IGNORED). -Thus, you can use times obtained from `current-time' -and from `file-attributes'. +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. Some operating systems cannot provide all this information to Emacs; in this case, `current-time-zone' returns a list containing nil for