Update copyright for years from Emacs 21 to present (mainly adding

[bpt/emacs.git] / lispref / lists.texi

diff --git a/lispref/lists.texi b/lispref/lists.texi
index cb60bae..24214bb 100644 (file)
--- a/lispref/lists.texi
+++ b/lispref/lists.texi
@@ -1,7 +1,7 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2002, 2003,
-@c   2004, 2005, 2006 Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001,
+@c   2002, 2003, 2004, 2005, 2006, 2007  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
@@ -713,12 +713,14 @@ l
 
   Two functions modify lists that are the values of variables.
 
-@defun add-to-list symbol element &optional append
+@defun add-to-list symbol element &optional append compare-fn
 This function sets the variable @var{symbol} by consing @var{element}
 onto the old value, if @var{element} is not already a member of that
 value.  It returns the resulting list, whether updated or not.  The
 value of @var{symbol} had better be a list already before the call.
-Membership is tested using @code{equal}.
+@code{add-to-list} uses @var{compare-fn} to compare @var{element}
+against existing list members; if @var{compare-fn} is @code{nil}, it
+uses @code{equal}.
 
 Normally, if @var{element} is added, it is added to the front of
 @var{symbol}, but if the optional argument @var{append} is
@@ -1395,6 +1397,27 @@ The function @code{delq} offers a way to perform this operation
 destructively.  See @ref{Sets And Lists}.
 @end defun
 
+@defun memql object list
+The function @code{memql} tests to see whether @var{object} is a member
+of @var{list}, comparing members with @var{object} using @code{eql},
+so floating point elements are compared by value.
+If @var{object} is a member, @code{memql} returns a list starting with
+its first occurrence in @var{list}.  Otherwise, it returns @code{nil}.
+
+Compare this with @code{memq}:
+
+@example
+@group
+(memql 1.2 '(1.1 1.2 1.3))  ; @r{@code{1.2} and @code{1.2} are @code{eql}.}
+     @result{} (1.2 1.3)
+@end group
+@group
+(memq 1.2 '(1.1 1.2 1.3))  ; @r{@code{1.2} and @code{1.2} are not @code{eq}.}
+     @result{} nil
+@end group
+@end example
+@end defun
+
 The following three functions are like @code{memq}, @code{delq} and
 @code{remq}, but use @code{equal} rather than @code{eq} to compare
 elements.  @xref{Equality Predicates}.
@@ -1489,7 +1512,7 @@ several @code{equal} occurrences of an element in @var{list},
 @code{delete-dups} keeps the first one.
 @end defun
 
-  See also the function @code{add-to-list}, in @ref{Setting Variables},
+  See also the function @code{add-to-list}, in @ref{List Variables},
 for another way to add an element to a list stored in a variable.
 
 @node Association Lists