Tech Note 42: Using the Dictionary Library

January 19, 2009

© NSB Corporation. All rights reserved.
This library kindly contributed by Bobby Kolov of BEIKS LLC.

NSBDictLib implements a key/value dictionary container object. It is useful for storing named variables, preferences, limited user input etc., so they can be rapidly accessed. All stored entries are in the Dynamic Heap, so they can't be too big.

This can be useful for storing values between forms or loading initial settings. Another use would be to keep a set of string values depending on language (English, German, Japanese, etc), and use it to load captions and titles in your app.

To use it, add NSBDictLib.prc to your project as a resource. It is a small file, about 4k in size. Initialise it in your Startup code as follows: 

     loadLibrary "NSDictLib", "NSDL"   'case is important
To see how each of these functions works, see the NSBDictLib sample project.

Files included:
NSBDictLib.INF The info file for NSBDictLib. Put this in your \nsbasic\lib folder.
NSBDictLib.prc The library. Put this into your \nsbasic\lib folder and add it to your project.
Dictionary.prj A sample project that demonstrates the functions.

NewDict()

Returns a reference to a new dictionary. Use this value in subsequent calls to the library. When you are done using a dictionary, use FreeDict to release it.
' Create a new dictionary object; the library can produce and operate over multiple dictionaries
' which is very convenient
Dim ref as Integer
ref = NSDL.NewDict()

FreeDict(ref)

Get rid of the dictionary and free up the memory it used. This needs to be doen for each dictionary that is created, or you will get an error when closing the program.
NSDL.FreeDict(ref)

SetKeyVal(ref, keyname, value)

Set a value in the dictionary to a string. If keyname does not exist, it is created. KeyName can be any string.
NSDL.SetKeyVal(ref, "Key1", "Value1")

GetKeyVal(ref, keyname)

Returns a value from the dictionary. 
varpref = NSDL.GetKeyVal(ref, "Key1")

DelKey(ref, keyname)

Delete a key from the dictionary.
NSDL.DelKey(ref, "Key1")

Count(ref)

Returns the number of keys in the dictionary.
NumberOfKeys = NSDL.count(ref)

GetKeyAt(ref, pos)

Returns the key at item 'pos' in the dictionary.
key12 = NSDL.GetKeyAt(ref, 12)

GetValAt(ref, pos)

Returns the value at item 'pos' in the dictionary.
val12 = NSDL.GetValAt(ref, 12)

Clear(ref)

Clear out all keys and values from a dictionary.
NSDL.Clear(ref)

FromString(ref, in, delimiter)

Create a number of keys from a string of values. This lets you set a up a series of values in one step. A handy trick is to store the 'in' string in a database.
Dim in as String
in = "A=Cartman|B=Kenny|C=Chef"
NSDL.FromString(ref, in, "|")
This sample creates 3 keys ("A", "B", "C") with the values "Cartman", "Kenny" and "Chef" respectively.

ToString(ref, delimiter)

Return a string of all the keynames and values in the dictionary.
Dim out as String
out = NSDL.ToString(ref, "|")
The string, out, will now have the value "A=Cartman|B=Kenny|C=Chef"