1@c -*-texinfo-*- 2@c This is part of the GNU Emacs Lisp Reference Manual. 3@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, 4@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. 5@c See the file elisp.texi for copying conditions. 6@setfilename ../info/numbers 7@node Numbers, Strings and Characters, Lisp Data Types, Top 8@chapter Numbers 9@cindex integers 10@cindex numbers 11 12 GNU Emacs supports two numeric data types: @dfn{integers} and 13@dfn{floating point numbers}. Integers are whole numbers such as 14@minus{}3, 0, 7, 13, and 511. Their values are exact. Floating point 15numbers are numbers with fractional parts, such as @minus{}4.5, 0.0, or 162.71828. They can also be expressed in exponential notation: 1.5e2 17equals 150; in this example, @samp{e2} stands for ten to the second 18power, and that is multiplied by 1.5. Floating point values are not 19exact; they have a fixed, limited amount of precision. 20 21@menu 22* Integer Basics:: Representation and range of integers. 23* Float Basics:: Representation and range of floating point. 24* Predicates on Numbers:: Testing for numbers. 25* Comparison of Numbers:: Equality and inequality predicates. 26* Numeric Conversions:: Converting float to integer and vice versa. 27* Arithmetic Operations:: How to add, subtract, multiply and divide. 28* Rounding Operations:: Explicitly rounding floating point numbers. 29* Bitwise Operations:: Logical and, or, not, shifting. 30* Math Functions:: Trig, exponential and logarithmic functions. 31* Random Numbers:: Obtaining random integers, predictable or not. 32@end menu 33 34@node Integer Basics 35@comment node-name, next, previous, up 36@section Integer Basics 37 38 The range of values for an integer depends on the machine. The 39minimum range is @minus{}268435456 to 268435455 (29 bits; i.e., 40@ifnottex 41-2**28 42@end ifnottex 43@tex 44@math{-2^{28}} 45@end tex 46to 47@ifnottex 482**28 - 1), 49@end ifnottex 50@tex 51@math{2^{28}-1}), 52@end tex 53but some machines may provide a wider range. Many examples in this 54chapter assume an integer has 29 bits. 55@cindex overflow 56 57 The Lisp reader reads an integer as a sequence of digits with optional 58initial sign and optional final period. 59 60@example 61 1 ; @r{The integer 1.} 62 1. ; @r{The integer 1.} 63+1 ; @r{Also the integer 1.} 64-1 ; @r{The integer @minus{}1.} 65 536870913 ; @r{Also the integer 1, due to overflow.} 66 0 ; @r{The integer 0.} 67-0 ; @r{The integer 0.} 68@end example 69 70@cindex integers in specific radix 71@cindex radix for reading an integer 72@cindex base for reading an integer 73@cindex hex numbers 74@cindex octal numbers 75@cindex reading numbers in hex, octal, and binary 76 The syntax for integers in bases other than 10 uses @samp{#} 77followed by a letter that specifies the radix: @samp{b} for binary, 78@samp{o} for octal, @samp{x} for hex, or @samp{@var{radix}r} to 79specify radix @var{radix}. Case is not significant for the letter 80that specifies the radix. Thus, @samp{#b@var{integer}} reads 81@var{integer} in binary, and @samp{#@var{radix}r@var{integer}} reads 82@var{integer} in radix @var{radix}. Allowed values of @var{radix} run 83from 2 to 36. For example: 84 85@example 86#b101100 @result{} 44 87#o54 @result{} 44 88#x2c @result{} 44 89#24r1k @result{} 44 90@end example 91 92 To understand how various functions work on integers, especially the 93bitwise operators (@pxref{Bitwise Operations}), it is often helpful to 94view the numbers in their binary form. 95 96 In 29-bit binary, the decimal integer 5 looks like this: 97 98@example 990 0000 0000 0000 0000 0000 0000 0101 100@end example 101 102@noindent 103(We have inserted spaces between groups of 4 bits, and two spaces 104between groups of 8 bits, to make the binary integer easier to read.) 105 106 The integer @minus{}1 looks like this: 107 108@example 1091 1111 1111 1111 1111 1111 1111 1111 110@end example 111 112@noindent 113@cindex two's complement 114@minus{}1 is represented as 29 ones. (This is called @dfn{two's 115complement} notation.) 116 117 The negative integer, @minus{}5, is creating by subtracting 4 from 118@minus{}1. In binary, the decimal integer 4 is 100. Consequently, 119@minus{}5 looks like this: 120 121@example 1221 1111 1111 1111 1111 1111 1111 1011 123@end example 124 125 In this implementation, the largest 29-bit binary integer value is 126268,435,455 in decimal. In binary, it looks like this: 127 128@example 1290 1111 1111 1111 1111 1111 1111 1111 130@end example 131 132 Since the arithmetic functions do not check whether integers go 133outside their range, when you add 1 to 268,435,455, the value is the 134negative integer @minus{}268,435,456: 135 136@example 137(+ 1 268435455) 138 @result{} -268435456 139 @result{} 1 0000 0000 0000 0000 0000 0000 0000 140@end example 141 142 Many of the functions described in this chapter accept markers for 143arguments in place of numbers. (@xref{Markers}.) Since the actual 144arguments to such functions may be either numbers or markers, we often 145give these arguments the name @var{number-or-marker}. When the argument 146value is a marker, its position value is used and its buffer is ignored. 147 148@defvar most-positive-fixnum 149The value of this variable is the largest integer that Emacs Lisp 150can handle. 151@end defvar 152 153@defvar most-negative-fixnum 154The value of this variable is the smallest integer that Emacs Lisp can 155handle. It is negative. 156@end defvar 157 158@node Float Basics 159@section Floating Point Basics 160 161 Floating point numbers are useful for representing numbers that are 162not integral. The precise range of floating point numbers is 163machine-specific; it is the same as the range of the C data type 164@code{double} on the machine you are using. 165 166 The read-syntax for floating point numbers requires either a decimal 167point (with at least one digit following), an exponent, or both. For 168example, @samp{1500.0}, @samp{15e2}, @samp{15.0e2}, @samp{1.5e3}, and 169@samp{.15e4} are five ways of writing a floating point number whose 170value is 1500. They are all equivalent. You can also use a minus sign 171to write negative floating point numbers, as in @samp{-1.0}. 172 173@cindex @acronym{IEEE} floating point 174@cindex positive infinity 175@cindex negative infinity 176@cindex infinity 177@cindex NaN 178 Most modern computers support the @acronym{IEEE} floating point standard, 179which provides for positive infinity and negative infinity as floating point 180values. It also provides for a class of values called NaN or 181``not-a-number''; numerical functions return such values in cases where 182there is no correct answer. For example, @code{(/ 0.0 0.0)} returns a 183NaN. For practical purposes, there's no significant difference between 184different NaN values in Emacs Lisp, and there's no rule for precisely 185which NaN value should be used in a particular case, so Emacs Lisp 186doesn't try to distinguish them (but it does report the sign, if you 187print it). Here are the read syntaxes for these special floating 188point values: 189 190@table @asis 191@item positive infinity 192@samp{1.0e+INF} 193@item negative infinity 194@samp{-1.0e+INF} 195@item Not-a-number 196@samp{0.0e+NaN} or @samp{-0.0e+NaN}. 197@end table 198 199 To test whether a floating point value is a NaN, compare it with 200itself using @code{=}. That returns @code{nil} for a NaN, and 201@code{t} for any other floating point value. 202 203 The value @code{-0.0} is distinguishable from ordinary zero in 204@acronym{IEEE} floating point, but Emacs Lisp @code{equal} and 205@code{=} consider them equal values. 206 207 You can use @code{logb} to extract the binary exponent of a floating 208point number (or estimate the logarithm of an integer): 209 210@defun logb number 211This function returns the binary exponent of @var{number}. More 212precisely, the value is the logarithm of @var{number} base 2, rounded 213down to an integer. 214 215@example 216(logb 10) 217 @result{} 3 218(logb 10.0e20) 219 @result{} 69 220@end example 221@end defun 222 223@node Predicates on Numbers 224@section Type Predicates for Numbers 225@cindex predicates for numbers 226 227 The functions in this section test for numbers, or for a specific 228type of number. The functions @code{integerp} and @code{floatp} can 229take any type of Lisp object as argument (they would not be of much 230use otherwise), but the @code{zerop} predicate requires a number as 231its argument. See also @code{integer-or-marker-p} and 232@code{number-or-marker-p}, in @ref{Predicates on Markers}. 233 234@defun floatp object 235This predicate tests whether its argument is a floating point 236number and returns @code{t} if so, @code{nil} otherwise. 237 238@code{floatp} does not exist in Emacs versions 18 and earlier. 239@end defun 240 241@defun integerp object 242This predicate tests whether its argument is an integer, and returns 243@code{t} if so, @code{nil} otherwise. 244@end defun 245 246@defun numberp object 247This predicate tests whether its argument is a number (either integer or 248floating point), and returns @code{t} if so, @code{nil} otherwise. 249@end defun 250 251@defun wholenump object 252@cindex natural numbers 253The @code{wholenump} predicate (whose name comes from the phrase 254``whole-number-p'') tests to see whether its argument is a nonnegative 255integer, and returns @code{t} if so, @code{nil} otherwise. 0 is 256considered non-negative. 257 258@findex natnump 259@code{natnump} is an obsolete synonym for @code{wholenump}. 260@end defun 261 262@defun zerop number 263This predicate tests whether its argument is zero, and returns @code{t} 264if so, @code{nil} otherwise. The argument must be a number. 265 266@code{(zerop x)} is equivalent to @code{(= x 0)}. 267@end defun 268 269@node Comparison of Numbers 270@section Comparison of Numbers 271@cindex number comparison 272@cindex comparing numbers 273 274 To test numbers for numerical equality, you should normally use 275@code{=}, not @code{eq}. There can be many distinct floating point 276number objects with the same numeric value. If you use @code{eq} to 277compare them, then you test whether two values are the same 278@emph{object}. By contrast, @code{=} compares only the numeric values 279of the objects. 280 281 At present, each integer value has a unique Lisp object in Emacs Lisp. 282Therefore, @code{eq} is equivalent to @code{=} where integers are 283concerned. It is sometimes convenient to use @code{eq} for comparing an 284unknown value with an integer, because @code{eq} does not report an 285error if the unknown value is not a number---it accepts arguments of any 286type. By contrast, @code{=} signals an error if the arguments are not 287numbers or markers. However, it is a good idea to use @code{=} if you 288can, even for comparing integers, just in case we change the 289representation of integers in a future Emacs version. 290 291 Sometimes it is useful to compare numbers with @code{equal}; it 292treats two numbers as equal if they have the same data type (both 293integers, or both floating point) and the same value. By contrast, 294@code{=} can treat an integer and a floating point number as equal. 295@xref{Equality Predicates}. 296 297 There is another wrinkle: because floating point arithmetic is not 298exact, it is often a bad idea to check for equality of two floating 299point values. Usually it is better to test for approximate equality. 300Here's a function to do this: 301 302@example 303(defvar fuzz-factor 1.0e-6) 304(defun approx-equal (x y) 305 (or (and (= x 0) (= y 0)) 306 (< (/ (abs (- x y)) 307 (max (abs x) (abs y))) 308 fuzz-factor))) 309@end example 310 311@cindex CL note---integers vrs @code{eq} 312@quotation 313@b{Common Lisp note:} Comparing numbers in Common Lisp always requires 314@code{=} because Common Lisp implements multi-word integers, and two 315distinct integer objects can have the same numeric value. Emacs Lisp 316can have just one integer object for any given value because it has a 317limited range of integer values. 318@end quotation 319 320@defun = number-or-marker1 number-or-marker2 321This function tests whether its arguments are numerically equal, and 322returns @code{t} if so, @code{nil} otherwise. 323@end defun 324 325@defun eql value1 value2 326This function acts like @code{eq} except when both arguments are 327numbers. It compares numbers by type and numeric value, so that 328@code{(eql 1.0 1)} returns @code{nil}, but @code{(eql 1.0 1.0)} and 329@code{(eql 1 1)} both return @code{t}. 330@end defun 331 332@defun /= number-or-marker1 number-or-marker2 333This function tests whether its arguments are numerically equal, and 334returns @code{t} if they are not, and @code{nil} if they are. 335@end defun 336 337@defun < number-or-marker1 number-or-marker2 338This function tests whether its first argument is strictly less than 339its second argument. It returns @code{t} if so, @code{nil} otherwise. 340@end defun 341 342@defun <= number-or-marker1 number-or-marker2 343This function tests whether its first argument is less than or equal 344to its second argument. It returns @code{t} if so, @code{nil} 345otherwise. 346@end defun 347 348@defun > number-or-marker1 number-or-marker2 349This function tests whether its first argument is strictly greater 350than its second argument. It returns @code{t} if so, @code{nil} 351otherwise. 352@end defun 353 354@defun >= number-or-marker1 number-or-marker2 355This function tests whether its first argument is greater than or 356equal to its second argument. It returns @code{t} if so, @code{nil} 357otherwise. 358@end defun 359 360@defun max number-or-marker &rest numbers-or-markers 361This function returns the largest of its arguments. 362If any of the arguments is floating-point, the value is returned 363as floating point, even if it was given as an integer. 364 365@example 366(max 20) 367 @result{} 20 368(max 1 2.5) 369 @result{} 2.5 370(max 1 3 2.5) 371 @result{} 3.0 372@end example 373@end defun 374 375@defun min number-or-marker &rest numbers-or-markers 376This function returns the smallest of its arguments. 377If any of the arguments is floating-point, the value is returned 378as floating point, even if it was given as an integer. 379 380@example 381(min -4 1) 382 @result{} -4 383@end example 384@end defun 385 386@defun abs number 387This function returns the absolute value of @var{number}. 388@end defun 389 390@node Numeric Conversions 391@section Numeric Conversions 392@cindex rounding in conversions 393@cindex number conversions 394@cindex converting numbers 395 396To convert an integer to floating point, use the function @code{float}. 397 398@defun float number 399This returns @var{number} converted to floating point. 400If @var{number} is already a floating point number, @code{float} returns 401it unchanged. 402@end defun 403 404There are four functions to convert floating point numbers to integers; 405they differ in how they round. All accept an argument @var{number} 406and an optional argument @var{divisor}. Both arguments may be 407integers or floating point numbers. @var{divisor} may also be 408@code{nil}. If @var{divisor} is @code{nil} or omitted, these 409functions convert @var{number} to an integer, or return it unchanged 410if it already is an integer. If @var{divisor} is non-@code{nil}, they 411divide @var{number} by @var{divisor} and convert the result to an 412integer. An @code{arith-error} results if @var{divisor} is 0. 413 414@defun truncate number &optional divisor 415This returns @var{number}, converted to an integer by rounding towards 416zero. 417 418@example 419(truncate 1.2) 420 @result{} 1 421(truncate 1.7) 422 @result{} 1 423(truncate -1.2) 424 @result{} -1 425(truncate -1.7) 426 @result{} -1 427@end example 428@end defun 429 430@defun floor number &optional divisor 431This returns @var{number}, converted to an integer by rounding downward 432(towards negative infinity). 433 434If @var{divisor} is specified, this uses the kind of division 435operation that corresponds to @code{mod}, rounding downward. 436 437@example 438(floor 1.2) 439 @result{} 1 440(floor 1.7) 441 @result{} 1 442(floor -1.2) 443 @result{} -2 444(floor -1.7) 445 @result{} -2 446(floor 5.99 3) 447 @result{} 1 448@end example 449@end defun 450 451@defun ceiling number &optional divisor 452This returns @var{number}, converted to an integer by rounding upward 453(towards positive infinity). 454 455@example 456(ceiling 1.2) 457 @result{} 2 458(ceiling 1.7) 459 @result{} 2 460(ceiling -1.2) 461 @result{} -1 462(ceiling -1.7) 463 @result{} -1 464@end example 465@end defun 466 467@defun round number &optional divisor 468This returns @var{number}, converted to an integer by rounding towards the 469nearest integer. Rounding a value equidistant between two integers 470may choose the integer closer to zero, or it may prefer an even integer, 471depending on your machine. 472 473@example 474(round 1.2) 475 @result{} 1 476(round 1.7) 477 @result{} 2 478(round -1.2) 479 @result{} -1 480(round -1.7) 481 @result{} -2 482@end example 483@end defun 484 485@node Arithmetic Operations 486@section Arithmetic Operations 487@cindex arithmetic operations 488 489 Emacs Lisp provides the traditional four arithmetic operations: 490addition, subtraction, multiplication, and division. Remainder and modulus 491functions supplement the division functions. The functions to 492add or subtract 1 are provided because they are traditional in Lisp and 493commonly used. 494 495 All of these functions except @code{%} return a floating point value 496if any argument is floating. 497 498 It is important to note that in Emacs Lisp, arithmetic functions 499do not check for overflow. Thus @code{(1+ 268435455)} may evaluate to 500@minus{}268435456, depending on your hardware. 501 502@defun 1+ number-or-marker 503This function returns @var{number-or-marker} plus 1. 504For example, 505 506@example 507(setq foo 4) 508 @result{} 4 509(1+ foo) 510 @result{} 5 511@end example 512 513This function is not analogous to the C operator @code{++}---it does not 514increment a variable. It just computes a sum. Thus, if we continue, 515 516@example 517foo 518 @result{} 4 519@end example 520 521If you want to increment the variable, you must use @code{setq}, 522like this: 523 524@example 525(setq foo (1+ foo)) 526 @result{} 5 527@end example 528@end defun 529 530@defun 1- number-or-marker 531This function returns @var{number-or-marker} minus 1. 532@end defun 533 534@defun + &rest numbers-or-markers 535This function adds its arguments together. When given no arguments, 536@code{+} returns 0. 537 538@example 539(+) 540 @result{} 0 541(+ 1) 542 @result{} 1 543(+ 1 2 3 4) 544 @result{} 10 545@end example 546@end defun 547 548@defun - &optional number-or-marker &rest more-numbers-or-markers 549The @code{-} function serves two purposes: negation and subtraction. 550When @code{-} has a single argument, the value is the negative of the 551argument. When there are multiple arguments, @code{-} subtracts each of 552the @var{more-numbers-or-markers} from @var{number-or-marker}, 553cumulatively. If there are no arguments, the result is 0. 554 555@example 556(- 10 1 2 3 4) 557 @result{} 0 558(- 10) 559 @result{} -10 560(-) 561 @result{} 0 562@end example 563@end defun 564 565@defun * &rest numbers-or-markers 566This function multiplies its arguments together, and returns the 567product. When given no arguments, @code{*} returns 1. 568 569@example 570(*) 571 @result{} 1 572(* 1) 573 @result{} 1 574(* 1 2 3 4) 575 @result{} 24 576@end example 577@end defun 578 579@defun / dividend divisor &rest divisors 580This function divides @var{dividend} by @var{divisor} and returns the 581quotient. If there are additional arguments @var{divisors}, then it 582divides @var{dividend} by each divisor in turn. Each argument may be a 583number or a marker. 584 585If all the arguments are integers, then the result is an integer too. 586This means the result has to be rounded. On most machines, the result 587is rounded towards zero after each division, but some machines may round 588differently with negative arguments. This is because the Lisp function 589@code{/} is implemented using the C division operator, which also 590permits machine-dependent rounding. As a practical matter, all known 591machines round in the standard fashion. 592 593@cindex @code{arith-error} in division 594If you divide an integer by 0, an @code{arith-error} error is signaled. 595(@xref{Errors}.) Floating point division by zero returns either 596infinity or a NaN if your machine supports @acronym{IEEE} floating point; 597otherwise, it signals an @code{arith-error} error. 598 599@example 600@group 601(/ 6 2) 602 @result{} 3 603@end group 604(/ 5 2) 605 @result{} 2 606(/ 5.0 2) 607 @result{} 2.5 608(/ 5 2.0) 609 @result{} 2.5 610(/ 5.0 2.0) 611 @result{} 2.5 612(/ 25 3 2) 613 @result{} 4 614@group 615(/ -17 6) 616 @result{} -2 @r{(could in theory be @minus{}3 on some machines)} 617@end group 618@end example 619@end defun 620 621@defun % dividend divisor 622@cindex remainder 623This function returns the integer remainder after division of @var{dividend} 624by @var{divisor}. The arguments must be integers or markers. 625 626For negative arguments, the remainder is in principle machine-dependent 627since the quotient is; but in practice, all known machines behave alike. 628 629An @code{arith-error} results if @var{divisor} is 0. 630 631@example 632(% 9 4) 633 @result{} 1 634(% -9 4) 635 @result{} -1 636(% 9 -4) 637 @result{} 1 638(% -9 -4) 639 @result{} -1 640@end example 641 642For any two integers @var{dividend} and @var{divisor}, 643 644@example 645@group 646(+ (% @var{dividend} @var{divisor}) 647 (* (/ @var{dividend} @var{divisor}) @var{divisor})) 648@end group 649@end example 650 651@noindent 652always equals @var{dividend}. 653@end defun 654 655@defun mod dividend divisor 656@cindex modulus 657This function returns the value of @var{dividend} modulo @var{divisor}; 658in other words, the remainder after division of @var{dividend} 659by @var{divisor}, but with the same sign as @var{divisor}. 660The arguments must be numbers or markers. 661 662Unlike @code{%}, @code{mod} returns a well-defined result for negative 663arguments. It also permits floating point arguments; it rounds the 664quotient downward (towards minus infinity) to an integer, and uses that 665quotient to compute the remainder. 666 667An @code{arith-error} results if @var{divisor} is 0. 668 669@example 670@group 671(mod 9 4) 672 @result{} 1 673@end group 674@group 675(mod -9 4) 676 @result{} 3 677@end group 678@group 679(mod 9 -4) 680 @result{} -3 681@end group 682@group 683(mod -9 -4) 684 @result{} -1 685@end group 686@group 687(mod 5.5 2.5) 688 @result{} .5 689@end group 690@end example 691 692For any two numbers @var{dividend} and @var{divisor}, 693 694@example 695@group 696(+ (mod @var{dividend} @var{divisor}) 697 (* (floor @var{dividend} @var{divisor}) @var{divisor})) 698@end group 699@end example 700 701@noindent 702always equals @var{dividend}, subject to rounding error if either 703argument is floating point. For @code{floor}, see @ref{Numeric 704Conversions}. 705@end defun 706 707@node Rounding Operations 708@section Rounding Operations 709@cindex rounding without conversion 710 711The functions @code{ffloor}, @code{fceiling}, @code{fround}, and 712@code{ftruncate} take a floating point argument and return a floating 713point result whose value is a nearby integer. @code{ffloor} returns the 714nearest integer below; @code{fceiling}, the nearest integer above; 715@code{ftruncate}, the nearest integer in the direction towards zero; 716@code{fround}, the nearest integer. 717 718@defun ffloor float 719This function rounds @var{float} to the next lower integral value, and 720returns that value as a floating point number. 721@end defun 722 723@defun fceiling float 724This function rounds @var{float} to the next higher integral value, and 725returns that value as a floating point number. 726@end defun 727 728@defun ftruncate float 729This function rounds @var{float} towards zero to an integral value, and 730returns that value as a floating point number. 731@end defun 732 733@defun fround float 734This function rounds @var{float} to the nearest integral value, 735and returns that value as a floating point number. 736@end defun 737 738@node Bitwise Operations 739@section Bitwise Operations on Integers 740@cindex bitwise arithmetic 741@cindex logical arithmetic 742 743 In a computer, an integer is represented as a binary number, a 744sequence of @dfn{bits} (digits which are either zero or one). A bitwise 745operation acts on the individual bits of such a sequence. For example, 746@dfn{shifting} moves the whole sequence left or right one or more places, 747reproducing the same pattern ``moved over.'' 748 749 The bitwise operations in Emacs Lisp apply only to integers. 750 751@defun lsh integer1 count 752@cindex logical shift 753@code{lsh}, which is an abbreviation for @dfn{logical shift}, shifts the 754bits in @var{integer1} to the left @var{count} places, or to the right 755if @var{count} is negative, bringing zeros into the vacated bits. If 756@var{count} is negative, @code{lsh} shifts zeros into the leftmost 757(most-significant) bit, producing a positive result even if 758@var{integer1} is negative. Contrast this with @code{ash}, below. 759 760Here are two examples of @code{lsh}, shifting a pattern of bits one 761place to the left. We show only the low-order eight bits of the binary 762pattern; the rest are all zero. 763 764@example 765@group 766(lsh 5 1) 767 @result{} 10 768;; @r{Decimal 5 becomes decimal 10.} 76900000101 @result{} 00001010 770 771(lsh 7 1) 772 @result{} 14 773;; @r{Decimal 7 becomes decimal 14.} 77400000111 @result{} 00001110 775@end group 776@end example 777 778@noindent 779As the examples illustrate, shifting the pattern of bits one place to 780the left produces a number that is twice the value of the previous 781number. 782 783Shifting a pattern of bits two places to the left produces results 784like this (with 8-bit binary numbers): 785 786@example 787@group 788(lsh 3 2) 789 @result{} 12 790;; @r{Decimal 3 becomes decimal 12.} 79100000011 @result{} 00001100 792@end group 793@end example 794 795On the other hand, shifting one place to the right looks like this: 796 797@example 798@group 799(lsh 6 -1) 800 @result{} 3 801;; @r{Decimal 6 becomes decimal 3.} 80200000110 @result{} 00000011 803@end group 804 805@group 806(lsh 5 -1) 807 @result{} 2 808;; @r{Decimal 5 becomes decimal 2.} 80900000101 @result{} 00000010 810@end group 811@end example 812 813@noindent 814As the example illustrates, shifting one place to the right divides the 815value of a positive integer by two, rounding downward. 816 817The function @code{lsh}, like all Emacs Lisp arithmetic functions, does 818not check for overflow, so shifting left can discard significant bits 819and change the sign of the number. For example, left shifting 820268,435,455 produces @minus{}2 on a 29-bit machine: 821 822@example 823(lsh 268435455 1) ; @r{left shift} 824 @result{} -2 825@end example 826 827In binary, in the 29-bit implementation, the argument looks like this: 828 829@example 830@group 831;; @r{Decimal 268,435,455} 8320 1111 1111 1111 1111 1111 1111 1111 833@end group 834@end example 835 836@noindent 837which becomes the following when left shifted: 838 839@example 840@group 841;; @r{Decimal @minus{}2} 8421 1111 1111 1111 1111 1111 1111 1110 843@end group 844@end example 845@end defun 846 847@defun ash integer1 count 848@cindex arithmetic shift 849@code{ash} (@dfn{arithmetic shift}) shifts the bits in @var{integer1} 850to the left @var{count} places, or to the right if @var{count} 851is negative. 852 853@code{ash} gives the same results as @code{lsh} except when 854@var{integer1} and @var{count} are both negative. In that case, 855@code{ash} puts ones in the empty bit positions on the left, while 856@code{lsh} puts zeros in those bit positions. 857 858Thus, with @code{ash}, shifting the pattern of bits one place to the right 859looks like this: 860 861@example 862@group 863(ash -6 -1) @result{} -3 864;; @r{Decimal @minus{}6 becomes decimal @minus{}3.} 8651 1111 1111 1111 1111 1111 1111 1010 866 @result{} 8671 1111 1111 1111 1111 1111 1111 1101 868@end group 869@end example 870 871In contrast, shifting the pattern of bits one place to the right with 872@code{lsh} looks like this: 873 874@example 875@group 876(lsh -6 -1) @result{} 268435453 877;; @r{Decimal @minus{}6 becomes decimal 268,435,453.} 8781 1111 1111 1111 1111 1111 1111 1010 879 @result{} 8800 1111 1111 1111 1111 1111 1111 1101 881@end group 882@end example 883 884Here are other examples: 885 886@c !!! Check if lined up in smallbook format! XDVI shows problem 887@c with smallbook but not with regular book! --rjc 16mar92 888@smallexample 889@group 890 ; @r{ 29-bit binary values} 891 892(lsh 5 2) ; 5 = @r{0 0000 0000 0000 0000 0000 0000 0101} 893 @result{} 20 ; = @r{0 0000 0000 0000 0000 0000 0001 0100} 894@end group 895@group 896(ash 5 2) 897 @result{} 20 898(lsh -5 2) ; -5 = @r{1 1111 1111 1111 1111 1111 1111 1011} 899 @result{} -20 ; = @r{1 1111 1111 1111 1111 1111 1110 1100} 900(ash -5 2) 901 @result{} -20 902@end group 903@group 904(lsh 5 -2) ; 5 = @r{0 0000 0000 0000 0000 0000 0000 0101} 905 @result{} 1 ; = @r{0 0000 0000 0000 0000 0000 0000 0001} 906@end group 907@group 908(ash 5 -2) 909 @result{} 1 910@end group 911@group 912(lsh -5 -2) ; -5 = @r{1 1111 1111 1111 1111 1111 1111 1011} 913 @result{} 134217726 ; = @r{0 0111 1111 1111 1111 1111 1111 1110} 914@end group 915@group 916(ash -5 -2) ; -5 = @r{1 1111 1111 1111 1111 1111 1111 1011} 917 @result{} -2 ; = @r{1 1111 1111 1111 1111 1111 1111 1110} 918@end group 919@end smallexample 920@end defun 921 922@defun logand &rest ints-or-markers 923This function returns the ``logical and'' of the arguments: the 924@var{n}th bit is set in the result if, and only if, the @var{n}th bit is 925set in all the arguments. (``Set'' means that the value of the bit is 1 926rather than 0.) 927 928For example, using 4-bit binary numbers, the ``logical and'' of 13 and 92912 is 12: 1101 combined with 1100 produces 1100. 930In both the binary numbers, the leftmost two bits are set (i.e., they 931are 1's), so the leftmost two bits of the returned value are set. 932However, for the rightmost two bits, each is zero in at least one of 933the arguments, so the rightmost two bits of the returned value are 0's. 934 935@noindent 936Therefore, 937 938@example 939@group 940(logand 13 12) 941 @result{} 12 942@end group 943@end example 944 945If @code{logand} is not passed any argument, it returns a value of 946@minus{}1. This number is an identity element for @code{logand} 947because its binary representation consists entirely of ones. If 948@code{logand} is passed just one argument, it returns that argument. 949 950@smallexample 951@group 952 ; @r{ 29-bit binary values} 953 954(logand 14 13) ; 14 = @r{0 0000 0000 0000 0000 0000 0000 1110} 955 ; 13 = @r{0 0000 0000 0000 0000 0000 0000 1101} 956 @result{} 12 ; 12 = @r{0 0000 0000 0000 0000 0000 0000 1100} 957@end group 958 959@group 960(logand 14 13 4) ; 14 = @r{0 0000 0000 0000 0000 0000 0000 1110} 961 ; 13 = @r{0 0000 0000 0000 0000 0000 0000 1101} 962 ; 4 = @r{0 0000 0000 0000 0000 0000 0000 0100} 963 @result{} 4 ; 4 = @r{0 0000 0000 0000 0000 0000 0000 0100} 964@end group 965 966@group 967(logand) 968 @result{} -1 ; -1 = @r{1 1111 1111 1111 1111 1111 1111 1111} 969@end group 970@end smallexample 971@end defun 972 973@defun logior &rest ints-or-markers 974This function returns the ``inclusive or'' of its arguments: the @var{n}th bit 975is set in the result if, and only if, the @var{n}th bit is set in at least 976one of the arguments. If there are no arguments, the result is zero, 977which is an identity element for this operation. If @code{logior} is 978passed just one argument, it returns that argument. 979 980@smallexample 981@group 982 ; @r{ 29-bit binary values} 983 984(logior 12 5) ; 12 = @r{0 0000 0000 0000 0000 0000 0000 1100} 985 ; 5 = @r{0 0000 0000 0000 0000 0000 0000 0101} 986 @result{} 13 ; 13 = @r{0 0000 0000 0000 0000 0000 0000 1101} 987@end group 988 989@group 990(logior 12 5 7) ; 12 = @r{0 0000 0000 0000 0000 0000 0000 1100} 991 ; 5 = @r{0 0000 0000 0000 0000 0000 0000 0101} 992 ; 7 = @r{0 0000 0000 0000 0000 0000 0000 0111} 993 @result{} 15 ; 15 = @r{0 0000 0000 0000 0000 0000 0000 1111} 994@end group 995@end smallexample 996@end defun 997 998@defun logxor &rest ints-or-markers 999This function returns the ``exclusive or'' of its arguments: the 1000@var{n}th bit is set in the result if, and only if, the @var{n}th bit is 1001set in an odd number of the arguments. If there are no arguments, the 1002result is 0, which is an identity element for this operation. If 1003@code{logxor} is passed just one argument, it returns that argument. 1004 1005@smallexample 1006@group 1007 ; @r{ 29-bit binary values} 1008 1009(logxor 12 5) ; 12 = @r{0 0000 0000 0000 0000 0000 0000 1100} 1010 ; 5 = @r{0 0000 0000 0000 0000 0000 0000 0101} 1011 @result{} 9 ; 9 = @r{0 0000 0000 0000 0000 0000 0000 1001} 1012@end group 1013 1014@group 1015(logxor 12 5 7) ; 12 = @r{0 0000 0000 0000 0000 0000 0000 1100} 1016 ; 5 = @r{0 0000 0000 0000 0000 0000 0000 0101} 1017 ; 7 = @r{0 0000 0000 0000 0000 0000 0000 0111} 1018 @result{} 14 ; 14 = @r{0 0000 0000 0000 0000 0000 0000 1110} 1019@end group 1020@end smallexample 1021@end defun 1022 1023@defun lognot integer 1024This function returns the logical complement of its argument: the @var{n}th 1025bit is one in the result if, and only if, the @var{n}th bit is zero in 1026@var{integer}, and vice-versa. 1027 1028@example 1029(lognot 5) 1030 @result{} -6 1031;; 5 = @r{0 0000 0000 0000 0000 0000 0000 0101} 1032;; @r{becomes} 1033;; -6 = @r{1 1111 1111 1111 1111 1111 1111 1010} 1034@end example 1035@end defun 1036 1037@node Math Functions 1038@section Standard Mathematical Functions 1039@cindex transcendental functions 1040@cindex mathematical functions 1041@cindex floating-point functions 1042 1043 These mathematical functions allow integers as well as floating point 1044numbers as arguments. 1045 1046@defun sin arg 1047@defunx cos arg 1048@defunx tan arg 1049These are the ordinary trigonometric functions, with argument measured 1050in radians. 1051@end defun 1052 1053@defun asin arg 1054The value of @code{(asin @var{arg})} is a number between 1055@ifnottex 1056@minus{}pi/2 1057@end ifnottex 1058@tex 1059@math{-\pi/2} 1060@end tex 1061and 1062@ifnottex 1063pi/2 1064@end ifnottex 1065@tex 1066@math{\pi/2} 1067@end tex 1068(inclusive) whose sine is @var{arg}; if, however, @var{arg} is out of 1069range (outside [@minus{}1, 1]), it signals a @code{domain-error} error. 1070@end defun 1071 1072@defun acos arg 1073The value of @code{(acos @var{arg})} is a number between 0 and 1074@ifnottex 1075pi 1076@end ifnottex 1077@tex 1078@math{\pi} 1079@end tex 1080(inclusive) whose cosine is @var{arg}; if, however, @var{arg} is out 1081of range (outside [@minus{}1, 1]), it signals a @code{domain-error} error. 1082@end defun 1083 1084@defun atan y &optional x 1085The value of @code{(atan @var{y})} is a number between 1086@ifnottex 1087@minus{}pi/2 1088@end ifnottex 1089@tex 1090@math{-\pi/2} 1091@end tex 1092and 1093@ifnottex 1094pi/2 1095@end ifnottex 1096@tex 1097@math{\pi/2} 1098@end tex 1099(exclusive) whose tangent is @var{y}. If the optional second 1100argument @var{x} is given, the value of @code{(atan y x)} is the 1101angle in radians between the vector @code{[@var{x}, @var{y}]} and the 1102@code{X} axis. 1103@end defun 1104 1105@defun exp arg 1106This is the exponential function; it returns 1107@tex 1108@math{e} 1109@end tex 1110@ifnottex 1111@i{e} 1112@end ifnottex 1113to the power @var{arg}. 1114@tex 1115@math{e} 1116@end tex 1117@ifnottex 1118@i{e} 1119@end ifnottex 1120is a fundamental mathematical constant also called the base of natural 1121logarithms. 1122@end defun 1123 1124@defun log arg &optional base 1125This function returns the logarithm of @var{arg}, with base @var{base}. 1126If you don't specify @var{base}, the base 1127@tex 1128@math{e} 1129@end tex 1130@ifnottex 1131@i{e} 1132@end ifnottex 1133is used. If @var{arg} is negative, it signals a @code{domain-error} 1134error. 1135@end defun 1136 1137@ignore 1138@defun expm1 arg 1139This function returns @code{(1- (exp @var{arg}))}, but it is more 1140accurate than that when @var{arg} is negative and @code{(exp @var{arg})} 1141is close to 1. 1142@end defun 1143 1144@defun log1p arg 1145This function returns @code{(log (1+ @var{arg}))}, but it is more 1146accurate than that when @var{arg} is so small that adding 1 to it would 1147lose accuracy. 1148@end defun 1149@end ignore 1150 1151@defun log10 arg 1152This function returns the logarithm of @var{arg}, with base 10. If 1153@var{arg} is negative, it signals a @code{domain-error} error. 1154@code{(log10 @var{x})} @equiv{} @code{(log @var{x} 10)}, at least 1155approximately. 1156@end defun 1157 1158@defun expt x y 1159This function returns @var{x} raised to power @var{y}. If both 1160arguments are integers and @var{y} is positive, the result is an 1161integer; in this case, overflow causes truncation, so watch out. 1162@end defun 1163 1164@defun sqrt arg 1165This returns the square root of @var{arg}. If @var{arg} is negative, 1166it signals a @code{domain-error} error. 1167@end defun 1168 1169@node Random Numbers 1170@section Random Numbers 1171@cindex random numbers 1172 1173A deterministic computer program cannot generate true random numbers. 1174For most purposes, @dfn{pseudo-random numbers} suffice. A series of 1175pseudo-random numbers is generated in a deterministic fashion. The 1176numbers are not truly random, but they have certain properties that 1177mimic a random series. For example, all possible values occur equally 1178often in a pseudo-random series. 1179 1180In Emacs, pseudo-random numbers are generated from a ``seed'' number. 1181Starting from any given seed, the @code{random} function always 1182generates the same sequence of numbers. Emacs always starts with the 1183same seed value, so the sequence of values of @code{random} is actually 1184the same in each Emacs run! For example, in one operating system, the 1185first call to @code{(random)} after you start Emacs always returns 1186@minus{}1457731, and the second one always returns @minus{}7692030. This 1187repeatability is helpful for debugging. 1188 1189If you want random numbers that don't always come out the same, execute 1190@code{(random t)}. This chooses a new seed based on the current time of 1191day and on Emacs's process @acronym{ID} number. 1192 1193@defun random &optional limit 1194This function returns a pseudo-random integer. Repeated calls return a 1195series of pseudo-random integers. 1196 1197If @var{limit} is a positive integer, the value is chosen to be 1198nonnegative and less than @var{limit}. 1199 1200If @var{limit} is @code{t}, it means to choose a new seed based on the 1201current time of day and on Emacs's process @acronym{ID} number. 1202@c "Emacs'" is incorrect usage! 1203 1204On some machines, any integer representable in Lisp may be the result 1205of @code{random}. On other machines, the result can never be larger 1206than a certain maximum or less than a certain (negative) minimum. 1207@end defun 1208 1209@ignore 1210 arch-tag: 574e8dd2-d513-4616-9844-c9a27869782e 1211@end ignore 1212