Overview of Classes that Implement a Dictionary

A dictionary stores and retrieves various data using identifying information. The C++ platform implements a dictionary as a set of data structured as an array. Each item consists of three elements: identification number (ID) of OdUInt32 type, keyword (Key) of the OdString type, and smart pointer to an instance (Object) of the OdRxObjectPtr type. Items are associated with instances of various objects that have the RX-interface. Instances are placed free in memory.

An identification number is an integer value that begins with zero, increases by one when a new item is added in the dictionary, and does not change when an item is deleted or modified. A programmer can not modify the identification number using methods of the dictionary. An identification number never is set to a zero value and never decreases (only increases). When a program removes an item from the dictionary, the dictionary marks this item with a NULL value and hides it for iterators and methods of the dictionary. The removed item is in the dictionary, but it is not accessible for external objects or functions of the program.

A keyword is an arbitrary string that can be up to 255 characters long and can contain letters, digits, blank spaces, underscores, and some special characters, but can not contain inadmissible letters (see Naming objects). Each keyword is unique; a dictionary can not contain two identical keywords.

An object is a non-typified smart pointer to an existing instance of a class derived from the OdRxObject class. The item associates an instance with a keyword for the current identification number of the dictionary. The object must be created before it is put in the dictionary. The smart pointer increases the reference counter of the instance when it is added in the dictionary and decreases the reference counter of the instance when it is removed from the dictionary. A dictionary can contain any number of objects and objects of any types, including other dictionaries and custom objects.

To work with dictionaries, use the following:

OdRxDictionary abstract class
OdRxDictionaryItemImpl class
OdRxDictionaryImpl template class
OdRxDictionaryIterator abstract class
OdRxDictionaryIteratorImpl template class
odrxSysRegistry() global function
odrxClassDictionary() global function
odrxServiceDictionary() global function
odrxCreateRxDictionary() global function
odrxCreateSyncRxDictionary() global function

OdRxDictionary class

The OdRxDictionary abstract class provides the base interface for all dictionaries and is used only for deriving classes. Developers cannot create an instance of this class. It declares the following specific methods:

getAt() pure virtual method — Returns the object associated with the specified key or ID.
idAt() pure virtual method — Returns the ID associated with a key.
keyAt() pure virtual method — Returns the key associated with an ID.
resetKey() pure virtual method — Sets a new key for the specified ID.
has() pure virtual method — Checks whether the specified key or ID exists in the dictionary.
isCaseSensitive() pure virtual method — Checks whether the searching of keys is case-sensitive.
numEntries() pure virtual method — Returns the number of items.
putAt() pure virtual method — Puts the specified object in the dictionary with the specified key, that is, creates a new item, assigns a new ID for it, and associates the specified object with the specified key in the item.
remove() pure virtual method — Removes the item associated with the specified key or ID, but does not delete the associated object.

These methods do not have an implementation and are the declaration of the dictionary interface. Classes derived from the OdRxDictionary class must redefine these methods for working with items. You can either implement these methods in the class that you derive or you can use the OdRxDictionaryImpl template class that creates the standard implementation of these methods.

The OdRxDictionary abstract class is the successor of the OdRxObject abstract class which provides the base interface for working with smart pointers. The OdRxDictionary class also inherits reference counter functionality. Therefore you must additionally implement the numRefs(), addRef(), and release() pure virtual methods that work with the reference counter.

Instead of the custom implementation, you can use the standard implementation of the dictionary object using the odrxCreateRxDictionary() and odrxCreateSyncRxDictionary() global functions.

OdRxDictionaryItemImpl class

The OdRxDictionaryItemImpl class creates the standard implementation of the dictionary item. This class defines three members:

m_key — The keyword of the item (OdString type).
m_nextId — The ID of the item (OdUInt32 type).
m_val — The reference to the associated object (OdRxObjectPtr type).

Each instance of the OdRxDictionaryItemImpl class is an item of the dictionary.

The OdRxDictionaryItemImpl class implements the getKey() method which returns the keyword associated with this item, the setKey() method which sets a new keyword for the item using the specified string, the getVal() method which returns the non-typified smart pointer to the instance of the object associated with this item, setVal() method which sets a new instance for the item using the specified smart pointer, the isErase() method which checks whether the item is associated with an object, the erase() method which disassociates the item with the object, the nextId() method which returns the identification number of the item, and the setNextId() method which sets a new identification number for the item using the specified integer value.

OdRxDictionaryImpl template

The OdRxDictionaryImpl template creates the standard implementation of the pure virtual methods for classes derived from the OdRxDictionary class. This template wraps the specified class using a new class that inherits all methods of the specified class and creates the implementation of the pure virtual methods for it. The OdRxDictionaryImpl template uses the OdBaseDictionaryImpl template as a base class to create a dictionary as the sorted array of the OdRxDictionaryItemImpl instances. It defines the operators for getting, finding, checking, and setting elements. The OdRxDictionaryImpl template does not create the implementation of the numRefs(), addRef(), and release() methods, therefore, after applying it you should use the OdRxObjectImpl template to implement the standard reference counter functionality.

OdRxDictionaryIterator abstract class

The OdRxDictionaryIterator abstract class provides the base interface for all dictionary iterators and is used only for their deriving. Developers cannot create an instance of this class. It declares the following specific methods:

next() pure virtual method — Traverses to the next item of the dictionary.
done() pure virtual method — Checks whether the traversing is completed.
object() pure virtual method — Returns the smart pointer of the object to which the iterator refers.
getKey() pure virtual method — Returns the keyword associated with the item to which the iterator refers.
id() pure virtual method — Returns the identification number associated with the item to which the iterator refers.

These methods do not have an implementation and are the declaration of the dictionary iterating interface. Classes derived from the OdRxDictionaryIterator class must redefine these methods for working with items. You can either implement these methods in the class that you derive or you can use the OdRxDictionaryIteratorImpl template class that creates the standard implementation of these methods.

The OdRxDictionaryIterator abstract class is the successor of the OdRxIterator abstract class that provides the base interface for working with iterators. The OdRxDictionaryIterator abstract class also is the successor of the OdRxObject abstract class which provides the base interface for working with smart pointers. The OdRxDictionaryIterator class inherits the iterating functionality and the reference counter functionality. Therefore you must additionally implement the pure virtual methods that work with these functionalities.

Instead of the custom implementation, you can use the standard implementation of the dictionary iterator defined by the newIterator() method.

OdRxDictionaryIteratorImpl template

The OdRxDictionaryIteratorImpl template creates the standard implementation of the pure virtual methods for classes derived from the OdRxDictionaryIterator class. This template wraps the specified class using a new class that inherits all methods of the specified class and creates the implementation of the pure virtual methods for it. The OdRxDictionaryIteratorImpl template uses the OdBaseIteratorImpl template as a base class to implement the base iterating functionality and the OdRxObjectImpl template to implement the standard reference counter functionality.

Global functions

The odrxInitialize() global function creates the root run-time dictionary, dictionary of the registered classes, dictionary of the registered services, dictionary of the system variables, and combines them in the tree-shape hierarchical structure. These dictionaries are used to access to the available objects of an application.

The odrxSysRegistry() global function returns the smart pointer to the root run-time dictionary which stores information about objects registered at run-time. The odrxClassDictionary() global function returns the smart pointer to the dictionary of the registered classes. The odrxServiceDictionary() global function returns the smart pointer to the dictionary of the registered services. Both dictionaries are a branch of the root run-time dictionary.

The odrxCreateRxDictionary() global function creates a new dictionary object that can be modified only from a single thread. The odrxCreateSyncRxDictionary() global function creates a new dictionary object that can be modified from multiple threads. The odrxCreateRxDictionary() and odrxCreateSyncRxDictionary() functions use the OdRxDictionaryImpl template for implementing standard dictionary functionality and the OdRxObjectImpl template for implementing standard reference counting functionality. They return the smart pointer to a new dictionary object. These functions do not put the created dictionary in the root dictionary and do not add it to the hierarchical structure. A new dictionary is placed free in memory.