Mercurial > hg > xemacs-beta

comparison man/lispref/lists.texi @ 5791:9fae6227ede5

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up pointers to all nodes. See xemacs-patches message with ID <5315f7bf.sHpFD7lXYR05GH6E%james@xemacs.org>.
author Jerry James <james@xemacs.org>
date Thu, 27 Mar 2014 08:59:03 -0600
parents 10f179710250
children
comparison
equal deleted inserted replaced
5790:dcf9067f26bb 5791:9fae6227ede5
25 * Association Lists:: A list can represent a finite relation or mapping. 25 * Association Lists:: A list can represent a finite relation or mapping.
26 * Property Lists:: A different way to represent a finite mapping. 26 * Property Lists:: A different way to represent a finite mapping.
27 * Weak Lists:: A list with special garbage-collection behavior. 27 * Weak Lists:: A list with special garbage-collection behavior.
28 @end menu 28 @end menu
29 29
30 @node Cons Cells 30 @node Cons Cells, Lists as Boxes, Lists, Lists
31 @section Lists and Cons Cells 31 @section Lists and Cons Cells
32 @cindex lists and cons cells 32 @cindex lists and cons cells
33 @cindex @code{nil} and lists 33 @cindex @code{nil} and lists
34 34
35 Lists in Lisp are not a primitive data type; they are built up from 35 Lists in Lisp are not a primitive data type; they are built up from
58 @sc{car}). 58 @sc{car}).
59 59
60 The @sc{cdr} of any nonempty list @var{l} is a list containing all the 60 The @sc{cdr} of any nonempty list @var{l} is a list containing all the
61 elements of @var{l} except the first. 61 elements of @var{l} except the first.
62 62
63 @node Lists as Boxes 63 @node Lists as Boxes, List-related Predicates, Cons Cells, Lists
64 @section Lists as Linked Pairs of Boxes 64 @section Lists as Linked Pairs of Boxes
65 @cindex box representation for lists 65 @cindex box representation for lists
66 @cindex lists represented as boxes 66 @cindex lists represented as boxes
67 @cindex cons cell as box 67 @cindex cons cell as box
68 68
141 @end example 141 @end example
142 142
143 @xref{Cons Cell Type}, for the read and print syntax of cons cells and 143 @xref{Cons Cell Type}, for the read and print syntax of cons cells and
144 lists, and for more ``box and arrow'' illustrations of lists. 144 lists, and for more ``box and arrow'' illustrations of lists.
145 145
146 @node List-related Predicates 146 @node List-related Predicates, List Elements, Lists as Boxes, Lists
147 @section Predicates on Lists 147 @section Predicates on Lists
148 148
149 The following predicates test whether a Lisp object is an atom, is a 149 The following predicates test whether a Lisp object is an atom, is a
150 cons cell or is a list, or whether it is the distinguished object 150 cons cell or is a list, or whether it is the distinguished object
151 @code{nil}. (Many of these predicates can be defined in terms of the 151 @code{nil}. (Many of these predicates can be defined in terms of the
219 @end example 219 @end example
220 @end defun 220 @end defun
221 221
222 @need 2000 222 @need 2000
223 223
224 @node List Elements 224 @node List Elements, Building Lists, List-related Predicates, Lists
225 @section Accessing Elements of Lists 225 @section Accessing Elements of Lists
226 @cindex list elements 226 @cindex list elements
227 227
228 @defun car cons-cell 228 @defun car cons-cell
229 This function returns the value pointed to by the first pointer of the 229 This function returns the value pointed to by the first pointer of the
440 These are equivalent to @code{(nth 2 @var{list})} through 440 These are equivalent to @code{(nth 2 @var{list})} through
441 @code{(nth 9 @var{list})} respectively, i.e. the third through tenth 441 @code{(nth 9 @var{list})} respectively, i.e. the third through tenth
442 elements of @var{list}. 442 elements of @var{list}.
443 @end defun 443 @end defun
444 444
445 @node Building Lists 445 @node Building Lists, Modifying Lists, List Elements, Lists
446 @section Building Cons Cells and Lists 446 @section Building Cons Cells and Lists
447 @cindex cons cells 447 @cindex cons cells
448 @cindex building lists 448 @cindex building lists
449 449
450 Many functions build lists, as lists reside at the very heart of Lisp. 450 Many functions build lists, as lists reside at the very heart of Lisp.
672 @result{} (1 2 3 4) 672 @result{} (1 2 3 4)
673 @end group 673 @end group
674 @end example 674 @end example
675 @end defun 675 @end defun
676 676
677 @node Modifying Lists 677 @node Modifying Lists, Sets And Lists, Building Lists, Lists
678 @section Modifying Existing List Structure 678 @section Modifying Existing List Structure
679 679
680 You can modify the @sc{car} and @sc{cdr} contents of a cons cell with the 680 You can modify the @sc{car} and @sc{cdr} contents of a cons cell with the
681 primitives @code{setcar} and @code{setcdr}. 681 primitives @code{setcar} and @code{setcdr}.
682 682
696 * Setcdr:: Replacing part of the list backbone. 696 * Setcdr:: Replacing part of the list backbone.
697 This can be used to remove or add elements. 697 This can be used to remove or add elements.
698 * Rearrangement:: Reordering the elements in a list; combining lists. 698 * Rearrangement:: Reordering the elements in a list; combining lists.
699 @end menu 699 @end menu
700 700
701 @node Setcar 701 @node Setcar, Setcdr, Modifying Lists, Modifying Lists
702 @subsection Altering List Elements with @code{setcar} 702 @subsection Altering List Elements with @code{setcar}
703 703
704 Changing the @sc{car} of a cons cell is done with @code{setcar}. When 704 Changing the @sc{car} of a cons cell is done with @code{setcar}. When
705 used on a list, @code{setcar} replaces one element of a list with a 705 used on a list, @code{setcar} replaces one element of a list with a
706 different element. 706 different element.
798 | | | 798 | | |
799 -------------- 799 --------------
800 @end group 800 @end group
801 @end example 801 @end example
802 802
803 @node Setcdr 803 @node Setcdr, Rearrangement, Setcar, Modifying Lists
804 @subsection Altering the CDR of a List 804 @subsection Altering the CDR of a List
805 805
806 The lowest-level primitive for modifying a @sc{cdr} is @code{setcdr}: 806 The lowest-level primitive for modifying a @sc{cdr} is @code{setcdr}:
807 807
808 @defun setcdr cons-cell object 808 @defun setcdr cons-cell object
898 | | | 898 | | |
899 --------------- 899 ---------------
900 @end group 900 @end group
901 @end smallexample 901 @end smallexample
902 902
903 @node Rearrangement 903 @node Rearrangement, , Setcdr, Modifying Lists
904 @subsection Functions that Rearrange Lists 904 @subsection Functions that Rearrange Lists
905 @cindex rearrangement of lists 905 @cindex rearrangement of lists
906 @cindex modification of lists 906 @cindex modification of lists
907 907
908 Here are some functions that rearrange lists ``destructively'' by 908 Here are some functions that rearrange lists ``destructively'' by
1137 @xref{Sorting}, for more functions that perform sorting. 1137 @xref{Sorting}, for more functions that perform sorting.
1138 See @code{documentation} in @ref{Accessing Documentation}, for a 1138 See @code{documentation} in @ref{Accessing Documentation}, for a
1139 useful example of @code{sort*}. 1139 useful example of @code{sort*}.
1140 @end defun 1140 @end defun
1141 1141
1142 @node Sets And Lists 1142 @node Sets And Lists, Association Lists, Modifying Lists, Lists
1143 @section Using Lists as Sets 1143 @section Using Lists as Sets
1144 @cindex lists as sets 1144 @cindex lists as sets
1145 @cindex sets 1145 @cindex sets
1146 1146
1147 A list can represent an unordered mathematical set---simply consider a 1147 A list can represent an unordered mathematical set---simply consider a
1384 @end defun 1384 @end defun
1385 1385
1386 See also the function @code{add-to-list}, in @ref{Setting Variables}, 1386 See also the function @code{add-to-list}, in @ref{Setting Variables},
1387 for another way to add an element to a list stored in a variable. 1387 for another way to add an element to a list stored in a variable.
1388 1388
1389 @node Association Lists 1389 @node Association Lists, Property Lists, Sets And Lists, Lists
1390 @section Association Lists 1390 @section Association Lists
1391 @cindex association list 1391 @cindex association list
1392 @cindex alist 1392 @cindex alist
1393 1393
1394 An @dfn{association list}, or @dfn{alist} for short, records a mapping 1394 An @dfn{association list}, or @dfn{alist} for short, records a mapping
1627 @code{remassq}, @code{remrassq}, @code{remassoc}, and @code{remrassoc} with 1627 @code{remassq}, @code{remrassq}, @code{remassoc}, and @code{remrassoc} with
1628 this behavior, but they are neither available under GNU Emacs nor Common Lisp. 1628 this behavior, but they are neither available under GNU Emacs nor Common Lisp.
1629 They are marked as obsolete, and it is preferable to fix your code to avoid 1629 They are marked as obsolete, and it is preferable to fix your code to avoid
1630 adding non-cons objects to alists. 1630 adding non-cons objects to alists.
1631 1631
1632 @node Property Lists 1632 @node Property Lists, Weak Lists, Association Lists, Lists
1633 @section Property Lists 1633 @section Property Lists
1634 @cindex property list 1634 @cindex property list
1635 @cindex plist 1635 @cindex plist
1636 1636
1637 A @dfn{property list} (or @dfn{plist}) is another way of representing a 1637 A @dfn{property list} (or @dfn{plist}) is another way of representing a
1674 * Working With Normal Plists:: Functions for normal plists. 1674 * Working With Normal Plists:: Functions for normal plists.
1675 * Working With Lax Plists:: Functions for lax plists. 1675 * Working With Lax Plists:: Functions for lax plists.
1676 * Converting Plists To/From Alists:: Alist to plist and vice-versa. 1676 * Converting Plists To/From Alists:: Alist to plist and vice-versa.
1677 @end menu 1677 @end menu
1678 1678
1679 @node Working With Normal Plists 1679 @node Working With Normal Plists, Working With Lax Plists, Property Lists, Property Lists
1680 @subsection Working With Normal Plists 1680 @subsection Working With Normal Plists
1681 1681
1682 @defun plist-get plist property &optional default 1682 @defun plist-get plist property &optional default
1683 This function extracts a value from a property list. The function 1683 This function extracts a value from a property list. The function
1684 returns the value corresponding to the given @var{property}, or 1684 returns the value corresponding to the given @var{property}, or
1730 The new plist is returned. If @var{nil-means-not-present} is given, the 1730 The new plist is returned. If @var{nil-means-not-present} is given, the
1731 return value may not be @code{eq} to the passed-in value, so make sure 1731 return value may not be @code{eq} to the passed-in value, so make sure
1732 to @code{setq} the value back into where it came from. 1732 to @code{setq} the value back into where it came from.
1733 @end defun 1733 @end defun
1734 1734
1735 @node Working With Lax Plists 1735 @node Working With Lax Plists, Converting Plists To/From Alists, Working With Normal Plists, Property Lists
1736 @subsection Working With Lax Plists 1736 @subsection Working With Lax Plists
1737 1737
1738 Recall that a @dfn{lax plist} is a property list whose keys are compared 1738 Recall that a @dfn{lax plist} is a property list whose keys are compared
1739 using @code{equal} instead of @code{eq}. 1739 using @code{equal} instead of @code{eq}.
1740 1740
1784 The new plist is returned. If @var{nil-means-not-present} is given, the 1784 The new plist is returned. If @var{nil-means-not-present} is given, the
1785 return value may not be @code{eq} to the passed-in value, so make sure 1785 return value may not be @code{eq} to the passed-in value, so make sure
1786 to @code{setq} the value back into where it came from. 1786 to @code{setq} the value back into where it came from.
1787 @end defun 1787 @end defun
1788 1788
1789 @node Converting Plists To/From Alists 1789 @node Converting Plists To/From Alists, , Working With Lax Plists, Property Lists
1790 @subsection Converting Plists To/From Alists 1790 @subsection Converting Plists To/From Alists
1791 1791
1792 @defun alist-to-plist alist 1792 @defun alist-to-plist alist
1793 This function converts association list @var{alist} into the equivalent 1793 This function converts association list @var{alist} into the equivalent
1794 property-list form. The plist is returned. This converts from 1794 property-list form. The plist is returned. This converts from
1836 @defun destructive-plist-to-alist plist 1836 @defun destructive-plist-to-alist plist
1837 This function destructively converts property list @var{plist} into the 1837 This function destructively converts property list @var{plist} into the
1838 equivalent association-list form. The alist is returned. 1838 equivalent association-list form. The alist is returned.
1839 @end defun 1839 @end defun
1840 1840
1841 @node Weak Lists 1841 @node Weak Lists, , Property Lists, Lists
1842 @section Weak Lists 1842 @section Weak Lists
1843 @cindex weak list 1843 @cindex weak list
1844 1844
1845 A @dfn{weak list} is a special sort of list whose members are not counted 1845 A @dfn{weak list} is a special sort of list whose members are not counted
1846 as references for the purpose of garbage collection. This means that, 1846 as references for the purpose of garbage collection. This means that,