Index  |  Related pages  |  Classes  |  Functions  |  Entities  |  Function Sets  |  Groups

Function set core_dict_funcs

Dictionary related functions.


Function list

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.

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.

Returns:

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

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.

Returns:

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

dictClear()

Removes all the items from a dictionary.

dictClear( dict )
dict

The dictionary to be cleared.

dictFind()

Returns an iterator set to a given key.

dictFind( dict, key )
dict

The dictionary.

key

The key to be found.

Returns:

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.

dictGet()

Retreives a value associated with the given key

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.

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.

dictInsert()

Inserts a new key/value pair in the dictionary

dictInsert( dict, key, value )
dict

a dictionary

key

the new key

value

the new value

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.

dictKeys()

Returns an array containing all the keys in the dictionary.

dictKeys( dict )
dict

A dictionary.

Returns:

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.

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

dictRemove()

Removes a given key from the dictionary.

dictRemove( dict, key )
dict

A dictionary.

key

The key to be removed

Returns:

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.

dictValues()

Extracts all the values in the dictionary.

dictValues( dict )
dict

A dictionary.

Returns:

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.


Index  |  Related pages  |  Classes  |  Functions  |  Entities  |  Function Sets  |  Groups
Made with Faldoc 1.0.0