marcuskammer/cl-sites
1
0
Fork 0
Code Activity
cl-sites/ecl.common-lisp.dev/static/manual/Hash-tables.html

322 lines
16 KiB
HTML
Raw Normal View History

Add ecl manual
2024-12-24 19:15:49 +01:00
<!DOCTYPE html>
<html>
<!-- Created by GNU Texinfo 7.0.3, https://www.gnu.org/software/texinfo/ -->
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>Hash tables (ECL Manual)</title>
<meta name="description" content="Hash tables (ECL Manual)">
<meta name="keywords" content="Hash tables (ECL Manual)">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta name="viewport" content="width=device-width,initial-scale=1">
<link href="index.html" rel="start" title="Top">
<link href="Indexes.html" rel="index" title="Indexes">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="Standards.html" rel="up" title="Standards">
<link href="Filenames.html#Filenames" rel="next" title="Filenames">
<link href="Sequences.html" rel="prev" title="Sequences">
<style type="text/css">
<!--
/* colors */
a.copiable-link {visibility: hidden; text-decoration: none; line-height: 0em}
div.example {margin-left: 3.2em}
span.r {font-family: initial; font-weight: normal; font-style: normal}
span:hover a.copiable-link {visibility: visible}
strong.def-name {font-family: monospace; font-weight: bold; font-size: larger}
@media (prefers-color-scheme: dark) {
/* dark theme */
html { color: seashell;
background: #1A1A1A; }
body { background: #1A1A1A; }
th { border-bottom: 2px solid lightgray; }
h1, h2, h3, h4, h5 { background-image: linear-gradient(to left, #202020, #3A3A3A); }
code, var, code a { color: darkorange;
background: #2A2A2A; }
a { color: seashell; }
pre { background: #2A2A2A;
color: seashell;
/* mark longer code block with stripe on the left */
border-left: 5px solid darkorange;
padding-left: 10px; }
pre.screen { background: #2A2A2A;
border: 1px solid lightgray; }
pre.programlisting { background: #2A2A2A;
border-left: 1px solid lightgray;
border-top: 1px solid lightgray; }
/* we need a light background in order for the images to be readable */
img { background: white }
}
@media (prefers-color-scheme: light) {
/* light theme */
html { background: white }
body { background: white }
th { border-bottom: 2px solid gray; }
h1, h2, h3, h4, h5 { background: lightgray; }
code, var, code a { color: darkred;
background: whitesmoke; }
a { color: #000; }
pre { background: whitesmoke;
color: black;
/* mark longer code block with stripe on the left */
border-left: 5px solid darkred;
padding-left: 10px; }
pre.screen { background: #EEE;
border: 1px solid black; }
pre.programlisting { background: #EEEEEE;
border-left: 1px solid black;
border-top: 1px solid black; }
}
body {
margin: 1em 125px 0 10%;
line-height: 1.5em;
padding: 0 2em 1em 2em;
font: 13px Verdana,Arial, sans-serif
}
ul, dd, dl, dt { margin-top: 0; margin-bottom: 0; }
p, code, td, dl, dt {
line-height: 1.5em;
}
table {
font: inherit;
border-collapse: collapse;
}
th, td {
vertical-align: top;
}
h1, h2, h3 { padding-left: 15px; }
h4, h5 { padding-left: 5px; }
code, pre {
font-size: 1em;
font-family: monospace;
}
var {
font-size: 1em;
}
/* links inside code appear the same as the code itself */
code a {
font-weight: normal;
text-decoration: none;
}
/* but get an underline when hovering */
code a:hover {
text-decoration: underline;
}
/* ordinary links appear in bold */
a { font-weight: bold; }
pre.verbatim {
margin: 0 0 0 0;
}
pre {
overflow: auto;
}
pre.screen {
font-weight: bold;
padding: 0.5em;
}
pre.programlisting {
padding: 0.5em;
}
div p { padding: 0 2em }
li p { padding: 0; margin: 0 }
hr { display: none; }
div.funcsynopsis p {
text-indent: -2em;
}
div.variablelist {
padding: 0 2em;
}
.type, .funcsynopsis, .symbol {
font-family: monospace;
}
.type, .symbol, .replaceable {
white-space: nowrap;
}
-->
</style>
</head>
<body lang="en">
<div class="section-level-extent" id="Hash-tables">
<div class="nav-panel">
<p>
Next: <a href="Filenames.html#Filenames" accesskey="n" rel="next">Filenames</a>, Previous: <a href="Sequences.html" accesskey="p" rel="prev">Sequences</a>, Up: <a href="Standards.html" accesskey="u" rel="up">Standards</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Indexes.html" title="Index" rel="index">Index</a>]</p>
</div>
<h3 class="section" id="Hash-tables-1">2.16 Hash tables</h3>
<ul class="mini-toc">
<li><a href="Hash-tables.html#Hash-tables-_002d-Extensions" accesskey="1">Extensions</a></li>
<li><a href="Hash-tables.html#Hash-tables-_002d-C-Reference" accesskey="2">C Reference</a></li>
</ul>
<hr>
<div class="subsection-level-extent" id="Hash-tables-_002d-Extensions">
<div class="nav-panel">
<p>
Next: <a href="Hash-tables.html#Hash-tables-_002d-C-Reference" accesskey="n" rel="next">C Reference</a>, Up: <a href="Hash-tables.html#Hash-tables" accesskey="u" rel="up">Hash tables</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Indexes.html" title="Index" rel="index">Index</a>]</p>
</div>
<h4 class="subsection" id="Extensions-2">2.16.1 Extensions</h4>
<ul class="mini-toc">
<li><a href="Hash-tables.html#Weakness-in-hash-tables" accesskey="1">Weakness in hash tables</a></li>
<li><a href="Hash-tables.html#Thread_002dsafe-hash-tables" accesskey="2">Thread-safe hash tables</a></li>
<li><a href="Hash-tables.html#Hash-tables-serialization" accesskey="3">Hash tables serialization</a></li>
<li><a href="Hash-tables.html#Custom-equivalence-predicate" accesskey="4">Custom equivalence predicate</a></li>
<li><a href="Hash-tables.html#Example" accesskey="5">Example</a></li>
</ul>
<div class="subsubsection-level-extent" id="Weakness-in-hash-tables">
<h4 class="subsubsection">2.16.1.1 Weakness in hash tables</h4>
<a class="index-entry-id" id="index-Weak-hash-tables"></a>
<a class="index-entry-id" id="index-ECL_002dWEAK_002dHASH"></a>
<p>Weak hash tables allow the garbage collector to reclaim some of the
entries if they are not strongly referenced elsewhere. ECL supports
four kinds of weakness in hash tables: <code class="code">:key</code>, <code class="code">:value</code>,
<code class="code">:key-and-value</code> and <code class="code">:key-or-value</code>.
</p>
<p>To make hash table weak, programmer has to provide <code class="code">:weakness</code>
keyword argument to <code class="code">cl:make-hash-table</code> with the desired kind of
weakness value (<code class="code">nil</code> means that the hash table has only strong
references).
</p>
<p>For more information see
<a class="url" href="https://www.haible.de/bruno/papers/cs/weak/WeakDatastructures-writeup.html">Weak
References - Data Types and Implementation</a> by Bruno Haible.
</p>
<a class="anchor" id="ext_003ahash_002dtable_002dweakness"></a><a class="index-entry-id" id="index-ext_003ahash_002dtable_002dweakness-1"></a>
<dl class="first-deffn first-defun-alias-first-deffn">
<dt class="deffn defun-alias-deffn" id="index-ext_003ahash_002dtable_002dweakness"><span class="category-def">Function: </span><span><strong class="def-name">ext:hash-table-weakness</strong> <var class="def-var-arguments">ht</var><a class="copiable-link" href='Hash-tables.html#index-ext_003ahash_002dtable_002dweakness'> &para;</a></span></dt>
<dd><p>Returns type of the hash table weakness. Possible return values are:
<code class="code">:key</code>, <code class="code">:value</code>, <code class="code">:key-and-value</code>, <code class="code">:key-or-value</code>
or <code class="code">nil</code>.
</p></dd></dl>
</div>
<div class="subsubsection-level-extent" id="Thread_002dsafe-hash-tables">
<h4 class="subsubsection">2.16.1.2 Thread-safe hash tables</h4>
<a class="index-entry-id" id="index-Synchronized-hash-tables"></a>
<a class="index-entry-id" id="index-Thread_002dsafe-hash-tables"></a>
<p>By default ECL doesn&rsquo;t protect hash tables from simultaneous access
for performance reasons. Read and write access may is synchronized
when <code class="code">:synchronized</code> keyword argument to <code class="code">make-hash-table</code> is
<code class="code">t</code> - <code class="code">(make-hash-table :synchronized t)</code>.
</p>
<a class="anchor" id="ext_003ahash_002dtable_002dsynchronized_002dp"></a><a class="index-entry-id" id="index-ext_003ahash_002dtable_002dsynchronized_002dp-1"></a>
<dl class="first-deffn first-defun-alias-first-deffn">
<dt class="deffn defun-alias-deffn" id="index-ext_003ahash_002dtable_002dsynchronized_002dp"><span class="category-def">Function: </span><span><strong class="def-name">ext:hash-table-synchronized-p</strong> <var class="def-var-arguments">ht</var><a class="copiable-link" href='Hash-tables.html#index-ext_003ahash_002dtable_002dsynchronized_002dp'> &para;</a></span></dt>
<dd><p>Predicate answering whether hash table is synchronized or not.
</p></dd></dl>
</div>
<div class="subsubsection-level-extent" id="Hash-tables-serialization">
<h4 class="subsubsection">2.16.1.3 Hash tables serialization</h4>
<a class="index-entry-id" id="index-Hash-table-serialization"></a>
<a class="anchor" id="hash_002dtable_002dcontent"></a><a class="index-entry-id" id="index-hash_002dtable_002dcontent"></a>
<dl class="first-deffn first-defun-alias-first-deffn">
<dt class="deffn defun-alias-deffn" id="index-ext_003ahash_002dtable_002dcontent"><span class="category-def">Function: </span><span><strong class="def-name">ext:hash-table-content</strong> <var class="def-var-arguments">ht</var><a class="copiable-link" href='Hash-tables.html#index-ext_003ahash_002dtable_002dcontent'> &para;</a></span></dt>
<dd><p>Returns freshly consed list of pairs <code class="code">(key . val)</code> being contents
of the hash table.
</p></dd></dl>
<a class="anchor" id="ext_003ahash_002dtable_002dfill"></a><a class="index-entry-id" id="index-ext_003ahash_002dtable_002dfill-1"></a>
<dl class="first-deffn first-defun-alias-first-deffn">
<dt class="deffn defun-alias-deffn" id="index-ext_003ahash_002dtable_002dfill"><span class="category-def">Function: </span><span><strong class="def-name">ext:hash-table-fill</strong> <var class="def-var-arguments">ht values</var><a class="copiable-link" href='Hash-tables.html#index-ext_003ahash_002dtable_002dfill'> &para;</a></span></dt>
<dd><p>Fills <var class="var">ht</var> with <var class="var">values</var> being list of <code class="code">(key . val)</code>. Hash
table may have some content already, but conflicting keys will be
overwritten.
</p></dd></dl>
</div>
<div class="subsubsection-level-extent" id="Custom-equivalence-predicate">
<h4 class="subsubsection">2.16.1.4 Custom equivalence predicate</h4>
<a class="index-entry-id" id="index-Hash-table-generic-test"></a>
<p><code class="code">make-hash-table</code> may accept arbitrary <code class="code">:test</code> keyword for
the equivalence predicate. If it is not one of the standard predicates
(<code class="code">:eq</code>, <code class="code">:eql</code>, <code class="code">:equal</code>, <code class="code">:equalp</code>) a keyword
argument <code class="code">:hashing-function</code> must be a function accepting one
argument and returning a positive fixnum. Otherwise the argument is
ignored.
</p>
</div>
<div class="subsubsection-level-extent" id="Example">
<h4 class="subsubsection">2.16.1.5 Example</h4>
<a class="index-entry-id" id="index-Hash-table-extensions-example"></a>
<div class="example lisp">
<pre class="lisp-preformatted">CL-USER&gt; (defparameter *ht*
(make-hash-table :synchronized t
:weakness :key-or-value))
*HT*
CL-USER&gt; (ext:hash-table-weakness *ht*)
:KEY-OR-VALUE
CL-USER&gt; (ext:hash-table-synchronized-p *ht*)
T
CL-USER&gt; (ext:hash-table-fill *ht* '((:foo 3) (:bar 4) (:quux 5)))
#&lt;hash-table 000055b1229e0b40&gt;
CL-USER&gt; (ext:hash-table-content *ht*)
((#&lt;weak-pointer 000055b121866350&gt; . #&lt;weak-pointer 000055b121866320&gt;)
(#&lt;weak-pointer 000055b121866370&gt; . #&lt;weak-pointer 000055b121866360&gt;)
(#&lt;weak-pointer 000055b121866390&gt; . #&lt;weak-pointer 000055b121866380&gt;))
</pre></div>
<hr>
</div>
</div>
<div class="subsection-level-extent" id="Hash-tables-_002d-C-Reference">
<div class="nav-panel">
<p>
Previous: <a href="Hash-tables.html#Hash-tables-_002d-Extensions" accesskey="p" rel="prev">Extensions</a>, Up: <a href="Hash-tables.html#Hash-tables" accesskey="u" rel="up">Hash tables</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Indexes.html" title="Index" rel="index">Index</a>]</p>
</div>
<h4 class="subsection" id="C-Reference-15">2.16.2 C Reference</h4>
<ul class="mini-toc">
<li><a href="Hash-tables.html#ANSI-dictionary-4" accesskey="1">ANSI dictionary</a></li>
</ul>
<div class="subsubsection-level-extent" id="ANSI-dictionary-4">
<h4 class="subsubsection">2.16.2.1 ANSI dictionary</h4>
<p>Common Lisp and C equivalence
</p>
<table class="multitable">
<thead><tr><th width="30%">Lisp symbol</th><th width="70%">C function</th></tr></thead>
<tbody><tr><td width="30%"><a class="url" href="http://www.lispworks.com/documentation/HyperSpec/Body/f_clrhas.htm">clrhash</a></td><td width="70%">cl_object cl_clrhash(cl_object hash_table)</td></tr>
<tr><td width="30%"><a class="url" href="http://www.lispworks.com/documentation/HyperSpec/Body/f_gethas.htm">gethash</a></td><td width="70%">cl_object cl_gethash(cl_narg narg, cl_object key, cl_object hash_table, ...)</td></tr>
<tr><td width="30%"><a class="url" href="http://www.lispworks.com/documentation/HyperSpec/Body/f_gethas.htm">(setf gethash)</a></td><td width="70%">cl_object si_hash_set(cl_object key, cl_object hash_table, cl_object value)</td></tr>
<tr><td width="30%"><a class="url" href="http://www.lispworks.com/documentation/HyperSpec/Body/f_hash_1.htm">hash-table-count</a></td><td width="70%">cl_object cl_hash_table_count(cl_object hash_table)</td></tr>
<tr><td width="30%"><a class="url" href="http://www.lispworks.com/documentation/HyperSpec/Body/f_hash_t.htm">hash-table-p</a></td><td width="70%">cl_object cl_hash_table_p(cl_object hash_table)</td></tr>
<tr><td width="30%"><a class="url" href="http://www.lispworks.com/documentation/HyperSpec/Body/f_hash_2.htm">hash-table-rehash-size</a></td><td width="70%">cl_object cl_hash_table_rehash_size(cl_object hash_table)</td></tr>
<tr><td width="30%"><a class="url" href="http://www.lispworks.com/documentation/HyperSpec/Body/f_hash_3.htm">hash-table-rehash-threshold</a></td><td width="70%">cl_object cl_hash_table_rehash_threshold(cl_object hash_table)</td></tr>
<tr><td width="30%"><a class="url" href="http://www.lispworks.com/documentation/HyperSpec/Body/f_hash_4.htm">hash-table-size</a></td><td width="70%">cl_object cl_hash_table_size(cl_object hash_table)</td></tr>
<tr><td width="30%"><a class="url" href="http://www.lispworks.com/documentation/HyperSpec/Body/f_hash_5.htm">hash-table-test</a></td><td width="70%">cl_object cl_hash_table_test(cl_object hash_table)</td></tr>
<tr><td width="30%"><a class="url" href="http://www.lispworks.com/documentation/HyperSpec/Body/f_mk_has.htm">make-hash-table</a></td><td width="70%">cl_object cl_make_hash_table(cl_narg narg, ...)</td></tr>
<tr><td width="30%"><a class="url" href="http://www.lispworks.com/documentation/HyperSpec/Body/f_maphas.htm">maphash</a></td><td width="70%">cl_object cl_maphash(cl_object function, cl_object hash_table)</td></tr>
<tr><td width="30%"><a class="url" href="http://www.lispworks.com/documentation/HyperSpec/Body/f_remhas.htm">remhash</a></td><td width="70%">cl_object cl_remhash(cl_object key, cl_object hash_table)</td></tr>
<tr><td width="30%"><a class="url" href="http://www.lispworks.com/documentation/HyperSpec/Body/f_sxhash.htm">sxhash</a></td><td width="70%">cl_object cl_sxhash(cl_object object)</td></tr>
</tbody>
</table>
</div>
</div>
</div>
<hr>
<div class="nav-panel">
<p>
Next: <a href="Filenames.html#Filenames" accesskey="n" rel="next">Filenames</a>, Previous: <a href="Sequences.html" accesskey="p" rel="prev">Sequences</a>, Up: <a href="Standards.html" accesskey="u" rel="up">Standards</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Indexes.html" title="Index" rel="index">Index</a>]</p>
</div>
</body>
</html>
Copy permalink