Mercurial > hg > xemacs-beta

comparison 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
comparison
equal deleted inserted replaced
5251:b0ba3598beb1 5252:378a34562cbe
869 it unchanged. 869 it unchanged.
870 @end defun 870 @end defun
871 871
872 There are four functions to convert floating point numbers to integers; 872 There are four functions to convert floating point numbers to integers;
873 they differ in how they round. These functions accept integer arguments 873 they differ in how they round. These functions accept integer arguments
874 also, and return such arguments unchanged. 874 also, and return such arguments unchanged. They return multiple values,
875 875 @pxref{(cl.info)Multiple values}.
876 @defun truncate number 876
877 All these functions take optional @var{divisor} arguments, and if this
878 argument is specified, the @var{number} argument is divided by
879 @var{divisor} before the calculation is made. An @code{arith-error}
880 results if @var{divisor} is 0.
881
882 @defun truncate number &optional divisor
877 This returns @var{number}, converted to an integer by rounding towards 883 This returns @var{number}, converted to an integer by rounding towards
878 zero. 884 zero.
879 @end defun 885 @end defun
880 886
881 @defun floor number &optional divisor 887 @defun floor number &optional divisor
882 This returns @var{number}, converted to an integer by rounding downward 888 This returns @var{number}, converted to an integer by rounding downward
883 (towards negative infinity). 889 (towards negative infinity).
884 890 @end defun
885 If @var{divisor} is specified, @var{number} is divided by @var{divisor} 891
886 before the floor is taken; this is the division operation that 892 @defun ceiling number &optional divisor
887 corresponds to @code{mod}. An @code{arith-error} results if
888 @var{divisor} is 0.
889 @end defun
890
891 @defun ceiling number
892 This returns @var{number}, converted to an integer by rounding upward 893 This returns @var{number}, converted to an integer by rounding upward
893 (towards positive infinity). 894 (towards positive infinity).
894 @end defun 895 @end defun
895 896
896 @defun round number 897 @defun round number &optional divisor
897 This returns @var{number}, converted to an integer by rounding towards the 898 This returns @var{number}, converted to an integer by rounding towards the
898 nearest integer. Rounding a value equidistant between two integers 899 nearest integer.
899 may choose the integer closer to zero, or it may prefer an even integer, 900
900 depending on your machine. 901 Rounding a value equidistant between two integers chooses the even
902 integer. GNU Emacs and older XEmacs did not guarantee this, and the
903 direction of rounding depended on the underlying machine and the C
904 implementation.
901 @end defun 905 @end defun
902 906
903 @node Arithmetic Operations 907 @node Arithmetic Operations
904 @section Arithmetic Operations 908 @section Arithmetic Operations
905 909
1152 point result whose value is a nearby integer. @code{ffloor} returns the 1156 point result whose value is a nearby integer. @code{ffloor} returns the
1153 nearest integer below; @code{fceiling}, the nearest integer above; 1157 nearest integer below; @code{fceiling}, the nearest integer above;
1154 @code{ftruncate}, the nearest integer in the direction towards zero; 1158 @code{ftruncate}, the nearest integer in the direction towards zero;
1155 @code{fround}, the nearest integer. 1159 @code{fround}, the nearest integer.
1156 1160
1157 @defun ffloor number 1161 All these functions take optional @var{divisor} arguments, and if this
1162 argument is specified, the @var{number} argument is divided by
1163 @var{divisor} before the calculation is made. An @code{arith-error}
1164 results if @var{divisor} is 0. Also, they return multiple values,
1165 @pxref{(cl.info)Multiple values}; the second value is the remainder.
1166
1167 @defun ffloor number &optional divisor
1158 This function rounds @var{number} to the next lower integral value, and 1168 This function rounds @var{number} to the next lower integral value, and
1159 returns that value as a floating point number. 1169 returns that value as a floating point number.
1160 @end defun 1170 @end defun
1161 1171
1162 @defun fceiling number 1172 @defun fceiling number &optional divisor
1163 This function rounds @var{number} to the next higher integral value, and 1173 This function rounds @var{number} to the next higher integral value, and
1164 returns that value as a floating point number. 1174 returns that value as a floating point number.
1165 @end defun 1175 @end defun
1166 1176
1167 @defun ftruncate number 1177 @defun ftruncate number &optional divisor
1168 This function rounds @var{number} towards zero to an integral value, and 1178 This function rounds @var{number} towards zero to an integral value, and
1169 returns that value as a floating point number. 1179 returns that value as a floating point number.
1170 @end defun 1180 @end defun
1171 1181
1172 @defun fround number 1182 @defun fround number &optional divisor
1173 This function rounds @var{number} to the nearest integral value, 1183 This function rounds @var{number} to the nearest integral value,
1174 and returns that value as a floating point number. 1184 and returns that value as a floating point number.
1185
1186 Rounding a value equidistant between two integral values chooses the
1187 even value. While this is specified by Common Lisp, GNU Emacs and older
1188 XEmacs did not make this guarantee, and the direction of rounding
1189 depended on the underlying machine and the C implementation.
1175 @end defun 1190 @end defun
1176 1191
1177 @node Bitwise Operations 1192 @node Bitwise Operations
1178 @section Bitwise Operations on Integers 1193 @section Bitwise Operations on Integers
1179 1194