1.2.5Class Dictionary

Metaclass for Falcon dictionary types.

Class Dictionary from \
                 BOM( )

This class holds the methods that can be applied to Falcon dictionary items.

Methods
backReturns the last item in the dictionary.
bestReturns an iterator set to a given key, or finds the best position for its insertion.
clearRemoves all the items from this dictionary.
compAppends elements to this dictionary through a filter.
doRepeats a function for each key/value pair in the dictionary.
dopDictionary default operation.
fillFills the array with the given element.
findReturns an iterator set to a given key.
firstReturns an iterator to the head of this dictionary.
frontReturns the first item in the dictionary.
getRetreives a value associated with the given key
keysReturns an array containing all the keys in this dictionary.
lastReturns an iterator to the head of this dictionary.
mcompAppends elements to this dictionary through a filter.
mergeMerges a dictionary into this one.
mfcompAppends elements to this dictionary through a filter.
propertiesReturns all the properties in the dictionary.
removeRemoves a given key from the dictionary.
setPropertySets a property in dictionary based instances.
valuesExtracts all the values in this dictionary.
Methods inherited from class BOM
__addOverrides binary addition operand.
__callOverrides call operator "self()".
__decOverrides decrement unary prefix operand.
__decpostOverrides decrement unary postfix operand.
__divOverrides binary division operand.
__getIndexOverrides array access operator []
__incOverrides increment unary prefix operand.
__incpostOverrides increment unary postifx operand.
__modOverrides modulo operand.
__mulOverrides binary multiplication operand.
__powOverrides power operand.
__setIndexOverrides array write operator []
__subOverrides binary subtraction operand.
baseClassReturns the class item from which an object has been instantiated.
boundDetermines if an item is bound or not.
classNameReturns the name of the class an instance is instantiated from.
clonePerforms a deep copy of the item.
comparePerforms a lexicographical comparison.
derivedFromChecks if this item has a given parent.
describeReturns the deep contents of an item on a string representation.
isCallableDetermines if an item is callable.
lenRetrieves the length of a collection
metaclassReturns the metaclass associated with this item.
ptrReturns a raw memory pointer out of this data (as an integer).
serializeSerialize the item on a stream for persistent storage.
toStringCoverts the object to string.
typeIdReturns an integer indicating the type of this item.

Methods

back

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.
ReturnThe last value (or key) in the dictionary.
Raise
AccessError if the dictionary is empty.

best

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.
ReturnAn iterator to the best possible position.

See also: dictBest.

clear

Removes all the items from this dictionary.

Dictionary.clear()

comp

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.
ReturnThis 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.

do

Repeats a function for each key/value pair in the dictionary.

Dictionary.do( func, [acc] )
func The function to be repeated.
acc Accumulator item.
ReturnThe 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()

dop

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.
ReturnThe 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.

fill

Fills the array with the given element.

Dictionary.fill( item )
item The item to be replicated.
ReturnThis dictionary.

This method allows to clear all the values in this dictionary, resetting all the elements to a default value.

find

Returns an iterator set to a given key.

Dictionary.find( key )
key The key to be found.
ReturnAn 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.

first

Returns an iterator to the head of this dictionary.

Dictionary.first()
ReturnAn iterator.

front

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.
ReturnThe first value (or key) in the dictionary.
Raise
AccessError if the dictionary is empty

get

Retreives a value associated with the given key

Dictionary.get( key )
key The key to be found.
ReturnThe 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.

keys

Returns an array containing all the keys in this dictionary.

Dictionary.keys()
ReturnAn 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.

last

Returns an iterator to the head of this dictionary.

Dictionary.last()
ReturnAn iterator.

mcomp

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.
ReturnThis dictionary.

Please, see the description of Sequence.comp, and the general Dictionary.comp for dictioanry-specific notes.

See also: Sequence.

merge

Merges a dictionary into this one.

Dictionary.merge( sourceDict )
sourceDict A dictionary that will be inserted in destDict

mfcomp

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.
ReturnThis dictionary.

Please, see the description of Sequence.comp, and the general Dictionary.comp for dictioanry-specific notes.

See also: Sequence.

properties

Returns all the properties in the dictionary.

Dictionary.properties()
ReturnAn 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.

remove

Removes a given key from the dictionary.

Dictionary.remove( key )
key The key to be removed
ReturnTrue 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.

setProperty

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
AccessError If the property can't be found.

Alters the value of the property in the given dictionary. If the required property is not present, an AccessError is raised.

values

Extracts all the values in this dictionary.

Dictionary.values()
ReturnAn 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.

Made with http://www.falconpl.org