-This is Info file ../info/lispref.info, produced by Makeinfo version
-1.68 from the input file lispref/lispref.texi.
+This is ../info/lispref.info, produced by makeinfo version 4.0 from
+lispref/lispref.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
The most general way to check the type of an object is to call the
function `type-of'. Recall that each object belongs to one and only
one primitive type; `type-of' tells you which one (*note Lisp Data
-Types::.). But `type-of' knows nothing about non-primitive types. In
+Types::). But `type-of' knows nothing about non-primitive types. In
most cases, it is more convenient to use type predicates than `type-of'.
- - Function: type-of OBJECT
+ - Function: type-of object
This function returns a symbol naming the primitive type of
OBJECT. The value is one of `bit-vector', `buffer', `char-table',
`character', `charset', `coding-system', `cons', `color-instance',
types, e.g., strings. For these predicates, see the appropriate chapter
describing the data type.
- - Function: eq OBJECT1 OBJECT2
+ - Function: eq object1 object2
This function returns `t' if OBJECT1 and OBJECT2 are the same
object, `nil' otherwise. The "same object" means that a change in
one will be reflected by the same change in the other.
=> nil
- - Function: old-eq OBJ1 OBJ2
+ - Function: old-eq object1 object2
This function exists under XEmacs 20 and is exactly like `eq'
except that it suffers from the char-int confoundance disease. In
other words, it returns `t' if given a character and the
equivalent integer, even though the objects are of different types!
- You should *not* ever call this function explicitly in your code.
+ You should _not_ ever call this function explicitly in your code.
However, be aware that all calls to `eq' in byte code compiled
under version 19 map to `old-eq' in XEmacs 20. (Likewise for
`old-equal', `old-memq', `old-member', `old-assq' and
(eq ?A 65)
=> nil ; We are still healthy.
- - Function: equal OBJECT1 OBJECT2
+ - Function: equal object1 object2
This function returns `t' if OBJECT1 and OBJECT2 have equal
components, `nil' otherwise. Whereas `eq' tests if its arguments
are the same object, `equal' looks inside nonidentical arguments
-0 ; The integer 0.
To understand how various functions work on integers, especially the
-bitwise operators (*note Bitwise Operations::.), it is often helpful to
+bitwise operators (*note Bitwise Operations::), it is often helpful to
view the numbers in their binary form.
In 28-bit binary, the decimal integer 5 looks like this:
You can use `logb' to extract the binary exponent of a floating
point number (or estimate the logarithm of an integer):
- - Function: logb NUMBER
+ - Function: logb number
This function returns the binary exponent of NUMBER. More
precisely, the value is the logarithm of NUMBER base 2, rounded
down to an integer.
`integer-or-marker-p', `integer-char-or-marker-p', `number-or-marker-p'
and `number-char-or-marker-p', in *Note Predicates on Markers::.
- - Function: floatp OBJECT
+ - Function: floatp object
This predicate tests whether its argument is a floating point
number and returns `t' if so, `nil' otherwise.
`floatp' does not exist in Emacs versions 18 and earlier.
- - Function: integerp OBJECT
+ - Function: integerp object
This predicate tests whether its argument is an integer, and
returns `t' if so, `nil' otherwise.
- - Function: numberp OBJECT
+ - Function: numberp object
This predicate tests whether its argument is a number (either
integer or floating point), and returns `t' if so, `nil' otherwise.
- - Function: natnump OBJECT
+ - Function: natnump object
The `natnump' predicate (whose name comes from the phrase
"natural-number-p") tests to see whether its argument is a
nonnegative integer, and returns `t' if so, `nil' otherwise. 0 is
considered non-negative.
- - Function: zerop NUMBER
+ - Function: zerop number
This predicate tests whether its argument is zero, and returns `t'
if so, `nil' otherwise. The argument must be a number.
To test numbers for numerical equality, you should normally use `=',
not `eq'. There can be many distinct floating point number objects
with the same numeric value. If you use `eq' to compare them, then you
-test whether two values are the same *object*. By contrast, `='
+test whether two values are the same _object_. By contrast, `='
compares only the numeric values of the objects.
At present, each integer value has a unique Lisp object in XEmacs
characters and markers as arguments, and treat them as their number
equivalents.
- - Function: = NUMBER &rest MORE-NUMBERS
+ - Function: = number &rest more-numbers
This function returns `t' if all of its arguments are numerically
equal, `nil' otherwise.
(= 5 5 6)
=> nil
- - Function: /= NUMBER &rest MORE-NUMBERS
+ - Function: /= number &rest more-numbers
This function returns `t' if no two arguments are numerically
equal, `nil' otherwise.
(/= 5 6 1)
=> t
- - Function: < NUMBER &rest MORE-NUMBERS
+ - Function: < number &rest more-numbers
This function returns `t' if the sequence of its arguments is
monotonically increasing, `nil' otherwise.
(< 5 6 7)
=> t
- - Function: <= NUMBER &rest MORE-NUMBERS
+ - Function: <= number &rest more-numbers
This function returns `t' if the sequence of its arguments is
monotonically nondecreasing, `nil' otherwise.
(<= 5 6 5)
=> nil
- - Function: > NUMBER &rest MORE-NUMBERS
+ - Function: > number &rest more-numbers
This function returns `t' if the sequence of its arguments is
monotonically decreasing, `nil' otherwise.
- - Function: >= NUMBER &rest MORE-NUMBERS
+ - Function: >= number &rest more-numbers
This function returns `t' if the sequence of its arguments is
monotonically nonincreasing, `nil' otherwise.
- - Function: max NUMBER &rest MORE-NUMBERS
+ - Function: max number &rest more-numbers
This function returns the largest of its arguments.
(max 20)
(max 1 3 2.5)
=> 3
- - Function: min NUMBER &rest MORE-NUMBERS
+ - Function: min number &rest more-numbers
This function returns the smallest of its arguments.
(min -4 1)
To convert an integer to floating point, use the function `float'.
- - Function: float NUMBER
+ - Function: float number
This returns NUMBER converted to floating point. If NUMBER is
already a floating point number, `float' returns it unchanged.
integers; they differ in how they round. These functions accept
integer arguments also, and return such arguments unchanged.
- - Function: truncate NUMBER
+ - Function: truncate number
This returns NUMBER, converted to an integer by rounding towards
zero.
- - Function: floor NUMBER &optional DIVISOR
+ - Function: floor number &optional divisor
This returns NUMBER, converted to an integer by rounding downward
(towards negative infinity).
floor is taken; this is the division operation that corresponds to
`mod'. An `arith-error' results if DIVISOR is 0.
- - Function: ceiling NUMBER
+ - Function: ceiling number
This returns NUMBER, converted to an integer by rounding upward
(towards positive infinity).
- - Function: round NUMBER
+ - Function: round number
This returns NUMBER, converted to an integer by rounding towards
the nearest integer. Rounding a value equidistant between two
integers may choose the integer closer to zero, or it may prefer
not check for overflow. Thus `(1+ 134217727)' may evaluate to
-134217728, depending on your hardware.
- - Function: 1+ NUMBER-OR-MARKER
- This function returns NUMBER-OR-MARKER plus 1. For example,
+ - Function: 1+ number
+ This function returns NUMBER plus one. NUMBER may be a number,
+ character or marker. Markers and characters are converted to
+ integers.
+
+ For example,
(setq foo 4)
=> 4
more convenient and natural way to increment a variable is
`(incf foo)'.
- - Function: 1- NUMBER-OR-MARKER
- This function returns NUMBER-OR-MARKER minus 1.
+ - Function: 1- number
+ This function returns NUMBER minus one. NUMBER may be a number,
+ character or marker. Markers and characters are converted to
+ integers.
- - Function: abs NUMBER
+ - Function: abs number
This returns the absolute value of NUMBER.
- - Function: + &rest NUMBERS-OR-MARKERS
+ - Function: + &rest numbers
This function adds its arguments together. When given no
arguments, `+' returns 0.
+ If any of the arguments are characters or markers, they are first
+ converted to integers.
+
(+)
=> 0
(+ 1)
(+ 1 2 3 4)
=> 10
- - Function: - &optional NUMBER-OR-MARKER &rest OTHER-NUMBERS-OR-MARKERS
+ - Function: - &optional number &rest other-numbers
The `-' function serves two purposes: negation and subtraction.
When `-' has a single argument, the value is the negative of the
argument. When there are multiple arguments, `-' subtracts each of
- the OTHER-NUMBERS-OR-MARKERS from NUMBER-OR-MARKER, cumulatively.
- If there are no arguments, the result is 0.
+ the OTHER-NUMBERS from NUMBER, cumulatively. If there are no
+ arguments, an error is signaled.
+
+ If any of the arguments are characters or markers, they are first
+ converted to integers.
(- 10 1 2 3 4)
=> 0
(-)
=> 0
- - Function: * &rest NUMBERS-OR-MARKERS
+ - Function: * &rest numbers
This function multiplies its arguments together, and returns the
product. When given no arguments, `*' returns 1.
+ If any of the arguments are characters or markers, they are first
+ converted to integers.
+
(*)
=> 1
(* 1)
(* 1 2 3 4)
=> 24
- - Function: / DIVIDEND DIVISOR &rest DIVISORS
- This function divides DIVIDEND by DIVISOR and returns the
- quotient. If there are additional arguments DIVISORS, then it
- divides DIVIDEND by each divisor in turn. Each argument may be a
- number or a marker.
+ - Function: / dividend &rest divisors
+ The `/' function serves two purposes: inversion and division. When
+ `/' has a single argument, the value is the inverse of the
+ argument. When there are multiple arguments, `/' divides DIVIDEND
+ by each of the DIVISORS, cumulatively, returning the quotient. If
+ there are no arguments, an error is signaled.
- If all the arguments are integers, then the result is an integer
- too. This means the result has to be rounded. On most machines,
- the result is rounded towards zero after each division, but some
+ If none of the arguments are floats, then the result is an integer.
+ This means the result has to be rounded. On most machines, the
+ result is rounded towards zero after each division, but some
machines may round differently with negative arguments. This is
because the Lisp function `/' is implemented using the C division
operator, which also permits machine-dependent rounding. As a
practical matter, all known machines round in the standard fashion.
+ If any of the arguments are characters or markers, they are first
+ converted to integers.
+
If you divide by 0, an `arith-error' error is signaled. (*Note
Errors::.)
=> 2
(/ 25 3 2)
=> 4
+ (/ 3.0)
+ => 0.3333333333333333
(/ -17 6)
=> -2
The result of `(/ -17 6)' could in principle be -3 on some
machines.
- - Function: % DIVIDEND DIVISOR
+ - Function: % dividend divisor
This function returns the integer remainder after division of
DIVIDEND by DIVISOR. The arguments must be integers or markers.
always equals DIVIDEND.
- - Function: mod DIVIDEND DIVISOR
+ - Function: mod dividend divisor
This function returns the value of DIVIDEND modulo DIVISOR; in
other words, the remainder after division of DIVIDEND by DIVISOR,
but with the same sign as DIVISOR. The arguments must be numbers
`fceiling', the nearest integer above; `ftruncate', the nearest integer
in the direction towards zero; `fround', the nearest integer.
- - Function: ffloor FLOAT
- This function rounds FLOAT to the next lower integral value, and
+ - Function: ffloor number
+ This function rounds NUMBER to the next lower integral value, and
returns that value as a floating point number.
- - Function: fceiling FLOAT
- This function rounds FLOAT to the next higher integral value, and
+ - Function: fceiling number
+ This function rounds NUMBER to the next higher integral value, and
returns that value as a floating point number.
- - Function: ftruncate FLOAT
- This function rounds FLOAT towards zero to an integral value, and
+ - Function: ftruncate number
+ This function rounds NUMBER towards zero to an integral value, and
returns that value as a floating point number.
- - Function: fround FLOAT
- This function rounds FLOAT to the nearest integral value, and
+ - Function: fround number
+ This function rounds NUMBER to the nearest integral value, and
returns that value as a floating point number.
\1f
The bitwise operations in XEmacs Lisp apply only to integers.
- - Function: lsh INTEGER1 COUNT
+ - Function: lsh integer1 count
`lsh', which is an abbreviation for "logical shift", shifts the
bits in INTEGER1 to the left COUNT places, or to the right if
COUNT is negative, bringing zeros into the vacated bits. If COUNT
;; Decimal -2
1111 1111 1111 1111 1111 1111 1110
- - Function: ash INTEGER1 COUNT
+ - Function: ash integer1 count
`ash' ("arithmetic shift") shifts the bits in INTEGER1 to the left
COUNT places, or to the right if COUNT is negative.
Here are other examples:
- ; 28-bit binary values
+ ; 28-bit binary values
(lsh 5 2) ; 5 = 0000 0000 0000 0000 0000 0000 0101
=> 20 ; = 0000 0000 0000 0000 0000 0001 0100
-
(ash 5 2)
=> 20
(lsh -5 2) ; -5 = 1111 1111 1111 1111 1111 1111 1011
=> -20 ; = 1111 1111 1111 1111 1111 1110 1100
(ash -5 2)
=> -20
-
(lsh 5 -2) ; 5 = 0000 0000 0000 0000 0000 0000 0101
=> 1 ; = 0000 0000 0000 0000 0000 0000 0001
-
(ash 5 -2)
=> 1
-
(lsh -5 -2) ; -5 = 1111 1111 1111 1111 1111 1111 1011
=> 4194302 ; = 0011 1111 1111 1111 1111 1111 1110
-
(ash -5 -2) ; -5 = 1111 1111 1111 1111 1111 1111 1011
=> -2 ; = 1111 1111 1111 1111 1111 1111 1110
- - Function: logand &rest INTS-OR-MARKERS
+ - Function: logand &rest ints-or-markers
This function returns the "logical and" of the arguments: the Nth
bit is set in the result if, and only if, the Nth bit is set in
all the arguments. ("Set" means that the value of the bit is 1
representation consists entirely of ones. If `logand' is passed
just one argument, it returns that argument.
- ; 28-bit binary values
+ ; 28-bit binary values
(logand 14 13) ; 14 = 0000 0000 0000 0000 0000 0000 1110
; 13 = 0000 0000 0000 0000 0000 0000 1101
=> 12 ; 12 = 0000 0000 0000 0000 0000 0000 1100
-
+
(logand 14 13 4) ; 14 = 0000 0000 0000 0000 0000 0000 1110
; 13 = 0000 0000 0000 0000 0000 0000 1101
; 4 = 0000 0000 0000 0000 0000 0000 0100
=> 4 ; 4 = 0000 0000 0000 0000 0000 0000 0100
-
+
(logand)
=> -1 ; -1 = 1111 1111 1111 1111 1111 1111 1111
- - Function: logior &rest INTS-OR-MARKERS
+ - Function: logior &rest ints-or-markers
This function returns the "inclusive or" of its arguments: the Nth
bit is set in the result if, and only if, the Nth bit is set in at
least one of the arguments. If there are no arguments, the result
is zero, which is an identity element for this operation. If
`logior' is passed just one argument, it returns that argument.
- ; 28-bit binary values
+ ; 28-bit binary values
(logior 12 5) ; 12 = 0000 0000 0000 0000 0000 0000 1100
; 5 = 0000 0000 0000 0000 0000 0000 0101
=> 13 ; 13 = 0000 0000 0000 0000 0000 0000 1101
-
+
(logior 12 5 7) ; 12 = 0000 0000 0000 0000 0000 0000 1100
; 5 = 0000 0000 0000 0000 0000 0000 0101
; 7 = 0000 0000 0000 0000 0000 0000 0111
=> 15 ; 15 = 0000 0000 0000 0000 0000 0000 1111
- - Function: logxor &rest INTS-OR-MARKERS
+ - Function: logxor &rest ints-or-markers
This function returns the "exclusive or" of its arguments: the Nth
bit is set in the result if, and only if, the Nth bit is set in an
odd number of the arguments. If there are no arguments, the
result is 0, which is an identity element for this operation. If
`logxor' is passed just one argument, it returns that argument.
- ; 28-bit binary values
+ ; 28-bit binary values
(logxor 12 5) ; 12 = 0000 0000 0000 0000 0000 0000 1100
; 5 = 0000 0000 0000 0000 0000 0000 0101
=> 9 ; 9 = 0000 0000 0000 0000 0000 0000 1001
-
+
(logxor 12 5 7) ; 12 = 0000 0000 0000 0000 0000 0000 1100
; 5 = 0000 0000 0000 0000 0000 0000 0101
; 7 = 0000 0000 0000 0000 0000 0000 0111
=> 14 ; 14 = 0000 0000 0000 0000 0000 0000 1110
- - Function: lognot INTEGER
+ - Function: lognot integer
This function returns the logical complement of its argument: the
Nth bit is one in the result if, and only if, the Nth bit is zero
in INTEGER, and vice-versa.
supported (which is the normal state of affairs). They allow integers
as well as floating point numbers as arguments.
- - Function: sin ARG
- - Function: cos ARG
- - Function: tan ARG
+ - Function: sin number
+ - Function: cos number
+ - Function: tan number
These are the ordinary trigonometric functions, with argument
measured in radians.
- - Function: asin ARG
- The value of `(asin ARG)' is a number between -pi/2 and pi/2
- (inclusive) whose sine is ARG; if, however, ARG is out of range
- (outside [-1, 1]), then the result is a NaN.
+ - Function: asin number
+ The value of `(asin NUMBER)' is a number between -pi/2 and pi/2
+ (inclusive) whose sine is NUMBER; if, however, NUMBER is out of
+ range (outside [-1, 1]), then the result is a NaN.
+
+ - Function: acos number
+ The value of `(acos NUMBER)' is a number between 0 and pi
+ (inclusive) whose cosine is NUMBER; if, however, NUMBER is out of
+ range (outside [-1, 1]), then the result is a NaN.
- - Function: acos ARG
- The value of `(acos ARG)' is a number between 0 and pi (inclusive)
- whose cosine is ARG; if, however, ARG is out of range (outside
- [-1, 1]), then the result is a NaN.
+ - Function: atan number &optional number2
+ The value of `(atan NUMBER)' is a number between -pi/2 and pi/2
+ (exclusive) whose tangent is NUMBER.
- - Function: atan ARG
- The value of `(atan ARG)' is a number between -pi/2 and pi/2
- (exclusive) whose tangent is ARG.
+ If optional argument NUMBER2 is supplied, the function returns
+ `atan2(NUMBER,NUMBER2)'.
- - Function: sinh ARG
- - Function: cosh ARG
- - Function: tanh ARG
+ - Function: sinh number
+ - Function: cosh number
+ - Function: tanh number
These are the ordinary hyperbolic trigonometric functions.
- - Function: asinh ARG
- - Function: acosh ARG
- - Function: atanh ARG
+ - Function: asinh number
+ - Function: acosh number
+ - Function: atanh number
These are the inverse hyperbolic trigonometric functions.
- - Function: exp ARG
- This is the exponential function; it returns e to the power ARG.
- e is a fundamental mathematical constant also called the base of
- natural logarithms.
+ - Function: exp number
+ This is the exponential function; it returns e to the power
+ NUMBER. e is a fundamental mathematical constant also called the
+ base of natural logarithms.
- - Function: log ARG &optional BASE
- This function returns the logarithm of ARG, with base BASE. If
- you don't specify BASE, the base E is used. If ARG is negative,
- the result is a NaN.
+ - Function: log number &optional base
+ This function returns the logarithm of NUMBER, with base BASE. If
+ you don't specify BASE, the base E is used. If NUMBER is
+ negative, the result is a NaN.
- - Function: log10 ARG
- This function returns the logarithm of ARG, with base 10. If ARG
- is negative, the result is a NaN. `(log10 X)' == `(log X 10)', at
- least approximately.
+ - Function: log10 number
+ This function returns the logarithm of NUMBER, with base 10. If
+ NUMBER is negative, the result is a NaN. `(log10 X)' == `(log X
+ 10)', at least approximately.
- - Function: expt X Y
+ - Function: expt x y
This function returns X raised to power Y. If both arguments are
integers and Y is positive, the result is an integer; in this
case, it is truncated to fit the range of possible integer values.
- - Function: sqrt ARG
- This returns the square root of ARG. If ARG is negative, the
- value is a NaN.
+ - Function: sqrt number
+ This returns the square root of NUMBER. If NUMBER is negative,
+ the value is a NaN.
- - Function: cube-root ARG
- This returns the cube root of ARG.
+ - Function: cube-root number
+ This returns the cube root of NUMBER.
\1f
File: lispref.info, Node: Random Numbers, Prev: Math Functions, Up: Numbers
t)'. This chooses a new seed based on the current time of day and on
XEmacs's process ID number.
- - Function: random &optional LIMIT
+ - Function: random &optional limit
This function returns a pseudo-random integer. Repeated calls
return a series of pseudo-random integers.
* Menu:
-* Basics: String Basics. Basic properties of strings and characters.
+* String Basics:: Basic properties of strings and characters.
* Predicates for Strings:: Testing whether an object is a string or char.
* Creating Strings:: Functions to allocate new strings.
* Predicates for Characters:: Testing whether an object is a character.