/[emacs]/emacs/lispref/lists.texi
ViewVC logotype

Diff of /emacs/lispref/lists.texi

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.35.2.1 by miles, Mon Apr 19 07:01:42 2004 UTC revision 1.35.2.2 by miles, Mon Jun 28 07:28:50 2004 UTC
# Line 51  the @sc{car} and the @sc{cdr} is entirel Line 51  the @sc{car} and the @sc{cdr} is entirel
51  level of cons cells, the @sc{car} and @sc{cdr} slots have the same  level of cons cells, the @sc{car} and @sc{cdr} slots have the same
52  characteristics.  characteristics.
53    
54    @cindex true list
55      Since @code{nil} is the conventional value to put in the @sc{cdr} of
56    the last cons cell in the list, we call that case a @dfn{true list}.
57    
58      In Lisp, we consider the symbol @code{nil} a list as well as a
59    symbol; it is the list with no elements.  For convenience, the symbol
60    @code{nil} is considered to have @code{nil} as its @sc{cdr} (and also
61    as its @sc{car}).  Therefore, the @sc{cdr} of a true list is always a
62    true list.
63    
64    @cindex dotted list
65    @cindex circular list
66      If the @sc{cdr} of a list's last cons cell is some other value,
67    neither @code{nil} nor another cons cell, we call the structure a
68    @dfn{dotted list}, since its printed representation would use
69    @samp{.}.  There is one other possibility: some cons cell's @sc{cdr}
70    could point to one of the previous cons cells in the list.  We call
71    that structure a @dfn{circular list}.
72    
73      For some purposes, it does not matter whether a list is true,
74    circular or dotted.  If the program doesn't look far enough down the
75    list to see the @sc{cdr} of the final cons cell, it won't care.
76    However, some functions that operate on lists demand true lists and
77    signal errors if given a dotted list.  Most functions that try to find
78    the end of a list enter infinite loops if given a circular list.
79    
80  @cindex list structure  @cindex list structure
81    Because most cons cells are used as part of lists, the phrase    Because most cons cells are used as part of lists, the phrase
82  @dfn{list structure} has come to mean any structure made out of cons  @dfn{list structure} has come to mean any structure made out of cons
83  cells.  cells.
84    
   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}).  
   
85    The @sc{cdr} of any nonempty list @var{l} is a list containing all the    The @sc{cdr} of any nonempty list @var{l} is a list containing all the
86  elements of @var{l} except the first.  elements of @var{l} except the first.
87    
# Line 327  x Line 348  x
348  @end example  @end example
349  @end defmac  @end defmac
350    
351    @anchor{Definition of nth}
352  @defun nth n list  @defun nth n list
353  This function returns the @var{n}th element of @var{list}.  Elements  This function returns the @var{n}th element of @var{list}.  Elements
354  are numbered starting with zero, so the @sc{car} of @var{list} is  are numbered starting with zero, so the @sc{car} of @var{list} is
# Line 391  this link is the list's last element.  I Line 413  this link is the list's last element.  I
413  if @var{n} is bigger than @var{list}'s length.  if @var{n} is bigger than @var{list}'s length.
414  @end defun  @end defun
415    
416    @anchor{Definition of safe-length}
417  @defun safe-length list  @defun safe-length list
418  This function returns the length of @var{list}, with no risk  This function returns the length of @var{list}, with no risk of either
419  of either an error or an infinite loop.  an error or an infinite loop.  It generally returns the number of
420    distinct cons cells in the list.  However, for circular lists,
421    the value is just an upper bound; it is often too large.
422    
423  If @var{list} is not really a list, @code{safe-length} returns 0.  If  If @var{list} is not @code{nil} or a cons cell, @code{safe-length}
424  @var{list} is circular, it returns a finite value which is at least the  returns 0.
 number of distinct elements.  
425  @end defun  @end defun
426    
427    The most common way to compute the length of a list, when you are not    The most common way to compute the length of a list, when you are not
# Line 565  object.  The final argument is not copie Line 589  object.  The final argument is not copie
589  @sc{cdr} of the last cons cell in the new list.  If the final argument  @sc{cdr} of the last cons cell in the new list.  If the final argument
590  is itself a list, then its elements become in effect elements of the  is itself a list, then its elements become in effect elements of the
591  result list.  If the final element is not a list, the result is a  result list.  If the final element is not a list, the result is a
592  ``dotted list'' since its final @sc{cdr} is not @code{nil} as required  dotted list since its final @sc{cdr} is not @code{nil} as required
593  in a true list.  in a true list.
594    
595  In Emacs 20 and before, the @code{append} function also allowed  In Emacs 20 and before, the @code{append} function also allowed
# Line 708  x Line 732  x
732  @end defun  @end defun
733    
734  @defun copy-tree tree &optional vecp  @defun copy-tree tree &optional vecp
735  This function returns a copy the tree @code{tree}.  If @var{tree} is a  This function returns a copy of the tree @code{tree}.  If @var{tree} is a
736  cons cell, this makes a new cons cell with the same @sc{car} and  cons cell, this makes a new cons cell with the same @sc{car} and
737  @sc{cdr}, then recursively copies the @sc{car} and @sc{cdr} in the  @sc{cdr}, then recursively copies the @sc{car} and @sc{cdr} in the
738  same way.  same way.
# Line 732  All arguments can be integers or floatin Line 756  All arguments can be integers or floatin
756  floating point arguments can be tricky, because floating point  floating point arguments can be tricky, because floating point
757  arithmetic is inexact.  For instance, depending on the machine, it may  arithmetic is inexact.  For instance, depending on the machine, it may
758  quite well happen that @code{(number-sequence 0.4 0.6 0.2)} returns  quite well happen that @code{(number-sequence 0.4 0.6 0.2)} returns
759  the one element list @code{(0.4)}, whereas  the one element list @code{(0.4)}, whereas
760  @code{(number-sequence 0.4 0.8 0.2)} returns a list with three  @code{(number-sequence 0.4 0.8 0.2)} returns a list with three
761  elements.  The @var{n}th element of the list is computed by the exact  elements.  The @var{n}th element of the list is computed by the exact
762  formula @code{(+ @var{from} (* @var{n} @var{separation}))}.  Thus, if  formula @code{(+ @var{from} (* @var{n} @var{separation}))}.  Thus, if

Legend:
Removed from v.1.35.2.1  
changed lines
  Added in v.1.35.2.2

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26