+++ /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: List Elements, Next: Building Lists, Prev: List-related Predicates, Up: Lists
-
-Accessing Elements of Lists
-===========================
-
- - 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.
-
- As a special case, if CONS-CELL is `nil', then `car' is defined to
- return `nil'; therefore, any list is a valid argument for `car'.
- An error is signaled if the argument is not a cons cell or `nil'.
-
- (car '(a b c))
- => a
- (car '())
- => nil
-
- - 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.
-
- As a special case, if CONS-CELL is `nil', then `cdr' is defined to
- return `nil'; therefore, any list is a valid argument for `cdr'.
- An error is signaled if the argument is not a cons cell or `nil'.
-
- (cdr '(a b c))
- => (b c)
- (cdr '())
- => nil
-
- - 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', which signals an error if OBJECT is not a list.
-
- (car-safe OBJECT)
- ==
- (let ((x OBJECT))
- (if (consp x)
- (car x)
- nil))
-
- - 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', which signals an error if OBJECT is not a list.
-
- (cdr-safe OBJECT)
- ==
- (let ((x OBJECT))
- (if (consp x)
- (cdr x)
- nil))
-
- - 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'.
-
- If N is negative, `nth' returns the first element of LIST.
-
- (nth 2 '(1 2 3 4))
- => 3
- (nth 10 '(1 2 3 4))
- => nil
- (nth -3 '(1 2 3 4))
- => 1
-
- (nth n x) == (car (nthcdr n x))
-
- - 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.
-
- If N is zero or negative, `nthcdr' returns all of LIST. If the
- length of LIST is N or less, `nthcdr' returns `nil'.
-
- (nthcdr 1 '(1 2 3 4))
- => (2 3 4)
- (nthcdr 10 '(1 2 3 4))
- => nil
- (nthcdr -3 '(1 2 3 4))
- => (1 2 3 4)
-
- Many convenience functions are provided to make it easier for you to
-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
- Each of these functions is equivalent to one or more applications
- of `car' and/or `cdr'. For example,
-
- (cadr x)
-
- is equivalent to
-
- (car (cdr x))
-
- and
-
- (cdaddr x)
-
- is equivalent to
-
- (cdr (car (cdr (cdr x))))
-
- 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
- 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
- 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
- These are equivalent to `(nth 2 LIST)' through `(nth 9 LIST)'
- respectively, i.e. the third through tenth elements of LIST.
-
-\1f
-File: lispref.info, Node: Building Lists, Next: Modifying Lists, Prev: List Elements, Up: Lists
-
-Building Cons Cells and Lists
-=============================
-
- Many functions build lists, as lists reside at the very heart of
-Lisp. `cons' is the fundamental list-building function; however, it is
-interesting to note that `list' is used more times in the source code
-for Emacs than `cons'.
-
- - 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
- arguments OBJECT1 and OBJECT2 may be any Lisp objects, but most
- often OBJECT2 is a list.
-
- (cons 1 '(2))
- => (1 2)
- (cons 1 '())
- => (1)
- (cons 1 2)
- => (1 . 2)
-
- `cons' is often used to add a single element to the front of a
- list. This is called "consing the element onto the list". For
- example:
-
- (setq list (cons newelt list))
-
- Note that there is no conflict between the variable named `list'
- used in this example and the function named `list' described below;
- any symbol can serve both purposes.
-
- - 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 1 2 3 4 5)
- => (1 2 3 4 5)
- (list 1 2 '(3 4 5) 'foo)
- => (1 2 (3 4 5) foo)
- (list)
- => nil
-
- - 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::.).
-
- (make-list 3 'pigs)
- => (pigs pigs pigs)
- (make-list 0 'pigs)
- => nil
-
- - 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
- are copied, so none of them are altered.
-
- More generally, the final argument to `append' may be any Lisp
- object. The final argument is not copied or converted; it becomes
- the CDR of the last cons cell in the new list. If the final
- argument is itself a list, then its elements become in effect
- elements of the result list. If the final element is not a list,
- the result is a "dotted list" since its final CDR is not `nil' as
- required in a true list.
-
- See `nconc' in *Note Rearrangement::, for a way to join lists with
- no copying.
-
- Here is an example of using `append':
-
- (setq trees '(pine oak))
- => (pine oak)
- (setq more-trees (append '(maple birch) trees))
- => (maple birch pine oak)
-
- trees
- => (pine oak)
- more-trees
- => (maple birch pine oak)
- (eq trees (cdr (cdr more-trees)))
- => t
-
- You can see how `append' works by looking at a box diagram. The
- variable `trees' is set to the list `(pine oak)' and then the
- variable `more-trees' is set to the list `(maple birch pine oak)'.
- However, the variable `trees' continues to refer to the original
- list:
-
- more-trees trees
- | |
- | ___ ___ ___ ___ -> ___ ___ ___ ___
- --> |___|___|--> |___|___|--> |___|___|--> |___|___|--> nil
- | | | |
- | | | |
- --> maple -->birch --> pine --> oak
-
- An empty sequence contributes nothing to the value returned by
- `append'. As a consequence of this, a final `nil' argument forces
- a copy of the previous argument.
-
- trees
- => (pine oak)
- (setq wood (append trees ()))
- => (pine oak)
- wood
- => (pine oak)
- (eq wood trees)
- => nil
-
- This once was the usual way to copy a list, before the function
- `copy-sequence' was invented. *Note Sequences Arrays Vectors::.
-
- With the help of `apply', we can append all the lists in a list of
- lists:
-
- (apply 'append '((a b c) nil (x y z) nil))
- => (a b c x y z)
-
- If no SEQUENCES are given, `nil' is returned:
-
- (append)
- => nil
-
- Here are some examples where the final argument is not a list:
-
- (append '(x y) 'z)
- => (x y . z)
- (append '(x y) [z])
- => (x y . [z])
-
- The second example shows that when the final argument is a
- sequence but not a list, the sequence's elements do not become
- elements of the resulting list. Instead, the sequence becomes the
- final CDR, like any other non-list final argument.
-
- The `append' function also allows integers as arguments. It
- converts them to strings of digits, making up the decimal print
- representation of the integer, and then uses the strings instead
- 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::.).
-
- - 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*
- altered.
-
- (setq x '(1 2 3 4))
- => (1 2 3 4)
- (reverse x)
- => (4 3 2 1)
- x
- => (1 2 3 4)
-
-\1f
-File: lispref.info, Node: Modifying Lists, Next: Sets And Lists, Prev: Building Lists, Up: Lists
-
-Modifying Existing List Structure
-=================================
-
- You can modify the CAR and CDR contents of a cons cell with the
-primitives `setcar' and `setcdr'.
-
- Common Lisp note: Common Lisp uses functions `rplaca' and `rplacd'
- to alter list structure; they change structure the same way as
- `setcar' and `setcdr', but the Common Lisp functions return the
- cons cell while `setcar' and `setcdr' return the new CAR or CDR.
-
-* Menu:
-
-* Setcar:: Replacing an element in a list.
-* Setcdr:: Replacing part of the list backbone.
- This can be used to remove or add elements.
-* Rearrangement:: Reordering the elements in a list; combining lists.
-
-\1f
-File: lispref.info, Node: Setcar, Next: Setcdr, Up: Modifying Lists
-
-Altering List Elements with `setcar'
-------------------------------------
-
- Changing the CAR of a cons cell is done with `setcar'. When used on
-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:
-
- (setq x '(1 2))
- => (1 2)
- (setcar x 4)
- => 4
- x
- => (4 2)
-
- When a cons cell is part of the shared structure of several lists,
-storing a new CAR into the cons changes one element of each of these
-lists. Here is an example:
-
- ;; Create two lists that are partly shared.
- (setq x1 '(a b c))
- => (a b c)
- (setq x2 (cons 'z (cdr x1)))
- => (z b c)
-
- ;; Replace the CAR of a shared link.
- (setcar (cdr x1) 'foo)
- => foo
- x1 ; Both lists are changed.
- => (a foo c)
- x2
- => (z foo c)
-
- ;; Replace the CAR of a link that is not shared.
- (setcar x1 'baz)
- => baz
- x1 ; Only one list is changed.
- => (baz foo c)
- x2
- => (z foo c)
-
- Here is a graphical depiction of the shared structure of the two
-lists in the variables `x1' and `x2', showing why replacing `b' changes
-them both:
-
- ___ ___ ___ ___ ___ ___
- x1---> |___|___|----> |___|___|--> |___|___|--> nil
- | --> | |
- | | | |
- --> a | --> b --> c
- |
- ___ ___ |
- x2--> |___|___|--
- |
- |
- --> z
-
- Here is an alternative form of box diagram, showing the same
-relationship:
-
- x1:
- -------------- -------------- --------------
- | car | cdr | | car | cdr | | car | cdr |
- | a | o------->| b | o------->| c | nil |
- | | | -->| | | | | |
- -------------- | -------------- --------------
- |
- x2: |
- -------------- |
- | car | cdr | |
- | z | o----
- | | |
- --------------
-
-\1f
-File: lispref.info, Node: Setcdr, Next: Rearrangement, Prev: Setcar, Up: Modifying Lists
-
-Altering the CDR of a List
---------------------------
-
- 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.
-
- 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
-different sequence of elements. The first element is unchanged,
-because it resides in the CAR of the list, and is not reached via the
-CDR.
-
- (setq x '(1 2 3))
- => (1 2 3)
- (setcdr x '(4))
- => (4)
- x
- => (1 4)
-
- You can delete elements from the middle of a list by altering the
-CDRs of the cons cells in the list. For example, here we delete the
-second element, `b', from the list `(a b c)', by changing the CDR of
-the first cell:
-
- (setq x1 '(a b c))
- => (a b c)
- (setcdr x1 (cdr (cdr x1)))
- => (c)
- x1
- => (a c)
-
- Here is the result in box notation:
-
- --------------------
- | |
- -------------- | -------------- | --------------
- | car | cdr | | | car | cdr | -->| car | cdr |
- | a | o----- | b | o-------->| c | nil |
- | | | | | | | | |
- -------------- -------------- --------------
-
-The second cons cell, which previously held the element `b', still
-exists and its CAR is still `b', but it no longer forms part of this
-list.
-
- It is equally easy to insert a new element by changing CDRs:
-
- (setq x1 '(a b c))
- => (a b c)
- (setcdr x1 (cons 'd (cdr x1)))
- => (d b c)
- x1
- => (a d b c)
-
- Here is this result in box notation:
-
- -------------- ------------- -------------
- | car | cdr | | car | cdr | | car | cdr |
- | a | o | -->| b | o------->| c | nil |
- | | | | | | | | | | |
- --------- | -- | ------------- -------------
- | |
- ----- --------
- | |
- | --------------- |
- | | car | cdr | |
- -->| d | o------
- | | |
- ---------------
-
-\1f
-File: lispref.info, Node: Rearrangement, Prev: Setcdr, Up: Modifying Lists
-
-Functions that Rearrange Lists
-------------------------------
-
- Here are some functions that rearrange lists "destructively" by
-modifying the CDRs of their component cons cells. We call these
-functions "destructive" because they chew up the original lists passed
-to them as arguments, to produce a new list that is the returned value.
-
- See `delq', in *Note Sets And Lists::, for another function that
-modifies cons cells.
-
- - Function: nconc &rest LISTS
- This function returns a list containing all the elements of LISTS.
- 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:
-
- (setq x '(1 2 3))
- => (1 2 3)
- (nconc x '(4 5))
- => (1 2 3 4 5)
- x
- => (1 2 3 4 5)
-
- Since the last argument of `nconc' is not itself modified, it is
- reasonable to use a constant list, such as `'(4 5)', as in the
- above example. For the same reason, the last argument need not be
- a list:
-
- (setq x '(1 2 3))
- => (1 2 3)
- (nconc x 'z)
- => (1 2 3 . z)
- x
- => (1 2 3 . z)
-
- A common pitfall is to use a quoted constant list as a non-last
- argument to `nconc'. If you do this, your program will change
- each time you run it! Here is what happens:
-
- (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
- 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
- the last one in LIST becomes the first cell of the value.
-
- For example:
-
- (setq x '(1 2 3 4))
- => (1 2 3 4)
- x
- => (1 2 3 4)
- (nreverse x)
- => (4 3 2 1)
- ;; The cell that was first is now last.
- x
- => (1)
-
- To avoid confusion, we usually store the result of `nreverse' back
- in the same variable which held the original list:
-
- (setq x (nreverse x))
-
- Here is the `nreverse' of our favorite example, `(a b c)',
- presented graphically:
-
- Original list head: Reversed list:
- ------------- ------------- ------------
- | car | cdr | | car | cdr | | car | cdr |
- | a | nil |<-- | b | o |<-- | c | o |
- | | | | | | | | | | | | |
- ------------- | --------- | - | -------- | -
- | | | |
- ------------- ------------
-
- - 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
- relative order before and after the sort. Stability is important
- when successive sorts are used to order elements according to
- different criteria.
-
- The argument PREDICATE must be a function that accepts two
- arguments. It is called with two elements of LIST. To get an
- increasing order sort, the PREDICATE should return `t' if the
- first element is "less than" the second, or `nil' if not.
-
- The destructive aspect of `sort' is that it rearranges the cons
- cells forming LIST by changing CDRs. A nondestructive sort
- function would create new cons cells to store the elements in their
- sorted order. If you wish to make a sorted copy without
- destroying the original, copy it first with `copy-sequence' and
- then sort.
-
- Sorting does not change the CARs of the cons cells in LIST; the
- cons cell that originally contained the element `a' in LIST still
- has `a' in its CAR after sorting, but it now appears in a
- different position in the list due to the change of CDRs. For
- example:
-
- (setq nums '(1 3 2 6 5 4 0))
- => (1 3 2 6 5 4 0)
- (sort nums '<)
- => (0 1 2 3 4 5 6)
- nums
- => (1 2 3 4 5 6)
-
- Note that the list in `nums' no longer contains 0; this is the same
- cons cell that it was before, but it is no longer the first one in
- the list. Don't assume a variable that formerly held the argument
- now holds the entire sorted list! Instead, save the result of
- `sort' and use that. Most often we store the result back into the
- variable that held the original list:
-
- (setq nums (sort nums '<))
-
- *Note Sorting::, for more functions that perform sorting. See
- `documentation' in *Note Accessing Documentation::, for a useful
- example of `sort'.
-
-\1f
-File: lispref.info, Node: Sets And Lists, Next: Association Lists, Prev: Modifying Lists, Up: Lists
-
-Using Lists as Sets
-===================
-
- A list can represent an unordered mathematical set--simply consider a
-value an element of a set if it appears in the list, and ignore the
-order of the list. To form the union of two sets, use `append' (as
-long as you don't mind having duplicate elements). Other useful
-functions for sets include `memq' and `delq', and their `equal'
-versions, `member' and `delete'.
-
- Common Lisp note: Common Lisp has functions `union' (which avoids
- duplicate elements) and `intersection' for set operations, but
- XEmacs Lisp does not have them. You can write them in Lisp if you
- wish.
-
- - 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'
- says that it uses `eq' to compare OBJECT against the elements of
- the list. For example:
-
- (memq 'b '(a b c b a))
- => (b c b a)
- (memq '(2) '((1) (2))) ; `(2)' and `(2)' are not `eq'.
- => nil
-
- - 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'.
-
- When `delq' deletes elements from the front of the list, it does so
-simply by advancing down the list and returning a sublist that starts
-after those elements:
-
- (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::.).
-
- (setq sample-list '(a b c (4)))
- => (a b c (4))
- (delq 'a sample-list)
- => (b c (4))
- sample-list
- => (a b c (4))
- (delq 'c sample-list)
- => (a b (4))
- sample-list
- => (a b (4))
-
- Note that `(delq 'c sample-list)' modifies `sample-list' to splice
-out the third element, but `(delq 'a sample-list)' does not splice
-anything--it just returns a shorter list. Don't assume that a variable
-which formerly held the argument LIST now has fewer elements, or that
-it still holds the original list! Instead, save the result of `delq'
-and use that. Most often we store the result back into the variable
-that held the original list:
-
- (setq flowers (delq 'rose flowers))
-
- In the following example, the `(4)' that `delq' attempts to match
-and the `(4)' in the `sample-list' are not `eq':
-
- (delq '(4) sample-list)
- => (a 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
- 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
- in LIST. Otherwise, it returns `nil'.
-
- Compare this with `memq':
-
- (member '(2) '((1) (2))) ; `(2)' and `(2)' are `equal'.
- => ((2))
- (memq '(2) '((1) (2))) ; `(2)' and `(2)' are not `eq'.
- => nil
- ;; Two strings with the same contents are `equal'.
- (member "foo" '("foo" "bar"))
- => ("foo" "bar")
-
- - 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
- finds an element that matches, it removes the element just as
- `delq' would. For example:
-
- (delete '(2) '((2) (1) (2)))
- => '((1))
-
- Common Lisp note: The functions `member' and `delete' in XEmacs
- Lisp are derived from Maclisp, not Common Lisp. The Common Lisp
- versions do not use `equal' to compare elements.
-
- See also the function `add-to-list', in *Note Setting Variables::,
-for another way to add an element to a list stored in a variable.
-
-\1f
-File: lispref.info, Node: Association Lists, Next: Property Lists, Prev: Sets And Lists, Up: Lists
-
-Association Lists
-=================
-
- An "association list", or "alist" for short, records a mapping from
-keys to values. It is a list of cons cells called "associations": the
-CAR of each cell is the "key", and the CDR is the "associated value".(1)
-
- Here is an example of an alist. The key `pine' is associated with
-the value `cones'; the key `oak' is associated with `acorns'; and the
-key `maple' is associated with `seeds'.
-
- '((pine . cones)
- (oak . acorns)
- (maple . seeds))
-
- 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:
-
- ((a . 1) ("b" 2 3))
-
- Sometimes it is better to design an alist to store the associated
-value in the CAR of the CDR of the element. Here is an example:
-
- '((rose red) (lily white) (buttercup yellow))
-
-Here we regard `red' as the value associated with `rose'. One
-advantage of this method is that you can store other related
-information--even a list of other items--in the CDR of the CDR. One
-disadvantage is that you cannot use `rassq' (see below) to find the
-element containing a given value. When neither of these considerations
-is important, the choice is a matter of taste, as long as you are
-consistent about it for any given alist.
-
- Note that the same alist shown above could be regarded as having the
-associated value in the CDR of the element; the value associated with
-`rose' would be the list `(red)'.
-
- Association lists are often used to record information that you might
-otherwise keep on a stack, since new associations may be added easily to
-the front of the list. When searching an association list for an
-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
-list is not a cons cell. The alist search functions simply ignore such
-elements. Many other versions of Lisp signal errors in such cases.
-
- Note that property lists are similar to association lists in several
-respects. A property list behaves like an association list in which
-each key can occur only once. *Note Property Lists::, for a comparison
-of property lists and association lists.
-
- - 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
- ALIST has a CAR `equal' to KEY. For example:
-
- (setq trees '((pine . cones) (oak . acorns) (maple . seeds)))
- => ((pine . cones) (oak . acorns) (maple . seeds))
- (assoc 'oak trees)
- => (oak . acorns)
- (cdr (assoc 'oak trees))
- => acorns
- (assoc 'birch trees)
- => nil
-
- Here is another example, in which the keys and values are not
- symbols:
-
- (setq needles-per-cluster
- '((2 "Austrian Pine" "Red Pine")
- (3 "Pitch Pine")
- (5 "White Pine")))
-
- (cdr (assoc 3 needles-per-cluster))
- => ("Pitch Pine")
- (cdr (assoc 2 needles-per-cluster))
- => ("Austrian Pine" "Red Pine")
-
- - 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.
-
- `rassoc' is like `assoc' except that it compares the CDR of each
- 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
- 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
- in ALIST has a CAR `eq' to KEY. This function is used more often
- than `assoc', since `eq' is faster than `equal' and most alists
- use symbols as keys. *Note Equality Predicates::.
-
- (setq trees '((pine . cones) (oak . acorns) (maple . seeds)))
- => ((pine . cones) (oak . acorns) (maple . seeds))
- (assq 'pine trees)
- => (pine . cones)
-
- On the other hand, `assq' is not usually useful in alists where the
- keys may not be symbols:
-
- (setq leaves
- '(("simple leaves" . oak)
- ("compound leaves" . horsechestnut)))
-
- (assq "simple leaves" leaves)
- => nil
- (assoc "simple leaves" leaves)
- => ("simple leaves" . oak)
-
- - 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.
-
- `rassq' is like `assq' except that it compares the CDR of each
- ALIST association instead of the CAR. You can think of this as
- "reverse `assq'", finding the key for a given value.
-
- For example:
-
- (setq trees '((pine . cones) (oak . acorns) (maple . seeds)))
-
- (rassq 'acorns trees)
- => (oak . acorns)
- (rassq 'spores trees)
- => nil
-
- Note that `rassq' cannot search for a value stored in the CAR of
- the CDR of an element:
-
- (setq colors '((rose red) (lily white) (buttercup yellow)))
-
- (rassq 'white colors)
- => nil
-
- In this case, the CDR of the association `(lily white)' is not the
- symbol `white', but rather the list `(white)'. This becomes
- clearer if the association is written in dotted pair notation:
-
- (lily white) == (lily . (white))
-
- - 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
- `equal' to KEY. The modified ALIST is returned.
-
- If the first member of ALIST has a `car' that is `equal' to KEY,
- there is no way to remove it by side effect; therefore, write
- `(setq foo (remassoc key foo))' to be sure of changing the value
- of `foo'.
-
- - 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
- `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
- This function deletes by side effect any associations with value
- 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,
- there is no way to remove it by side effect; therefore, write
- `(setq foo (remassoc value foo))' to be sure of changing the value
- of `foo'.
-
- `remrassoc' is like `remassoc' except that it compares the CDR of
- each ALIST association instead of the CAR. You can think of this
- as "reverse `remassoc'", removing an association based on its
- value instead of its key.
-
- - 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
- `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
- 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.
-
- (setq needles-per-cluster
- '((2 . ("Austrian Pine" "Red Pine"))
- (3 . ("Pitch Pine"))
- (5 . ("White Pine"))))
- =>
- ((2 "Austrian Pine" "Red Pine")
- (3 "Pitch Pine")
- (5 "White Pine"))
-
- (setq copy (copy-alist needles-per-cluster))
- =>
- ((2 "Austrian Pine" "Red Pine")
- (3 "Pitch Pine")
- (5 "White Pine"))
-
- (eq needles-per-cluster copy)
- => nil
- (equal needles-per-cluster copy)
- => t
- (eq (car needles-per-cluster) (car copy))
- => nil
- (cdr (car (cdr needles-per-cluster)))
- => ("Pitch Pine")
- (eq (cdr (car (cdr needles-per-cluster)))
- (cdr (car (cdr copy))))
- => t
-
- This example shows how `copy-alist' makes it possible to change
- the associations of one copy without affecting the other:
-
- (setcdr (assq 3 copy) '("Martian Vacuum Pine"))
- (cdr (assq 3 needles-per-cluster))
- => ("Pitch Pine")
-
- ---------- Footnotes ----------
-
- (1) This usage of "key" is not related to the term "key sequence";
-it means a value used to look up an item in a table. In this case, the
-table is the alist, and the alist associations are the items.
-
-\1f
-File: lispref.info, Node: Property Lists, Next: Weak Lists, Prev: Association Lists, Up: Lists
-
-Property Lists
-==============
-
- A "property list" (or "plist") is another way of representing a
-mapping from keys to values. Instead of the list consisting of conses
-of a key and a value, the keys and values alternate as successive
-entries in the list. Thus, the association list
-
- ((a . 1) (b . 2) (c . 3))
-
- has the equivalent property list form
-
- (a 1 b 2 c 3)
-
- Property lists are used to represent the properties associated with
-various sorts of objects, such as symbols, strings, frames, etc. The
-convention is that property lists can be modified in-place, while
-association lists generally are not.
-
- Plists come in two varieties: "normal" plists, whose keys are
-compared with `eq', and "lax" plists, whose keys are compared with
-`equal',
-
- - 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
- 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.
-
-* Menu:
-
-* Working With Normal Plists:: Functions for normal plists.
-* Working With Lax Plists:: Functions for lax plists.
-* Converting Plists To/From Alists:: Alist to plist and vice-versa.
-
-\1f
-File: lispref.info, Node: Working With Normal Plists, Next: Working With Lax Plists, Up: Property Lists
-
-Working With Normal Plists
---------------------------
-
- - Function: plist-get PLIST PROP &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.
-
- - Function: plist-member PLIST PROP
- This function returns `t' if PROP 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.
-This feature is a virus that has infected old Lisp implementations (and
-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
- 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
- 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
- This function destructively removes any duplicate entries from a
- plist. In such cases, the first entry applies.
-
- The new plist is returned. If NIL-MEANS-NOT-PRESENT is given, the
- return value may not be `eq' to the passed-in value, so make sure
- to `setq' the value back into where it came from.
-
-\1f
-File: lispref.info, Node: Working With Lax Plists, Next: Converting Plists To/From Alists, Prev: Working With Normal Plists, Up: Property Lists
-
-Working With Lax Plists
------------------------
-
- 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
- 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: lax-plist-put LAX-PLIST PROP VAL
- This function changes the value in LAX-PLIST of PROP to VAL.
-
- - Function: lax-plist-remprop LAX-PLIST PROP
- This function removes from LAX-PLIST the property PROP 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
- modified by side effects.
-
- - Function: lax-plist-member LAX-PLIST PROP
- This function returns `t' if PROP has a value specified in
- LAX-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.
-This feature is a virus that has infected old Lisp implementations (and
-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
- 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
- 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
- This function destructively removes any duplicate entries from a
- lax plist. In such cases, the first entry applies.
-
- The new plist is returned. If NIL-MEANS-NOT-PRESENT is given, the
- return value may not be `eq' to the passed-in value, so make sure
- to `setq' the value back into where it came from.
-
-\1f
-File: lispref.info, Node: Converting Plists To/From Alists, Prev: Working With Lax Plists, Up: Property Lists
-
-Converting Plists To/From Alists
---------------------------------
-
- - Function: alist-to-plist ALIST
- This function converts association list ALIST into the equivalent
- property-list form. The plist is returned. This converts from
-
- ((a . 1) (b . 2) (c . 3))
-
- into
-
- (a 1 b 2 c 3)
-
- The original alist is not modified.
-
- - Function: plist-to-alist PLIST
- This function converts property list PLIST into the equivalent
- association-list form. The alist is returned. This converts from
-
- (a 1 b 2 c 3)
-
- into
-
- ((a . 1) (b . 2) (c . 3))
-
- The original plist is not modified.
-
- The following two functions are equivalent to the preceding two
-except that they destructively modify their arguments, using cons cells
-from the original list to form the new list rather than allocating new
-cons cells.
-
- - 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
- This function destructively converts property list PLIST into the
- equivalent association-list form. The alist is returned.
-
-\1f
-File: lispref.info, Node: Weak Lists, Prev: Property Lists, Up: Lists
-
-Weak Lists
-==========
-
- A "weak list" is a special sort of list whose members are not counted
-as references for the purpose of garbage collection. This means that,
-for any object in the list, if there are no references to the object
-anywhere outside of the list (or other weak list or weak hash table),
-that object will disappear the next time a garbage collection happens.
-Weak lists can be useful for keeping track of things such as unobtrusive
-lists of another function's buffers or markers. When that function is
-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
-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::.).
-
- - Function: weak-list-p OBJECT
- This function returns non-`nil' if OBJECT is a weak list.
-
- Weak lists come in one of four types:
-
-`simple'
- Objects in the list disappear if not referenced outside of the
- list.
-
-`assoc'
- Objects in the list disappear if they are conses and either the
- car or the cdr of the cons is not referenced outside of the list.
-
-`key-assoc'
- Objects in the list disappear if they are conses and the car is not
- referenced outside of the list.
-
-`value-assoc'
- 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
- 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
- This function returns the type of the given weak-list object.
-
- - Function: weak-list-list WEAK
- This function returns the list contained in a weak-list object.
-
- - Function: set-weak-list-list WEAK NEW-LIST
- This function changes the list contained in a weak-list object.
-
-\1f
-File: lispref.info, Node: Sequences Arrays Vectors, Next: Symbols, Prev: Lists, Up: Top
-
-Sequences, Arrays, and Vectors
-******************************
-
- Recall that the "sequence" type is the union of four other Lisp
-types: lists, vectors, bit vectors, and strings. In other words, any
-list is a sequence, any vector is a sequence, any bit vector is a
-sequence, and any string is a sequence. The common property that all
-sequences have is that each is an ordered collection of elements.
-
- An "array" is a single primitive object that has a slot for each
-elements. All the elements are accessible in constant time, but the
-length of an existing array cannot be changed. Strings, vectors, and
-bit vectors are the three types of arrays.
-
- A list is a sequence of elements, but it is not a single primitive
-object; it is made of cons cells, one cell per element. Finding the
-Nth element requires looking through N cons cells, so elements farther
-from the beginning of the list take longer to access. But it is
-possible to add elements to the list, or remove elements.
-
- The following diagram shows the relationship between these types:
-
- ___________________________________
- | |
- | Sequence |
- | ______ ______________________ |
- | | | | | |
- | | List | | Array | |
- | | | | ________ _______ | |
- | |______| | | | | | | |
- | | | Vector | | String| | |
- | | |________| |_______| | |
- | | __________________ | |
- | | | | | |
- | | | Bit Vector | | |
- | | |__________________| | |
- | |______________________| |
- |___________________________________|
-
- The elements of vectors and lists may be any Lisp objects. The
-elements of strings are all characters. The elements of bit vectors
-are the numbers 0 and 1.
-
-* Menu:
-
-* Sequence Functions:: Functions that accept any kind of sequence.
-* Arrays:: Characteristics of arrays in XEmacs Lisp.
-* Array Functions:: Functions specifically for arrays.
-* Vectors:: Special characteristics of XEmacs Lisp vectors.
-* Vector Functions:: Functions specifically for vectors.
-* Bit Vectors:: Special characteristics of XEmacs Lisp bit vectors.
-* Bit Vector Functions:: Functions specifically for bit vectors.
-
projects / chise / xemacs-chise.git.1 / blobdiff