Mercurial > hg > xemacs-beta

diff man/lispref/numbers.texi @ 5252:378a34562cbe

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Fix style, documentation for rounding functions and multiple values. src/ChangeLog addition: 2010-08-30 Aidan Kehoe <kehoea@parhasard.net> * floatfns.c (ceiling_one_mundane_arg, floor_one_mundane_arg) (round_one_mundane_arg, truncate_one_mundane_arg): INTEGERP is always available, no need to wrap calls to it with #ifdef HAVE_BIGNUM. (Fceiling, Ffloor, Fround, Ftruncate, Ffceiling, Fffloor) (Ffround, Fftruncate): Correct some code formatting here. * doprnt.c (emacs_doprnt_1): Remove some needless #ifdef WITH_NUMBER_TYPES, now number.h is always #included. man/ChangeLog addition: 2010-08-30 Aidan Kehoe <kehoea@parhasard.net> * lispref/eval.texi (Evaluation, Multiple values): Document our implementation of multiple values; point the reader to the CLTL or the Hyperspec for details of exactly when values are discarded. * lispref/numbers.texi (Numeric Conversions): Document the optional DIVISOR arguments to the rounding functions, and document that they all return multiple values. (Rounding Operations): Ditto. * cl.texi (Multiple Values): Document that we've moved the multiple values implementation to core code, and cross-reference to the Lispref. (Numerical Functions): The various rounding functions are now identical to the built-in rounding functions, with the exception that they return lists, not multiple values; document this.
author Aidan Kehoe <kehoea@parhasard.net>
date Mon, 30 Aug 2010 15:23:42 +0100
parents 6772ce4d982b
children a2912073be85
line wrap: on
line diff
--- a/man/lispref/numbers.texi	Mon Aug 30 15:21:04 2010 +0100
+++ b/man/lispref/numbers.texi	Mon Aug 30 15:23:42 2010 +0100
@@ -871,9 +871,15 @@
 
 There are four functions to convert floating point numbers to integers;
 they differ in how they round.  These functions accept integer arguments
-also, and return such arguments unchanged.
+also, and return such arguments unchanged.  They return multiple values,
+@pxref{(cl.info)Multiple values}.
 
-@defun truncate number
+All these functions take optional @var{divisor} arguments, and if this
+argument is specified, the @var{number} argument is divided by
+@var{divisor} before the calculation is made.  An @code{arith-error}
+results if @var{divisor} is 0.
+
+@defun truncate number &optional divisor
 This returns @var{number}, converted to an integer by rounding towards
 zero.
 @end defun
@@ -881,23 +887,21 @@
 @defun floor number &optional divisor
 This returns @var{number}, converted to an integer by rounding downward
 (towards negative infinity).
-
-If @var{divisor} is specified, @var{number} is divided by @var{divisor}
-before the floor is taken; this is the division operation that
-corresponds to @code{mod}.  An @code{arith-error} results if
-@var{divisor} is 0.
 @end defun
 
-@defun ceiling number
+@defun ceiling number &optional divisor
 This returns @var{number}, converted to an integer by rounding upward
 (towards positive infinity).
 @end defun
 
-@defun round number
+@defun round number &optional divisor
 This returns @var{number}, converted to an integer by rounding towards the
-nearest integer.  Rounding a value equidistant between two integers
-may choose the integer closer to zero, or it may prefer an even integer,
-depending on your machine.
+nearest integer.
+
+Rounding a value equidistant between two integers chooses the even
+integer.  GNU Emacs and older XEmacs did not guarantee this, and the
+direction of rounding depended on the underlying machine and the C
+implementation.
 @end defun
 
 @node Arithmetic Operations
@@ -1154,24 +1158,35 @@
 @code{ftruncate}, the nearest integer in the direction towards zero;
 @code{fround}, the nearest integer.
 
-@defun ffloor number
+All these functions take optional @var{divisor} arguments, and if this
+argument is specified, the @var{number} argument is divided by
+@var{divisor} before the calculation is made.  An @code{arith-error}
+results if @var{divisor} is 0.  Also, they return multiple values,
+@pxref{(cl.info)Multiple values}; the second value is the remainder.
+
+@defun ffloor number &optional divisor
 This function rounds @var{number} to the next lower integral value, and
 returns that value as a floating point number.
 @end defun
 
-@defun fceiling number
+@defun fceiling number &optional divisor
 This function rounds @var{number} to the next higher integral value, and
 returns that value as a floating point number.
 @end defun
 
-@defun ftruncate number
+@defun ftruncate number &optional divisor
 This function rounds @var{number} towards zero to an integral value, and
 returns that value as a floating point number.
 @end defun
 
-@defun fround number
+@defun fround number &optional divisor
 This function rounds @var{number} to the nearest integral value,
 and returns that value as a floating point number.
+
+Rounding a value equidistant between two integral values chooses the
+even value.  While this is specified by Common Lisp, GNU Emacs and older
+XEmacs did not make this guarantee, and the direction of rounding
+depended on the underlying machine and the C implementation.
 @end defun
 
 @node Bitwise Operations