X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/b5ef0e9225a05268e98b1304cf37259dc79aa9c2..c5c927519c95b69cf998228a975c66e0d75d3215:/lispref/lists.texi

diff --git a/lispref/lists.texi b/lispref/lists.texi
index da9d57319e..1894fc3e15 100644
--- a/lispref/lists.texi
+++ b/lispref/lists.texi
@@ -1,6 +1,7 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. 
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999
+@c   Free Software Foundation, Inc. 
 @c See the file elisp.texi for copying conditions.
 @setfilename ../info/lists
 @node Lists, Sequences Arrays Vectors, Strings and Characters, Top
@@ -32,16 +33,21 @@ the whole list.
 
   Lists in Lisp are not a primitive data type; they are built up from
 @dfn{cons cells}.  A cons cell is a data object that represents an
-ordered pair.  It records two Lisp objects, one labeled as the @sc{car},
-and the other labeled as the @sc{cdr}.  These names are traditional; see
-@ref{Cons Cell Type}.  @sc{cdr} is pronounced ``could-er.''
-
-  A list is a series of cons cells chained together, one cons cell per
-element of the list.  By convention, the @sc{car}s of the cons cells are
-the elements of the list, and the @sc{cdr}s are used to chain the list:
-the @sc{cdr} of each cons cell is the following cons cell.  The @sc{cdr}
-of the last cons cell is @code{nil}.  This asymmetry between the
-@sc{car} and the @sc{cdr} is entirely a matter of convention; at the
+ordered pair.  That is, it has two slots, and each slot @dfn{holds}, or
+@dfn{refers to}, some Lisp object.  One slot is known as the @sc{car},
+and the other is known as the @sc{cdr}.  (These names are traditional;
+see @ref{Cons Cell Type}.)  @sc{cdr} is pronounced ``could-er.''
+
+  We say that ``the @sc{car} of this cons cell is'' whatever object
+its @sc{car} slot currently holds, and likewise for the @sc{cdr}.
+
+  A list is a series of cons cells ``chained together,'' so that each
+cell refers to the next one.  There is one cons cell for each element of
+the list.  By convention, the @sc{car}s of the cons cells hold the
+elements of the list, and the @sc{cdr}s are used to chain the list: the
+@sc{cdr} slot of each cons cell refers to the following cons cell.  The
+@sc{cdr} of the last cons cell is @code{nil}.  This asymmetry between
+the @sc{car} and the @sc{cdr} is entirely a matter of convention; at the
 level of cons cells, the @sc{car} and @sc{cdr} slots have the same
 characteristics.
 
@@ -81,19 +87,20 @@ made from two cons cells:
 @end example
 
   Each pair of boxes represents a cons cell.  Each box ``refers to'',
-``points to'' or ``contains'' a Lisp object.  (These terms are
-synonymous.)  The first box, which is the @sc{car} of the first cons
-cell, contains the symbol @code{tulip}.  The arrow from the @sc{cdr} of
-the first cons cell to the second cons cell indicates that the @sc{cdr}
-of the first cons cell points to the second cons cell.
+``points to'' or ``holds'' a Lisp object.  (These terms are
+synonymous.)  The first box, which describes the @sc{car} of the first
+cons cell, contains the symbol @code{tulip}.  The arrow from the
+@sc{cdr} box of the first cons cell to the second cons cell indicates
+that the @sc{cdr} of the first cons cell is the second cons cell.
 
   The same list can be illustrated in a different sort of box notation
 like this:
 
 @example
 @group
-    ___ ___      ___ ___
-   |___|___|--> |___|___|--> nil
+    --- ---      --- ---
+   |   |   |--> |   |   |--> nil
+    --- ---      --- ---
      |            |
      |            |
       --> tulip    --> lily
@@ -106,14 +113,16 @@ two-element list:
 
 @example
 @group
-    ___ ___      ___ ___      ___ ___
-   |___|___|--> |___|___|--> |___|___|--> nil
+    --- ---      --- ---      --- ---
+   |   |   |--> |   |   |--> |   |   |--> nil
+    --- ---      --- ---      --- ---
      |            |            |
      |            |            |
      |             --> oak      --> maple
      |
-     |     ___ ___      ___ ___
-      --> |___|___|--> |___|___|--> nil
+     |     --- ---      --- ---
+      --> |   |   |--> |   |   |--> nil
+           --- ---      --- ---
             |            |
             |            |
              --> pine     --> needles
@@ -218,7 +227,7 @@ considered a list and @code{not} when it is considered a truth value
 @cindex list elements
 
 @defun car cons-cell
-This function returns the value pointed to by the first pointer of the
+This function returns the value referred to by the first slot of the
 cons cell @var{cons-cell}.  Expressed another way, this function
 returns the @sc{car} of @var{cons-cell}.
 
@@ -240,7 +249,7 @@ or @code{nil}.
 @end defun
 
 @defun cdr cons-cell
-This function returns the value pointed to by the second pointer of
+This function returns the value referred to by the second slot of
 the cons cell @var{cons-cell}.  Expressed another way, this function
 returns the @sc{cdr} of @var{cons-cell}.
 
@@ -298,6 +307,26 @@ This is in contrast to @code{cdr}, which signals an error if
 @end example
 @end defun
 
+@tindex pop
+@defmac pop listname
+This macro is a way of examining the @sc{car} of a list,
+and taking it off the list, all at once.  It is new in Emacs 21.
+
+It operates on the list which is stored in the symbol @var{listname}.
+It removes this element from the list by setting @var{listname}
+to the @sc{cdr} of its old value---but it also returns the @sc{car}
+of that list, which is the element being removed.
+
+@example
+x
+     @result{} (a b c)
+(pop x)
+     @result{} a
+x
+     @result{} (b c)
+@end example
+@end defmac
+
 @defun nth n list
 This function returns the @var{n}th element of @var{list}.  Elements
 are numbered starting with zero, so the @sc{car} of @var{list} is
@@ -323,11 +352,15 @@ If @var{n} is negative, @code{nth} returns the first element of
 (nth n x) @equiv{} (car (nthcdr n x))
 @end group
 @end example
+
+The function @code{elt} is similar, but applies to any kind of sequence.
+For historical reasons, it takes its arguments in the opposite order.
+@xref{Sequence Functions}.
 @end defun
 
 @defun nthcdr n list
 This function returns the @var{n}th @sc{cdr} of @var{list}.  In other
-words, it removes the first @var{n} links of @var{list} and returns
+words, it skips past the first @var{n} links of @var{list} and returns
 what follows.
 
 If @var{n} is zero or negative, @code{nthcdr} returns all of
@@ -350,6 +383,59 @@ If @var{n} is zero or negative, @code{nthcdr} returns all of
 @end example
 @end defun
 
+@defun last list &optional n
+This function returns the last link of @var{list}.  The
+@code{car} of this link is the list's last element.  If @var{list} is
+null, @code{nil} is returned.  If @var{n} is non-nil the
+@var{n}-th-to-last link is returned instead, or the whole @var{list} if
+@var{n} is bigger than @var{list}'s length.
+@end defun
+
+@defun safe-length list
+This function returns the length of @var{list}, with no risk
+of either an error or an infinite loop.
+
+If @var{list} is not really a list, @code{safe-length} returns 0.  If
+@var{list} is circular, it returns a finite value which is at least the
+number of distinct elements.
+@end defun
+
+  The most common way to compute the length of a list, when you are not
+worried that it may be circular, is with @code{length}.  @xref{Sequence
+Functions}.
+
+@defun caar cons-cell
+This is the same as @code{(car (car @var{cons-cell}))}.
+@end defun
+
+@defun cadr cons-cell
+This is the same as @code{(car (cdr @var{cons-cell}))}
+or @code{(nth 1 @var{cons-cell})}.
+@end defun
+
+@defun cdar cons-cell
+This is the same as @code{(cdr (car @var{cons-cell}))}.
+@end defun
+
+@defun cddr cons-cell
+This is the same as @code{(cdr (cdr @var{cons-cell}))}
+or @code{(nthcdr 2 @var{cons-cell})}.
+@end defun
+
+@defun butlast x &optional n
+This function returns the list @var{x} with the last element,
+or the last @var{n} elements, removed.  If @var{n} is greater
+than zero it makes a copy of the list so as not to damage the
+original list.  In general, @code{(append (butlast @var{x} @var{n})
+(last @var{x} @var{n}))} will return a list equal to @var{x}.
+@end defun
+
+@defun nbutlast x &optional n
+This is a version of @code{butlast} that works by destructively
+modifying the @code{cdr} of the appropriate element, rather than
+making a copy of the list.
+@end defun
+
 @node Building Lists
 @comment  node-name,  next,  previous,  up
 @section Building Cons Cells and Lists
@@ -385,8 +471,16 @@ objects, but most often @var{object2} is a list.
 
 @cindex consing
 @code{cons} is often used to add a single element to the front of a
-list.  This is called @dfn{consing the element onto the list}.  For
-example:
+list.  This is called @dfn{consing the element onto the list}.
+@footnote{There is no strictly equivalent way to add an element to
+the end of a list.  You can use @code{(append @var{listname} (list
+@var{newelt}))}, which creates a whole new list by copying @var{listname}
+and adding @var{newelt} to its end.  Or you can use @code{(nconc
+@var{listname} (list @var{newelt}))}, which modifies @var{listname}
+by following all the @sc{cdr}s and then replacing the terminating
+@code{nil}.  Compare this to adding an element to the beginning of a
+list with @code{cons}, which neither copies nor modifies the list.}
+For example:
 
 @example
 (setq list (cons newelt list))
@@ -397,6 +491,22 @@ used in this example and the function named @code{list} described below;
 any symbol can serve both purposes.
 @end defun
 
+@tindex push
+@defmac push newelt listname
+This macro provides an alternative way to write
+@code{(setq @var{listname} (cons @var{newelt} @var{listname}))}.
+It is new in Emacs 21.
+
+@example
+(setq l '(a b)) 
+     @result{} (a b)
+(push 'c l)
+     @result{} (c a b)
+l
+     @result{} (c a b)
+@end example
+@end defmac
+
 @defun list &rest objects
 This function creates a list with @var{objects} as its elements.  The
 resulting list is always @code{nil}-terminated.  If no @var{objects}
@@ -419,9 +529,9 @@ are given, the empty list is returned.
 @end defun
 
 @defun make-list length object
-This function creates a list of length @var{length}, in which all the
-elements have the identical value @var{object}.  Compare
-@code{make-list} with @code{make-string} (@pxref{Creating Strings}).
+This function creates a list of @var{length} elements, in which each
+element is @var{object}.  Compare @code{make-list} with
+@code{make-string} (@pxref{Creating Strings}).
 
 @example
 @group
@@ -432,15 +542,23 @@ elements have the identical value @var{object}.  Compare
 (make-list 0 'pigs)
      @result{} nil
 @end group
+@group
+(setq l (make-list 3 '(a b))
+     @result{} ((a b) (a b) (a b))
+(eq (car l) (cadr l))
+     @result{} t
+@end group
 @end example
 @end defun
 
 @defun append &rest sequences
 @cindex copying lists
 This function returns a list containing all the elements of
-@var{sequences}.  The @var{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.
+@var{sequences}.  The @var{sequences} may be lists, vectors,
+bool-vectors, or strings, but the last one should usually be a list.
+All arguments except the last one are copied, so none of the arguments
+is altered.  (See @code{nconc} in @ref{Rearrangement}, for a way to join
+lists with no copying.)
 
 More generally, the final argument to @code{append} may be any Lisp
 object.  The final argument is not copied or converted; it becomes the
@@ -450,10 +568,17 @@ result list.  If the final element is not a list, the result is a
 ``dotted list'' since its final @sc{cdr} is not @code{nil} as required
 in a true list.
 
-See @code{nconc} in @ref{Rearrangement}, for a way to join lists with no
-copying.
+The @code{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.  @strong{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
+@code{format} (@pxref{Formatting Strings}) or @code{number-to-string}
+(@pxref{String Conversion}).
+@end defun
 
-Here is an example of using @code{append}:
+  Here is an example of using @code{append}:
 
 @example
 @group
@@ -475,7 +600,7 @@ more-trees
 @end group
 @end example
 
-You can see how @code{append} works by looking at a box diagram.  The
+  You can see how @code{append} works by looking at a box diagram.  The
 variable @code{trees} is set to the list @code{(pine oak)} and then the
 variable @code{more-trees} is set to the list @code{(maple birch pine
 oak)}.  However, the variable @code{trees} continues to refer to the
@@ -485,17 +610,18 @@ original list:
 @group
 more-trees                trees
 |                           |
-|     ___ ___      ___ ___   -> ___ ___      ___ ___
- --> |___|___|--> |___|___|--> |___|___|--> |___|___|--> nil
+|     --- ---      --- ---   -> --- ---      --- ---
+ --> |   |   |--> |   |   |--> |   |   |--> |   |   |--> nil
+      --- ---      --- ---      --- ---      --- ---
        |            |            |            |
        |            |            |            |
         --> maple    -->birch     --> pine     --> oak
 @end group
 @end smallexample
 
-An empty sequence contributes nothing to the value returned by
+  An empty sequence contributes nothing to the value returned by
 @code{append}.  As a consequence of this, a final @code{nil} argument
-forces a copy of the previous argument.
+forces a copy of the previous argument:
 
 @example
 @group
@@ -503,7 +629,7 @@ trees
      @result{} (pine oak)
 @end group
 @group
-(setq wood (append trees ()))
+(setq wood (append trees nil))
      @result{} (pine oak)
 @end group
 @group
@@ -520,8 +646,17 @@ wood
 This once was the usual way to copy a list, before the function
 @code{copy-sequence} was invented.  @xref{Sequences Arrays Vectors}.
 
-With the help of @code{apply}, we can append all the lists in a list of
-lists:
+  Here we show the use of vectors and strings as arguments to @code{append}:
+
+@example
+@group
+(append [a b] "cd" nil)
+     @result{} (a b 99 100)
+@end group
+@end example
+
+  With the help of @code{apply} (@pxref{Calling Functions}), we can append
+all the lists in a list of lists:
 
 @example
 @group
@@ -530,7 +665,7 @@ lists:
 @end group
 @end example
 
-If no @var{sequences} are given, @code{nil} is returned:
+  If no @var{sequences} are given, @code{nil} is returned:
 
 @example
 @group
@@ -539,7 +674,7 @@ If no @var{sequences} are given, @code{nil} is returned:
 @end group
 @end example
 
-Here are some examples where the final argument is not a list:
+  Here are some examples where the final argument is not a list:
 
 @example
 (append '(x y) 'z)
@@ -554,16 +689,6 @@ not a list, the sequence's elements do not become elements of the
 resulting list.  Instead, the sequence becomes the final @sc{cdr}, like
 any other non-list final argument.
 
-The @code{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.  @strong{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
-@code{format} (@pxref{Formatting Strings}) or @code{number-to-string}
-(@pxref{String Conversion}).
-@end defun
-
 @defun reverse list
 This function creates a new list whose elements are the elements of
 @var{list}, but in reverse order.  The original argument @var{list} is
@@ -583,11 +708,38 @@ x
 @end example
 @end defun
 
+@defun remq object list
+This function returns a copy of @var{list}, with all elements removed
+which are @code{eq} to @var{object}.  The letter @samp{q} in @code{remq}
+says that it uses @code{eq} to compare @var{object} against the elements
+of @code{list}.
+
+@example
+@group
+(setq sample-list '(a b c a b c))
+     @result{} (a b c a b c)
+@end group
+@group
+(remq 'a sample-list)
+     @result{} (b c b c)
+@end group
+@group
+sample-list
+     @result{} (a b c a b c)
+@end group
+@end example
+@noindent
+The function @code{delq} offers a way to perform this operation
+destructively.  See @ref{Sets And Lists}.
+@end defun
+
 @node Modifying Lists
 @section Modifying Existing List Structure
+@cindex destructive list operations
 
   You can modify the @sc{car} and @sc{cdr} contents of a cons cell with the
-primitives @code{setcar} and @code{setcdr}.
+primitives @code{setcar} and @code{setcdr}.  We call these ``destructive'' 
+operations because they change existing list structure.
 
 @cindex CL note---@code{rplaca} vrs @code{setcar}
 @quotation
@@ -616,8 +768,9 @@ different element.
 
 @defun setcar cons object
 This function stores @var{object} as the new @sc{car} of @var{cons},
-replacing its previous @sc{car}.  It returns the value @var{object}.
-For example:
+replacing its previous @sc{car}.  In other words, it changes the
+@sc{car} slot of @var{cons} to refer to @var{object}.  It returns the
+value @var{object}.  For example:
 
 @example
 @group
@@ -675,14 +828,16 @@ changes them both:
 
 @example
 @group
-        ___ ___        ___ ___      ___ ___
-x1---> |___|___|----> |___|___|--> |___|___|--> nil
+        --- ---        --- ---      --- ---
+x1---> |   |   |----> |   |   |--> |   |   |--> nil
+        --- ---        --- ---      --- ---
          |        -->   |            |
          |       |      |            |
           --> a  |       --> b        --> c
                  |
-       ___ ___   |
-x2--> |___|___|--
+       --- ---   |
+x2--> |   |   |--
+       --- ---
         |
         |
          --> z
@@ -716,7 +871,9 @@ x2:              |
 
 @defun setcdr cons object
 This function stores @var{object} as the new @sc{cdr} of @var{cons},
-replacing its previous @sc{cdr}.  It returns the value @var{object}.
+replacing its previous @sc{cdr}.  In other words, it changes the
+@sc{cdr} slot of @var{cons} to refer to @var{object}.  It returns the
+value @var{object}.
 @end defun
 
   Here is an example of replacing the @sc{cdr} of a list with a
@@ -743,7 +900,7 @@ x
   You can delete elements from the middle of a list by altering the
 @sc{cdr}s of the cons cells in the list.  For example, here we delete
 the second element, @code{b}, from the list @code{(a b c)}, by changing
-the @sc{cdr} of the first cell:
+the @sc{cdr} of the first cons cell:
 
 @example
 @group
@@ -817,12 +974,13 @@ x1
   Here are some functions that rearrange lists ``destructively'' by
 modifying the @sc{cdr}s 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.
+to them as arguments, relinking their cons cells to form a new list that
+is the returned value.
 
-@ifinfo
+@ifnottex
   See @code{delq}, in @ref{Sets And Lists}, for another function
 that modifies cons cells.
-@end ifinfo
+@end ifnottex
 @iftex
    The function @code{delq} in the following section is another example
 of destructive list manipulation.
@@ -872,6 +1030,8 @@ x
 @end group
 @end example
 
+However, the other arguments (all but the last) must be lists.
+
 A common pitfall is to use a quoted constant list as a non-last
 argument to @code{nconc}.  If you do this, your program will change
 each time you run it!  Here is what happens:
@@ -912,26 +1072,26 @@ each time you run it!  Here is what happens:
   This function reverses the order of the elements of @var{list}.
 Unlike @code{reverse}, @code{nreverse} alters its argument by reversing
 the @sc{cdr}s in the cons cells forming the list.  The cons cell that
-used to be the last one in @var{list} becomes the first cell of the
+used to be the last one in @var{list} becomes the first cons cell of the
 value.
 
   For example:
 
 @example
 @group
-(setq x '(1 2 3 4))
-     @result{} (1 2 3 4)
+(setq x '(a b c))
+     @result{} (a b c)
 @end group
 @group
 x
-     @result{} (1 2 3 4)
+     @result{} (a b c)
 (nreverse x)
-     @result{} (4 3 2 1)
+     @result{} (c b a)
 @end group
 @group
-;; @r{The cell that was first is now last.}
+;; @r{The cons cell that was first is now last.}
 x
-     @result{} (1)
+     @result{} (a)
 @end group
 @end example
 
@@ -974,6 +1134,15 @@ arguments.  It is called with two elements of @var{list}.  To get an
 increasing order sort, the @var{predicate} should return @code{t} if the
 first element is ``less than'' the second, or @code{nil} if not.
 
+The comparison function @var{predicate} must give reliable results for
+any given pair of arguments, at least within a single call to
+@code{sort}.  It must be @dfn{antisymmetric}; that is, if @var{a} is
+less than @var{b}, @var{b} must not be less than @var{a}.  It must be
+@dfn{transitive}---that is, if @var{a} is less than @var{b}, and @var{b}
+is less than @var{c}, then @var{a} must be less than @var{c}.  If you
+use a comparison function which does not meet these requirements, the
+result of @code{sort} is unpredictable.
+
 The destructive aspect of @code{sort} is that it rearranges the cons
 cells forming @var{list} by changing @sc{cdr}s.  A nondestructive sort
 function would create new cons cells to store the elements in their
@@ -1002,12 +1171,12 @@ nums
 @end example
 
 @noindent
-Note that the list in @code{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 @code{sort} and use
-that.  Most often we store the result back into the variable that held
-the original list:
+@strong{Warning}: Note that the list in @code{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 @code{sort} and use that.  Most often we store the result back into
+the variable that held the original list:
 
 @example
 (setq nums (sort nums '<))
@@ -1058,12 +1227,19 @@ compare @var{object} against the elements of the list.  For example:
 @end example
 @end defun
 
+@defun member-ignore-case object list
+This function is like @code{member}, except that it ignores
+differences in letter-case and text representation: upper-case and
+lower-case letters are treated as equal, and unibyte strings are
+converted to multibyte prior to comparison.
+@end defun
+
 @defun delq object list
 @cindex deletion of elements
 This function destructively removes all elements @code{eq} to
 @var{object} from @var{list}.  The letter @samp{q} in @code{delq} says
 that it uses @code{eq} to compare @var{object} against the elements of
-the list, like @code{memq}.
+the list, like @code{memq} and @code{remq}.
 @end defun
 
 When @code{delq} deletes elements from the front of the list, it does so
@@ -1125,8 +1301,8 @@ and the @code{(4)} in the @code{sample-list} are not @code{eq}:
 @end example
 
 The following two functions are like @code{memq} and @code{delq} but use
-@code{equal} rather than @code{eq} to compare elements.  They are new in
-Emacs 19.
+@code{equal} rather than @code{eq} to compare elements.  @xref{Equality
+Predicates}.
 
 @defun member object list
 The function @code{member} tests to see whether @var{object} is a member
@@ -1153,25 +1329,54 @@ Compare this with @code{memq}:
 @end example
 @end defun
 
-@defun delete object list
-This function destructively removes all elements @code{equal} to
-@var{object} from @var{list}.  It is to @code{delq} as @code{member} is
-to @code{memq}: it uses @code{equal} to compare elements with
-@var{object}, like @code{member}; when it finds an element that matches,
-it removes the element just as @code{delq} would.  For example:
+@defun delete object sequence
+If @code{sequence} is a list, this function destructively removes all
+elements @code{equal} to @var{object} from @var{sequence}.  For lists,
+@code{delete} is to @code{delq} as @code{member} is to @code{memq}: it
+uses @code{equal} to compare elements with @var{object}, like
+@code{member}; when it finds an element that matches, it removes the
+element just as @code{delq} would.
+
+If @code{sequence} is a vector or string, @code{delete} returns a copy
+of @code{sequence} with all elements @code{equal} to @code{object}
+removed.
+
+For example:
 
 @example
 @group
 (delete '(2) '((2) (1) (2)))
      @result{} ((1))
 @end group
+@group
+(delete '(2) [(2) (1) (2)])
+     @result{} [(1)]
+@end group
+@end example
+@end defun
+
+@defun remove object sequence
+This function is the non-destructive counterpart of @code{delete}.  If
+returns a copy of @code{sequence}, a list, vector, or string, with
+elements @code{equal} to @code{object} removed.  For example:
+
+@example
+@group
+(remove '(2) '((2) (1) (2)))
+     @result{} ((1))
+@end group
+@group
+(remove '(2) [(2) (1) (2)])
+     @result{} [(1)]
+@end group
 @end example
 @end defun
 
 @quotation
-@b{Common Lisp note:} The functions @code{member} and @code{delete} in
-GNU Emacs Lisp are derived from Maclisp, not Common Lisp.  The Common
-Lisp versions do not use @code{equal} to compare elements.
+@b{Common Lisp note:} The functions @code{member}, @code{delete} and
+@code{remove} in GNU Emacs Lisp are derived from Maclisp, not Common
+Lisp.  The Common Lisp versions do not use @code{equal} to compare
+elements.
 @end quotation
 
   See also the function @code{add-to-list}, in @ref{Setting Variables},
@@ -1184,7 +1389,7 @@ for another way to add an element to a list stored in a variable.
 
   An @dfn{association list}, or @dfn{alist} for short, records a mapping
 from keys to values.  It is a list of cons cells called
-@dfn{associations}: the @sc{car} of each cell is the @dfn{key}, and the
+@dfn{associations}: the @sc{car} of each cons cell is the @dfn{key}, and the
 @sc{cdr} is the @dfn{associated value}.@footnote{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
@@ -1196,9 +1401,9 @@ the value @code{cones}; the key @code{oak} is associated with
 
 @example
 @group
-'((pine . cones)
-  (oak . acorns)
-  (maple . seeds))
+((pine . cones)
+ (oak . acorns)
+ (maple . seeds))
 @end group
 @end example
 
@@ -1214,15 +1419,15 @@ the alist element:
 
   Sometimes it is better to design an alist to store the associated
 value in the @sc{car} of the @sc{cdr} of the element.  Here is an
-example:
+example of such an alist:
 
 @example
-'((rose red) (lily white) (buttercup yellow))
+((rose red) (lily white) (buttercup yellow))
 @end example
 
 @noindent
 Here we regard @code{red} as the value associated with @code{rose}.  One
-advantage of this method is that you can store other related
+advantage of this kind of alist is that you can store other related
 information---even a list of other items---in the @sc{cdr} of the
 @sc{cdr}.  One disadvantage is that you cannot use @code{rassq} (see
 below) to find the element containing a given value.  When neither of
@@ -1282,6 +1487,10 @@ Here is another example, in which the keys and values are not symbols:
 @end smallexample
 @end defun
 
+  The functions @code{assoc-ignore-representation} and
+@code{assoc-ignore-case} are much like @code{assoc} except using
+@code{compare-strings} to do the comparison.  @xref{Text Comparison}.
+
 @defun rassoc value alist
 This function returns the first association with value @var{value} in
 @var{alist}.  It returns @code{nil} if no association in @var{alist} has
@@ -1362,6 +1571,25 @@ becomes clearer if the association is written in dotted pair notation:
 @end smallexample
 @end defun
 
+@defun assoc-default key alist &optional test default
+This function searches @var{alist} for a match for @var{key}.  For each
+element of @var{alist}, it compares the element (if it is an atom) or
+the element's @sc{car} (if it is a cons) against @var{key}, by calling
+@var{test} with two arguments: the element or its @sc{car}, and
+@var{key}.  The arguments are passed in that order so that you can get
+useful results using @code{string-match} with an alist that contains
+regular expressions (@pxref{Regexp Search}).  If @var{test} is omitted
+or @code{nil}, @code{equal} is used for comparison.
+
+If an alist element matches @var{key} by this criterion,
+then @code{assoc-default} returns a value based on this element.
+If the element is a cons, then the value is the element's @sc{cdr}.
+Otherwise, the return value is @var{default}.
+
+If no alist element matches @var{key}, @code{assoc-default} returns
+@code{nil}.
+@end defun
+
 @defun copy-alist alist
 @cindex copying alists
 This function returns a two-level deep copy of @var{alist}: it creates a
@@ -1413,4 +1641,16 @@ the associations of one copy without affecting the other:
 @end smallexample
 @end defun
 
+@defun assq-delete-all key alist
+@tindex assq-delete-all
+This function deletes from @var{alist} all the elements whose @sc{car}
+is @code{eq} to @var{key}.  It returns @var{alist}, modified
+in this way.  Note that it modifies the original list structure
+of @var{alist}.
 
+@example
+(assq-delete-all 'foo
+                 '((foo 1) (bar 2) (foo 3) (lose 4)))
+     @result{} ((bar 2) (lose 4))
+@end example
+@end defun