PureDIC library

Overview

This is a purebasic associative array / dictionary library using some GDSL hash table functions.

Find more information about GDSL at http://directory.fsf.org/all/GDSL.html

An associative array is an abstract data type composed of a collection of keys and a collection of values, where each key is associated with one value. The operation of finding the value associated with a key is called a lookup or indexing, and this is the most important operation supported by an associative array. The relationship between a key and its value is sometimes called a mapping or binding. For example, if the value associated with the key "bob" is 7, we say that our array maps "bob" to 7.

Functions

PureDIC_Add(*HashTable, StringKey.s, Value.l [, SetNewValueIfAlreadyExists.l])

Add a unique element identified by it's key and stores the associated value, i.e. bind a new key to a new value

Parameters :
SetNewValueIfAlreadyExists	#True : if the element already exists, the new value is stored (Reassign : bind an old key to a new value).
			#False : if the element already exists, nothing happens [default].

Returned value :
Returns #NULL if failed

PureDIC_Close(*HashTable)

Close the dictionary.

PureDIC_Count(*HashTable)

Count the elements in the dictionary.

PureDIC_Create()

Create new dictionary.

Returned values :
- *HashTable (dictionary handle) if success
- #Null in case of insufficient memory

PureDIC_Delete(*HashTable, *StringKey)

Delete an element from the dictionary

PureDIC_Exist(*HashTable, StringKey.s)

Test if an element [key] does exist ?

Returned value :
#True	Element exists
#False	Element does not exist

PureDIC_Get(*HashTable, StringKey.s)

Get dictionary element by key

Returned value :
Value associated to the key

PureDIC_Parse(*HashTable, *ProcedureC_CB [, UserData])

Parse all elements of the dictionnary

Parameters :
- *HashTable	dictionary handle
- ProcedureC_CB	callback function called for each element
- UserData		user data transmitted to the callback function

Important : the callback function must be a ProcedureC !

The callback procedure is declared like this :

ProcedureC ParseCB(*HTEObject.HTElement, NotUsed.l, *uData.HTInfo) 
  Protected StringKey.s, Value.l, UserValue.l, *HashTable
  ;
  *HashTable = *uData\HT
  StringKey = PeekS(*HTEObject\key)
  Value = *HTEObject\uData
  UserValue = *HTEObject\uData
  ;
  Debug Str(*HashTable) + " -> '" + StringKey + "' : " + Str(Value) + " [" + Str(UserValue) + "]"
  ;
  ProcedureReturn #GDSL_MAP_CONT 
EndProcedure 

Callback return values :
- #GDSL_MAP_STOP : the parsing must be stopped
- #GDSL_MAP_CONT : the parsing must continue

PureDIC_Size(*HashTable)

Returns the dictionary size in bytes.