[Emacs-diffs] Changes to emacs/lispref/lists.texi [emacs-unicode-2]

[Miles Bader]

Index: emacs/lispref/lists.texi
diff -c emacs/lispref/lists.texi:1.35.2.1 emacs/lispref/lists.texi:1.35.2.2
*** emacs/lispref/lists.texi:1.35.2.1   Mon Apr 19 07:01:42 2004
--- emacs/lispref/lists.texi    Mon Jun 28 07:28:50 2004
***************
*** 51,66 ****
  level of cons cells, the @sc{car} and @sc{cdr} slots have the same
  characteristics.
  
  @cindex list structure
    Because most cons cells are used as part of lists, the phrase
  @dfn{list structure} has come to mean any structure made out of cons
  cells.
  
-   The symbol @code{nil} is considered a list as well as a symbol; it is
- the list with no elements.  For convenience, the symbol @code{nil} is
- considered to have @code{nil} as its @sc{cdr} (and also as its
- @sc{car}).
- 
    The @sc{cdr} of any nonempty list @var{l} is a list containing all the
  elements of @var{l} except the first.
  
--- 51,87 ----
  level of cons cells, the @sc{car} and @sc{cdr} slots have the same
  characteristics.
  
+ @cindex true list
+   Since @code{nil} is the conventional value to put in the @sc{cdr} of
+ the last cons cell in the list, we call that case a @dfn{true list}.
+ 
+   In Lisp, we consider the symbol @code{nil} a list as well as a
+ symbol; it is the list with no elements.  For convenience, the symbol
+ @code{nil} is considered to have @code{nil} as its @sc{cdr} (and also
+ as its @sc{car}).  Therefore, the @sc{cdr} of a true list is always a
+ true list.
+ 
+ @cindex dotted list
+ @cindex circular list
+   If the @sc{cdr} of a list's last cons cell is some other value,
+ neither @code{nil} nor another cons cell, we call the structure a
+ @dfn{dotted list}, since its printed representation would use
+ @samp{.}.  There is one other possibility: some cons cell's @sc{cdr}
+ could point to one of the previous cons cells in the list.  We call
+ that structure a @dfn{circular list}.
+ 
+   For some purposes, it does not matter whether a list is true,
+ circular or dotted.  If the program doesn't look far enough down the
+ list to see the @sc{cdr} of the final cons cell, it won't care.
+ However, some functions that operate on lists demand true lists and
+ signal errors if given a dotted list.  Most functions that try to find
+ the end of a list enter infinite loops if given a circular list.
+ 
  @cindex list structure
    Because most cons cells are used as part of lists, the phrase
  @dfn{list structure} has come to mean any structure made out of cons
  cells.
  
    The @sc{cdr} of any nonempty list @var{l} is a list containing all the
  elements of @var{l} except the first.
  
***************
*** 327,332 ****
--- 348,354 ----
  @end example
  @end defmac
  
+ @anchor{Definition of nth}
  @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
***************
*** 391,403 ****
  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
--- 413,427 ----
  if @var{n} is bigger than @var{list}'s length.
  @end defun
  
+ @anchor{Definition of safe-length}
  @defun safe-length list
! This function returns the length of @var{list}, with no risk of either
! an error or an infinite loop.  It generally returns the number of
! distinct cons cells in the list.  However, for circular lists,
! the value is just an upper bound; it is often too large.
  
! If @var{list} is not @code{nil} or a cons cell, @code{safe-length}
! returns 0.
  @end defun
  
    The most common way to compute the length of a list, when you are not
***************
*** 565,571 ****
  @sc{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 @sc{cdr} is not @code{nil} as required
  in a true list.
  
  In Emacs 20 and before, the @code{append} function also allowed
--- 589,595 ----
  @sc{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 @sc{cdr} is not @code{nil} as required
  in a true list.
  
  In Emacs 20 and before, the @code{append} function also allowed
***************
*** 708,714 ****
  @end defun
  
  @defun copy-tree tree &optional vecp
! This function returns a copy the tree @code{tree}.  If @var{tree} is a
  cons cell, this makes a new cons cell with the same @sc{car} and
  @sc{cdr}, then recursively copies the @sc{car} and @sc{cdr} in the
  same way.
--- 732,738 ----
  @end defun
  
  @defun copy-tree tree &optional vecp
! This function returns a copy of the tree @code{tree}.  If @var{tree} is a
  cons cell, this makes a new cons cell with the same @sc{car} and
  @sc{cdr}, then recursively copies the @sc{car} and @sc{cdr} in the
  same way.
***************
*** 732,738 ****
  floating point arguments can be tricky, because floating point
  arithmetic is inexact.  For instance, depending on the machine, it may
  quite well happen that @code{(number-sequence 0.4 0.6 0.2)} returns
! the one element list @code{(0.4)}, whereas 
  @code{(number-sequence 0.4 0.8 0.2)} returns a list with three
  elements.  The @var{n}th element of the list is computed by the exact
  formula @code{(+ @var{from} (* @var{n} @var{separation}))}.  Thus, if
--- 756,762 ----
  floating point arguments can be tricky, because floating point
  arithmetic is inexact.  For instance, depending on the machine, it may
  quite well happen that @code{(number-sequence 0.4 0.6 0.2)} returns
! the one element list @code{(0.4)}, whereas
  @code{(number-sequence 0.4 0.8 0.2)} returns a list with three
  elements.  The @var{n}th element of the list is computed by the exact
  formula @code{(+ @var{from} (* @var{n} @var{separation}))}.  Thus, if