<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en" >
<head><meta content="text/html;charset=&quot;utf-8&quot;" http-equiv="Content-type"/><link href="faldoc.css" rel="stylesheet" type="text/css"/><title> - Dictionary support</title></head><body class="faldoc"><ul class="navi_top"><li class="top"><a href="index.html">Top: Table of contents</a></li>
<li class="up"><a href="core.html">Up: The core module</a></li>
<li class="prev"><a href="core_core_basic_io.html">Previous: Basic I/O</a></li>
<li class="next"><a href="core_core_dir_funcs.html">Next: Directory functions</a></li>
<li class="clear"></li>
</ul><div id="page_body"><h1><span class="toc_number">1.11</span>Dictionary support</h1><p class="brief">Dictionary related functions. </p>
<h2>Functions</h2><h3><a name="bless">bless</a></h3><p class="brief">Blesses a dictionary, making it an OOP instance. </p>
<pre class="prototype">bless( dict, [mode] )</pre>
<table class="prototype">
<tbody><tr class="param"><td class="name">dict</td><td class="content"> A dictionary to be blessed. </td></tr>
<tr class="optparam"><td class="name">mode</td><td class="content"> True (default) to bless the dictionary, false to unbless it. </td></tr>
<tr class="return"><td class="name">Return</td><td class="content">The same dictonary passed as <b>dict.</b> </td></tr>
</tbody>
</table>
<p>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>
<h3><a name="dictBack">dictBack</a></h3><p class="brief">Returns the last item in the dictionary. </p>
<pre class="prototype">dictBack( dict, [remove],[key] )</pre>
<table class="prototype">
<tbody><tr class="param"><td class="name">dict</td><td class="content"> The dictionary on which to operate. </td></tr>
<tr class="optparam"><td class="name">remove</td><td class="content"> If true, remove the dictionary entry too. </td></tr>
<tr class="optparam"><td class="name">key</td><td class="content"> If true, return the key instead of the value. </td></tr>
<tr class="return"><td class="name">Return</td><td class="content">The last value (or key) in the dictionary. </td></tr>
<tr class="raise"><td class="name">Raise</td><td class="content"><table>
<tbody><tr><td class="name"><a href="core_AccessError.html">AccessError</a></td><td class="content"> if the dictionary is empty </td></tr>
</tbody>
</table>
</td></tr>
</tbody>
</table>
<h3><a name="dictBest">dictBest</a></h3><p class="brief">Returns an iterator set to a given key, or finds the best position for its insertion. </p>
<pre class="prototype">dictBest( dict, key )</pre>
<table class="prototype">
<tbody><tr class="param"><td class="name">dict</td><td class="content"> The dictionary. </td></tr>
<tr class="param"><td class="name">key</td><td class="content"> The key to be found. </td></tr>
<tr class="return"><td class="name">Return</td><td class="content">An iterator to the best possible position. </td></tr>
</tbody>
</table>
<p>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>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>
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>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>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>
<h3><a name="dictClear">dictClear</a></h3><p class="brief">Removes all the items from a dictionary. </p>
<pre class="prototype">dictClear( dict )</pre>
<table class="prototype">
<tbody><tr class="param"><td class="name">dict</td><td class="content"> The dictionary to be cleared. </td></tr>
</tbody>
</table>
<h3><a name="dictFill">dictFill</a></h3><p class="brief">Fills the dictionary values with the given item. </p>
<pre class="prototype">dictFill( dict, item )</pre>
<table class="prototype">
<tbody><tr class="param"><td class="name">dict</td><td class="content"> The array where to add the new item. </td></tr>
<tr class="param"><td class="name">item</td><td class="content"> The item to be replicated. </td></tr>
<tr class="return"><td class="name">Return</td><td class="content">The same <b>dict</b> passed as parameter. </td></tr>
</tbody>
</table>
<p>This method allows to clear all the values in this dictionary, resetting all the elements to a default value. </p>
<h3><a name="dictFind">dictFind</a></h3><p class="brief">Returns an iterator set to a given key. </p>
<pre class="prototype">dictFind( dict, key )</pre>
<table class="prototype">
<tbody><tr class="param"><td class="name">dict</td><td class="content"> The dictionary. </td></tr>
<tr class="param"><td class="name">key</td><td class="content"> The key to be found. </td></tr>
<tr class="return"><td class="name">Return</td><td class="content">An iterator to the found item, or nil if not found. </td></tr>
</tbody>
</table>
<p>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>
<h3><a name="dictFront">dictFront</a></h3><p class="brief">Returns the first item in the dictionary. </p>
<pre class="prototype">dictFront( dict, [remove],[key] )</pre>
<table class="prototype">
<tbody><tr class="param"><td class="name">dict</td><td class="content"> The dictionary on which to operate. </td></tr>
<tr class="optparam"><td class="name">remove</td><td class="content"> If true, remove the dictionary entry too. </td></tr>
<tr class="optparam"><td class="name">key</td><td class="content"> If true, return the key instead of the value. </td></tr>
<tr class="return"><td class="name">Return</td><td class="content">The first value (or key) in the dictionary. </td></tr>
<tr class="raise"><td class="name">Raise</td><td class="content"><table>
<tbody><tr><td class="name"><a href="core_AccessError.html">AccessError</a></td><td class="content"> if the dictionary is empty </td></tr>
</tbody>
</table>
</td></tr>
</tbody>
</table>
<h3><a name="dictGet">dictGet</a></h3><p class="brief">Retreives a value associated with the given key </p>
<pre class="prototype">dictGet( dict, key )</pre>
<table class="prototype">
<tbody><tr class="param"><td class="name">dict</td><td class="content"> A dictionary. </td></tr>
<tr class="param"><td class="name">key</td><td class="content"> The key to be found. </td></tr>
<tr class="return"><td class="name">Return</td><td class="content">The value associated with a key, or an out-of-band nil if not found. </td></tr>
</tbody>
</table>
<p>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 class="see_also">See also: <a href="core_oob_support.html#oob">oob</a>.</p>
<h3><a name="dictKeys">dictKeys</a></h3><p class="brief">Returns an array containing all the keys in the dictionary. </p>
<pre class="prototype">dictKeys( dict )</pre>
<table class="prototype">
<tbody><tr class="param"><td class="name">dict</td><td class="content"> A dictionary. </td></tr>
<tr class="return"><td class="name">Return</td><td class="content">An array containing all the keys. </td></tr>
</tbody>
</table>
<p>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>If the dictionary is empty, then an empty array is returned. </p>
<h3><a name="dictMerge">dictMerge</a></h3><p class="brief">Merges two dictionaries. </p>
<pre class="prototype">dictMerge( destDict, sourceDict )</pre>
<table class="prototype">
<tbody><tr class="param"><td class="name">destDict</td><td class="content"> The dictionary where the merge will take place. </td></tr>
<tr class="param"><td class="name">sourceDict</td><td class="content"> A dictionary that will be inserted in destDict </td></tr>
</tbody>
</table>
<p>The function allows to merge two dictionaries. </p>
<h3><a name="dictRemove">dictRemove</a></h3><p class="brief">Removes a given key from the dictionary. </p>
<pre class="prototype">dictRemove( dict, key )</pre>
<table class="prototype">
<tbody><tr class="param"><td class="name">dict</td><td class="content"> A dictionary. </td></tr>
<tr class="param"><td class="name">key</td><td class="content"> The key to be removed </td></tr>
<tr class="return"><td class="name">Return</td><td class="content">True if the key is found and removed, false otherwise. </td></tr>
</tbody>
</table>
<p>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>
<h3><a name="dictSet">dictSet</a></h3><p class="brief">Stores a value in a dictionary </p>
<pre class="prototype">dictSet( dict, key, value )</pre>
<table class="prototype">
<tbody><tr class="param"><td class="name">dict</td><td class="content"> A dictionary. </td></tr>
<tr class="param"><td class="name">key</td><td class="content"> The key to be found. </td></tr>
<tr class="param"><td class="name">value</td><td class="content"> The key to be set. </td></tr>
<tr class="return"><td class="name">Return</td><td class="content">True if the value was overwritten, false if it has been inserted anew. </td></tr>
</tbody>
</table>
<p class='note'><b>Note:</b> This method bypassess setIndex<u> override in blessed (POOP) dictionaries. </u></p>
<p class="see_also">See also: <a href="core_oob_support.html#oob">oob</a>.</p>
<h3><a name="dictValues">dictValues</a></h3><p class="brief">Extracts all the values in the dictionary. </p>
<pre class="prototype">dictValues( dict )</pre>
<table class="prototype">
<tbody><tr class="param"><td class="name">dict</td><td class="content"> A dictionary. </td></tr>
<tr class="return"><td class="name">Return</td><td class="content">An array containing all the values. </td></tr>
</tbody>
</table>
<p>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>If the dictionary is empty, then an empty array is returned. </p>
<h3><a name="set">set</a></h3><p class="brief">Stores a value in a dictionary </p>
<pre class="prototype">set( key, value )</pre>
<table class="prototype">
<tbody><tr class="param"><td class="name">key</td><td class="content"> The key to be found. </td></tr>
<tr class="param"><td class="name">value</td><td class="content"> The key to be set. </td></tr>
<tr class="return"><td class="name">Return</td><td class="content">True if the value was overwritten, false if it has been inserted anew. </td></tr>
</tbody>
</table>
<p class='note'><b>Note:</b> This method bypassess setIndex<u> override in blessed (POOP) dictionaries. </u></p>
<p class="see_also">See also: <a href="core_oob_support.html#oob">oob</a>.</p>
<p class="see_also">See also: <a href="core_oob_support.html#oob">oob</a>.</p>
</div><ul class="navi_bottom"><li class="top"><a href="index.html">Top: Table of contents</a></li>
<li class="up"><a href="core.html">Up: The core module</a></li>
<li class="prev"><a href="core_core_basic_io.html">Previous: Basic I/O</a></li>
<li class="next"><a href="core_core_dir_funcs.html">Next: Directory functions</a></li>
<li class="clear"></li>
</ul><div class="signature">Made with <a href="faldoc 3.0">http://www.falconpl.org</a></div></body></html>
