A dict object (a dictionary) is a collection of dictionary items (dict_item objects), each of which is a triple (key, label, object). The key must be unique over the dict.
Dict objects can be made visible by attaching them to a browser object or list_browser object. The browser can then be used to select dict_item objects.
The access to a dict_item object from a key is implemented using a hash_table object.
Bugs:
Class dict is very old and is based on some outdated
ideas. Currently its primary use is to provide the storage facilities
for a browser.
Its definition might be revised some day to be more in line with the
spirit of the current PCE system. Notably try not to rely on dict->format
and dict<-current.
->sort.
<-label.
<-dict
contains the reverse pointer.
When the dict is modified, it will send messages to the list_browser object:
|](108,
[105,115,116,95,98,114,111,119,115,101,114,32,45,62,95,100,101,108,101,116,101,95,105,116,101,109,58,32,100,105,99,116,95,105,116,101,109])|](108,
[105,115,116,95,98,114,111,119,115,101,114,32,45,62,95,105,110,115,101,114,116,95,105,116,101,109,58,32,100,105,99,116,95,105,116,101,109])|](108,
[105,115,116,95,98,114,111,119,115,101,114,32,45,62,95,99,108,101,97,114])<-members
to maintain ordering information (see dict->sort
and dict->append)
and once in the hash_table
object dict<-table
to get fast access from a key to a dict_item
object.
<->sort_by
defines the behaviour of dict->insert
as well as the default behaviour of dict->sort.
If its value is @nil,
no sorting is done. dict->insert
and will behave as dict->append.
Using
@default, the
arguments are sorted alphabetically on their printed representation. dict->insert
will insert a new item according to this order. If the dict<-sort_by
contains a code object,
this will be used for comparing the pairs of dict_item
objects. See also chain->sort.
It dict<-sort_by
is assigned another value than @nil, dict->sort
will be activated to establish the desired order.
Using dict->sort_by
is a good technique to insert new items at the right place in the list.
It is not a good technique to build up a sorted list as this will result
in quadratic behaviour for long lists, while dict->sort
uses the QuickSort algorithm.
<-key
to the corresponding dict_item
object is maintained by this hash_table
object.
<-members).
Note that class dict_item
defines a conversion function to create a dict_item from a key. See dict_item<-convert.
See also dict->insert_after
and dict->insert.
Bugs: If there is already a dict_item with this dict_item<-key,
the old entry is deleted from dict<-table.
A subsequent dict<-member
wil this return the last appended dict_item with this dict<-key.
<-browser.
|dict_item<-key.
Diagnostics: Fails silently when the argument is not a member dict_item or and the key of a member dict_item.
->for_all
on the chain of dict<-members.
->for_some
on the chain of dict<-members.
<-sort_by.
If dict<-sort_by
is @nil, just dict->append.
If dict<-sort_by
is @default,
insert the item before the first item that is alphabetically larger. It dict<-sort_by
contains a code object,
insert it before the first item for which executing the code (if it is a
function) return larger.
See also chain->sort, dict->insert_after, dict->append, dict->sort
and
dict->sort_by.
|dict_item*->append)
after the specified item (a dict_item or key). If the second argument is @nil,
the dict_item is inserted as the first item.
|dict_item<-key)
is member of the is dict.
Bugs: Redundant. Use dict<-member
instead.
|code|function],
ignore_blanks=[bool], reverse=[bool]<-members.
There are two possibilities:
<-label.
The first argument requests to compare case-insensitive. The second to
ignore leading and trailing blank space and to collapse multiple blanks
in the middle to a single space character. (see also string->strip).
->sort
for details.
If dict<-sort_by
contains a code object,
this will be used as the default. See also dict<-sort_by
to maintain a list of sorted objects.
Defaults:
# case-insensitive: dict.sort_ignore_case
.sort_ignore_blanks
@see dict.sort_ignore_case
@see dict.sort_ignore_blanks
<-find
on the chain of dict<-members.
<-find_all
on the chain of dict<-members.
<-members
whose dict<-label (or dict<-key
if the dict<-label is @default)
has the specified prefix. The search starts at the nth dict_item
(0-based). The last argument requests case-insensitive (@on)
or case-sensitive (@off).
Diagnostics: # Start index: 0
<-match
@see dict.sort_ignore_case
<-label
(or dict_item<-key
when the label is @default)
match (using char_array->sub)
the argument name.
Note that more complicated searches may be performed using dict<-find_all.
Bugs: Should allow for case-insensitive matching.
|dict_item -> dict_item<-dict
equals this dict. Otherwise, invoke hash_table<-member
on dict<-table
and return the result.
Note that many of the methods of the class that require a member
dict_item argument use dict<-member
to find the dict_item.