<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Function set "Dictionary support" - Function set "Dictionary support"</title>
<link href="faldoc.css" rel="stylesheet" type="text/css"/>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
</head>
<body class="faldoc_body">
<div class="navitop">
<div class="tabs">
<ul>
<li><a href="./index.html"><span>Main</span></a></li>
<li><a href="./pages.html"><span>Related pages</span></a></li>
<li><a href="./groups.html"><span>Groups</span></a></li>
<li><a href="./funset.html"><span>Function sets</span></a></li>
<li><a href="./classes.html"><span>Classes</span></a></li>
<li><a href="./objects.html"><span>Objects</span></a></li>
<li><a href="./functions.html"><span>All functions</span></a></li>
<li><a href="./globals.html"><span>Globals</span></a></li>
</ul>
</div>
</div>
<hr/>
<h1 class="faldoc_title">Function set "Dictionary support"</h1>
<p class="faldoc_brief">Dictionary related functions. </p>
<h2 class="faldoc_title">Summary</h2>
<table class="faldoc_list">
<tr><td><a href="#bless">bless()</a></td><td>Blesses a dictionary, making it an OOP instance. </td></tr>
<tr><td><a href="#dictBack">dictBack()</a></td><td>Returns the last item in the dictionary. </td></tr>
<tr><td><a href="#dictBest">dictBest()</a></td><td>Returns an iterator set to a given key, or finds the best position for its insertion. </td></tr>
<tr><td><a href="#dictClear">dictClear()</a></td><td>Removes all the items from a dictionary. </td></tr>
<tr><td><a href="#dictFill">dictFill()</a></td><td>Fills the dictionary values with the given item. </td></tr>
<tr><td><a href="#dictFind">dictFind()</a></td><td>Returns an iterator set to a given key. </td></tr>
<tr><td><a href="#dictFront">dictFront()</a></td><td>Returns the first item in the dictionary. </td></tr>
<tr><td><a href="#dictGet">dictGet()</a></td><td>Retreives a value associated with the given key </td></tr>
<tr><td><a href="#dictKeys">dictKeys()</a></td><td>Returns an array containing all the keys in the dictionary. </td></tr>
<tr><td><a href="#dictMerge">dictMerge()</a></td><td>Merges two dictionaries. </td></tr>
<tr><td><a href="#dictRemove">dictRemove()</a></td><td>Removes a given key from the dictionary. </td></tr>
<tr><td><a href="#dictSet">dictSet()</a></td><td>Stores a value in a dictionary </td></tr>
<tr><td><a href="#dictValues">dictValues()</a></td><td>Extracts all the values in the dictionary. </td></tr>
<tr><td><a href="#set">set()</a></td><td>Stores a value in a dictionary </td></tr>
</table>
<h2 class="faldoc_title">Members</h2>
<h3 class="faldoc_funcname"><a name="bless">bless()</a></h3>
<p class="item_brief">Blesses a dictionary, making it an OOP instance. </p>
<p class="faldoc_funcdecl">bless( dict, [mode] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">dict</td><td class="faldoc_paramdesc">A dictionary to be blessed. </td></tr>
<tr><td class="faldoc_optparam">mode</td><td class="faldoc_optparamdesc">True (default) to bless the dictionary, false to unbless it. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc"> The same dictonary passed as <b>dict</b>. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">Blessed dictionaries become sensible to OOP operators: dot accessors and "provides" keyword behave as if the dictionary was an object instance, with its string entries being properties. </p>
</p>
<h3 class="faldoc_funcname"><a name="dictBack">dictBack()</a></h3>
<p class="item_brief">Returns the last item in the dictionary. </p>
<p class="faldoc_funcdecl">dictBack( dict, [remove], [key] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">dict</td><td class="faldoc_paramdesc">The dictionary on which to operate. </td></tr>
<tr><td class="faldoc_optparam">remove</td><td class="faldoc_optparamdesc">If true, remove the dictionary entry too. </td></tr><tr><td class="faldoc_optparam">key</td><td class="faldoc_optparamdesc">If true, return the key instead of the value. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The last value (or key) in the dictionary. </td></tr>
<tr><td class="faldoc_raise">Raises:</td><td class="faldoc_raisedesc">
<table class="faldoc_raise">
<tr><td class="faldoc_raiseitem"><a href="./class_AccessError.html">AccessError</a></td><td class="faldoc_raisedesc">if the dictionary is empty </td></tr>
</table>
</td></tr>
</table>
<h3 class="faldoc_funcname"><a name="dictBest">dictBest()</a></h3>
<p class="item_brief">Returns an iterator set to a given key, or finds the best position for its insertion. </p>
<p class="faldoc_funcdecl">dictBest( dict, key )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">dict</td><td class="faldoc_paramdesc">The dictionary. </td></tr><tr><td class="faldoc_param">key</td><td class="faldoc_paramdesc">The key to be found. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">An iterator to the best possible position. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">If the key is found in the dictionary, an iterator pointing to that key is returned. It is then possible to change the value of the found item, insert one item after or before the returned iterator or eventually delete the key. If the key is not found, an iterator pointing to the first key greater than the searched one is returned. The position is so that an insertion there would place the key in the right order. If the key is not found, the returned iterator is marked as out-of-band (see oob() at page 14). </p>
<p class="faldoc_text">The method insert() of the Iterator class is optimized so that if the iterator is already in a valid position where to insert its key, the binary search is not performed again. Compare: </p>
<pre class="faldoc_code">
d = [ "a" => 1, "c"=>2 ]
// two searches
if "b" notin d
d["b"] = 0
else
d["b"]++
end
// one search
iter = dictBest( dict, "b" )
isoob(iter) ? iter.insert( "b", 0 ) : iter.value( iter.value() + 1 )
</pre>
<p class="faldoc_text">In the first case, the insertion of a special value in a dictionary where the value is still not present has required a first search then a second one at insertion or modify. In the second case, the iterator can use the position information it has stored to avoid a second search. </p>
<p class="faldoc_text">This function can also be used just to know what is the nearest key being present in the dictionary. The searched key is greater than the one that can be reached with Iterator.prev(), and less or equal than the one pointed. If Iterator.hasPrev() is false, then the searched key is smaller than any other in the collection, and if Iterator.hasCurrent() is false, then the key is greater than any other. </p>
</p>
<h3 class="faldoc_funcname"><a name="dictClear">dictClear()</a></h3>
<p class="item_brief">Removes all the items from a dictionary. </p>
<p class="faldoc_funcdecl">dictClear( dict )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">dict</td><td class="faldoc_paramdesc">The dictionary to be cleared. </td></tr>
</table>
<h3 class="faldoc_funcname"><a name="dictFill">dictFill()</a></h3>
<p class="item_brief">Fills the dictionary values with the given item. </p>
<p class="faldoc_funcdecl">dictFill( dict, item )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">dict</td><td class="faldoc_paramdesc">The array where to add the new item. </td></tr><tr><td class="faldoc_param">item</td><td class="faldoc_paramdesc">The item to be replicated. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc"> The same <b>dict</b> passed as parameter. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This method allows to clear all the values in this dictionary, resetting all the elements to a default value. </p>
</p>
<h3 class="faldoc_funcname"><a name="dictFind">dictFind()</a></h3>
<p class="item_brief">Returns an iterator set to a given key. </p>
<p class="faldoc_funcdecl">dictFind( dict, key )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">dict</td><td class="faldoc_paramdesc">The dictionary. </td></tr><tr><td class="faldoc_param">key</td><td class="faldoc_paramdesc">The key to be found. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">An iterator to the found item, or nil if not found. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">If the key is found in the dictionary, an iterator pointing to that key is returned. It is then possible to change the value of the found item, insert one item after or before the returned iterator or eventually delete the key. If the key is not found, the function returns nil. </p>
</p>
<h3 class="faldoc_funcname"><a name="dictFront">dictFront()</a></h3>
<p class="item_brief">Returns the first item in the dictionary. </p>
<p class="faldoc_funcdecl">dictFront( dict, [remove], [key] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">dict</td><td class="faldoc_paramdesc">The dictionary on which to operate. </td></tr>
<tr><td class="faldoc_optparam">remove</td><td class="faldoc_optparamdesc">If true, remove the dictionary entry too. </td></tr><tr><td class="faldoc_optparam">key</td><td class="faldoc_optparamdesc">If true, return the key instead of the value. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The first value (or key) in the dictionary. </td></tr>
<tr><td class="faldoc_raise">Raises:</td><td class="faldoc_raisedesc">
<table class="faldoc_raise">
<tr><td class="faldoc_raiseitem"><a href="./class_AccessError.html">AccessError</a></td><td class="faldoc_raisedesc">if the dictionary is empty </td></tr>
</table>
</td></tr>
</table>
<h3 class="faldoc_funcname"><a name="dictGet">dictGet()</a></h3>
<p class="item_brief">Retreives a value associated with the given key </p>
<p class="faldoc_funcdecl">dictGet( dict, key )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">dict</td><td class="faldoc_paramdesc">A dictionary. </td></tr><tr><td class="faldoc_param">key</td><td class="faldoc_paramdesc">The key to be found. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The value associated with a key, or an out-of-band nil if not found. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">Return the value associated with the key, if present, or one of the values if more than one key matching the given one is present. If not present, the value returned will be nil. Notice that nil may be also returned if the value associated with a given key is exactly nil. In case the key cannot be found, the returned value will be marked as OOB. </p>
</p>
<h3 class="faldoc_funcname"><a name="dictKeys">dictKeys()</a></h3>
<p class="item_brief">Returns an array containing all the keys in the dictionary. </p>
<p class="faldoc_funcdecl">dictKeys( dict )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">dict</td><td class="faldoc_paramdesc">A dictionary. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">An array containing all the keys. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">The returned keyArray contains all the keys in the dictionary. The values in the returned array are not necessarily sorted; however, they respect the internal dictionary ordering, which depends on a hashing criterion. </p>
<p class="faldoc_text">If the dictionary is empty, then an empty array is returned. </p>
</p>
<h3 class="faldoc_funcname"><a name="dictMerge">dictMerge()</a></h3>
<p class="item_brief">Merges two dictionaries. </p>
<p class="faldoc_funcdecl">dictMerge( destDict, sourceDict )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">destDict</td><td class="faldoc_paramdesc">The dictionary where the merge will take place. </td></tr><tr><td class="faldoc_param">sourceDict</td><td class="faldoc_paramdesc">A dictionary that will be inserted in destDict </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">The function allows to merge two dictionaries. </p>
</p>
<h3 class="faldoc_funcname"><a name="dictRemove">dictRemove()</a></h3>
<p class="item_brief">Removes a given key from the dictionary. </p>
<p class="faldoc_funcdecl">dictRemove( dict, key )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">dict</td><td class="faldoc_paramdesc">A dictionary. </td></tr><tr><td class="faldoc_param">key</td><td class="faldoc_paramdesc">The key to be removed </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">True if the key is found and removed, false otherwise. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">If the given key is found, it is removed from the dictionary, and the function returns true. If it's not found, it returns false. </p>
</p>
<h3 class="faldoc_funcname"><a name="dictSet">dictSet()</a></h3>
<p class="item_brief">Stores a value in a dictionary </p>
<p class="faldoc_funcdecl">dictSet( dict, key, value )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">dict</td><td class="faldoc_paramdesc">A dictionary. </td></tr><tr><td class="faldoc_param">key</td><td class="faldoc_paramdesc">The key to be found. </td></tr><tr><td class="faldoc_param">value</td><td class="faldoc_paramdesc">The key to be set. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">True if the value was overwritten, false if it has been inserted anew. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_note"><span class="faldoc_notetype">Note:</span> This method bypassess setIndex__ override in blessed (POOP) dictionaries. </p>
</p>
<h3 class="faldoc_funcname"><a name="dictValues">dictValues()</a></h3>
<p class="item_brief">Extracts all the values in the dictionary. </p>
<p class="faldoc_funcdecl">dictValues( dict )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">dict</td><td class="faldoc_paramdesc">A dictionary. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">An array containing all the values. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">The returned array contains all the value in the dictionary, in the same order by which they can be accessed traversing the dictionary. </p>
<p class="faldoc_text">If the dictionary is empty, then an empty array is returned. </p>
</p>
<h3 class="faldoc_funcname"><a name="set">set()</a></h3>
<p class="item_brief">Stores a value in a dictionary </p>
<p class="faldoc_funcdecl">set( key, value )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">key</td><td class="faldoc_paramdesc">The key to be found. </td></tr><tr><td class="faldoc_param">value</td><td class="faldoc_paramdesc">The key to be set. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">True if the value was overwritten, false if it has been inserted anew. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">Dictionary </p>
<p class="faldoc_note"><span class="faldoc_notetype">Note:</span> This method bypassess setIndex__ override in blessed (POOP) dictionaries. </p>
</p>
<hr/>
<div class="navibottom">
<center>
<a href="./index.html">Main</a> - <a href="./pages.html">Related pages</a> - <a href="./groups.html">Groups</a> - <a href="./funset.html">Function sets</a> - <a href="./classes.html">Classes</a> - <a href="./objects.html">Objects</a> - <a href="./functions.html">All functions</a> - <a href="./globals.html">Globals</a>
</center>
</div>
</div>
<div class="faldoc_signature">Made with <a href="http://www.falconpl.org">faldoc 2.2.0</div>
</body>
</html>
