Falcon Function Reference

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.

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

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.

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.

This functions adds a couple of key/values in the dictionary, the key being forcibly unique.

If the given key is already present is found on the dictionary, the previous value is overwritten.

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.

The function allows to merge two dictionaries. If the optional parameter is not given, or false, in case of keys in sourceDict matching the ones in destDict, the relative values will be overwritten with the ones coming from sourceDict.

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.

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.

bless	Blesses a dictionary, making it an OOP instance.
dictBest	Returns an iterator set to a given key, or finds the best position for its insertion.
dictClear	Removes all the items from a dictionary.
dictFind	Returns an iterator set to a given key.
dictGet	Retreives a value associated with the given key
dictInsert	Inserts a new key/value pair in the dictionary
dictKeys	Returns an array containing all the keys in the dictionary.
dictMerge	Merges two dictionaries.
dictRemove	Removes a given key from the dictionary.
dictValues	Extracts all the values in the dictionary.

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

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

dictFind( dict, key )
dict	The dictionary.
key	The key to be found.
Returns:	An iterator to the found item, or nil if not found.

dictGet( dict, key )
dict	A dictionary.
key	The key to be found.
Returns:	The value associated with a key, or an out-of-band nil if not found.

Function set core_dict_funcs

Function list

Functions

bless()

dictBest()

dictClear()

dictFind()

dictGet()

dictInsert()

dictKeys()

dictMerge()

dictRemove()

dictValues()

dictInsert( dict, key, value )
dict	a dictionary
key	the new key
value	the new value

dictKeys( dict )
dict	A dictionary.
Returns:	An array containing all the keys.

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

dictRemove( dict, key )
dict	A dictionary.
key	The key to be removed
Returns:	True if the key is found and removed, false otherwise.

dictValues( dict )
dict	A dictionary.
Returns:	An array containing all the values.