diff options
Diffstat (limited to 'doc/lispref/numbers.texi')
| -rw-r--r-- | doc/lispref/numbers.texi | 491 |
1 files changed, 240 insertions, 251 deletions
diff --git a/doc/lispref/numbers.texi b/doc/lispref/numbers.texi index c12ffe2cde7..d03113674f5 100644 --- a/doc/lispref/numbers.texi +++ b/doc/lispref/numbers.texi @@ -14,9 +14,9 @@ fractional parts, such as @minus{}4.5, 0.0, and 2.71828. They can also be expressed in exponential notation: @samp{1.5e2} is the same as @samp{150.0}; here, @samp{e2} stands for ten to the second power, and -that is multiplied by 1.5. Integer computations are exact, though -they may overflow. Floating-point computations often involve rounding -errors, as the numbers have a fixed amount of precision. +that is multiplied by 1.5. Integer computations are exact. +Floating-point computations often involve rounding errors, as the +numbers have a fixed amount of precision. @menu * Integer Basics:: Representation and range of integers. @@ -34,7 +34,23 @@ errors, as the numbers have a fixed amount of precision. @node Integer Basics @section Integer Basics - The range of values for an integer depends on the machine. The + Integers in Emacs Lisp are not limited to the machine word size. + + Under the hood, though, there are two kinds of integers: smaller +ones, called @dfn{fixnums}, and larger ones, called @dfn{bignums}. +Some functions in Emacs accept only fixnums. Also, while fixnums can +always be compared for numeric equality with @code{eq}, bignums +require more-heavyweight equality predicates like @code{eql}. + + The range of values for bignums is limited by the amount of main +memory, by machine characteristics such as the size of the word used +to represent a bignum's exponent, and by the @code{integer-width} +variable. These limits are typically much more generous than the +limits for fixnums. A bignum is never numerically equal to a fixnum; +if Emacs computes an integer in fixnum range, it represents the +integer as a fixnum, not a bignum. + + The range of values for a fixnum depends on the machine. The minimum range is @minus{}536,870,912 to 536,870,911 (30 bits; i.e., @ifnottex @minus{}2**29 @@ -49,21 +65,17 @@ to @tex @math{2^{29}-1}), @end tex -but many machines provide a wider range. Many examples in this -chapter assume the minimum integer width of 30 bits. -@cindex overflow +but many machines provide a wider range. - The Lisp reader reads an integer as a sequence of digits with optional -initial sign and optional final period. An integer that is out of the -Emacs range is treated as a floating-point number. + The Lisp reader reads an integer as a nonempty sequence +of decimal digits with optional initial sign and optional +final period. @example 1 ; @r{The integer 1.} 1. ; @r{The integer 1.} +1 ; @r{Also the integer 1.} -1 ; @r{The integer @minus{}1.} - 9000000000000000000 - ; @r{The floating-point number 9e18.} 0 ; @r{The integer 0.} -0 ; @r{The integer 0.} @end example @@ -74,14 +86,17 @@ Emacs range is treated as a floating-point number. @cindex hex numbers @cindex octal numbers @cindex reading numbers in hex, octal, and binary - The syntax for integers in bases other than 10 uses @samp{#} -followed by a letter that specifies the radix: @samp{b} for binary, -@samp{o} for octal, @samp{x} for hex, or @samp{@var{radix}r} to -specify radix @var{radix}. Case is not significant for the letter -that specifies the radix. Thus, @samp{#b@var{integer}} reads + The syntax for integers in bases other than 10 consists of @samp{#} +followed by a radix indication followed by one or more digits. The +radix indications are @samp{b} for binary, @samp{o} for octal, +@samp{x} for hex, and @samp{@var{radix}r} for radix @var{radix}. +Thus, @samp{#b@var{integer}} reads @var{integer} in binary, and @samp{#@var{radix}r@var{integer}} reads @var{integer} in radix @var{radix}. Allowed values of @var{radix} run -from 2 to 36. For example: +from 2 to 36, and allowed digits are the first @var{radix} characters +taken from @samp{0}--@samp{9}, @samp{A}--@samp{Z}. +Letter case is ignored and there is no initial sign or final period. +For example: @example #b101100 @result{} 44 @@ -94,26 +109,26 @@ from 2 to 36. For example: bitwise operators (@pxref{Bitwise Operations}), it is often helpful to view the numbers in their binary form. - In 30-bit binary, the decimal integer 5 looks like this: + In binary, the decimal integer 5 looks like this: @example -0000...000101 (30 bits total) +@dots{}000101 @end example @noindent -(The @samp{...} stands for enough bits to fill out a 30-bit word; in -this case, @samp{...} stands for twenty 0 bits. Later examples also -use the @samp{...} notation to make binary integers easier to read.) +(The ellipsis @samp{@dots{}} stands for a conceptually infinite number +of bits that match the leading bit; here, an infinite number of 0 +bits. Later examples also use this @samp{@dots{}} notation.) The integer @minus{}1 looks like this: @example -1111...111111 (30 bits total) +@dots{}111111 @end example @noindent @cindex two's complement -@minus{}1 is represented as 30 ones. (This is called @dfn{two's +@minus{}1 is represented as all ones. (This is called @dfn{two's complement} notation.) Subtracting 4 from @minus{}1 returns the negative integer @minus{}5. @@ -121,24 +136,7 @@ In binary, the decimal integer 4 is 100. Consequently, @minus{}5 looks like this: @example -1111...111011 (30 bits total) -@end example - - In this implementation, the largest 30-bit binary integer is -536,870,911 in decimal. In binary, it looks like this: - -@example -0111...111111 (30 bits total) -@end example - - Since the arithmetic functions do not check whether integers go -outside their range, when you add 1 to 536,870,911, the value is the -negative integer @minus{}536,870,912: - -@example -(+ 1 536870911) - @result{} -536870912 - @result{} 1000...000000 (30 bits total) +@dots{}111011 @end example Many of the functions described in this chapter accept markers for @@ -147,11 +145,11 @@ arguments to such functions may be either numbers or markers, we often give these arguments the name @var{number-or-marker}. When the argument value is a marker, its position value is used and its buffer is ignored. -@cindex largest Lisp integer -@cindex maximum Lisp integer +@cindex largest fixnum +@cindex maximum fixnum @defvar most-positive-fixnum -The value of this variable is the largest integer that Emacs Lisp can -handle. Typical values are +The value of this variable is the greatest ``small'' integer that Emacs +Lisp can handle. Typical values are @ifnottex 2**29 @minus{} 1 @end ifnottex @@ -168,11 +166,11 @@ on 32-bit and on 64-bit platforms. @end defvar -@cindex smallest Lisp integer -@cindex minimum Lisp integer +@cindex smallest fixnum +@cindex minimum fixnum @defvar most-negative-fixnum -The value of this variable is the smallest integer that Emacs Lisp can -handle. It is negative. Typical values are +The value of this variable is the numerically least ``small'' integer +that Emacs Lisp can handle. It is negative. Typical values are @ifnottex @minus{}2**29 @end ifnottex @@ -189,6 +187,26 @@ on 32-bit and on 64-bit platforms. @end defvar +@cindex bignum range +@cindex integer range +@cindex number of bignum bits, limit on +@defvar integer-width +The value of this variable is a nonnegative integer that is an upper +bound on the number of bits in a bignum. Integers outside the fixnum +range are limited to absolute values less than +@ifnottex +2**@var{n}, +@end ifnottex +@tex +@math{2^{n}}, +@end tex +where @var{n} is this variable's value. Attempts to create bignums outside +this range signal a range error. Setting this variable +to zero disables creation of bignums; setting it to a large number can +cause Emacs to consume large quantities of memory if a computation +creates huge integers. +@end defvar + In Emacs Lisp, text characters are represented by integers. Any integer between zero and the value of @code{(max-char)}, inclusive, is considered to be valid as a character. @xref{Character Codes}. @@ -213,7 +231,7 @@ least one digit after any decimal point in a floating-point number; @samp{1500.} is an integer, not a floating-point number. Emacs Lisp treats @code{-0.0} as numerically equal to ordinary zero -with respect to @code{equal} and @code{=}. This follows the +with respect to numeric comparisons like @code{=}. This follows the @acronym{IEEE} floating-point standard, which says @code{-0.0} and @code{0.0} are numerically equal even though other operations can distinguish them. @@ -227,8 +245,20 @@ infinity and negative infinity as floating-point values. It also provides for a class of values called NaN, or ``not a number''; numerical functions return such values in cases where there is no correct answer. For example, @code{(/ 0.0 0.0)} returns a NaN@. -Although NaN values carry a sign, for practical purposes there is no other -significant difference between different NaN values in Emacs Lisp. +A NaN is never numerically equal to any value, not even to itself. +NaNs carry a sign and a significand, and non-numeric functions treat +two NaNs as equal when their +signs and significands agree. Significands of NaNs are +machine-dependent, as are the digits in their string representation. + + When NaNs and signed zeros are involved, non-numeric functions like +@code{eql}, @code{equal}, @code{sxhash-eql}, @code{sxhash-equal} and +@code{gethash} determine whether values are indistinguishable, not +whether they are numerically equal. For example, when @var{x} and +@var{y} are the same NaN, @code{(equal x y)} returns @code{t} whereas +@code{(= x y)} uses numeric comparison and returns @code{nil}; +conversely, @code{(equal 0.0 -0.0)} returns @code{nil} whereas +@code{(= 0.0 -0.0)} returns @code{t}. Here are read syntaxes for these special floating-point values: @@ -305,6 +335,18 @@ use otherwise), but the @code{zerop} predicate requires a number as its argument. See also @code{integer-or-marker-p} and @code{number-or-marker-p}, in @ref{Predicates on Markers}. +@defun bignump object +This predicate tests whether its argument is a large integer, and +returns @code{t} if so, @code{nil} otherwise. Unlike small integers, +large integers can be @code{=} or @code{eql} even if they are not @code{eq}. +@end defun + +@defun fixnump object +This predicate tests whether its argument is a small integer, and +returns @code{t} if so, @code{nil} otherwise. Small integers can be +compared with @code{eq}. +@end defun + @defun floatp object This predicate tests whether its argument is floating point and returns @code{t} if so, @code{nil} otherwise. @@ -344,23 +386,27 @@ if so, @code{nil} otherwise. The argument must be a number. @cindex comparing numbers To test numbers for numerical equality, you should normally use -@code{=}, not @code{eq}. There can be many distinct floating-point -objects with the same numeric value. If you use @code{eq} to -compare them, then you test whether two values are the same -@emph{object}. By contrast, @code{=} compares only the numeric values -of the objects. - - In Emacs Lisp, each integer is a unique Lisp object. -Therefore, @code{eq} is equivalent to @code{=} where integers are -concerned. It is sometimes convenient to use @code{eq} for comparing -an unknown value with an integer, because @code{eq} does not report an +@code{=} instead of non-numeric comparison predicates like @code{eq}, +@code{eql} and @code{equal}. Distinct floating-point and large +integer objects can be numerically equal. If you use @code{eq} to +compare them, you test whether they are the same @emph{object}; if you +use @code{eql} or @code{equal}, you test whether their values are +@emph{indistinguishable}. In contrast, @code{=} uses numeric +comparison, and sometimes returns @code{t} when a non-numeric +comparison would return @code{nil} and vice versa. @xref{Float +Basics}. + + In Emacs Lisp, if two fixnums are numerically equal, they are the +same Lisp object. That is, @code{eq} is equivalent to @code{=} on +fixnums. It is sometimes convenient to use @code{eq} for comparing +an unknown value with a fixnum, because @code{eq} does not report an error if the unknown value is not a number---it accepts arguments of any type. By contrast, @code{=} signals an error if the arguments are not numbers or markers. However, it is better programming practice to use @code{=} if you can, even for comparing integers. - Sometimes it is useful to compare numbers with @code{equal}, which -treats two numbers as equal if they have the same data type (both + Sometimes it is useful to compare numbers with @code{eql} or @code{equal}, +which treat two numbers as equal if they have the same data type (both integers, or both floating point) and the same value. By contrast, @code{=} can treat an integer and a floating-point number as equal. @xref{Equality Predicates}. @@ -379,15 +425,6 @@ Here's a function to do this: fuzz-factor))) @end example -@cindex CL note---integers vrs @code{eq} -@quotation -@b{Common Lisp note:} Comparing numbers in Common Lisp always requires -@code{=} because Common Lisp implements multi-word integers, and two -distinct integer objects can have the same numeric value. Emacs Lisp -can have just one integer object for any given value because it has a -limited range of integers. -@end quotation - @defun = number-or-marker &rest number-or-markers This function tests whether all its arguments are numerically equal, and returns @code{t} if so, @code{nil} otherwise. @@ -397,7 +434,8 @@ and returns @code{t} if so, @code{nil} otherwise. This function acts like @code{eq} except when both arguments are numbers. It compares numbers by type and numeric value, so that @code{(eql 1.0 1)} returns @code{nil}, but @code{(eql 1.0 1.0)} and -@code{(eql 1 1)} both return @code{t}. +@code{(eql 1 1)} both return @code{t}. This can be used to compare +large integers as well as small ones. @end defun @defun /= number-or-marker1 number-or-marker2 @@ -557,10 +595,6 @@ Except for @code{%}, each of these functions accepts both integer and floating-point arguments, and returns a floating-point number if any argument is floating point. - Emacs Lisp arithmetic functions do not check for integer overflow. -Thus @code{(1+ 536870911)} may evaluate to -@minus{}536870912, depending on your hardware. - @defun 1+ number-or-marker This function returns @var{number-or-marker} plus 1. For example, @@ -814,181 +848,119 @@ Rounding a value equidistant between two integers returns the even integer. @cindex logical arithmetic In a computer, an integer is represented as a binary number, a -sequence of @dfn{bits} (digits which are either zero or one). A bitwise +sequence of @dfn{bits} (digits which are either zero or one). +Conceptually the bit sequence is infinite on the left, with the +most-significant bits being all zeros or all ones. A bitwise operation acts on the individual bits of such a sequence. For example, @dfn{shifting} moves the whole sequence left or right one or more places, reproducing the same pattern moved over. The bitwise operations in Emacs Lisp apply only to integers. -@defun lsh integer1 count -@cindex logical shift -@code{lsh}, which is an abbreviation for @dfn{logical shift}, shifts the -bits in @var{integer1} to the left @var{count} places, or to the right -if @var{count} is negative, bringing zeros into the vacated bits. If -@var{count} is negative, @code{lsh} shifts zeros into the leftmost -(most-significant) bit, producing a positive result even if -@var{integer1} is negative. Contrast this with @code{ash}, below. +@defun ash integer1 count +@cindex arithmetic shift +@code{ash} (@dfn{arithmetic shift}) shifts the bits in @var{integer1} +to the left @var{count} places, or to the right if @var{count} is +negative. Left shifts introduce zero bits on the right; right shifts +discard the rightmost bits. Considered as an integer operation, +@code{ash} multiplies @var{integer1} by +@ifnottex +2**@var{count}, +@end ifnottex +@tex +@math{2^{count}}, +@end tex +and then converts the result to an integer by rounding downward, toward +minus infinity. -Here are two examples of @code{lsh}, shifting a pattern of bits one -place to the left. We show only the low-order eight bits of the binary -pattern; the rest are all zero. +Here are examples of @code{ash}, shifting a pattern of bits one place +to the left and to the right. These examples show only the low-order +bits of the binary pattern; leading bits all agree with the +highest-order bit shown. As you can see, shifting left by one is +equivalent to multiplying by two, whereas shifting right by one is +equivalent to dividing by two and then rounding toward minus infinity. @example @group -(lsh 5 1) - @result{} 10 -;; @r{Decimal 5 becomes decimal 10.} -00000101 @result{} 00001010 - -(lsh 7 1) - @result{} 14 +(ash 7 1) @result{} 14 ;; @r{Decimal 7 becomes decimal 14.} -00000111 @result{} 00001110 +@dots{}000111 + @result{} +@dots{}001110 @end group -@end example - -@noindent -As the examples illustrate, shifting the pattern of bits one place to -the left produces a number that is twice the value of the previous -number. - -Shifting a pattern of bits two places to the left produces results -like this (with 8-bit binary numbers): -@example @group -(lsh 3 2) - @result{} 12 -;; @r{Decimal 3 becomes decimal 12.} -00000011 @result{} 00001100 +(ash 7 -1) @result{} 3 +@dots{}000111 + @result{} +@dots{}000011 @end group -@end example -On the other hand, shifting one place to the right looks like this: - -@example @group -(lsh 6 -1) - @result{} 3 -;; @r{Decimal 6 becomes decimal 3.} -00000110 @result{} 00000011 +(ash -7 1) @result{} -14 +@dots{}111001 + @result{} +@dots{}110010 @end group @group -(lsh 5 -1) - @result{} 2 -;; @r{Decimal 5 becomes decimal 2.} -00000101 @result{} 00000010 +(ash -7 -1) @result{} -4 +@dots{}111001 + @result{} +@dots{}111100 @end group @end example -@noindent -As the example illustrates, shifting one place to the right divides the -value of a positive integer by two, rounding downward. +Here are examples of shifting left or right by two bits: -The function @code{lsh}, like all Emacs Lisp arithmetic functions, does -not check for overflow, so shifting left can discard significant bits -and change the sign of the number. For example, left shifting -536,870,911 produces @minus{}2 in the 30-bit implementation: - -@example -(lsh 536870911 1) ; @r{left shift} - @result{} -2 -@end example - -In binary, the argument looks like this: - -@example +@smallexample @group -;; @r{Decimal 536,870,911} -0111...111111 (30 bits total) + ; @r{ binary values} +(ash 5 2) ; 5 = @r{@dots{}000101} + @result{} 20 ; = @r{@dots{}010100} +(ash -5 2) ; -5 = @r{@dots{}111011} + @result{} -20 ; = @r{@dots{}101100} @end group -@end example - -@noindent -which becomes the following when left shifted: - -@example @group -;; @r{Decimal @minus{}2} -1111...111110 (30 bits total) +(ash 5 -2) + @result{} 1 ; = @r{@dots{}000001} @end group -@end example -@end defun - -@defun ash integer1 count -@cindex arithmetic shift -@code{ash} (@dfn{arithmetic shift}) shifts the bits in @var{integer1} -to the left @var{count} places, or to the right if @var{count} -is negative. - -@code{ash} gives the same results as @code{lsh} except when -@var{integer1} and @var{count} are both negative. In that case, -@code{ash} puts ones in the empty bit positions on the left, while -@code{lsh} puts zeros in those bit positions. - -Thus, with @code{ash}, shifting the pattern of bits one place to the right -looks like this: - -@example @group -(ash -6 -1) @result{} -3 -;; @r{Decimal @minus{}6 becomes decimal @minus{}3.} -1111...111010 (30 bits total) - @result{} -1111...111101 (30 bits total) +(ash -5 -2) + @result{} -2 ; = @r{@dots{}111110} @end group -@end example - -In contrast, shifting the pattern of bits one place to the right with -@code{lsh} looks like this: +@end smallexample +@end defun -@example -@group -(lsh -6 -1) @result{} 536870909 -;; @r{Decimal @minus{}6 becomes decimal 536,870,909.} -1111...111010 (30 bits total) - @result{} -0111...111101 (30 bits total) -@end group -@end example +@defun lsh integer1 count +@cindex logical shift +@code{lsh}, which is an abbreviation for @dfn{logical shift}, shifts the +bits in @var{integer1} to the left @var{count} places, or to the right +if @var{count} is negative, bringing zeros into the vacated bits. If +@var{count} is negative, then @var{integer1} must be either a fixnum +or a positive bignum, and @code{lsh} treats a negative fixnum as if it +were unsigned by subtracting twice @code{most-negative-fixnum} before +shifting, producing a nonnegative result. This quirky behavior dates +back to when Emacs supported only fixnums; nowadays @code{ash} is a +better choice. -Here are other examples: +As @code{lsh} behaves like @code{ash} except when @var{integer1} and +@var{count1} are both negative, the following examples focus on these +exceptional cases. These examples assume 30-bit fixnums. -@c !!! Check if lined up in smallbook format! XDVI shows problem -@c with smallbook but not with regular book! --rjc 16mar92 @smallexample @group - ; @r{ 30-bit binary values} - -(lsh 5 2) ; 5 = @r{0000...000101} - @result{} 20 ; = @r{0000...010100} + ; @r{ binary values} +(ash -7 -1) ; -7 = @r{@dots{}111111111111111111111111111001} + @result{} -4 ; = @r{@dots{}111111111111111111111111111100} +(lsh -7 -1) + @result{} 536870908 ; = @r{@dots{}011111111111111111111111111100} @end group @group -(ash 5 2) - @result{} 20 -(lsh -5 2) ; -5 = @r{1111...111011} - @result{} -20 ; = @r{1111...101100} -(ash -5 2) - @result{} -20 -@end group -@group -(lsh 5 -2) ; 5 = @r{0000...000101} - @result{} 1 ; = @r{0000...000001} -@end group -@group -(ash 5 -2) - @result{} 1 -@end group -@group -(lsh -5 -2) ; -5 = @r{1111...111011} - @result{} 268435454 - ; = @r{0011...111110} -@end group -@group -(ash -5 -2) ; -5 = @r{1111...111011} - @result{} -2 ; = @r{1111...111110} +(ash -5 -2) ; -5 = @r{@dots{}111111111111111111111111111011} + @result{} -2 ; = @r{@dots{}111111111111111111111111111110} +(lsh -5 -2) + @result{} 268435454 ; = @r{@dots{}001111111111111111111111111110} @end group @end smallexample @end defun @@ -1022,23 +994,23 @@ because its binary representation consists entirely of ones. If @smallexample @group - ; @r{ 30-bit binary values} + ; @r{ binary values} -(logand 14 13) ; 14 = @r{0000...001110} - ; 13 = @r{0000...001101} - @result{} 12 ; 12 = @r{0000...001100} +(logand 14 13) ; 14 = @r{@dots{}001110} + ; 13 = @r{@dots{}001101} + @result{} 12 ; 12 = @r{@dots{}001100} @end group @group -(logand 14 13 4) ; 14 = @r{0000...001110} - ; 13 = @r{0000...001101} - ; 4 = @r{0000...000100} - @result{} 4 ; 4 = @r{0000...000100} +(logand 14 13 4) ; 14 = @r{@dots{}001110} + ; 13 = @r{@dots{}001101} + ; 4 = @r{@dots{}000100} + @result{} 4 ; 4 = @r{@dots{}000100} @end group @group (logand) - @result{} -1 ; -1 = @r{1111...111111} + @result{} -1 ; -1 = @r{@dots{}111111} @end group @end smallexample @end defun @@ -1052,18 +1024,18 @@ passed just one argument, it returns that argument. @smallexample @group - ; @r{ 30-bit binary values} + ; @r{ binary values} -(logior 12 5) ; 12 = @r{0000...001100} - ; 5 = @r{0000...000101} - @result{} 13 ; 13 = @r{0000...001101} +(logior 12 5) ; 12 = @r{@dots{}001100} + ; 5 = @r{@dots{}000101} + @result{} 13 ; 13 = @r{@dots{}001101} @end group @group -(logior 12 5 7) ; 12 = @r{0000...001100} - ; 5 = @r{0000...000101} - ; 7 = @r{0000...000111} - @result{} 15 ; 15 = @r{0000...001111} +(logior 12 5 7) ; 12 = @r{@dots{}001100} + ; 5 = @r{@dots{}000101} + ; 7 = @r{@dots{}000111} + @result{} 15 ; 15 = @r{@dots{}001111} @end group @end smallexample @end defun @@ -1077,18 +1049,18 @@ result is 0, which is an identity element for this operation. If @smallexample @group - ; @r{ 30-bit binary values} + ; @r{ binary values} -(logxor 12 5) ; 12 = @r{0000...001100} - ; 5 = @r{0000...000101} - @result{} 9 ; 9 = @r{0000...001001} +(logxor 12 5) ; 12 = @r{@dots{}001100} + ; 5 = @r{@dots{}000101} + @result{} 9 ; 9 = @r{@dots{}001001} @end group @group -(logxor 12 5 7) ; 12 = @r{0000...001100} - ; 5 = @r{0000...000101} - ; 7 = @r{0000...000111} - @result{} 14 ; 14 = @r{0000...001110} +(logxor 12 5 7) ; 12 = @r{@dots{}001100} + ; 5 = @r{@dots{}000101} + ; 7 = @r{@dots{}000111} + @result{} 14 ; 14 = @r{@dots{}001110} @end group @end smallexample @end defun @@ -1101,9 +1073,27 @@ bit is one in the result if, and only if, the @var{n}th bit is zero in @example (lognot 5) @result{} -6 -;; 5 = @r{0000...000101} (30 bits total) +;; 5 = @r{@dots{}000101} ;; @r{becomes} -;; -6 = @r{1111...111010} (30 bits total) +;; -6 = @r{@dots{}111010} +@end example +@end defun + +@cindex popcount +@cindex Hamming weight +@cindex counting set bits +@defun logcount integer +This function returns the @dfn{Hamming weight} of @var{integer}: the +number of ones in the binary representation of @var{integer}. +If @var{integer} is negative, it returns the number of zero bits in +its two's complement binary representation. The result is always +nonnegative. + +@example +(logcount 43) ; 43 = @r{@dots{}000101011} + @result{} 4 +(logcount -43) ; -43 = @r{@dots{}111010101} + @result{} 3 @end example @end defun @@ -1189,8 +1179,8 @@ returns a NaN. @defun expt x y This function returns @var{x} raised to power @var{y}. If both -arguments are integers and @var{y} is positive, the result is an -integer; in this case, overflow causes truncation, so watch out. +arguments are integers and @var{y} is nonnegative, the result is an +integer; in this case, overflow signals an error, so watch out. If @var{x} is a finite negative number and @var{y} is a finite non-integer, @code{expt} returns a NaN. @end defun @@ -1241,11 +1231,10 @@ other strings to choose various seed values. This function returns a pseudo-random integer. Repeated calls return a series of pseudo-random integers. -If @var{limit} is a positive integer, the value is chosen to be +If @var{limit} is a positive fixnum, the value is chosen to be nonnegative and less than @var{limit}. Otherwise, the value might be -any integer representable in Lisp, i.e., an integer between -@code{most-negative-fixnum} and @code{most-positive-fixnum} -(@pxref{Integer Basics}). +any fixnum, i.e., any integer from @code{most-negative-fixnum} through +@code{most-positive-fixnum} (@pxref{Integer Basics}). If @var{limit} is @code{t}, it means to choose a new seed as if Emacs were restarting, typically from the system entropy. On systems |