<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Class Dictionary - Class Dictionary</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">Class Dictionary</h1>
<p class="faldoc_brief">Metaclass for Falcon dictionary types. </p>
<p class="faldoc_funcdecl">
<b>class</b> Dictionary \
<b>from</b> <a href="./class_BOM.html">BOM</a>
</p>
<p class="faldoc_brief"><a href="#more">more...</a></p>
<h2 class="faldoc_title">Summary</h2>
<table class="faldoc_list">
<tr><td><a href="#back">back()</a></td><td>Returns the last item in the dictionary. </td></tr>
<tr><td><a href="#best">best()</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="#clear">clear()</a></td><td>Removes all the items from this dictionary. </td></tr>
<tr><td><a href="#comp">comp()</a></td><td>Appends elements to this dictionary through a filter. </td></tr>
<tr><td><a href="#fill">fill()</a></td><td>Fills the array with the given element. </td></tr>
<tr><td><a href="#find">find()</a></td><td>Returns an iterator set to a given key. </td></tr>
<tr><td><a href="#first">first()</a></td><td>Returns an iterator to the head of this dictionary. </td></tr>
<tr><td><a href="#front">front()</a></td><td>Returns the first item in the dictionary. </td></tr>
<tr><td><a href="#get">get()</a></td><td>Retreives a value associated with the given key </td></tr>
<tr><td><a href="#keys">keys()</a></td><td>Returns an array containing all the keys in this dictionary. </td></tr>
<tr><td><a href="#last">last()</a></td><td>Returns an iterator to the head of this dictionary. </td></tr>
<tr><td><a href="#mcomp">mcomp()</a></td><td>Appends elements to this dictionary through a filter. </td></tr>
<tr><td><a href="#merge">merge()</a></td><td>Merges a dictionary into this one. </td></tr>
<tr><td><a href="#mfcomp">mfcomp()</a></td><td>Appends elements to this dictionary through a filter. </td></tr>
<tr><td><a href="#properties">properties()</a></td><td>Returns all the properties in the dictionary. </td></tr>
<tr><td><a href="#remove">remove()</a></td><td>Removes a given key from the dictionary. </td></tr>
<tr><td><a href="#setProperty">setProperty()</a></td><td>Sets a property in dictionary based instances. </td></tr>
<tr><td><a href="#values">values()</a></td><td>Extracts all the values in this dictionary. </td></tr>
</table>
<h3 class="faldoc_title">Inherited methods</h3>
<table class="faldoc_list">
<tr><td><a href="./class_BOM.html#__add">__add</a> from BOM </td><td>Overrides binary addition operand. </td></tr>
<tr><td><a href="./class_BOM.html#__call">__call</a> from BOM </td><td>Overrides call operator "self()". </td></tr>
<tr><td><a href="./class_BOM.html#__dec">__dec</a> from BOM </td><td>Overrides decrement unary prefix operand. </td></tr>
<tr><td><a href="./class_BOM.html#__decpost">__decpost</a> from BOM </td><td>Overrides decrement unary postfix operand. </td></tr>
<tr><td><a href="./class_BOM.html#__div">__div</a> from BOM </td><td>Overrides binary division operand. </td></tr>
<tr><td><a href="./class_BOM.html#__getIndex">__getIndex</a> from BOM </td><td>Overrides array access operator [] </td></tr>
<tr><td><a href="./class_BOM.html#__inc">__inc</a> from BOM </td><td>Overrides increment unary prefix operand. </td></tr>
<tr><td><a href="./class_BOM.html#__incpost">__incpost</a> from BOM </td><td>Overrides increment unary postifx operand. </td></tr>
<tr><td><a href="./class_BOM.html#__mod">__mod</a> from BOM </td><td>Overrides modulo operand. </td></tr>
<tr><td><a href="./class_BOM.html#__mul">__mul</a> from BOM </td><td>Overrides binary multiplication operand. </td></tr>
<tr><td><a href="./class_BOM.html#__pow">__pow</a> from BOM </td><td>Overrides power operand. </td></tr>
<tr><td><a href="./class_BOM.html#__setIndex">__setIndex</a> from BOM </td><td>Overrides array write operator [] </td></tr>
<tr><td><a href="./class_BOM.html#__sub">__sub</a> from BOM </td><td>Overrides binary subtraction operand. </td></tr>
<tr><td><a href="./class_BOM.html#baseClass">baseClass</a> from BOM </td><td>Returns the class item from which an object has been instantiated. </td></tr>
<tr><td><a href="./class_BOM.html#bound">bound</a> from BOM </td><td>Determines if an item is bound or not. </td></tr>
<tr><td><a href="./class_BOM.html#className">className</a> from BOM </td><td>Returns the name of the class an instance is instantiated from. </td></tr>
<tr><td><a href="./class_BOM.html#clone">clone</a> from BOM </td><td>Performs a deep copy of the item. </td></tr>
<tr><td><a href="./class_BOM.html#compare">compare</a> from BOM </td><td>Performs a lexicographical comparison. </td></tr>
<tr><td><a href="./class_BOM.html#derivedFrom">derivedFrom</a> from BOM </td><td>Checks if this item has a given parent. </td></tr>
<tr><td><a href="./class_BOM.html#describe">describe</a> from BOM </td><td>Returns the deep contents of an item on a string representation. </td></tr>
<tr><td><a href="./class_BOM.html#isCallable">isCallable</a> from BOM </td><td>Determines if an item is callable. </td></tr>
<tr><td><a href="./class_BOM.html#len">len</a> from BOM </td><td>Retrieves the length of a collection </td></tr>
<tr><td><a href="./class_BOM.html#metaclass">metaclass</a> from BOM </td><td>Returns the metaclass associated with this item. </td></tr>
<tr><td><a href="./class_BOM.html#ptr">ptr</a> from BOM </td><td>Returns a raw memory pointer out of this data (as an integer). </td></tr>
<tr><td><a href="./class_BOM.html#serialize">serialize</a> from BOM </td><td>Serialize the item on a stream for persistent storage. </td></tr>
<tr><td><a href="./class_BOM.html#toString">toString</a> from BOM </td><td>Coverts the object to string. </td></tr>
<tr><td><a href="./class_BOM.html#typeId">typeId</a> from BOM </td><td>Returns an integer indicating the type of this item. </td></tr>
</table>
<a name="more"><h2 class="faldoc_title">Detailed description</h2></a>
<p class="faldoc_funcdecl">
<b>class</b> Dictionary \
<b>from</b> <a href="./class_BOM.html">BOM</a>
</p>
<table class="faldoc_function">
</table>
<br/>
<p class="item_brief">Metaclass for Falcon dictionary types. </p>
<p class="faldoc_text">This class holds the methods that can be applied to Falcon dictionary items. </p>
<h2 class="faldoc_title">Methods</h2>
<h3 class="faldoc_funcname"><a name="back">back()</a></h3>
<p class="item_brief">Returns the last item in the dictionary. </p>
<p class="faldoc_funcdecl">Dictionary.back( [remove], [key] )</p>
<table class="faldoc_function">
<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="best">best()</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">Dictionary.best( key )</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_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">An iterator to the best possible position. </td></tr>
</table>
<h3 class="faldoc_funcname"><a name="clear">clear()</a></h3>
<p class="item_brief">Removes all the items from this dictionary. </p>
<p class="faldoc_funcdecl">Dictionary.clear( )</p>
<h3 class="faldoc_funcname"><a name="comp">comp()</a></h3>
<p class="item_brief">Appends elements to this dictionary through a filter. </p>
<p class="faldoc_funcdecl">Dictionary.comp( source, [filter] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">source</td><td class="faldoc_paramdesc">A sequence, a range or a callable generating items. </td></tr>
<tr><td class="faldoc_optparam">filter</td><td class="faldoc_optparamdesc">A filtering function receiving one item at a time. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">This dictionary. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> Please, see the description of <a href="./class_Sequence.html#comp">Sequence.comp</a>. </p>
<p class="faldoc_text">When the target sequence (this item) is a dictionary, each element that is to be appended must be exactly an array with two items; the first will be used as a key, and the second as the relative value. </p>
<p class="faldoc_text">For example: </p>
<pre class="faldoc_code">
dict = [=>].comp(
// the source
.[ 'bananas' 'skip me' 'apples' 'oranges' '<end>' 'melons' ],
// the filter
{ element, dict =>
if " " in element: return oob(1)
if "<end>" == element: return oob(0)
return [ "A" / len(dict), element ] // (1)
}
)
</pre>
<p class="faldoc_text">The element generated by the filter is a 2 element array, which is then stored in the dictionary as a pair of key-value items. </p>
<p class="faldoc_note"><span class="faldoc_notetype">Note:</span> In the example, the expression marked with (1) "A"/len(dict) causes the current number of elements in the dictionary to be added to the UNICODE value of the "A" letter; so the generated key will be "A" when the dictionary has zero elements, "B" when it has one element and so on. </p>
<p class="faldoc_text"> If the dictionary is blessed, then it is treated as an object, and instead of adding directly the pair of key/value items, it's <b>append</b> method is repeatedly called with the generated item as its parameter. In this case, the type and length of each element is not relevant. </p>
</p>
<h3 class="faldoc_funcname"><a name="fill">fill()</a></h3>
<p class="item_brief">Fills the array with the given element. </p>
<p class="faldoc_funcdecl">Dictionary.fill( item )</p>
<table class="faldoc_function">
<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">This dictionary. </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="find">find()</a></h3>
<p class="item_brief">Returns an iterator set to a given key. </p>
<p class="faldoc_funcdecl">Dictionary.find( key )</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_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="first">first()</a></h3>
<p class="item_brief">Returns an iterator to the head of this dictionary. </p>
<p class="faldoc_funcdecl">Dictionary.first( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">An iterator. </td></tr>
</table>
<h3 class="faldoc_funcname"><a name="front">front()</a></h3>
<p class="item_brief">Returns the first item in the dictionary. </p>
<p class="faldoc_funcdecl">Dictionary.front( [remove], [key] )</p>
<table class="faldoc_function">
<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="get">get()</a></h3>
<p class="item_brief">Retreives a value associated with the given key </p>
<p class="faldoc_funcdecl">Dictionary.get( key )</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_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 class="faldoc_note"><span class="faldoc_notetype">Note:</span> This method bypassess getIndex__ override in blessed (POOP) dictionaries. </p>
</p>
<h3 class="faldoc_funcname"><a name="keys">keys()</a></h3>
<p class="item_brief">Returns an array containing all the keys in this dictionary. </p>
<p class="faldoc_funcdecl">Dictionary.keys( )</p>
<table class="faldoc_function">
<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="last">last()</a></h3>
<p class="item_brief">Returns an iterator to the head of this dictionary. </p>
<p class="faldoc_funcdecl">Dictionary.last( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">An iterator. </td></tr>
</table>
<h3 class="faldoc_funcname"><a name="mcomp">mcomp()</a></h3>
<p class="item_brief">Appends elements to this dictionary through a filter. </p>
<p class="faldoc_funcdecl">Dictionary.mcomp( ..., [filter] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">...</td><td class="faldoc_paramdesc">One or more sequences, ranges or callables generating items. </td></tr>
<tr><td class="faldoc_optparam">filter</td><td class="faldoc_optparamdesc">A filtering function receiving one item at a time. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">This dictionary. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> Please, see the description of <a href="./class_Sequence.html#comp">Sequence.comp</a>, and the general <a href="./class_Dictionary.html#comp">Dictionary.comp</a> for dictioanry-specific notes. </p>
</p>
<h3 class="faldoc_funcname"><a name="merge">merge()</a></h3>
<p class="item_brief">Merges a dictionary into this one. </p>
<p class="faldoc_funcdecl">Dictionary.merge( sourceDict )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">sourceDict</td><td class="faldoc_paramdesc">A dictionary that will be inserted in destDict </td></tr>
</table>
<h3 class="faldoc_funcname"><a name="mfcomp">mfcomp()</a></h3>
<p class="item_brief">Appends elements to this dictionary through a filter. </p>
<p class="faldoc_funcdecl">Dictionary.mfcomp( filter, ..., [filter] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">filter</td><td class="faldoc_paramdesc">A filter function receiving each element before its insertion, or nil. </td></tr><tr><td class="faldoc_param">...</td><td class="faldoc_paramdesc">One or more sequences, ranges or callables generating items. </td></tr>
<tr><td class="faldoc_optparam">filter</td><td class="faldoc_optparamdesc">A filtering function receiving one item at a time. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">This dictionary. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> Please, see the description of <a href="./class_Sequence.html#comp">Sequence.comp</a>, and the general <a href="./class_Dictionary.html#comp">Dictionary.comp</a> for dictioanry-specific notes. </p>
</p>
<h3 class="faldoc_funcname"><a name="properties">properties()</a></h3>
<p class="item_brief">Returns all the properties in the dictionary. </p>
<p class="faldoc_funcdecl">Dictionary.properties( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">An array of strings representing property names. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This method returns all the property name in this dictionary. If the dictionary is not blessed, returns an empty array. </p>
<p class="faldoc_text"> The returned list contains all those keys that are suitable to be directly accessed as properties (that is, strings without spaces, puntaction and so on). You may use <a href="./class_Dictionary.html#keys">Dictionary.keys</a> instead if you know that all the keys can be used as properties. </p>
<p class="faldoc_text">The property list includes properties that refer to any kind of data, including functions (that is, methods), but it doesn't include properties in the metaclass of this item (FBOM properties). </p>
<p class="faldoc_text">The returned list is ordered by UNICODE value of the property names. </p>
</p>
<h3 class="faldoc_funcname"><a name="remove">remove()</a></h3>
<p class="item_brief">Removes a given key from the dictionary. </p>
<p class="faldoc_funcdecl">Dictionary.remove( key )</p>
<table class="faldoc_function">
<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="setProperty">setProperty()</a></h3>
<p class="item_brief">Sets a property in dictionary based instances. </p>
<p class="faldoc_funcdecl">Dictionary.setProperty( propName, value )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">propName</td><td class="faldoc_paramdesc">A string representing the name of a property or a method inside the dictionary. </td></tr><tr><td class="faldoc_param">value</td><td class="faldoc_paramdesc">The property new value. </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 property can't be found. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">Alters the value of the property in the given dictionary. If the required property is not present, an AccessError is raised. </p>
</p>
<h3 class="faldoc_funcname"><a name="values">values()</a></h3>
<p class="item_brief">Extracts all the values in this dictionary. </p>
<p class="faldoc_funcdecl">Dictionary.values( )</p>
<table class="faldoc_function">
<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>
<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>
