+++ /dev/null
-This is Info file ../../info/lispref.info, produced by Makeinfo version
-1.68 from the input file lispref.texi.
-
-INFO-DIR-SECTION XEmacs Editor
-START-INFO-DIR-ENTRY
-* Lispref: (lispref). XEmacs Lisp Reference Manual.
-END-INFO-DIR-ENTRY
-
- Edition History:
-
- GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
-Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
-Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
-XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
-GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
-Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
-Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
-Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
-November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
-
- Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
-Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
-Copyright (C) 1995, 1996 Ben Wing.
-
- Permission is granted to make and distribute verbatim copies of this
-manual provided the copyright notice and this permission notice are
-preserved on all copies.
-
- Permission is granted to copy and distribute modified versions of
-this manual under the conditions for verbatim copying, provided that the
-entire resulting derived work is distributed under the terms of a
-permission notice identical to this one.
-
- Permission is granted to copy and distribute translations of this
-manual into another language, under the above conditions for modified
-versions, except that this permission notice may be stated in a
-translation approved by the Foundation.
-
- Permission is granted to copy and distribute modified versions of
-this manual under the conditions for verbatim copying, provided also
-that the section entitled "GNU General Public License" is included
-exactly as in the original, and provided that the entire resulting
-derived work is distributed under the terms of a permission notice
-identical to this one.
-
- Permission is granted to copy and distribute translations of this
-manual into another language, under the above conditions for modified
-versions, except that the section entitled "GNU General Public License"
-may be included in a translation approved by the Free Software
-Foundation instead of in the original English.
-
-\1f
-File: lispref.info, Node: Specifier Type, Next: Font Instance Type, Prev: Glyph Type, Up: Window-System Types
-
-Specifier Type
---------------
-
- (not yet documented)
-
-\1f
-File: lispref.info, Node: Font Instance Type, Next: Color Instance Type, Prev: Specifier Type, Up: Window-System Types
-
-Font Instance Type
-------------------
-
- (not yet documented)
-
-\1f
-File: lispref.info, Node: Color Instance Type, Next: Image Instance Type, Prev: Font Instance Type, Up: Window-System Types
-
-Color Instance Type
--------------------
-
- (not yet documented)
-
-\1f
-File: lispref.info, Node: Image Instance Type, Next: Toolbar Button Type, Prev: Color Instance Type, Up: Window-System Types
-
-Image Instance Type
--------------------
-
- (not yet documented)
-
-\1f
-File: lispref.info, Node: Toolbar Button Type, Next: Subwindow Type, Prev: Image Instance Type, Up: Window-System Types
-
-Toolbar Button Type
--------------------
-
- (not yet documented)
-
-\1f
-File: lispref.info, Node: Subwindow Type, Next: X Resource Type, Prev: Toolbar Button Type, Up: Window-System Types
-
-Subwindow Type
---------------
-
- (not yet documented)
-
-\1f
-File: lispref.info, Node: X Resource Type, Prev: Subwindow Type, Up: Window-System Types
-
-X Resource Type
----------------
-
- (not yet documented)
-
-\1f
-File: lispref.info, Node: Type Predicates, Next: Equality Predicates, Prev: Window-System Types, Up: Lisp Data Types
-
-Type Predicates
-===============
-
- The XEmacs Lisp interpreter itself does not perform type checking on
-the actual arguments passed to functions when they are called. It could
-not do so, since function arguments in Lisp do not have declared data
-types, as they do in other programming languages. It is therefore up to
-the individual function to test whether each actual argument belongs to
-a type that the function can use.
-
- All built-in functions do check the types of their actual arguments
-when appropriate, and signal a `wrong-type-argument' error if an
-argument is of the wrong type. For example, here is what happens if you
-pass an argument to `+' that it cannot handle:
-
- (+ 2 'a)
- error--> Wrong type argument: integer-or-marker-p, a
-
- If you want your program to handle different types differently, you
-must do explicit type checking. The most common way to check the type
-of an object is to call a "type predicate" function. Emacs has a type
-predicate for each type, as well as some predicates for combinations of
-types.
-
- A type predicate function takes one argument; it returns `t' if the
-argument belongs to the appropriate type, and `nil' otherwise.
-Following a general Lisp convention for predicate functions, most type
-predicates' names end with `p'.
-
- Here is an example which uses the predicates `listp' to check for a
-list and `symbolp' to check for a symbol.
-
- (defun add-on (x)
- (cond ((symbolp x)
- ;; If X is a symbol, put it on LIST.
- (setq list (cons x list)))
- ((listp x)
- ;; If X is a list, add its elements to LIST.
- (setq list (append x list)))
- (t
- ;; We only handle symbols and lists.
- (error "Invalid argument %s in add-on" x))))
-
- Here is a table of predefined type predicates, in alphabetical order,
-with references to further information.
-
-`annotationp'
- *Note annotationp: Annotation Primitives.
-
-`arrayp'
- *Note arrayp: Array Functions.
-
-`atom'
- *Note atom: List-related Predicates.
-
-`bit-vector-p'
- *Note bit-vector-p: Bit Vector Functions.
-
-`bitp'
- *Note bitp: Bit Vector Functions.
-
-`boolean-specifier-p'
- *Note boolean-specifier-p: Specifier Types.
-
-`buffer-glyph-p'
- *Note buffer-glyph-p: Glyph Types.
-
-`buffer-live-p'
- *Note buffer-live-p: Killing Buffers.
-
-`bufferp'
- *Note bufferp: Buffer Basics.
-
-`button-event-p'
- *Note button-event-p: Event Predicates.
-
-`button-press-event-p'
- *Note button-press-event-p: Event Predicates.
-
-`button-release-event-p'
- *Note button-release-event-p: Event Predicates.
-
-`case-table-p'
- *Note case-table-p: Case Tables.
-
-`char-int-p'
- *Note char-int-p: Character Codes.
-
-`char-or-char-int-p'
- *Note char-or-char-int-p: Character Codes.
-
-`char-or-string-p'
- *Note char-or-string-p: Predicates for Strings.
-
-`char-table-p'
- *Note char-table-p: Char Tables.
-
-`characterp'
- *Note characterp: Predicates for Characters.
-
-`color-instance-p'
- *Note color-instance-p: Colors.
-
-`color-pixmap-image-instance-p'
- *Note color-pixmap-image-instance-p: Image Instance Types.
-
-`color-specifier-p'
- *Note color-specifier-p: Specifier Types.
-
-`commandp'
- *Note commandp: Interactive Call.
-
-`compiled-function-p'
- *Note compiled-function-p: Compiled-Function Type.
-
-`console-live-p'
- *Note console-live-p: Connecting to a Console or Device.
-
-`consolep'
- *Note consolep: Consoles and Devices.
-
-`consp'
- *Note consp: List-related Predicates.
-
-`database-live-p'
- *Note database-live-p: Connecting to a Database.
-
-`databasep'
- *Note databasep: Databases.
-
-`device-live-p'
- *Note device-live-p: Connecting to a Console or Device.
-
-`device-or-frame-p'
- *Note device-or-frame-p: Basic Device Functions.
-
-`devicep'
- *Note devicep: Consoles and Devices.
-
-`eval-event-p'
- *Note eval-event-p: Event Predicates.
-
-`event-live-p'
- *Note event-live-p: Event Predicates.
-
-`eventp'
- *Note eventp: Events.
-
-`extent-live-p'
- *Note extent-live-p: Creating and Modifying Extents.
-
-`extentp'
- *Note extentp: Extents.
-
-`face-boolean-specifier-p'
- *Note face-boolean-specifier-p: Specifier Types.
-
-`facep'
- *Note facep: Basic Face Functions.
-
-`floatp'
- *Note floatp: Predicates on Numbers.
-
-`font-instance-p'
- *Note font-instance-p: Fonts.
-
-`font-specifier-p'
- *Note font-specifier-p: Specifier Types.
-
-`frame-live-p'
- *Note frame-live-p: Deleting Frames.
-
-`framep'
- *Note framep: Frames.
-
-`functionp'
- (not yet documented)
-
-`generic-specifier-p'
- *Note generic-specifier-p: Specifier Types.
-
-`glyphp'
- *Note glyphp: Glyphs.
-
-`hash-table-p'
- *Note hash-table-p: Hash Tables.
-
-`icon-glyph-p'
- *Note icon-glyph-p: Glyph Types.
-
-`image-instance-p'
- *Note image-instance-p: Images.
-
-`image-specifier-p'
- *Note image-specifier-p: Specifier Types.
-
-`integer-char-or-marker-p'
- *Note integer-char-or-marker-p: Predicates on Markers.
-
-`integer-or-char-p'
- *Note integer-or-char-p: Predicates for Characters.
-
-`integer-or-marker-p'
- *Note integer-or-marker-p: Predicates on Markers.
-
-`integer-specifier-p'
- *Note integer-specifier-p: Specifier Types.
-
-`integerp'
- *Note integerp: Predicates on Numbers.
-
-`itimerp'
- (not yet documented)
-
-`key-press-event-p'
- *Note key-press-event-p: Event Predicates.
-
-`keymapp'
- *Note keymapp: Creating Keymaps.
-
-`keywordp'
- (not yet documented)
-
-`listp'
- *Note listp: List-related Predicates.
-
-`markerp'
- *Note markerp: Predicates on Markers.
-
-`misc-user-event-p'
- *Note misc-user-event-p: Event Predicates.
-
-`mono-pixmap-image-instance-p'
- *Note mono-pixmap-image-instance-p: Image Instance Types.
-
-`motion-event-p'
- *Note motion-event-p: Event Predicates.
-
-`mouse-event-p'
- *Note mouse-event-p: Event Predicates.
-
-`natnum-specifier-p'
- *Note natnum-specifier-p: Specifier Types.
-
-`natnump'
- *Note natnump: Predicates on Numbers.
-
-`nlistp'
- *Note nlistp: List-related Predicates.
-
-`nothing-image-instance-p'
- *Note nothing-image-instance-p: Image Instance Types.
-
-`number-char-or-marker-p'
- *Note number-char-or-marker-p: Predicates on Markers.
-
-`number-or-marker-p'
- *Note number-or-marker-p: Predicates on Markers.
-
-`numberp'
- *Note numberp: Predicates on Numbers.
-
-`pointer-glyph-p'
- *Note pointer-glyph-p: Glyph Types.
-
-`pointer-image-instance-p'
- *Note pointer-image-instance-p: Image Instance Types.
-
-`process-event-p'
- *Note process-event-p: Event Predicates.
-
-`processp'
- *Note processp: Processes.
-
-`range-table-p'
- *Note range-table-p: Range Tables.
-
-`ringp'
- (not yet documented)
-
-`sequencep'
- *Note sequencep: Sequence Functions.
-
-`specifierp'
- *Note specifierp: Specifiers.
-
-`stringp'
- *Note stringp: Predicates for Strings.
-
-`subrp'
- *Note subrp: Function Cells.
-
-`subwindow-image-instance-p'
- *Note subwindow-image-instance-p: Image Instance Types.
-
-`subwindowp'
- *Note subwindowp: Subwindows.
-
-`symbolp'
- *Note symbolp: Symbols.
-
-`syntax-table-p'
- *Note syntax-table-p: Syntax Tables.
-
-`text-image-instance-p'
- *Note text-image-instance-p: Image Instance Types.
-
-`timeout-event-p'
- *Note timeout-event-p: Event Predicates.
-
-`toolbar-button-p'
- *Note toolbar-button-p: Toolbar.
-
-`toolbar-specifier-p'
- *Note toolbar-specifier-p: Toolbar.
-
-`user-variable-p'
- *Note user-variable-p: Defining Variables.
-
-`vectorp'
- *Note vectorp: Vectors.
-
-`weak-list-p'
- *Note weak-list-p: Weak Lists.
-
-`window-configuration-p'
- *Note window-configuration-p: Window Configurations.
-
-`window-live-p'
- *Note window-live-p: Deleting Windows.
-
-`windowp'
- *Note windowp: Basic Windows.
-
- 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
-most cases, it is more convenient to use type predicates than `type-of'.
-
- - 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',
- `compiled-function', `console', `database', `device', `event',
- `extent', `face', `float', `font-instance', `frame', `glyph',
- `hash-table', `image-instance', `integer', `keymap', `marker',
- `process', `range-table', `specifier', `string', `subr',
- `subwindow', `symbol', `toolbar-button', `tooltalk-message',
- `tooltalk-pattern', `vector', `weak-list', `window',
- `window-configuration', or `x-resource'.
-
- (type-of 1)
- => integer
- (type-of 'nil)
- => symbol
- (type-of '()) ; `()' is `nil'.
- => symbol
- (type-of '(x))
- => cons
-
-\1f
-File: lispref.info, Node: Equality Predicates, Prev: Type Predicates, Up: Lisp Data Types
-
-Equality Predicates
-===================
-
- Here we describe two functions that test for equality between any two
-objects. Other functions test equality between objects of specific
-types, e.g., strings. For these predicates, see the appropriate chapter
-describing the data type.
-
- - 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.
-
- `eq' returns `t' if OBJECT1 and OBJECT2 are integers with the same
- value. Also, since symbol names are normally unique, if the
- arguments are symbols with the same name, they are `eq'. For
- other types (e.g., lists, vectors, strings), two arguments with
- the same contents or elements are not necessarily `eq' to each
- other: they are `eq' only if they are the same object.
-
- (The `make-symbol' function returns an uninterned symbol that is
- not interned in the standard `obarray'. When uninterned symbols
- are in use, symbol names are no longer unique. Distinct symbols
- with the same name are not `eq'. *Note Creating Symbols::.)
-
- NOTE: Under XEmacs 19, characters are really just integers, and
- thus characters and integers are `eq'. Under XEmacs 20, it was
- necessary to preserve remnants of this in function such as `old-eq'
- in order to maintain byte-code compatibility. Byte code compiled
- under any Emacs 19 will automatically have calls to `eq' mapped to
- `old-eq' when executed under XEmacs 20.
-
- (eq 'foo 'foo)
- => t
-
- (eq 456 456)
- => t
-
- (eq "asdf" "asdf")
- => nil
-
- (eq '(1 (2 (3))) '(1 (2 (3))))
- => nil
-
- (setq foo '(1 (2 (3))))
- => (1 (2 (3)))
- (eq foo foo)
- => t
- (eq foo '(1 (2 (3))))
- => nil
-
- (eq [(1 2) 3] [(1 2) 3])
- => nil
-
- (eq (point-marker) (point-marker))
- => nil
-
-
- - Function: old-eq OBJ1 OBJ2
- 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.
- 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
- `old-assoc'.)
-
- ;; Remember, this does not apply under XEmacs 19.
- ?A
- => ?A
- (char-int ?A)
- => 65
- (old-eq ?A 65)
- => t ; Eek, we've been infected.
- (eq ?A 65)
- => nil ; We are still healthy.
-
- - 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
- to see if their elements are the same. So, if two objects are
- `eq', they are `equal', but the converse is not always true.
-
- (equal 'foo 'foo)
- => t
-
- (equal 456 456)
- => t
-
- (equal "asdf" "asdf")
- => t
- (eq "asdf" "asdf")
- => nil
-
- (equal '(1 (2 (3))) '(1 (2 (3))))
- => t
- (eq '(1 (2 (3))) '(1 (2 (3))))
- => nil
-
- (equal [(1 2) 3] [(1 2) 3])
- => t
- (eq [(1 2) 3] [(1 2) 3])
- => nil
-
- (equal (point-marker) (point-marker))
- => t
-
- (eq (point-marker) (point-marker))
- => nil
-
- Comparison of strings is case-sensitive.
-
- Note that in FSF GNU Emacs, comparison of strings takes into
- account their text properties, and you have to use `string-equal'
- if you want only the strings themselves compared. This difference
- does not exist in XEmacs; `equal' and `string-equal' always return
- the same value on the same strings.
-
- (equal "asdf" "ASDF")
- => nil
-
- Two distinct buffers are never `equal', even if their contents are
- the same.
-
- The test for equality is implemented recursively, and circular lists
-may therefore cause infinite recursion (leading to an error).
-
-\1f
-File: lispref.info, Node: Numbers, Next: Strings and Characters, Prev: Lisp Data Types, Up: Top
-
-Numbers
-*******
-
- XEmacs supports two numeric data types: "integers" and "floating
-point numbers". Integers are whole numbers such as -3, 0, #b0111,
-#xFEED, #o744. Their values are exact. The number prefixes `#b',
-`#o', and `#x' are supported to represent numbers in binary, octal, and
-hexadecimal notation (or radix). Floating point numbers are numbers
-with fractional parts, such as -4.5, 0.0, or 2.71828. They can also be
-expressed in exponential notation: 1.5e2 equals 150; in this example,
-`e2' stands for ten to the second power, and is multiplied by 1.5.
-Floating point values are not exact; they have a fixed, limited amount
-of precision.
-
-* Menu:
-
-* Integer Basics:: Representation and range of integers.
-* Float Basics:: Representation and range of floating point.
-* Predicates on Numbers:: Testing for numbers.
-* Comparison of Numbers:: Equality and inequality predicates.
-* Numeric Conversions:: Converting float to integer and vice versa.
-* Arithmetic Operations:: How to add, subtract, multiply and divide.
-* Rounding Operations:: Explicitly rounding floating point numbers.
-* Bitwise Operations:: Logical and, or, not, shifting.
-* Math Functions:: Trig, exponential and logarithmic functions.
-* Random Numbers:: Obtaining random integers, predictable or not.
-
-\1f
-File: lispref.info, Node: Integer Basics, Next: Float Basics, Up: Numbers
-
-Integer Basics
-==============
-
- The range of values for an integer depends on the machine. The
-minimum range is -134217728 to 134217727 (28 bits; i.e., -2**27 to
-2**27 - 1), but some machines may provide a wider range. Many examples
-in this chapter assume an integer has 28 bits.
-
- The Lisp reader reads an integer as a sequence of digits with
-optional initial sign and optional final period.
-
- 1 ; The integer 1.
- 1. ; The integer 1.
- +1 ; Also the integer 1.
- -1 ; The integer -1.
- 268435457 ; Also the integer 1, due to overflow.
- 0 ; The integer 0.
- -0 ; The integer 0.
-
- To understand how various functions work on integers, especially the
-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:
-
- 0000 0000 0000 0000 0000 0000 0101
-
-(We have inserted spaces between groups of 4 bits, and two spaces
-between groups of 8 bits, to make the binary integer easier to read.)
-
- The integer -1 looks like this:
-
- 1111 1111 1111 1111 1111 1111 1111
-
--1 is represented as 28 ones. (This is called "two's complement"
-notation.)
-
- The negative integer, -5, is creating by subtracting 4 from -1. In
-binary, the decimal integer 4 is 100. Consequently, -5 looks like this:
-
- 1111 1111 1111 1111 1111 1111 1011
-
- In this implementation, the largest 28-bit binary integer is the
-decimal integer 134,217,727. In binary, it looks like this:
-
- 0111 1111 1111 1111 1111 1111 1111
-
- Since the arithmetic functions do not check whether integers go
-outside their range, when you add 1 to 134,217,727, the value is the
-negative integer -134,217,728:
-
- (+ 1 134217727)
- => -134217728
- => 1000 0000 0000 0000 0000 0000 0000
-
- Many of the following functions accept markers for arguments as well
-as integers. (*Note Markers::.) More precisely, the actual arguments
-to such functions may be either integers or markers, which is why we
-often give these arguments the name INT-OR-MARKER. When the argument
-value is a marker, its position value is used and its buffer is ignored.
-
-\1f
-File: lispref.info, Node: Float Basics, Next: Predicates on Numbers, Prev: Integer Basics, Up: Numbers
-
-Floating Point Basics
-=====================
-
- XEmacs supports floating point numbers. The precise range of
-floating point numbers is machine-specific; it is the same as the range
-of the C data type `double' on the machine in question.
-
- The printed representation for floating point numbers requires either
-a decimal point (with at least one digit following), an exponent, or
-both. For example, `1500.0', `15e2', `15.0e2', `1.5e3', and `.15e4'
-are five ways of writing a floating point number whose value is 1500.
-They are all equivalent. You can also use a minus sign to write
-negative floating point numbers, as in `-1.0'.
-
- Most modern computers support the IEEE floating point standard, which
-provides for positive 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, `(sqrt -1.0)' returns a NaN.
-For practical purposes, there's no significant difference between
-different NaN values in XEmacs Lisp, and there's no rule for precisely
-which NaN value should be used in a particular case, so this manual
-doesn't try to distinguish them. XEmacs Lisp has no read syntax for
-NaNs or infinities; perhaps we should create a syntax in the future.
-
- You can use `logb' to extract the binary exponent of a floating
-point number (or estimate the logarithm of an integer):
-
- - 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.
-
-\1f
-File: lispref.info, Node: Predicates on Numbers, Next: Comparison of Numbers, Prev: Float Basics, Up: Numbers
-
-Type Predicates for Numbers
-===========================
-
- The functions in this section test whether the argument is a number
-or whether it is a certain sort of number. The functions `integerp'
-and `floatp' can take any type of Lisp object as argument (the
-predicates would not be of much use otherwise); but the `zerop'
-predicate requires a number as its argument. See also
-`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
- 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
- This predicate tests whether its argument is an integer, and
- returns `t' if so, `nil' otherwise.
-
- - 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
- 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
- This predicate tests whether its argument is zero, and returns `t'
- if so, `nil' otherwise. The argument must be a number.
-
- These two forms are equivalent: `(zerop x)' == `(= x 0)'.
-
-\1f
-File: lispref.info, Node: Comparison of Numbers, Next: Numeric Conversions, Prev: Predicates on Numbers, Up: Numbers
-
-Comparison of Numbers
-=====================
-
- 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, `='
-compares only the numeric values of the objects.
-
- At present, each integer value has a unique Lisp object in XEmacs
-Lisp. Therefore, `eq' is equivalent to `=' where integers are
-concerned. It is sometimes convenient to use `eq' for comparing an
-unknown value with an integer, because `eq' does not report an error if
-the unknown value is not a number--it accepts arguments of any type.
-By contrast, `=' signals an error if the arguments are not numbers or
-markers. However, it is a good idea to use `=' if you can, even for
-comparing integers, just in case we change the representation of
-integers in a future XEmacs version.
-
- There is another wrinkle: because floating point arithmetic is not
-exact, it is often a bad idea to check for equality of two floating
-point values. Usually it is better to test for approximate equality.
-Here's a function to do this:
-
- (defconst fuzz-factor 1.0e-6)
- (defun approx-equal (x y)
- (or (and (= x 0) (= y 0))
- (< (/ (abs (- x y))
- (max (abs x) (abs y)))
- fuzz-factor)))
-
- Common Lisp note: Comparing numbers in Common Lisp always requires
- `=' because Common Lisp implements multi-word integers, and two
- distinct integer objects can have the same numeric value. XEmacs
- Lisp can have just one integer object for any given value because
- it has a limited range of integer values.
-
- In addition to numbers, all of the following functions also accept
-characters and markers as arguments, and treat them as their number
-equivalents.
-
- - Function: = NUMBER &rest MORE-NUMBERS
- This function returns `t' if all of its arguments are numerically
- equal, `nil' otherwise.
-
- (= 5)
- => t
- (= 5 6)
- => nil
- (= 5 5.0)
- => t
- (= 5 5 6)
- => nil
-
- - Function: /= NUMBER &rest MORE-NUMBERS
- This function returns `t' if no two arguments are numerically
- equal, `nil' otherwise.
-
- (/= 5 6)
- => t
- (/= 5 5 6)
- => nil
- (/= 5 6 1)
- => t
-
- - Function: < NUMBER &rest MORE-NUMBERS
- This function returns `t' if the sequence of its arguments is
- monotonically increasing, `nil' otherwise.
-
- (< 5 6)
- => t
- (< 5 6 6)
- => nil
- (< 5 6 7)
- => t
-
- - Function: <= NUMBER &rest MORE-NUMBERS
- This function returns `t' if the sequence of its arguments is
- monotonically nondecreasing, `nil' otherwise.
-
- (<= 5 6)
- => t
- (<= 5 6 6)
- => t
- (<= 5 6 5)
- => nil
-
- - 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
- This function returns `t' if the sequence of its arguments is
- monotonically nonincreasing, `nil' otherwise.
-
- - Function: max NUMBER &rest MORE-NUMBERS
- This function returns the largest of its arguments.
-
- (max 20)
- => 20
- (max 1 2.5)
- => 2.5
- (max 1 3 2.5)
- => 3
-
- - Function: min NUMBER &rest MORE-NUMBERS
- This function returns the smallest of its arguments.
-
- (min -4 1)
- => -4
-
-\1f
-File: lispref.info, Node: Numeric Conversions, Next: Arithmetic Operations, Prev: Comparison of Numbers, Up: Numbers
-
-Numeric Conversions
-===================
-
- To convert an integer to floating point, use the function `float'.
-
- - Function: float NUMBER
- This returns NUMBER converted to floating point. If NUMBER is
- already a floating point number, `float' returns it unchanged.
-
- There are four functions to convert floating point numbers to
-integers; they differ in how they round. These functions accept
-integer arguments also, and return such arguments unchanged.
-
- - Function: truncate NUMBER
- This returns NUMBER, converted to an integer by rounding towards
- zero.
-
- - Function: floor NUMBER &optional DIVISOR
- This returns NUMBER, converted to an integer by rounding downward
- (towards negative infinity).
-
- If DIVISOR is specified, NUMBER is divided by DIVISOR before the
- floor is taken; this is the division operation that corresponds to
- `mod'. An `arith-error' results if DIVISOR is 0.
-
- - Function: ceiling NUMBER
- This returns NUMBER, converted to an integer by rounding upward
- (towards positive infinity).
-
- - 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
- an even integer, depending on your machine.
-
-\1f
-File: lispref.info, Node: Arithmetic Operations, Next: Rounding Operations, Prev: Numeric Conversions, Up: Numbers
-
-Arithmetic Operations
-=====================
-
- XEmacs Lisp provides the traditional four arithmetic operations:
-addition, subtraction, multiplication, and division. Remainder and
-modulus functions supplement the division functions. The functions to
-add or subtract 1 are provided because they are traditional in Lisp and
-commonly used.
-
- All of these functions except `%' return a floating point value if
-any argument is floating.
-
- It is important to note that in XEmacs Lisp, arithmetic functions do
-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,
-
- (setq foo 4)
- => 4
- (1+ foo)
- => 5
-
- This function is not analogous to the C operator `++'--it does not
- increment a variable. It just computes a sum. Thus, if we
- continue,
-
- foo
- => 4
-
- If you want to increment the variable, you must use `setq', like
- this:
-
- (setq foo (1+ foo))
- => 5
-
- Now that the `cl' package is always available from lisp code, a
- 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: abs NUMBER
- This returns the absolute value of NUMBER.
-
- - Function: + &rest NUMBERS-OR-MARKERS
- This function adds its arguments together. When given no
- arguments, `+' returns 0.
-
- (+)
- => 0
- (+ 1)
- => 1
- (+ 1 2 3 4)
- => 10
-
- - Function: - &optional NUMBER-OR-MARKER &rest OTHER-NUMBERS-OR-MARKERS
- 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.
-
- (- 10 1 2 3 4)
- => 0
- (- 10)
- => -10
- (-)
- => 0
-
- - Function: * &rest NUMBERS-OR-MARKERS
- This function multiplies its arguments together, and returns the
- product. When given no arguments, `*' returns 1.
-
- (*)
- => 1
- (* 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.
-
- 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
- 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 you divide by 0, an `arith-error' error is signaled. (*Note
- Errors::.)
-
- (/ 6 2)
- => 3
- (/ 5 2)
- => 2
- (/ 25 3 2)
- => 4
- (/ -17 6)
- => -2
-
- The result of `(/ -17 6)' could in principle be -3 on some
- machines.
-
- - Function: % DIVIDEND DIVISOR
- This function returns the integer remainder after division of
- DIVIDEND by DIVISOR. The arguments must be integers or markers.
-
- For negative arguments, the remainder is in principle
- machine-dependent since the quotient is; but in practice, all
- known machines behave alike.
-
- An `arith-error' results if DIVISOR is 0.
-
- (% 9 4)
- => 1
- (% -9 4)
- => -1
- (% 9 -4)
- => 1
- (% -9 -4)
- => -1
-
- For any two integers DIVIDEND and DIVISOR,
-
- (+ (% DIVIDEND DIVISOR)
- (* (/ DIVIDEND DIVISOR) DIVISOR))
-
- always equals DIVIDEND.
-
- - 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
- or markers.
-
- Unlike `%', `mod' returns a well-defined result for negative
- arguments. It also permits floating point arguments; it rounds the
- quotient downward (towards minus infinity) to an integer, and uses
- that quotient to compute the remainder.
-
- An `arith-error' results if DIVISOR is 0.
-
- (mod 9 4)
- => 1
- (mod -9 4)
- => 3
- (mod 9 -4)
- => -3
- (mod -9 -4)
- => -1
- (mod 5.5 2.5)
- => .5
-
- For any two numbers DIVIDEND and DIVISOR,
-
- (+ (mod DIVIDEND DIVISOR)
- (* (floor DIVIDEND DIVISOR) DIVISOR))
-
- always equals DIVIDEND, subject to rounding error if either
- argument is floating point. For `floor', see *Note Numeric
- Conversions::.
-
-\1f
-File: lispref.info, Node: Rounding Operations, Next: Bitwise Operations, Prev: Arithmetic Operations, Up: Numbers
-
-Rounding Operations
-===================
-
- The functions `ffloor', `fceiling', `fround' and `ftruncate' take a
-floating point argument and return a floating point result whose value
-is a nearby integer. `ffloor' returns the nearest integer below;
-`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
- returns that value as a floating point number.
-
- - Function: fceiling FLOAT
- This function rounds FLOAT 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
- returns that value as a floating point number.
-
- - Function: fround FLOAT
- This function rounds FLOAT to the nearest integral value, and
- returns that value as a floating point number.
-
-\1f
-File: lispref.info, Node: Bitwise Operations, Next: Math Functions, Prev: Rounding Operations, Up: Numbers
-
-Bitwise Operations on Integers
-==============================
-
- In a computer, an integer is represented as a binary number, a
-sequence of "bits" (digits which are either zero or one). A bitwise
-operation acts on the individual bits of such a sequence. For example,
-"shifting" moves the whole sequence left or right one or more places,
-reproducing the same pattern "moved over".
-
- The bitwise operations in XEmacs Lisp apply only to integers.
-
- - 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
- is negative, `lsh' shifts zeros into the leftmost
- (most-significant) bit, producing a positive result even if
- INTEGER1 is negative. Contrast this with `ash', below.
-
- Here are two examples of `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.
-
- (lsh 5 1)
- => 10
- ;; Decimal 5 becomes decimal 10.
- 00000101 => 00001010
-
- (lsh 7 1)
- => 14
- ;; Decimal 7 becomes decimal 14.
- 00000111 => 00001110
-
- 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):
-
- (lsh 3 2)
- => 12
- ;; Decimal 3 becomes decimal 12.
- 00000011 => 00001100
-
- On the other hand, shifting one place to the right looks like this:
-
- (lsh 6 -1)
- => 3
- ;; Decimal 6 becomes decimal 3.
- 00000110 => 00000011
-
- (lsh 5 -1)
- => 2
- ;; Decimal 5 becomes decimal 2.
- 00000101 => 00000010
-
- As the example illustrates, shifting one place to the right
- divides the value of a positive integer by two, rounding downward.
-
- The function `lsh', like all XEmacs 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
- 134,217,727 produces -2 on a 28-bit machine:
-
- (lsh 134217727 1) ; left shift
- => -2
-
- In binary, in the 28-bit implementation, the argument looks like
- this:
-
- ;; Decimal 134,217,727
- 0111 1111 1111 1111 1111 1111 1111
-
- which becomes the following when left shifted:
-
- ;; Decimal -2
- 1111 1111 1111 1111 1111 1111 1110
-
- - 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.
-
- `ash' gives the same results as `lsh' except when INTEGER1 and
- COUNT are both negative. In that case, `ash' puts ones in the
- empty bit positions on the left, while `lsh' puts zeros in those
- bit positions.
-
- Thus, with `ash', shifting the pattern of bits one place to the
- right looks like this:
-
- (ash -6 -1) => -3
- ;; Decimal -6 becomes decimal -3.
- 1111 1111 1111 1111 1111 1111 1010
- =>
- 1111 1111 1111 1111 1111 1111 1101
-
- In contrast, shifting the pattern of bits one place to the right
- with `lsh' looks like this:
-
- (lsh -6 -1) => 134217725
- ;; Decimal -6 becomes decimal 134,217,725.
- 1111 1111 1111 1111 1111 1111 1010
- =>
- 0111 1111 1111 1111 1111 1111 1101
-
- Here are other examples:
-
- ; 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
- 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
- rather than 0.)
-
- For example, using 4-bit binary numbers, the "logical and" of 13
- and 12 is 12: 1101 combined with 1100 produces 1100. In both the
- binary numbers, the leftmost two bits are set (i.e., they are
- 1's), so the leftmost two bits of the returned value are set.
- However, for the rightmost two bits, each is zero in at least one
- of the arguments, so the rightmost two bits of the returned value
- are 0's.
-
- Therefore,
-
- (logand 13 12)
- => 12
-
- If `logand' is not passed any argument, it returns a value of -1.
- This number is an identity element for `logand' because its binary
- representation consists entirely of ones. If `logand' is passed
- just one argument, it returns that argument.
-
- ; 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
- 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
-
- (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
- 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
-
- (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
- 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.
-
- (lognot 5)
- => -6
- ;; 5 = 0000 0000 0000 0000 0000 0000 0101
- ;; becomes
- ;; -6 = 1111 1111 1111 1111 1111 1111 1010
-
-\1f
-File: lispref.info, Node: Math Functions, Next: Random Numbers, Prev: Bitwise Operations, Up: Numbers
-
-Standard Mathematical Functions
-===============================
-
- These mathematical functions are available if floating point is
-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
- 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: 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 ARG
- The value of `(atan ARG)' is a number between -pi/2 and pi/2
- (exclusive) whose tangent is ARG.
-
- - Function: sinh ARG
- - Function: cosh ARG
- - Function: tanh ARG
- These are the ordinary hyperbolic trigonometric functions.
-
- - Function: asinh ARG
- - Function: acosh ARG
- - Function: atanh ARG
- 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: 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: 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: 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: cube-root ARG
- This returns the cube root of ARG.
-
-\1f
-File: lispref.info, Node: Random Numbers, Prev: Math Functions, Up: Numbers
-
-Random Numbers
-==============
-
- A deterministic computer program cannot generate true random numbers.
-For most purposes, "pseudo-random numbers" suffice. A series of
-pseudo-random numbers is generated in a deterministic fashion. The
-numbers are not truly random, but they have certain properties that
-mimic a random series. For example, all possible values occur equally
-often in a pseudo-random series.
-
- In XEmacs, pseudo-random numbers are generated from a "seed" number.
-Starting from any given seed, the `random' function always generates
-the same sequence of numbers. XEmacs always starts with the same seed
-value, so the sequence of values of `random' is actually the same in
-each XEmacs run! For example, in one operating system, the first call
-to `(random)' after you start XEmacs always returns -1457731, and the
-second one always returns -7692030. This repeatability is helpful for
-debugging.
-
- If you want truly unpredictable random numbers, execute `(random
-t)'. This chooses a new seed based on the current time of day and on
-XEmacs's process ID number.
-
- - Function: random &optional LIMIT
- This function returns a pseudo-random integer. Repeated calls
- return a series of pseudo-random integers.
-
- If LIMIT is a positive integer, the value is chosen to be
- nonnegative and less than LIMIT.
-
- If LIMIT is `t', it means to choose a new seed based on the
- current time of day and on XEmacs's process ID number.
-
- On some machines, any integer representable in Lisp may be the
- result of `random'. On other machines, the result can never be
- larger than a certain maximum or less than a certain (negative)
- minimum.
-
-\1f
-File: lispref.info, Node: Strings and Characters, Next: Lists, Prev: Numbers, Up: Top
-
-Strings and Characters
-**********************
-
- A string in XEmacs Lisp is an array that contains an ordered sequence
-of characters. Strings are used as names of symbols, buffers, and
-files, to send messages to users, to hold text being copied between
-buffers, and for many other purposes. Because strings are so important,
-XEmacs Lisp has many functions expressly for manipulating them. XEmacs
-Lisp programs use strings more often than individual characters.
-
-* Menu:
-
-* Basics: 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.
-* Character Codes:: Each character has an equivalent integer.
-* Text Comparison:: Comparing characters or strings.
-* String Conversion:: Converting characters or strings and vice versa.
-* Modifying Strings:: Changing characters in a string.
-* String Properties:: Additional information attached to strings.
-* Formatting Strings:: `format': XEmacs's analog of `printf'.
-* Character Case:: Case conversion functions.
-* Case Tables:: Customizing case conversion.
-* Char Tables:: Mapping from characters to Lisp objects.
-
projects / chise / xemacs-chise.git.1 / blobdiff