Mercurial > hg > xemacs-beta

comparison man/lispref/numbers.texi @ 444:576fb035e263 r21-2-37

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Import from CVS: tag r21-2-37
author cvs
date Mon, 13 Aug 2007 11:36:19 +0200
parents 3ecd8885ac67
children f43f9ca6c7d9
comparison
equal deleted inserted replaced
443:a8296e22da4e 444:576fb035e263
1 @c -*-texinfo-*- 1 @c -*-texinfo-*-
2 @c This is part of the XEmacs Lisp Reference Manual. 2 @c This is part of the XEmacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. 3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
4 @c See the file lispref.texi for copying conditions. 4 @c See the file lispref.texi for copying conditions.
5 @setfilename ../../info/numbers.info 5 @setfilename ../../info/numbers.info
6 @node Numbers, Strings and Characters, Lisp Data Types, Top 6 @node Numbers, Strings and Characters, Lisp Data Types, Top
7 @chapter Numbers 7 @chapter Numbers
8 @cindex integers 8 @cindex integers
35 @node Integer Basics 35 @node Integer Basics
36 @section Integer Basics 36 @section Integer Basics
37 37
38 The range of values for an integer depends on the machine. The 38 The range of values for an integer depends on the machine. The
39 minimum range is @minus{}134217728 to 134217727 (28 bits; i.e., 39 minimum range is @minus{}134217728 to 134217727 (28 bits; i.e.,
40 @ifinfo 40 @ifinfo
41 -2**27 41 -2**27
42 @end ifinfo 42 @end ifinfo
43 @tex 43 @tex
44 $-2^{27}$ 44 $-2^{27}$
45 @end tex 45 @end tex
46 to 46 to
47 @ifinfo 47 @ifinfo
48 2**27 - 1), 48 2**27 - 1),
49 @end ifinfo 49 @end ifinfo
50 @tex 50 @tex
51 $2^{27}-1$), 51 $2^{27}-1$),
52 @end tex 52 @end tex
53 but some machines may provide a wider range. Many examples in this 53 but some machines may provide a wider range. Many examples in this
54 chapter assume an integer has 28 bits. 54 chapter assume an integer has 28 bits.
55 @cindex overflow 55 @cindex overflow
408 408
409 It is important to note that in XEmacs Lisp, arithmetic functions 409 It is important to note that in XEmacs Lisp, arithmetic functions
410 do not check for overflow. Thus @code{(1+ 134217727)} may evaluate to 410 do not check for overflow. Thus @code{(1+ 134217727)} may evaluate to
411 @minus{}134217728, depending on your hardware. 411 @minus{}134217728, depending on your hardware.
412 412
413 @defun 1+ number-or-marker 413 @defun 1+ number
414 This function returns @var{number-or-marker} plus 1. 414 This function returns @var{number} plus one. @var{number} may be a
415 number, character or marker. Markers and characters are converted to
416 integers.
417
415 For example, 418 For example,
416 419
417 @example 420 @example
418 (setq foo 4) 421 (setq foo 4)
419 @result{} 4 422 @result{} 4
440 Now that the @code{cl} package is always available from lisp code, a 443 Now that the @code{cl} package is always available from lisp code, a
441 more convenient and natural way to increment a variable is 444 more convenient and natural way to increment a variable is
442 @w{@code{(incf foo)}}. 445 @w{@code{(incf foo)}}.
443 @end defun 446 @end defun
444 447
445 @defun 1- number-or-marker 448 @defun 1- number
446 This function returns @var{number-or-marker} minus 1. 449 This function returns @var{number} minus one. @var{number} may be a
450 number, character or marker. Markers and characters are converted to
451 integers.
447 @end defun 452 @end defun
448 453
449 @defun abs number 454 @defun abs number
450 This returns the absolute value of @var{number}. 455 This returns the absolute value of @var{number}.
451 @end defun 456 @end defun
452 457
453 @defun + &rest numbers-or-markers 458 @defun + &rest numbers
454 This function adds its arguments together. When given no arguments, 459 This function adds its arguments together. When given no arguments,
455 @code{+} returns 0. 460 @code{+} returns 0.
461
462 If any of the arguments are characters or markers, they are first
463 converted to integers.
456 464
457 @example 465 @example
458 (+) 466 (+)
459 @result{} 0 467 @result{} 0
460 (+ 1) 468 (+ 1)
462 (+ 1 2 3 4) 470 (+ 1 2 3 4)
463 @result{} 10 471 @result{} 10
464 @end example 472 @end example
465 @end defun 473 @end defun
466 474
467 @defun - &optional number-or-marker &rest other-numbers-or-markers 475 @defun - &optional number &rest other-numbers
468 The @code{-} function serves two purposes: negation and subtraction. 476 The @code{-} function serves two purposes: negation and subtraction.
469 When @code{-} has a single argument, the value is the negative of the 477 When @code{-} has a single argument, the value is the negative of the
470 argument. When there are multiple arguments, @code{-} subtracts each of 478 argument. When there are multiple arguments, @code{-} subtracts each of
471 the @var{other-numbers-or-markers} from @var{number-or-marker}, 479 the @var{other-numbers} from @var{number}, cumulatively. If there are
472 cumulatively. If there are no arguments, the result is 0. 480 no arguments, an error is signaled.
481
482 If any of the arguments are characters or markers, they are first
483 converted to integers.
473 484
474 @example 485 @example
475 (- 10 1 2 3 4) 486 (- 10 1 2 3 4)
476 @result{} 0 487 @result{} 0
477 (- 10) 488 (- 10)
479 (-) 490 (-)
480 @result{} 0 491 @result{} 0
481 @end example 492 @end example
482 @end defun 493 @end defun
483 494
484 @defun * &rest numbers-or-markers 495 @defun * &rest numbers
485 This function multiplies its arguments together, and returns the 496 This function multiplies its arguments together, and returns the
486 product. When given no arguments, @code{*} returns 1. 497 product. When given no arguments, @code{*} returns 1.
498
499 If any of the arguments are characters or markers, they are first
500 converted to integers.
487 501
488 @example 502 @example
489 (*) 503 (*)
490 @result{} 1 504 @result{} 1
491 (* 1) 505 (* 1)
493 (* 1 2 3 4) 507 (* 1 2 3 4)
494 @result{} 24 508 @result{} 24
495 @end example 509 @end example
496 @end defun 510 @end defun
497 511
498 @defun / dividend divisor &rest divisors 512 @defun / dividend &rest divisors
499 This function divides @var{dividend} by @var{divisor} and returns the 513 The @code{/} function serves two purposes: inversion and division. When
500 quotient. If there are additional arguments @var{divisors}, then it 514 @code{/} has a single argument, the value is the inverse of the
501 divides @var{dividend} by each divisor in turn. Each argument may be a 515 argument. When there are multiple arguments, @code{/} divides
502 number or a marker. 516 @var{dividend} by each of the @var{divisors}, cumulatively, returning
503 517 the quotient. If there are no arguments, an error is signaled.
504 If all the arguments are integers, then the result is an integer too. 518
519 If none of the arguments are floats, then the result is an integer.
505 This means the result has to be rounded. On most machines, the result 520 This means the result has to be rounded. On most machines, the result
506 is rounded towards zero after each division, but some machines may round 521 is rounded towards zero after each division, but some machines may round
507 differently with negative arguments. This is because the Lisp function 522 differently with negative arguments. This is because the Lisp function
508 @code{/} is implemented using the C division operator, which also 523 @code{/} is implemented using the C division operator, which also
509 permits machine-dependent rounding. As a practical matter, all known 524 permits machine-dependent rounding. As a practical matter, all known
510 machines round in the standard fashion. 525 machines round in the standard fashion.
511 526
527 If any of the arguments are characters or markers, they are first
528 converted to integers.
529
512 @cindex @code{arith-error} in division 530 @cindex @code{arith-error} in division
513 If you divide by 0, an @code{arith-error} error is signaled. 531 If you divide by 0, an @code{arith-error} error is signaled.
514 (@xref{Errors}.) 532 (@xref{Errors}.)
515 533
516 @example 534 @example
520 @end group 538 @end group
521 (/ 5 2) 539 (/ 5 2)
522 @result{} 2 540 @result{} 2
523 (/ 25 3 2) 541 (/ 25 3 2)
524 @result{} 4 542 @result{} 4
543 (/ 3.0)
544 @result{} 0.3333333333333333
525 (/ -17 6) 545 (/ -17 6)
526 @result{} -2 546 @result{} -2
527 @end example 547 @end example
528 548
529 The result of @code{(/ -17 6)} could in principle be -3 on some 549 The result of @code{(/ -17 6)} could in principle be -3 on some
625 point result whose value is a nearby integer. @code{ffloor} returns the 645 point result whose value is a nearby integer. @code{ffloor} returns the
626 nearest integer below; @code{fceiling}, the nearest integer above; 646 nearest integer below; @code{fceiling}, the nearest integer above;
627 @code{ftruncate}, the nearest integer in the direction towards zero; 647 @code{ftruncate}, the nearest integer in the direction towards zero;
628 @code{fround}, the nearest integer. 648 @code{fround}, the nearest integer.
629 649
630 @defun ffloor float 650 @defun ffloor number
631 This function rounds @var{float} to the next lower integral value, and 651 This function rounds @var{number} to the next lower integral value, and
632 returns that value as a floating point number. 652 returns that value as a floating point number.
633 @end defun 653 @end defun
634 654
635 @defun fceiling float 655 @defun fceiling number
636 This function rounds @var{float} to the next higher integral value, and 656 This function rounds @var{number} to the next higher integral value, and
637 returns that value as a floating point number. 657 returns that value as a floating point number.
638 @end defun 658 @end defun
639 659
640 @defun ftruncate float 660 @defun ftruncate number
641 This function rounds @var{float} towards zero to an integral value, and 661 This function rounds @var{number} towards zero to an integral value, and
642 returns that value as a floating point number. 662 returns that value as a floating point number.
643 @end defun 663 @end defun
644 664
645 @defun fround float 665 @defun fround number
646 This function rounds @var{float} to the nearest integral value, 666 This function rounds @var{number} to the nearest integral value,
647 and returns that value as a floating point number. 667 and returns that value as a floating point number.
648 @end defun 668 @end defun
649 669
650 @node Bitwise Operations 670 @node Bitwise Operations
651 @section Bitwise Operations on Integers 671 @section Bitwise Operations on Integers
696 @example 716 @example
697 @group 717 @group
698 (lsh 3 2) 718 (lsh 3 2)
699 @result{} 12 719 @result{} 12
700 ;; @r{Decimal 3 becomes decimal 12.} 720 ;; @r{Decimal 3 becomes decimal 12.}
701 00000011 @result{} 00001100 721 00000011 @result{} 00001100
702 @end group 722 @end group
703 @end example 723 @end example
704 724
705 On the other hand, shifting one place to the right looks like this: 725 On the other hand, shifting one place to the right looks like this:
706 726
707 @example 727 @example
708 @group 728 @group
709 (lsh 6 -1) 729 (lsh 6 -1)
710 @result{} 3 730 @result{} 3
711 ;; @r{Decimal 6 becomes decimal 3.} 731 ;; @r{Decimal 6 becomes decimal 3.}
712 00000110 @result{} 00000011 732 00000110 @result{} 00000011
713 @end group 733 @end group
714 734
715 @group 735 @group
716 (lsh 5 -1) 736 (lsh 5 -1)
717 @result{} 2 737 @result{} 2
718 ;; @r{Decimal 5 becomes decimal 2.} 738 ;; @r{Decimal 5 becomes decimal 2.}
719 00000101 @result{} 00000010 739 00000101 @result{} 00000010
720 @end group 740 @end group
721 @end example 741 @end example
722 742
723 @noindent 743 @noindent
724 As the example illustrates, shifting one place to the right divides the 744 As the example illustrates, shifting one place to the right divides the
737 In binary, in the 28-bit implementation, the argument looks like this: 757 In binary, in the 28-bit implementation, the argument looks like this:
738 758
739 @example 759 @example
740 @group 760 @group
741 ;; @r{Decimal 134,217,727} 761 ;; @r{Decimal 134,217,727}
742 0111 1111 1111 1111 1111 1111 1111 762 0111 1111 1111 1111 1111 1111 1111
743 @end group 763 @end group
744 @end example 764 @end example
745 765
746 @noindent 766 @noindent
747 which becomes the following when left shifted: 767 which becomes the following when left shifted:
748 768
749 @example 769 @example
750 @group 770 @group
751 ;; @r{Decimal @minus{}2} 771 ;; @r{Decimal @minus{}2}
752 1111 1111 1111 1111 1111 1111 1110 772 1111 1111 1111 1111 1111 1111 1110
753 @end group 773 @end group
754 @end example 774 @end example
755 @end defun 775 @end defun
756 776
757 @defun ash integer1 count 777 @defun ash integer1 count
768 Thus, with @code{ash}, shifting the pattern of bits one place to the right 788 Thus, with @code{ash}, shifting the pattern of bits one place to the right
769 looks like this: 789 looks like this:
770 790
771 @example 791 @example
772 @group 792 @group
773 (ash -6 -1) @result{} -3 793 (ash -6 -1) @result{} -3
774 ;; @r{Decimal @minus{}6 becomes decimal @minus{}3.} 794 ;; @r{Decimal @minus{}6 becomes decimal @minus{}3.}
775 1111 1111 1111 1111 1111 1111 1010 795 1111 1111 1111 1111 1111 1111 1010
776 @result{} 796 @result{}
777 1111 1111 1111 1111 1111 1111 1101 797 1111 1111 1111 1111 1111 1111 1101
778 @end group 798 @end group
779 @end example 799 @end example
780 800
781 In contrast, shifting the pattern of bits one place to the right with 801 In contrast, shifting the pattern of bits one place to the right with
784 @example 804 @example
785 @group 805 @group
786 (lsh -6 -1) @result{} 134217725 806 (lsh -6 -1) @result{} 134217725
787 ;; @r{Decimal @minus{}6 becomes decimal 134,217,725.} 807 ;; @r{Decimal @minus{}6 becomes decimal 134,217,725.}
788 1111 1111 1111 1111 1111 1111 1010 808 1111 1111 1111 1111 1111 1111 1010
789 @result{} 809 @result{}
790 0111 1111 1111 1111 1111 1111 1101 810 0111 1111 1111 1111 1111 1111 1101
791 @end group 811 @end group
792 @end example 812 @end example
793 813
794 Here are other examples: 814 Here are other examples:
942 This function returns the logical complement of its argument: the @var{n}th 962 This function returns the logical complement of its argument: the @var{n}th
943 bit is one in the result if, and only if, the @var{n}th bit is zero in 963 bit is one in the result if, and only if, the @var{n}th bit is zero in
944 @var{integer}, and vice-versa. 964 @var{integer}, and vice-versa.
945 965
946 @example 966 @example
947 (lognot 5) 967 (lognot 5)
948 @result{} -6 968 @result{} -6
949 ;; 5 = @r{0000 0000 0000 0000 0000 0000 0101} 969 ;; 5 = @r{0000 0000 0000 0000 0000 0000 0101}
950 ;; @r{becomes} 970 ;; @r{becomes}
951 ;; -6 = @r{1111 1111 1111 1111 1111 1111 1010} 971 ;; -6 = @r{1111 1111 1111 1111 1111 1111 1010}
952 @end example 972 @end example
959 979
960 These mathematical functions are available if floating point is 980 These mathematical functions are available if floating point is
961 supported (which is the normal state of affairs). They allow integers 981 supported (which is the normal state of affairs). They allow integers
962 as well as floating point numbers as arguments. 982 as well as floating point numbers as arguments.
963 983
964 @defun sin arg 984 @defun sin number
965 @defunx cos arg 985 @defunx cos number
966 @defunx tan arg 986 @defunx tan number
967 These are the ordinary trigonometric functions, with argument measured 987 These are the ordinary trigonometric functions, with argument measured
968 in radians. 988 in radians.
969 @end defun 989 @end defun
970 990
971 @defun asin arg 991 @defun asin number
972 The value of @code{(asin @var{arg})} is a number between @minus{}pi/2 992 The value of @code{(asin @var{number})} is a number between @minus{}pi/2
973 and pi/2 (inclusive) whose sine is @var{arg}; if, however, @var{arg} 993 and pi/2 (inclusive) whose sine is @var{number}; if, however, @var{number}
974 is out of range (outside [-1, 1]), then the result is a NaN. 994 is out of range (outside [-1, 1]), then the result is a NaN.
975 @end defun 995 @end defun
976 996
977 @defun acos arg 997 @defun acos number
978 The value of @code{(acos @var{arg})} is a number between 0 and pi 998 The value of @code{(acos @var{number})} is a number between 0 and pi
979 (inclusive) whose cosine is @var{arg}; if, however, @var{arg} 999 (inclusive) whose cosine is @var{number}; if, however, @var{number}
980 is out of range (outside [-1, 1]), then the result is a NaN. 1000 is out of range (outside [-1, 1]), then the result is a NaN.
981 @end defun 1001 @end defun
982 1002
983 @defun atan arg 1003 @defun atan number &optional number2
984 The value of @code{(atan @var{arg})} is a number between @minus{}pi/2 1004 The value of @code{(atan @var{number})} is a number between @minus{}pi/2
985 and pi/2 (exclusive) whose tangent is @var{arg}. 1005 and pi/2 (exclusive) whose tangent is @var{number}.
986 @end defun 1006
987 1007 If optional argument @var{number2} is supplied, the function returns
988 @defun sinh arg 1008 @code{atan2(@var{number},@var{number2})}.
989 @defunx cosh arg 1009 @end defun
990 @defunx tanh arg 1010
1011 @defun sinh number
1012 @defunx cosh number
1013 @defunx tanh number
991 These are the ordinary hyperbolic trigonometric functions. 1014 These are the ordinary hyperbolic trigonometric functions.
992 @end defun 1015 @end defun
993 1016
994 @defun asinh arg 1017 @defun asinh number
995 @defunx acosh arg 1018 @defunx acosh number
996 @defunx atanh arg 1019 @defunx atanh number
997 These are the inverse hyperbolic trigonometric functions. 1020 These are the inverse hyperbolic trigonometric functions.
998 @end defun 1021 @end defun
999 1022
1000 @defun exp arg 1023 @defun exp number
1001 This is the exponential function; it returns @i{e} to the power 1024 This is the exponential function; it returns @i{e} to the power
1002 @var{arg}. @i{e} is a fundamental mathematical constant also called the 1025 @var{number}. @i{e} is a fundamental mathematical constant also called the
1003 base of natural logarithms. 1026 base of natural logarithms.
1004 @end defun 1027 @end defun
1005 1028
1006 @defun log arg &optional base 1029 @defun log number &optional base
1007 This function returns the logarithm of @var{arg}, with base @var{base}. 1030 This function returns the logarithm of @var{number}, with base @var{base}.
1008 If you don't specify @var{base}, the base @var{e} is used. If @var{arg} 1031 If you don't specify @var{base}, the base @var{e} is used. If @var{number}
1009 is negative, the result is a NaN. 1032 is negative, the result is a NaN.
1010 @end defun 1033 @end defun
1011 1034
1012 @ignore 1035 @defun log10 number
1013 @defun expm1 arg 1036 This function returns the logarithm of @var{number}, with base 10. If
1014 This function returns @code{(1- (exp @var{arg}))}, but it is more 1037 @var{number} is negative, the result is a NaN. @code{(log10 @var{x})}
1015 accurate than that when @var{arg} is negative and @code{(exp @var{arg})}
1016 is close to 1.
1017 @end defun
1018
1019 @defun log1p arg
1020 This function returns @code{(log (1+ @var{arg}))}, but it is more
1021 accurate than that when @var{arg} is so small that adding 1 to it would
1022 lose accuracy.
1023 @end defun
1024 @end ignore
1025
1026 @defun log10 arg
1027 This function returns the logarithm of @var{arg}, with base 10. If
1028 @var{arg} is negative, the result is a NaN. @code{(log10 @var{x})}
1029 @equiv{} @code{(log @var{x} 10)}, at least approximately. 1038 @equiv{} @code{(log @var{x} 10)}, at least approximately.
1030 @end defun 1039 @end defun
1031 1040
1032 @defun expt x y 1041 @defun expt x y
1033 This function returns @var{x} raised to power @var{y}. If both 1042 This function returns @var{x} raised to power @var{y}. If both
1034 arguments are integers and @var{y} is positive, the result is an 1043 arguments are integers and @var{y} is positive, the result is an
1035 integer; in this case, it is truncated to fit the range of possible 1044 integer; in this case, it is truncated to fit the range of possible
1036 integer values. 1045 integer values.
1037 @end defun 1046 @end defun
1038 1047
1039 @defun sqrt arg 1048 @defun sqrt number
1040 This returns the square root of @var{arg}. If @var{arg} is negative, 1049 This returns the square root of @var{number}. If @var{number} is negative,
1041 the value is a NaN. 1050 the value is a NaN.
1042 @end defun 1051 @end defun
1043 1052
1044 @defun cube-root arg 1053 @defun cube-root number
1045 This returns the cube root of @var{arg}. 1054 This returns the cube root of @var{number}.
1046 @end defun 1055 @end defun
1047 1056
1048 @node Random Numbers 1057 @node Random Numbers
1049 @section Random Numbers 1058 @section Random Numbers
1050 @cindex random numbers 1059 @cindex random numbers