-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.0b from
+lispref/lispref.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
Accessing Elements of Lists
===========================
- - Function: car CONS-CELL
+ - Function: car cons-cell
This function returns the value pointed to by the first pointer of
the cons cell CONS-CELL. Expressed another way, this function
returns the CAR of CONS-CELL.
(car '())
=> nil
- - Function: cdr CONS-CELL
+ - Function: cdr cons-cell
This function returns the value pointed to by the second pointer of
the cons cell CONS-CELL. Expressed another way, this function
returns the CDR of CONS-CELL.
(cdr '())
=> nil
- - Function: car-safe OBJECT
+ - Function: car-safe object
This function lets you take the CAR of a cons cell while avoiding
errors for other data types. It returns the CAR of OBJECT if
OBJECT is a cons cell, `nil' otherwise. This is in contrast to
(car x)
nil))
- - Function: cdr-safe OBJECT
+ - Function: cdr-safe object
This function lets you take the CDR of a cons cell while avoiding
errors for other data types. It returns the CDR of OBJECT if
OBJECT is a cons cell, `nil' otherwise. This is in contrast to
(cdr x)
nil))
- - Function: nth N LIST
+ - Function: nth n list
This function returns the Nth element of LIST. Elements are
numbered starting with zero, so the CAR of LIST is element number
zero. If the length of LIST is N or less, the value is `nil'.
(nth n x) == (car (nthcdr n x))
- - Function: nthcdr N LIST
+ - Function: nthcdr n list
This function returns the Nth CDR of LIST. In other words, it
removes the first N links of LIST and returns what follows.
access particular elements in a nested list. All of these can be
rewritten in terms of the functions just described.
- - Function: caar CONS-CELL
- - Function: cadr CONS-CELL
- - Function: cdar CONS-CELL
- - Function: cddr CONS-CELL
- - Function: caaar CONS-CELL
- - Function: caadr CONS-CELL
- - Function: cadar CONS-CELL
- - Function: caddr CONS-CELL
- - Function: cdaar CONS-CELL
- - Function: cdadr CONS-CELL
- - Function: cddar CONS-CELL
- - Function: cdddr CONS-CELL
- - Function: caaaar CONS-CELL
- - Function: caaadr CONS-CELL
- - Function: caadar CONS-CELL
- - Function: caaddr CONS-CELL
- - Function: cadaar CONS-CELL
- - Function: cadadr CONS-CELL
- - Function: caddar CONS-CELL
- - Function: cadddr CONS-CELL
- - Function: cdaaar CONS-CELL
- - Function: cdaadr CONS-CELL
- - Function: cdadar CONS-CELL
- - Function: cdaddr CONS-CELL
- - Function: cddaar CONS-CELL
- - Function: cddadr CONS-CELL
- - Function: cdddar CONS-CELL
- - Function: cddddr CONS-CELL
+ - Function: caar cons-cell
+ - Function: cadr cons-cell
+ - Function: cdar cons-cell
+ - Function: cddr cons-cell
+ - Function: caaar cons-cell
+ - Function: caadr cons-cell
+ - Function: cadar cons-cell
+ - Function: caddr cons-cell
+ - Function: cdaar cons-cell
+ - Function: cdadr cons-cell
+ - Function: cddar cons-cell
+ - Function: cdddr cons-cell
+ - Function: caaaar cons-cell
+ - Function: caaadr cons-cell
+ - Function: caadar cons-cell
+ - Function: caaddr cons-cell
+ - Function: cadaar cons-cell
+ - Function: cadadr cons-cell
+ - Function: caddar cons-cell
+ - Function: cadddr cons-cell
+ - Function: cdaaar cons-cell
+ - Function: cdaadr cons-cell
+ - Function: cdadar cons-cell
+ - Function: cdaddr cons-cell
+ - Function: cddaar cons-cell
+ - Function: cddadr cons-cell
+ - Function: cdddar cons-cell
+ - Function: cddddr cons-cell
Each of these functions is equivalent to one or more applications
of `car' and/or `cdr'. For example,
That is to say, read the a's and d's from right to left and apply
a `car' or `cdr' for each a or d found, respectively.
- - Function: first LIST
+ - Function: first list
This is equivalent to `(nth 0 LIST)', i.e. the first element of
LIST. (Note that this is also equivalent to `car'.)
- - Function: second LIST
+ - Function: second list
This is equivalent to `(nth 1 LIST)', i.e. the second element of
LIST.
- - Function: third LIST
- - Function: fourth LIST
- - Function: fifth LIST
- - Function: sixth LIST
- - Function: seventh LIST
- - Function: eighth LIST
- - Function: ninth LIST
- - Function: tenth LIST
+ - Function: third list
+ - Function: fourth list
+ - Function: fifth list
+ - Function: sixth list
+ - Function: seventh list
+ - Function: eighth list
+ - Function: ninth list
+ - Function: tenth list
These are equivalent to `(nth 2 LIST)' through `(nth 9 LIST)'
respectively, i.e. the third through tenth elements of LIST.
interesting to note that `list' is used more times in the source code
for Emacs than `cons'.
- - Function: cons OBJECT1 OBJECT2
+ - Function: cons object1 object2
This function is the fundamental function used to build new list
structure. It creates a new cons cell, making OBJECT1 the CAR,
and OBJECT2 the CDR. It then returns the new cons cell. The
used in this example and the function named `list' described below;
any symbol can serve both purposes.
- - Function: list &rest OBJECTS
+ - Function: list &rest objects
This function creates a list with OBJECTS as its elements. The
resulting list is always `nil'-terminated. If no OBJECTS are
given, the empty list is returned.
(list)
=> nil
- - Function: make-list LENGTH OBJECT
+ - Function: make-list length object
This function creates a list of length LENGTH, in which all the
elements have the identical value OBJECT. Compare `make-list'
- with `make-string' (*note Creating Strings::.).
+ with `make-string' (*note Creating Strings::).
(make-list 3 'pigs)
=> (pigs pigs pigs)
(make-list 0 'pigs)
=> nil
- - Function: append &rest SEQUENCES
+ - Function: append &rest sequences
This function returns a list containing all the elements of
SEQUENCES. The SEQUENCES may be lists, vectors, or strings, but
the last one should be a list. All arguments except the last one
of the original integers. *Don't use this feature; we plan to
eliminate it. If you already use this feature, change your
programs now!* The proper way to convert an integer to a decimal
- number in this way is with `format' (*note Formatting Strings::.)
- or `number-to-string' (*note String Conversion::.).
+ number in this way is with `format' (*note Formatting Strings::)
+ or `number-to-string' (*note String Conversion::).
- - Function: reverse LIST
+ - Function: reverse list
This function creates a new list whose elements are the elements of
- LIST, but in reverse order. The original argument LIST is *not*
+ LIST, but in reverse order. The original argument LIST is _not_
altered.
(setq x '(1 2 3 4))
a list, `setcar' replaces one element of a list with a different
element.
- - Function: setcar CONS OBJECT
- This function stores OBJECT as the new CAR of CONS, replacing its
- previous CAR. It returns the value OBJECT. For example:
+ - Function: setcar cons-cell object
+ This function stores OBJECT as the new CAR of CONS-CELL, replacing
+ its previous CAR. It returns the value OBJECT. For example:
(setq x '(1 2))
=> (1 2)
The lowest-level primitive for modifying a CDR is `setcdr':
- - Function: setcdr CONS OBJECT
- This function stores OBJECT as the new CDR of CONS, replacing its
- previous CDR. It returns the value OBJECT.
+ - Function: setcdr cons-cell object
+ This function stores OBJECT as the new CDR of CONS-CELL, replacing
+ its previous CDR. It returns the value OBJECT.
Here is an example of replacing the CDR of a list with a different
list. All but the first element of the list are removed in favor of a
Here is this result in box notation:
- -------------- ------------- -------------
+ -------------- ------------- -------------
| car | cdr | | car | cdr | | car | cdr |
| a | o | -->| b | o------->| c | nil |
| | | | | | | | | | |
See `delq', in *Note Sets And Lists::, for another function that
modifies cons cells.
- - Function: nconc &rest LISTS
+ - Function: nconc &rest lists
This function returns a list containing all the elements of LISTS.
- Unlike `append' (*note Building Lists::.), the LISTS are *not*
+ Unlike `append' (*note Building Lists::), the LISTS are _not_
copied. Instead, the last CDR of each of the LISTS is changed to
refer to the following list. The last of the LISTS is not
altered. For example:
(defun add-foo (x) ; We want this function to add
(nconc '(foo) x)) ; `foo' to the front of its arg.
-
+
(symbol-function 'add-foo)
=> (lambda (x) (nconc (quote (foo)) x))
-
+
(setq xx (add-foo '(1 2))) ; It seems to work.
=> (foo 1 2)
-
(setq xy (add-foo '(3 4))) ; What happened?
=> (foo 1 2 3 4)
-
(eq xx xy)
=> t
-
+
(symbol-function 'add-foo)
=> (lambda (x) (nconc (quote (foo 1 2 3 4) x)))
- - Function: nreverse LIST
+ - Function: nreverse list
This function reverses the order of the elements of LIST. Unlike
`reverse', `nreverse' alters its argument by reversing the CDRs in
the cons cells forming the list. The cons cell that used to be
| | | |
------------- ------------
- - Function: sort LIST PREDICATE
+ - Function: sort list predicate
This function sorts LIST stably, though destructively, and returns
the sorted list. It compares elements using PREDICATE. A stable
sort is one in which elements with equal sort keys maintain their
XEmacs Lisp does not have them. You can write them in Lisp if you
wish.
- - Function: memq OBJECT LIST
+ - Function: memq object list
This function tests to see whether OBJECT is a member of LIST. If
it is, `memq' returns a list starting with the first occurrence of
OBJECT. Otherwise, it returns `nil'. The letter `q' in `memq'
(memq '(2) '((1) (2))) ; `(2)' and `(2)' are not `eq'.
=> nil
- - Function: delq OBJECT LIST
+ - Function: delq object list
This function destructively removes all elements `eq' to OBJECT
from LIST. The letter `q' in `delq' says that it uses `eq' to
compare OBJECT against the elements of the list, like `memq'.
(delq 'a '(a b c)) == (cdr '(a b c))
When an element to be deleted appears in the middle of the list,
-removing it involves changing the CDRs (*note Setcdr::.).
+removing it involves changing the CDRs (*note Setcdr::).
(setq sample-list '(a b c (4)))
=> (a b c (4))
The following two functions are like `memq' and `delq' but use
`equal' rather than `eq' to compare elements. They are new in Emacs 19.
- - Function: member OBJECT LIST
+ - Function: member object list
The function `member' tests to see whether OBJECT is a member of
LIST, comparing members with OBJECT using `equal'. If OBJECT is a
member, `member' returns a list starting with its first occurrence
(member "foo" '("foo" "bar"))
=> ("foo" "bar")
- - Function: delete OBJECT LIST
+ - Function: delete object list
This function destructively removes all elements `equal' to OBJECT
from LIST. It is to `delq' as `member' is to `memq': it uses
`equal' to compare elements with OBJECT, like `member'; when it
The associated values in an alist may be any Lisp objects; so may the
keys. For example, in the following alist, the symbol `a' is
associated with the number `1', and the string `"b"' is associated with
-the *list* `(2 3)', which is the CDR of the alist element:
+the _list_ `(2 3)', which is the CDR of the alist element:
((a . 1) ("b" 2 3))
association with a given key, the first one found is returned, if there
is more than one.
- In XEmacs Lisp, it is *not* an error if an element of an association
+ In XEmacs Lisp, it is _not_ an error if an element of an association
list is not a cons cell. The alist search functions simply ignore such
elements. Many other versions of Lisp signal errors in such cases.
each key can occur only once. *Note Property Lists::, for a comparison
of property lists and association lists.
- - Function: assoc KEY ALIST
+ - Function: assoc key alist
This function returns the first association for KEY in ALIST. It
compares KEY against the alist elements using `equal' (*note
- Equality Predicates::.). It returns `nil' if no association in
+ Equality Predicates::). It returns `nil' if no association in
ALIST has a CAR `equal' to KEY. For example:
(setq trees '((pine . cones) (oak . acorns) (maple . seeds)))
(cdr (assoc 2 needles-per-cluster))
=> ("Austrian Pine" "Red Pine")
- - Function: rassoc VALUE ALIST
+ - Function: rassoc value alist
This function returns the first association with value VALUE in
ALIST. It returns `nil' if no association in ALIST has a CDR
`equal' to VALUE.
ALIST association instead of the CAR. You can think of this as
"reverse `assoc'", finding the key for a given value.
- - Function: assq KEY ALIST
+ - Function: assq key alist
This function is like `assoc' in that it returns the first
association for KEY in ALIST, but it makes the comparison using
`eq' instead of `equal'. `assq' returns `nil' if no association
(assoc "simple leaves" leaves)
=> ("simple leaves" . oak)
- - Function: rassq VALUE ALIST
+ - Function: rassq value alist
This function returns the first association with value VALUE in
ALIST. It returns `nil' if no association in ALIST has a CDR `eq'
to VALUE.
(lily white) == (lily . (white))
- - Function: remassoc KEY ALIST
+ - Function: remassoc key alist
This function deletes by side effect any associations with key KEY
- in ALIST - i.e. it removes any elements from ALIST whose `car' is
+ in ALIST--i.e. it removes any elements from ALIST whose `car' is
`equal' to KEY. The modified ALIST is returned.
If the first member of ALIST has a `car' that is `equal' to KEY,
`(setq foo (remassoc key foo))' to be sure of changing the value
of `foo'.
- - Function: remassq KEY ALIST
+ - Function: remassq key alist
This function deletes by side effect any associations with key KEY
- in ALIST - i.e. it removes any elements from ALIST whose `car' is
+ in ALIST--i.e. it removes any elements from ALIST whose `car' is
`eq' to KEY. The modified ALIST is returned.
This function is exactly like `remassoc', but comparisons between
KEY and keys in ALIST are done using `eq' instead of `equal'.
- - Function: remrassoc VALUE ALIST
+ - Function: remrassoc value alist
This function deletes by side effect any associations with value
- VALUE in ALIST - i.e. it removes any elements from ALIST whose
+ VALUE in ALIST--i.e. it removes any elements from ALIST whose
`cdr' is `equal' to VALUE. The modified ALIST is returned.
If the first member of ALIST has a `car' that is `equal' to VALUE,
as "reverse `remassoc'", removing an association based on its
value instead of its key.
- - Function: remrassq VALUE ALIST
+ - Function: remrassq value alist
This function deletes by side effect any associations with value
- VALUE in ALIST - i.e. it removes any elements from ALIST whose
+ VALUE in ALIST--i.e. it removes any elements from ALIST whose
`cdr' is `eq' to VALUE. The modified ALIST is returned.
This function is exactly like `remrassoc', but comparisons between
VALUE and values in ALIST are done using `eq' instead of `equal'.
- - Function: copy-alist ALIST
+ - Function: copy-alist alist
This function returns a two-level deep copy of ALIST: it creates a
new copy of each association, so that you can alter the
associations of the new alist without changing the old one.
compared with `eq', and "lax" plists, whose keys are compared with
`equal',
- - Function: valid-plist-p PLIST
+ - Function: valid-plist-p plist
Given a plist, this function returns non-`nil' if its format is
correct. If it returns `nil', `check-valid-plist' will signal an
error when given the plist; that means it's a malformed or circular
plist or has non-symbols as keywords.
- - Function: check-valid-plist PLIST
+ - Function: check-valid-plist plist
Given a plist, this function signals an error if there is anything
wrong with it. This means that it's a malformed or circular plist.
Working With Normal Plists
--------------------------
- - Function: plist-get PLIST PROP &optional DEFAULT
+ - Function: plist-get plist property &optional default
This function extracts a value from a property list. The function
- returns the value corresponding to the given PROP, or DEFAULT if
- PROP is not one of the properties on the list.
-
- - Function: plist-put PLIST PROP VAL
- This function changes the value in PLIST of PROP to VAL. If PROP
- is already a property on the list, its value is set to VAL,
- otherwise the new PROP VAL pair is added. The new plist is
- returned; use `(setq x (plist-put x prop val))' to be sure to use
- the new value. The PLIST is modified by side effects.
-
- - Function: plist-remprop PLIST PROP
- This function removes from PLIST the property PROP and its value.
- The new plist is returned; use `(setq x (plist-remprop x prop
- val))' to be sure to use the new value. The PLIST is modified by
- side effects.
+ returns the value corresponding to the given PROPERTY, or DEFAULT
+ if PROPERTY is not one of the properties on the list.
+
+ - Function: plist-put plist property value
+ This function changes the value in PLIST of PROPERTY to VALUE. If
+ PROPERTY is already a property on the list, its value is set to
+ VALUE, otherwise the new PROPERTY VALUE pair is added. The new
+ plist is returned; use `(setq x (plist-put x property value))' to
+ be sure to use the new value. The PLIST is modified by side
+ effects.
+
+ - Function: plist-remprop plist property
+ This function removes from PLIST the property PROPERTY and its
+ value. The new plist is returned; use `(setq x (plist-remprop x
+ property))' to be sure to use the new value. The PLIST is
+ modified by side effects.
- - Function: plist-member PLIST PROP
- This function returns `t' if PROP has a value specified in PLIST.
+ - Function: plist-member plist property
+ This function returns `t' if PROPERTY has a value specified in
+ PLIST.
In the following functions, if optional arg NIL-MEANS-NOT-PRESENT is
non-`nil', then a property with a `nil' value is ignored or removed.
thus E-Lisp, due to RMS's enamorment with old Lisps), but should not be
used except for backward compatibility.
- - Function: plists-eq A B &optional NIL-MEANS-NOT-PRESENT
+ - Function: plists-eq a b &optional nil-means-not-present
This function returns non-`nil' if property lists A and B are `eq'
(i.e. their values are `eq').
- - Function: plists-equal A B &optional NIL-MEANS-NOT-PRESENT
+ - Function: plists-equal a b &optional nil-means-not-present
This function returns non-`nil' if property lists A and B are
`equal' (i.e. their values are `equal'; their keys are still
compared using `eq').
- - Function: canonicalize-plist PLIST &optional NIL-MEANS-NOT-PRESENT
+ - Function: canonicalize-plist plist &optional nil-means-not-present
This function destructively removes any duplicate entries from a
plist. In such cases, the first entry applies.
Recall that a "lax plist" is a property list whose keys are compared
using `equal' instead of `eq'.
- - Function: lax-plist-get LAX-PLIST PROP &optional DEFAULT
+ - Function: lax-plist-get lax-plist property &optional default
This function extracts a value from a lax property list. The
- function returns the value corresponding to the given PROP, or
- DEFAULT if PROP is not one of the properties on the list.
+ function returns the value corresponding to the given PROPERTY, or
+ DEFAULT if PROPERTY is not one of the properties on the list.
- - Function: lax-plist-put LAX-PLIST PROP VAL
- This function changes the value in LAX-PLIST of PROP to VAL.
+ - Function: lax-plist-put lax-plist property value
+ This function changes the value in LAX-PLIST of PROPERTY to VALUE.
- - Function: lax-plist-remprop LAX-PLIST PROP
- This function removes from LAX-PLIST the property PROP and its
+ - Function: lax-plist-remprop lax-plist property
+ This function removes from LAX-PLIST the property PROPERTY and its
value. The new plist is returned; use `(setq x (lax-plist-remprop
- x prop val))' to be sure to use the new value. The LAX-PLIST is
+ x property))' to be sure to use the new value. The LAX-PLIST is
modified by side effects.
- - Function: lax-plist-member LAX-PLIST PROP
- This function returns `t' if PROP has a value specified in
+ - Function: lax-plist-member lax-plist property
+ This function returns `t' if PROPERTY has a value specified in
LAX-PLIST.
In the following functions, if optional arg NIL-MEANS-NOT-PRESENT is
thus E-Lisp, due to RMS's enamorment with old Lisps), but should not be
used except for backward compatibility.
- - Function: lax-plists-eq A B &optional NIL-MEANS-NOT-PRESENT
+ - Function: lax-plists-eq a b &optional nil-means-not-present
This function returns non-`nil' if lax property lists A and B are
`eq' (i.e. their values are `eq'; their keys are still compared
using `equal').
- - Function: lax-plists-equal A B &optional NIL-MEANS-NOT-PRESENT
+ - Function: lax-plists-equal a b &optional nil-means-not-present
This function returns non-`nil' if lax property lists A and B are
`equal' (i.e. their values are `equal').
- - Function: canonicalize-lax-plist LAX-PLIST &optional
- NIL-MEANS-NOT-PRESENT
+ - Function: canonicalize-lax-plist lax-plist &optional
+ nil-means-not-present
This function destructively removes any duplicate entries from a
lax plist. In such cases, the first entry applies.
Converting Plists To/From Alists
--------------------------------
- - Function: alist-to-plist ALIST
+ - Function: alist-to-plist alist
This function converts association list ALIST into the equivalent
property-list form. The plist is returned. This converts from
The original alist is not modified.
- - Function: plist-to-alist PLIST
+ - Function: plist-to-alist plist
This function converts property list PLIST into the equivalent
association-list form. The alist is returned. This converts from
from the original list to form the new list rather than allocating new
cons cells.
- - Function: destructive-alist-to-plist ALIST
+ - Function: destructive-alist-to-plist alist
This function destructively converts association list ALIST into
the equivalent property-list form. The plist is returned.
- - Function: destructive-plist-to-alist PLIST
+ - Function: destructive-plist-to-alist plist
This function destructively converts property list PLIST into the
equivalent association-list form. The alist is returned.
done with the elements, they will automatically disappear from the list.
Weak lists are used internally, for example, to manage the list
-holding the children of an extent - an extent that is unused but has a
+holding the children of an extent--an extent that is unused but has a
parent will still be reclaimed, and will automatically be removed from
its parent's list of children.
Weak lists are similar to weak hash tables (*note Weak Hash
-Tables::.).
+Tables::).
- - Function: weak-list-p OBJECT
+ - Function: weak-list-p object
This function returns non-`nil' if OBJECT is a weak list.
Weak lists come in one of four types:
Objects in the list disappear if they are conses and the cdr is not
referenced outside of the list.
- - Function: make-weak-list &optional TYPE
+ - Function: make-weak-list &optional type
This function creates a new weak list of type TYPE. TYPE is a
symbol (one of `simple', `assoc', `key-assoc', or `value-assoc',
as described above) and defaults to `simple'.
- - Function: weak-list-type WEAK
+ - Function: weak-list-type weak
This function returns the type of the given weak-list object.
- - Function: weak-list-list WEAK
+ - Function: weak-list-list weak
This function returns the list contained in a weak-list object.
- - Function: set-weak-list-list WEAK NEW-LIST
+ - Function: set-weak-list-list weak new-list
This function changes the list contained in a weak-list object.
\1f