Files
libaaruformat/docs/html/hash__map_8h.html

341 lines
20 KiB
HTML

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en-US">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
<meta name="generator" content="Doxygen 1.14.0"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>libaaruformat: include/aaruformat/hash_map.h File Reference</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<script type="text/javascript" src="clipboard.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript" src="cookie.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr id="projectrow">
<td id="projectalign">
<div id="projectname">libaaruformat<span id="projectnumber">&#160;1.0</span>
</div>
<div id="projectbrief">Aaru Data Preservation Suite - Format Library</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.14.0 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search/",'.html');
</script>
<script type="text/javascript">
$(function() { codefold.init(); });
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
$(function() {
initMenu('',true,false,'search.php','Search',true);
$(function() { init_search(); });
});
</script>
<div id="main-nav"></div>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
<div id="nav-tree">
<div id="nav-tree-contents">
<div id="nav-sync" class="sync"></div>
</div>
</div>
<div id="splitbar" style="-moz-user-select:none;"
class="ui-resizable-handle">
</div>
</div>
<script type="text/javascript">
$(function(){initNavTree('hash__map_8h.html','',''); });
</script>
<div id="container">
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>
<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<div id="MSearchResults">
<div class="SRPage">
<div id="SRIndex">
<div id="SRResults"></div>
<div class="SRStatus" id="Loading">Loading...</div>
<div class="SRStatus" id="Searching">Searching...</div>
<div class="SRStatus" id="NoMatches">No Matches</div>
</div>
</div>
</div>
</div>
<div class="header">
<div class="headertitle"><div class="title">hash_map.h File Reference</div></div>
</div><!--header-->
<div class="contents">
<div class="textblock"><code>#include &lt;stdbool.h&gt;</code><br />
<code>#include &lt;stdlib.h&gt;</code><br />
</div>
<p><a href="hash__map_8h_source.html">Go to the source code of this file.</a></p>
<table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 id="header-nested-classes" class="groupheader"><a id="nested-classes" name="nested-classes"></a>
Data Structures</h2></td></tr>
<tr class="memitem:kv_5Fpair_5Ft" id="r_kv_5Fpair_5Ft"><td class="memItemLeft" align="right" valign="top">struct &#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="structkv__pair__t.html">kv_pair_t</a></td></tr>
<tr class="memdesc:"><td class="mdescLeft">&#160;</td><td class="mdescRight">Single key/value slot used internally by the open-addressing hash map. <a href="structkv__pair__t.html#details">More...</a><br /></td></tr>
<tr class="memitem:hash_5Fmap_5Ft" id="r_hash_5Fmap_5Ft"><td class="memItemLeft" align="right" valign="top">struct &#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="structhash__map__t.html">hash_map_t</a></td></tr>
<tr class="memdesc:"><td class="mdescLeft">&#160;</td><td class="mdescRight">Minimal open-addressing hash map for 64-bit key/value pairs used in deduplication lookup. <a href="structhash__map__t.html#details">More...</a><br /></td></tr>
</table><table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 id="header-func-members" class="groupheader"><a id="func-members" name="func-members"></a>
Functions</h2></td></tr>
<tr class="memitem:a4698f62d88ee9530fb93bf672455676f" id="r_a4698f62d88ee9530fb93bf672455676f"><td class="memItemLeft" align="right" valign="top"><a class="el" href="structhash__map__t.html">hash_map_t</a> *&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="#a4698f62d88ee9530fb93bf672455676f">create_map</a> (size_t size)</td></tr>
<tr class="memdesc:a4698f62d88ee9530fb93bf672455676f"><td class="mdescLeft">&#160;</td><td class="mdescRight">Creates a new hash map with the specified initial size. <br /></td></tr>
<tr class="memitem:ab885e8c5bedaf6f3cca1877e378fd04f" id="r_ab885e8c5bedaf6f3cca1877e378fd04f"><td class="memItemLeft" align="right" valign="top">void&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="#ab885e8c5bedaf6f3cca1877e378fd04f">free_map</a> (<a class="el" href="structhash__map__t.html">hash_map_t</a> *map)</td></tr>
<tr class="memdesc:ab885e8c5bedaf6f3cca1877e378fd04f"><td class="mdescLeft">&#160;</td><td class="mdescRight">Frees all memory associated with a hash map. <br /></td></tr>
<tr class="memitem:a56a11edd19b5362f1dd719a11c06f892" id="r_a56a11edd19b5362f1dd719a11c06f892"><td class="memItemLeft" align="right" valign="top">bool&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="#a56a11edd19b5362f1dd719a11c06f892">insert_map</a> (<a class="el" href="structhash__map__t.html">hash_map_t</a> *map, uint64_t key, uint64_t value)</td></tr>
<tr class="memdesc:a56a11edd19b5362f1dd719a11c06f892"><td class="mdescLeft">&#160;</td><td class="mdescRight">Inserts a key-value pair into the hash map. <br /></td></tr>
<tr class="memitem:a0719b4ee8aaa73765678b6b1db733fcd" id="r_a0719b4ee8aaa73765678b6b1db733fcd"><td class="memItemLeft" align="right" valign="top">bool&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="#a0719b4ee8aaa73765678b6b1db733fcd">lookup_map</a> (const <a class="el" href="structhash__map__t.html">hash_map_t</a> *map, uint64_t key, uint64_t *out_value)</td></tr>
<tr class="memdesc:a0719b4ee8aaa73765678b6b1db733fcd"><td class="mdescLeft">&#160;</td><td class="mdescRight">Looks up a value by key in the hash map. <br /></td></tr>
</table>
<a name="doc-func-members" id="doc-func-members"></a><h2 id="header-doc-func-members" class="groupheader">Function Documentation</h2>
<a id="a4698f62d88ee9530fb93bf672455676f" name="a4698f62d88ee9530fb93bf672455676f"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a4698f62d88ee9530fb93bf672455676f">&#9670;&#160;</a></span>create_map()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="structhash__map__t.html">hash_map_t</a> * create_map </td>
<td>(</td>
<td class="paramtype">size_t</td> <td class="paramname"><span class="paramname"><em>size</em></span></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Creates a new hash map with the specified initial size. </p>
<p>Allocates and initializes a new hash map structure with the given size. The hash map uses open addressing with linear probing for collision resolution. The table is zero-initialized, making empty slots identifiable by having a key value of 0.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">size</td><td>Initial size of the hash table. Must be greater than 0.</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>Returns a pointer to the newly created hash map, or NULL if allocation fails. </dd></dl>
<dl class="retval"><dt>Return values</dt><dd>
<table class="retval">
<tr><td class="paramname">hash_map_t*</td><td>Successfully created hash map with:<ul>
<li>Allocated and zero-initialized table of specified size</li>
<li>Size set to the requested value</li>
<li>Count initialized to 0 (empty map) </li>
</ul>
</td></tr>
<tr><td class="paramname">NULL</td><td>Memory allocation failed</td></tr>
</table>
</dd>
</dl>
<dl class="section note"><dt>Note</dt><dd>The caller is responsible for freeing the returned hash map using <a class="el" href="hash__map_8c.html#ab885e8c5bedaf6f3cca1877e378fd04f" title="Frees all memory associated with a hash map.">free_map()</a>. </dd>
<dd>
A key value of 0 is reserved to indicate empty slots and cannot be used as a valid key.</dd></dl>
<dl class="section see"><dt>See also</dt><dd><a class="el" href="hash__map_8c.html#ab885e8c5bedaf6f3cca1877e378fd04f" title="Frees all memory associated with a hash map.">free_map()</a> </dd></dl>
<p class="definition">Definition at line <a class="el" href="hash__map_8c_source.html#l00049">49</a> of file <a class="el" href="hash__map_8c_source.html">hash_map.c</a>.</p>
<p class="reference">References <a class="el" href="hash__map_8h_source.html#l00053">hash_map_t::count</a>, <a class="el" href="hash__map_8h_source.html#l00052">hash_map_t::size</a>, and <a class="el" href="hash__map_8h_source.html#l00051">hash_map_t::table</a>.</p>
<p class="reference">Referenced by <a class="el" href="create_8c_source.html#l00279">aaruf_create()</a>.</p>
</div>
</div>
<a id="ab885e8c5bedaf6f3cca1877e378fd04f" name="ab885e8c5bedaf6f3cca1877e378fd04f"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ab885e8c5bedaf6f3cca1877e378fd04f">&#9670;&#160;</a></span>free_map()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">void free_map </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structhash__map__t.html">hash_map_t</a> *</td> <td class="paramname"><span class="paramname"><em>map</em></span></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Frees all memory associated with a hash map. </p>
<p>Deallocates the hash table and the hash map structure itself. After calling this function, the hash map pointer becomes invalid and should not be used.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">map</td><td>Pointer to the hash map to free. Can be NULL (no operation performed).</td></tr>
</table>
</dd>
</dl>
<dl class="section note"><dt>Note</dt><dd>This function does not free any memory pointed to by the values stored in the map. If the values are dynamically allocated, they must be freed separately before calling this function.</dd></dl>
<dl class="section see"><dt>See also</dt><dd><a class="el" href="hash__map_8c.html#a4698f62d88ee9530fb93bf672455676f" title="Creates a new hash map with the specified initial size.">create_map()</a> </dd></dl>
<p class="definition">Definition at line <a class="el" href="hash__map_8c_source.html#l00073">73</a> of file <a class="el" href="hash__map_8c_source.html">hash_map.c</a>.</p>
<p class="reference">References <a class="el" href="hash__map_8h_source.html#l00051">hash_map_t::table</a>.</p>
<p class="reference">Referenced by <a class="el" href="close_8c_source.html#l03995">aaruf_close()</a>, and <a class="el" href="create_8c_source.html#l00030">cleanup_failed_create()</a>.</p>
</div>
</div>
<a id="a56a11edd19b5362f1dd719a11c06f892" name="a56a11edd19b5362f1dd719a11c06f892"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a56a11edd19b5362f1dd719a11c06f892">&#9670;&#160;</a></span>insert_map()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">bool insert_map </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structhash__map__t.html">hash_map_t</a> *</td> <td class="paramname"><span class="paramname"><em>map</em></span>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">uint64_t</td> <td class="paramname"><span class="paramname"><em>key</em></span>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">uint64_t</td> <td class="paramname"><span class="paramname"><em>value</em></span>&#160;)</td>
</tr>
</table>
</div><div class="memdoc">
<p>Inserts a key-value pair into the hash map. </p>
<p>Adds a new key-value pair to the hash map using open addressing with linear probing for collision resolution. If the key already exists, the insertion fails and returns false. The function automatically resizes the hash table when the load factor exceeds the threshold (0.75) to maintain optimal performance.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">map</td><td>Pointer to the hash map. Must not be NULL. </td></tr>
<tr><td class="paramname">key</td><td>The key to insert. Must not be 0 as this value is reserved for empty slots. </td></tr>
<tr><td class="paramname">value</td><td>The value to associate with the key.</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>Returns the result of the insertion operation. </dd></dl>
<dl class="retval"><dt>Return values</dt><dd>
<table class="retval">
<tr><td class="paramname">true</td><td>Successfully inserted the key-value pair. The map count is incremented. </td></tr>
<tr><td class="paramname">false</td><td>Key already exists in the map. No changes made to the map.</td></tr>
</table>
</dd>
</dl>
<dl class="section note"><dt>Note</dt><dd>If insertion would exceed the load factor threshold, the hash table is automatically resized to twice its current size before insertion. </dd>
<dd>
Time complexity: O(1) average case, O(n) worst case with poor hash distribution. </dd>
<dd>
Space complexity: O(1) unless resizing occurs, in which case it's O(n).</dd></dl>
<dl class="section warning"><dt>Warning</dt><dd>Using 0 as a key value will result in undefined behavior as 0 is reserved for marking empty slots. </dd>
<dd>
If memory allocation fails during automatic resizing, the program may terminate.</dd></dl>
<dl class="section see"><dt>See also</dt><dd><a class="el" href="hash__map_8c.html#a0719b4ee8aaa73765678b6b1db733fcd" title="Looks up a value by key in the hash map.">lookup_map()</a> </dd>
<dd>
<a class="el" href="hash__map_8c.html#ad662d4309e791d854bc7a788b1cddf34" title="Resizes the hash map to a new size and rehashes all entries.">resize_map()</a> </dd></dl>
<p class="definition">Definition at line <a class="el" href="hash__map_8c_source.html#l00153">153</a> of file <a class="el" href="hash__map_8c_source.html">hash_map.c</a>.</p>
<p class="reference">References <a class="el" href="hash__map_8h_source.html#l00053">hash_map_t::count</a>, <a class="el" href="hash__map_8h_source.html#l00034">kv_pair_t::key</a>, <a class="el" href="hash__map_8c_source.html#l00026">LOAD_FACTOR</a>, <a class="el" href="hash__map_8c_source.html#l00101">resize_map()</a>, <a class="el" href="hash__map_8h_source.html#l00052">hash_map_t::size</a>, <a class="el" href="hash__map_8h_source.html#l00051">hash_map_t::table</a>, and <a class="el" href="hash__map_8h_source.html#l00035">kv_pair_t::value</a>.</p>
<p class="reference">Referenced by <a class="el" href="write_8c_source.html#l00098">aaruf_write_sector()</a>.</p>
</div>
</div>
<a id="a0719b4ee8aaa73765678b6b1db733fcd" name="a0719b4ee8aaa73765678b6b1db733fcd"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a0719b4ee8aaa73765678b6b1db733fcd">&#9670;&#160;</a></span>lookup_map()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">bool lookup_map </td>
<td>(</td>
<td class="paramtype">const <a class="el" href="structhash__map__t.html">hash_map_t</a> *</td> <td class="paramname"><span class="paramname"><em>map</em></span>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">uint64_t</td> <td class="paramname"><span class="paramname"><em>key</em></span>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">uint64_t *</td> <td class="paramname"><span class="paramname"><em>out_value</em></span>&#160;)</td>
</tr>
</table>
</div><div class="memdoc">
<p>Looks up a value by key in the hash map. </p>
<p>Searches for the specified key in the hash map and retrieves its associated value. Uses linear probing to handle collisions during the search. The function does not modify the hash map in any way.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">map</td><td>Pointer to the hash map to search. Must not be NULL. </td></tr>
<tr><td class="paramname">key</td><td>The key to search for. Must not be 0. </td></tr>
<tr><td class="paramname">out_value</td><td>Pointer to store the found value. Must not be NULL. Only modified if the key is found.</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>Returns whether the key was found in the map. </dd></dl>
<dl class="retval"><dt>Return values</dt><dd>
<table class="retval">
<tr><td class="paramname">true</td><td>Key found. The associated value is written to *out_value. </td></tr>
<tr><td class="paramname">false</td><td>Key not found. *out_value is not modified.</td></tr>
</table>
</dd>
</dl>
<dl class="section note"><dt>Note</dt><dd>Time complexity: O(1) average case, O(n) worst case with poor hash distribution or high load factor. </dd>
<dd>
The function is read-only and does not modify the hash map structure. </dd>
<dd>
Searching for key value 0 will always return false as 0 indicates empty slots.</dd></dl>
<dl class="section warning"><dt>Warning</dt><dd>The out_value parameter must point to valid memory location. Passing NULL will result in undefined behavior.</dd></dl>
<dl class="section see"><dt>See also</dt><dd><a class="el" href="hash__map_8c.html#a56a11edd19b5362f1dd719a11c06f892" title="Inserts a key-value pair into the hash map.">insert_map()</a> </dd></dl>
<p class="definition">Definition at line <a class="el" href="hash__map_8c_source.html#l00196">196</a> of file <a class="el" href="hash__map_8c_source.html">hash_map.c</a>.</p>
<p class="reference">References <a class="el" href="hash__map_8h_source.html#l00034">kv_pair_t::key</a>, <a class="el" href="hash__map_8h_source.html#l00052">hash_map_t::size</a>, <a class="el" href="hash__map_8h_source.html#l00051">hash_map_t::table</a>, and <a class="el" href="hash__map_8h_source.html#l00035">kv_pair_t::value</a>.</p>
<p class="reference">Referenced by <a class="el" href="write_8c_source.html#l00098">aaruf_write_sector()</a>.</p>
</div>
</div>
</div><!-- contents -->
</div><!-- doc-content -->
<div id="page-nav" class="page-nav-panel">
<div id="page-nav-resize-handle"></div>
<div id="page-nav-tree">
<div id="page-nav-contents">
</div><!-- page-nav-contents -->
</div><!-- page-nav-tree -->
</div><!-- page-nav -->
</div><!-- container -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
<ul>
<li class="navelem"><a href="dir_d44c64559bbebec7f509842c48db8b23.html">include</a></li><li class="navelem"><a href="dir_aeff2545c9dfcfc842fe9d84b123cb31.html">aaruformat</a></li><li class="navelem"><a href="hash__map_8h.html">hash_map.h</a></li>
<li class="footer">Generated by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.14.0 </li>
</ul>
</div>
</body>
</html>