Metaclass for Falcon dictionary types.
Class Dictionary from \
BOM( )
This class holds the methods that can be applied to Falcon dictionary items.
| Methods | |
| back | Returns the last item in the dictionary. |
| best | Returns an iterator set to a given key, or finds the best position for its insertion. |
| clear | Removes all the items from this dictionary. |
| comp | Appends elements to this dictionary through a filter. |
| do | Repeats a function for each key/value pair in the dictionary. |
| dop | Dictionary default operation. |
| fill | Fills the array with the given element. |
| find | Returns an iterator set to a given key. |
| first | Returns an iterator to the head of this dictionary. |
| front | Returns the first item in the dictionary. |
| get | Retreives a value associated with the given key |
| keys | Returns an array containing all the keys in this dictionary. |
| last | Returns an iterator to the head of this dictionary. |
| mcomp | Appends elements to this dictionary through a filter. |
| merge | Merges a dictionary into this one. |
| mfcomp | Appends elements to this dictionary through a filter. |
| properties | Returns all the properties in the dictionary. |
| remove | Removes a given key from the dictionary. |
| setProperty | Sets a property in dictionary based instances. |
| values | Extracts all the values in this dictionary. |
| Methods inherited from class BOM | |
| __add | Overrides binary addition operand. |
| __call | Overrides call operator "self()". |
| __dec | Overrides decrement unary prefix operand. |
| __decpost | Overrides decrement unary postfix operand. |
| __div | Overrides binary division operand. |
| __getIndex | Overrides array access operator [] |
| __inc | Overrides increment unary prefix operand. |
| __incpost | Overrides increment unary postifx operand. |
| __mod | Overrides modulo operand. |
| __mul | Overrides binary multiplication operand. |
| __pow | Overrides power operand. |
| __setIndex | Overrides array write operator [] |
| __sub | Overrides binary subtraction operand. |
| baseClass | Returns the class item from which an object has been instantiated. |
| bound | Determines if an item is bound or not. |
| className | Returns the name of the class an instance is instantiated from. |
| clone | Performs a deep copy of the item. |
| compare | Performs a lexicographical comparison. |
| derivedFrom | Checks if this item has a given parent. |
| describe | Returns the deep contents of an item on a string representation. |
| isCallable | Determines if an item is callable. |
| len | Retrieves the length of a collection |
| metaclass | Returns the metaclass associated with this item. |
| ptr | Returns a raw memory pointer out of this data (as an integer). |
| serialize | Serialize the item on a stream for persistent storage. |
| toString | Coverts the object to string. |
| typeId | Returns an integer indicating the type of this item. |
Returns the last item in the dictionary.
Dictionary.back( [remove],[key] )
| remove | If true, remove the dictionary entry too. | ||
| key | If true, return the key instead of the value. | ||
| Return | The last value (or key) in the dictionary. | ||
| Raise |
|
Returns an iterator set to a given key, or finds the best position for its insertion.
Dictionary.best( key )
| key | The key to be found. |
| Return | An iterator to the best possible position. |
See also: dictBest.
Removes all the items from this dictionary.
Dictionary.clear()
Appends elements to this dictionary through a filter.
Dictionary.comp( source, [filter] )
| source | A sequence, a range or a callable generating items. |
| filter | A filtering function receiving one item at a time. |
| Return | This dictionary. |
Please, see the description of Sequence.comp.
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.
For example:
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)
}
)
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.
Note: 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.
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 append method is repeatedly called with the generated item as its parameter. In this case, the type and length of each element is not relevant.
See also: Sequence.
Repeats a function for each key/value pair in the dictionary.
Dictionary.do( func, [acc] )
| func | The function to be repeated. |
| acc | Accumulator item. |
| Return | The accumulator item, if provided, or nil. |
The function is called repeatedly for each key/value pair in the dictionary, with the key passed as the first parameter and the value in the second.
If an accumulator item is given in the acc parameter, each returned element is plainly added to the accumulator item with the standard add semantic (equivalent to "+" operator). Objects overriding the add operator will receive the required callback.
If the function returns an oob(0), the loop is broken, while if it returns an oob(1), the current item is dropped. Any other out of band parameter is ignored.
For example:
dict = [ "first" => "v1",
"second" => "v2",
"third" => "v3" ]
dsum = dict.do( { k, v =>
if k == "second": return oob(1)
return k + "=" + v
}, [] )
> dsum.describe()
Dictionary default operation.
Dictionary.dop( key, dflt, [oper] )
| key | The key to be defaulted. |
| dflt | The default value to be applied. |
| oper | The operation to be applied. |
| Return | The value associated with key after the application of the operation. |
Given the key, dflt and oper parameters, this method inserts a default value on a dictionary, eventually performing a default operation. In short, if the key is not present in the dictionary, a new key is created and the dflt value is assigned to it. If a oper callable item (function) is given, then the current value associated with the key is passed to it as a parameter; in case that the key still doesn't exist, the dflt value is passed instead. In both case, the key is then associated with the return value of the oper function.
Finally, this method return the value that has just been associated with the dictionary.
More coinciserly the method works along the following pseudocode rules:
function dop of dict, key, dflt and oper
if key exists in dict
if oper is a callable entity
value = oper( dict[key] )
dict[key] = value
else
value = dict[key]
end
else
if oper is a callable entity
value = oper( dflt )
dict[key] = value
else
value = oper( dflt )
end
end
return value
end
This function comes extremely convenient when in need to do some complex operations on a possibly uninitialized dictionary value. Suppose that an application stores the list of currently logged in-users in an array under the "users" key of a given prog_data dictionary. Then,
// a new user comes in...
newcomer = ...
users = prog_data.dop( "users", [], { v => v += newcomer } )
In one line, this code creates a "users" entry in prog_data, if it doesn't exists, which is initialized to an empty array. The empty array is then lenghtened and also returned, so that the program has already it handy without having to scan for it in program_data again.
Fills the array with the given element.
Dictionary.fill( item )
| item | The item to be replicated. |
| Return | This dictionary. |
This method allows to clear all the values in this dictionary, resetting all the elements to a default value.
Returns an iterator set to a given key.
Dictionary.find( key )
| key | The key to be found. |
| Return | An iterator to the found item, or nil if not found. |
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.
Returns an iterator to the head of this dictionary.
Dictionary.first()
| Return | An iterator. |
Returns the first item in the dictionary.
Dictionary.front( [remove],[key] )
| remove | If true, remove the dictionary entry too. | ||
| key | If true, return the key instead of the value. | ||
| Return | The first value (or key) in the dictionary. | ||
| Raise |
|
Retreives a value associated with the given key
Dictionary.get( key )
| key | The key to be found. |
| Return | The value associated with a key, or an out-of-band nil if not found. |
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.
Note: This method bypassess getIndex override in blessed (POOP) dictionaries.
See also: oob.
Returns an array containing all the keys in this dictionary.
Dictionary.keys()
| Return | An array containing all the keys. |
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.
If the dictionary is empty, then an empty array is returned.
Returns an iterator to the head of this dictionary.
Dictionary.last()
| Return | An iterator. |
Appends elements to this dictionary through a filter.
Dictionary.mcomp( ..., [filter] )
| ... | One or more sequences, ranges or callables generating items. |
| filter | A filtering function receiving one item at a time. |
| Return | This dictionary. |
Please, see the description of Sequence.comp, and the general Dictionary.comp for dictioanry-specific notes.
See also: Sequence.
Merges a dictionary into this one.
Dictionary.merge( sourceDict )
| sourceDict | A dictionary that will be inserted in destDict |
Appends elements to this dictionary through a filter.
Dictionary.mfcomp( filter, ... )
| filter | A filter function receiving each element before its insertion, or nil. |
| ... | One or more sequences, ranges or callables generating items. |
| Return | This dictionary. |
Please, see the description of Sequence.comp, and the general Dictionary.comp for dictioanry-specific notes.
See also: Sequence.
Returns all the properties in the dictionary.
Dictionary.properties()
| Return | An array of strings representing property names. |
This method returns all the property name in this dictionary. If the dictionary is not blessed, returns an empty array.
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 Dictionary.keys instead if you know that all the keys can be used as properties.
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).
The returned list is ordered by UNICODE value of the property names.
Removes a given key from the dictionary.
Dictionary.remove( key )
| key | The key to be removed |
| Return | True if the key is found and removed, false otherwise. |
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.
Sets a property in dictionary based instances.
Dictionary.setProperty( propName, value )
| propName | A string representing the name of a property or a method inside the dictionary. | ||
| value | The property new value. | ||
| Raise |
|
Alters the value of the property in the given dictionary. If the required property is not present, an AccessError is raised.
Extracts all the values in this dictionary.
Dictionary.values()
| Return | An array containing all the values. |
The returned array contains all the value in the dictionary, in the same order by which they can be accessed traversing the dictionary.
If the dictionary is empty, then an empty array is returned.