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 |
|
|
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 |
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 |
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 |
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. |
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 |