| 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> </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> ⇒ <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>—a name suitable for the first argument to <b>macrolet</b>. |
| 53 |
</p> |
| 54 |
<p><i>hash-table</i>—a <i>form</i>, evaluated once, that should produce a <i>hash table</i>. |
| 55 |
</p> |
| 56 |
<p><i>declaration</i>—a <b>declare</b> <i>expression</i>; not evaluated. |
| 57 |
</p> |
| 58 |
<p><i>forms</i>—an <i>implicit progn</i>. |
| 59 |
</p> |
| 60 |
<p><i>results</i>—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 "Key ~S not found for value ~S" 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 "Generated entries and Maphash entries don't correspond")) |
| 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> </p> |
| 150 |
</div> |
| 151 |
|
| 152 |
|
| 153 |
|
| 154 |
</body> |
| 155 |
</html> |