method d first keyword -> cursor
  arg Dictionary d ; arg Str keyword ; arg_C Arrow cursor

method l next keyword old_cursor -> new_cursor
  arg Dictionary d ; arg Str keyword ; arg Arrow old_cursor ; arg_C Arrow new_cursor

The 'next' method exists because a dictionary may contain several elements associated to the same keyword

Here is an example:

 module "/pliant/language/unsafe.pli"
 ...
 var Dictionary d
 ...
 var Pointer:Arrow c :> d first "test"
 while c<>null
   ...
   if entry_type:c=Int
     var Pointer:Int i :> c map Int
     ...
   ...
   c :> l next "test" c

method d key keyword type -> data
  arg_rw Dictionary d ; arg Str keyword ; arg Type type ; arg_RW type data

Maps the element with the right keywpord and the right type in the dictionary.
If no such element is found (also if elements with the right key are found, but none with the right type), it will be created and inserted in the dictionary first.


When you add an element to a dictionary, it must be an object (something allocated using new function) because the dictionary will increment its reference count, so it must have one !

method d insert keyword ahead new_object_address
  arg_rw Dictionary d ; arg Str keyword ; arg CBool ahead ; arg address new_object_address

When some objects already exist in the dictionary, associated with the same keyword, if 'ahead' is true, then the new object you insert will be the first, otherwise it will be the last.

method d remove keyword object_address
  arg_rw Dictionary d ; arg Str keyword ; arg address object_address

If 'object_address' is null, then all elements associated with 'keyword' will be removed, otherwise only the object that is stored at 'object_address' will be removed.


each item dictionary [key name]
  body

each item dictionary type [key name]
  body

In the first case, the 'item' keyword will be the address of each element, one after the other, and the body will be executed each time.
In the second case, the 'item' keyword will be a pointer to each object in the dictionary with the correct type.
In both cases, if 'name' ident is provided, it will map the string associated with each element in the dictionary.

Here is an example:

 module "/pliant/language/unsafe.pli"
 ...
 var Dictionary d
 ...
 each value d Str key keyword
   console "the keyword is " keyword " and it's value is " value eol


method d store filename
  arg Dictionary d ; arg Str filename

The dictionary content will be stored in an ascii file.
Each element in the dictionary must have a type with a well defined 'to string' method.

method d load filename type1 type2 ...
  arg_rw Dictionary d ; arg Str filename ; arg Type type1 type2 ...

The dictionary content will be loaded from the ascii file.
Various objects types that may be stored in the ascii file must be provided so that we can safely map types names contained in the ascii file to Pliant real types.All these types must have a well defined from string method.

Another example:

 module "/pliant/language/unsafe.pli"
 ...
 var Dictionary d
 ...
 type Person
   field Str firstname lastname
   field Int age
 generate_string_functions person
 ...
 d load "file:/home/me/mydatabase.dict" Int Str Person


method d count -> nb
  arg Dictionary d ; arg Int nb

Returns the number of objects in the dictionary.

method d hashsize -> nb
  arg Dictionary d ; arg_C Int nb

Returns or sets the size of the hash table of the dictionary.

method d freeze
  arg_rw Dictionary d

This will prevent the dictionary from changing its hash size when new elements are inserted.
When you add elements to a dictionary, it's hash size expands each time the number of elements gets bigger than the hash size, so if you intend on adding a lot of elements, it is more efficient (avoids memory fragmentation) to set the dictionary hash size once, then freeze it.

method d insert2 keyword ahead new_object_address module
  arg_rw Dictionary d ; arg Str keyword ; arg CBool ahead
  arg address new_object_address ; arg Module module

In the pliant general dictionary, each object is furthermore associated with a module. Don't use this method unless you add an object to the pliant general dictionary.


pliant_general_dictionary contains all the identifiers known by Pliant (functions, global variables, local variables, constants, private identifiers)
pliant_module_dictionary contains all the modules that have been loaded
Standard programs should not use these dictionaries.