1.12Dictionary support

Dictionary related functions.

Functions

bless

Blesses a dictionary, making it an OOP instance.

bless( dict, [mode] )
dict A dictionary to be blessed.
mode True (default) to bless the dictionary, false to unbless it.
ReturnThe same dictonary passed as dict.

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.

dictBack

Returns the last item in the dictionary.

dictBack( dict, [remove],[key] )
dict The dictionary on which to operate.
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

dictBest

Returns an iterator set to a given key, or finds the best position for its insertion.

dictBest( dict, key )
dict The dictionary.
key The key to be found.
ReturnAn iterator to the best possible position.

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

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:


   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 )

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.

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.

dictClear

Removes all the items from a dictionary.

dictClear( dict )
dict The dictionary to be cleared.

dictFill

Fills the dictionary values with the given item.

dictFill( dict, item )
dict The array where to add the new item.
item The item to be replicated.
ReturnThe same dict passed as parameter.

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

dictFind

Returns an iterator set to a given key.

dictFind( dict, key )
dict The dictionary.
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.

dictFront

Returns the first item in the dictionary.

dictFront( dict, [remove],[key] )
dict The dictionary on which to operate.
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

dictGet

Retreives a value associated with the given key

dictGet( dict, key )
dict A dictionary.
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.

See also: oob.

dictKeys

Returns an array containing all the keys in the dictionary.

dictKeys( dict )
dict A dictionary.
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.

dictMerge

Merges two dictionaries.

dictMerge( destDict, sourceDict )
destDict The dictionary where the merge will take place.
sourceDict A dictionary that will be inserted in destDict

The function allows to merge two dictionaries.

dictRemove

Removes a given key from the dictionary.

dictRemove( dict, key )
dict A dictionary.
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.

dictSet

Stores a value in a dictionary

dictSet( dict, key, value )
dict A dictionary.
key The key to be found.
value The key to be set.
ReturnTrue if the value was overwritten, false if it has been inserted anew.

Note: This method bypassess setIndex override in blessed (POOP) dictionaries.

See also: oob.

dictValues

Extracts all the values in the dictionary.

dictValues( dict )
dict A dictionary.
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.

set

Stores a value in a dictionary

set( key, value )
key The key to be found.
value The key to be set.
ReturnTrue if the value was overwritten, false if it has been inserted anew.

Note: This method bypassess setIndex override in blessed (POOP) dictionaries.

See also: oob.

See also: oob.

Made with http://www.falconpl.org