Debian Codegraph @

info/gcl/with_002dhash_002dtable_002diterator.html

raw
1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
2 <html>
3 <!-- Created by GNU Texinfo 6.7, http://www.gnu.org/software/texinfo/ -->
4 <head>
5 <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
6 <title>with-hash-table-iterator (ANSI and GNU Common Lisp Document)</title>
7
8 <meta name="description" content="with-hash-table-iterator (ANSI and GNU Common Lisp Document)">
9 <meta name="keywords" content="with-hash-table-iterator (ANSI and GNU Common Lisp Document)">
10 <meta name="resource-type" content="document">
11 <meta name="distribution" content="global">
12 <meta name="Generator" content="makeinfo">
13 <link href="index.html" rel="start" title="Top">
14 <link href="Hash-Tables-Dictionary.html" rel="up" title="Hash Tables Dictionary">
15 <link href="clrhash.html" rel="next" title="clrhash">
16 <link href="maphash.html" rel="prev" title="maphash">
17 <style type="text/css">
18 <!--
19 a.summary-letter {text-decoration: none}
20 blockquote.indentedblock {margin-right: 0em}
21 div.display {margin-left: 3.2em}
22 div.example {margin-left: 3.2em}
23 div.lisp {margin-left: 3.2em}
24 kbd {font-style: oblique}
25 pre.display {font-family: inherit}
26 pre.format {font-family: inherit}
27 pre.menu-comment {font-family: serif}
28 pre.menu-preformatted {font-family: serif}
29 span.nolinebreak {white-space: nowrap}
30 span.roman {font-family: initial; font-weight: normal}
31 span.sansserif {font-family: sans-serif; font-weight: normal}
32 ul.no-bullet {list-style: none}
33 -->
34 </style>
35
36
37 </head>
38
39 <body lang="en">
40 <span id="with_002dhash_002dtable_002diterator"></span><div class="header">
41 <p>
42 Next: <a href="clrhash.html" accesskey="n" rel="next">clrhash</a>, Previous: <a href="maphash.html" accesskey="p" rel="prev">maphash</a>, Up: <a href="Hash-Tables-Dictionary.html" accesskey="u" rel="up">Hash Tables Dictionary</a> &nbsp; </p>
43 </div>
44 <hr>
45 <span id="with_002dhash_002dtable_002diterator-_005bMacro_005d"></span><h4 class="subsection">18.2.12 with-hash-table-iterator [Macro]</h4>
46
47 <p><code>with-hash-table-iterator</code> <i><span class="roman">(</span>name hash-table<span class="roman">)</span>
48 {<i>declaration</i>}* {<i>form</i>}*</i> &rArr; <i>{<i>result</i>}*</i>
49 </p>
50 <span id="Arguments-and-Values_003a_003a-386"></span><h4 class="subsubheading">Arguments and Values::</h4>
51
52 <p><i>name</i>&mdash;a name suitable for the first argument to <b>macrolet</b>.
53 </p>
54 <p><i>hash-table</i>&mdash;a <i>form</i>, evaluated once, that should produce a <i>hash table</i>.
55 </p>
56 <p><i>declaration</i>&mdash;a <b>declare</b> <i>expression</i>; not evaluated.
57 </p>
58 <p><i>forms</i>&mdash;an <i>implicit progn</i>.
59 </p>
60 <p><i>results</i>&mdash;the <i>values</i> returned by <i>forms</i>.
61 </p>
62 <span id="Description_003a_003a-502"></span><h4 class="subsubheading">Description::</h4>
63
64 <p>Within the lexical scope of the body, <i>name</i> is defined via <b>macrolet</b>
65 such that successive invocations of <tt>(<i>name</i>)</tt> return the items,
66 one by one, from the <i>hash table</i> that is obtained by evaluating
67 <i>hash-table</i> only once.
68 </p>
69 <p>An invocation <tt>(<i>name</i>)</tt> returns three values as follows:
70 </p>
71 <dl compact="compact">
72 <dt>1.</dt>
73 <dd><p>A <i>generalized boolean</i> that is <i>true</i> if an entry is returned.
74 </p></dd>
75 <dt>2.</dt>
76 <dd><p>The key from the <i>hash-table</i> entry.
77 </p></dd>
78 <dt>3.</dt>
79 <dd><p>The value from the <i>hash-table</i> entry.
80 </p></dd>
81 </dl>
82
83 <p>After all entries have been returned by successive invocations of
84 <tt>(<i>name</i>)</tt>, then only one value is returned, namely <b>nil</b>.
85 </p>
86 <p>It is unspecified what happens if any of the implicit interior state
87 of an iteration is returned outside the dynamic extent of the
88 <b>with-hash-table-iterator</b> <i>form</i>
89 such as by returning some <i>closure</i> over the invocation <i>form</i>.
90 </p>
91 <p>Any number of invocations of <b>with-hash-table-iterator</b>
92 can be nested, and the body of the innermost one can invoke all of the
93 locally <i>established</i> <i>macros</i>, provided all of those <i>macros</i>
94 have <i>distinct</i> names.
95 </p>
96 <span id="Examples_003a_003a-366"></span><h4 class="subsubheading">Examples::</h4>
97
98 <p>The following function should return <b>t</b> on any
99 <i>hash table</i>, and signal
100 an error if the usage of <b>with-hash-table-iterator</b> does not agree
101 with the corresponding usage of <b>maphash</b>.
102 </p>
103 <div class="example">
104 <pre class="example"> (defun test-hash-table-iterator (hash-table)
105 (let ((all-entries '())
106 (generated-entries '())
107 (unique (list nil)))
108 (maphash #'(lambda (key value) (push (list key value) all-entries))
109 hash-table)
110 (with-hash-table-iterator (generator-fn hash-table)
111 (loop
112 (multiple-value-bind (more? key value) (generator-fn)
113 (unless more? (return))
114 (unless (eql value (gethash key hash-table unique))
115 (error &quot;Key ~S not found for value ~S&quot; key value))
116 (push (list key value) generated-entries))))
117 (unless (= (length all-entries)
118 (length generated-entries)
119 (length (union all-entries generated-entries
120 :key #'car :test (hash-table-test hash-table))))
121 (error &quot;Generated entries and Maphash entries don't correspond&quot;))
122 t))
123 </pre></div>
124
125 <p>The following could be an acceptable definition of
126 <b>maphash</b>, implemented by <b>with-hash-table-iterator</b>.
127 </p>
128 <div class="example">
129 <pre class="example"> (defun maphash (function hash-table)
130 (with-hash-table-iterator (next-entry hash-table)
131 (loop (multiple-value-bind (more key value) (next-entry)
132 (unless more (return nil))
133 (funcall function key value)))))
134 </pre></div>
135
136 <span id="Exceptional-Situations_003a_003a-173"></span><h4 class="subsubheading">Exceptional Situations::</h4>
137
138 <p>The consequences are undefined if the local function named <i>name</i>
139 <i>established</i> by <b>with-hash-table-iterator</b> is called after it has
140 returned <i>false</i> as its <i>primary value</i>.
141 </p>
142 <span id="See-Also_003a_003a-410"></span><h4 class="subsubheading">See Also::</h4>
143
144 <p><a href="Traversal-Rules-and-Side-Effects.html">Traversal Rules and Side Effects</a>
145 </p>
146 <hr>
147 <div class="header">
148 <p>
149 Next: <a href="clrhash.html" accesskey="n" rel="next">clrhash</a>, Previous: <a href="maphash.html" accesskey="p" rel="prev">maphash</a>, Up: <a href="Hash-Tables-Dictionary.html" accesskey="u" rel="up">Hash Tables Dictionary</a> &nbsp; </p>
150 </div>
151
152
153
154 </body>
155 </html>