 |
VR-Forces 4.2 Class Documentation
|
|
VR-Forces 4.2 Class Documentation
|
Description: Maps string constants to integer constants and vice versa. More...
Public Member Functions | |
| DtStringIntMapper (unsigned mapSize=0, int offset=0, bool useStringHashlist=true) | |
| Main (and default) constructor. | |
| virtual | ~DtStringIntMapper () |
| deletes the intToStringMap and the stringToIntMap (if any) | |
| virtual bool | addMapping (const DtString &stringVal, int intVal) |
| registers a string / integer pair to be mapped. | |
| virtual bool | removeMapping (const DtString &stringVal, int intVal) |
| remove a string / integer mapping. | |
| virtual bool | getStringFromInt (int intVal, DtString &stringVal) const |
| Sets stringVal to the string registered with the specified intVal. | |
| virtual bool | getIntFromString (const DtString &stringVal, int &intVal) const |
| Sets intVal to the integer registered with the specified stringVal. | |
Protected Member Functions | |
| DtStringIntMapper (const DtStringIntMapper &orig) | |
| Copy and Assignment operators undefined. | |
| DtStringIntMapper & | operator= (const DtStringIntMapper &orig) |
| virtual bool | createIntToStringMap () |
| This allocates an array if myMapSize > 0, otherwise an integer hash list. | |
| virtual bool | createStringToIntMap () |
| This creates a string hash list if myUseStringHashlist == true. | |
| virtual bool | checkString (const DtString &stringVal, int intVal) const |
| utility functions for checking data validity | |
| virtual bool | checkInteger (int intVal, const DtString &stringVal) const |
| If the integer is already in the map, false is returned and it will not be added. | |
| bool | checkMapArrayInit (const DtString &caller) const |
| utility functions for general error checking | |
| bool | checkStringToIntHashlistInit (const DtString &caller) const |
| bool | checkIntToStringHashlistInit (const DtString &caller) const |
| bool | checkMapArrayIndexRange (int index, int intVal, const DtString &caller) const |
| void | emptyIntToStringArray () |
| utility functions to empty arrays and hashlists. | |
| void | emptyStringToIntHashlist () |
| utility functions to empty arrays and hashlists. | |
| void | emptyIntToStringHashlist () |
| utility functions to empty arrays and hashlists. | |
Protected Attributes | |
| unsigned | myMapSize |
| This argument is the total size of the myIntToStringArray array. | |
| bool | myUseStringHashlist |
| This argument to the constructor indicates whether to use a hash list for string lookup. | |
| int | myOffset |
| This argument to the constructor is subtracted from integers on the way in and added on the way out when using an intToString array. | |
| DtString ** | myIntToStringArray |
| This will be an array allocated to have mapSize entries. | |
| DtHashlist * | myStringToIntHashlist |
| This is only used if useStringHashlist == true. | |
| DtHashList * | myIntToStringHashlist |
| This is only used if myMapSize == 0. | |
Description: Maps string constants to integer constants and vice versa.
String / integer pairs are registered, and then one can be looked up using the other.
Forms: DtStringIntMapper() - When constructed with no arguments, the DtStringMapper will use the default argument values (mapSize = 0, offset = 0, useStringHashlist = true) which will result in the creation of an integer hash list to go from integer constants to string constants, and a string hash list to go the other way. This form is recommended when there is a large spread in the integer values, making the use of a simple array intolerably large and wasteful. For example, if 3 strings needed to be mapped to the integers 1, 8, and 4097, an integer hash list would be preferable to creating an array of DtStrings with 4098 elements.
DtStringIntMapper(mapSize) - When constructed with just a mapSize argument, DtStringMapper will use an array of mapSize elements of DtStrings, indexed by the integers that correspond to those strings. For example, a simple mapping from 0, 1, 2, 3, 4, 5 to "a", "b", "c", "d", "e", "f", respectively, would specify a mapSize of 6, and each string would quickly be looked up by using the integer an an index in the array. Since the default argument (, useStringHashlist = true) is in effect, a string hash list will be used in this case to go from strings back to integers.
DtStringIntMapper(mapSize, offset) - Similarly to DtStringMapper(mapSize), this form uses a fixed size array to map from integers to strings; but in this case, a non-zero offset will be subtracted from the integer constants when registered and added back on retrieval. This makes the use of a fixed array reasonable when mapping large integers that are close in range. For example, this allows the user to map a set of numbers like 1001, 1002, 1003, 1007 to four different strings by specifying an offset of 1001; then a mapsize of only eight is required.
DtStringMapper(mapSize, offset, false) DtStringMapper(mapSize, 0, false) - These two forms indicate that that a string hash list should not be created for going from strings to ints. This form is only meaningful if mapsize is nonzero; otherwise, a string hash list must be used. When no string hash list is created, strings will be mapped to integers by doing a linear search on the intToStringMap to find the desired string (and then the index is the desired result). This is arguably more efficient if only 2 or three mappings are needed. For example, all DtSimMessages are either interface messages or radio messages. Therfore only 2 mappings are required, and if the desired integer constants are close in range, no hash lists are needed.
| DtStringIntMapper::DtStringIntMapper | ( | unsigned | mapSize = 0, |
| int | offset = 0, |
||
| bool | useStringHashlist = true |
||
| ) |
Main (and default) constructor.
|
inlineprotected |
Copy and Assignment operators undefined.
|
virtual |
deletes the intToStringMap and the stringToIntMap (if any)
|
inlineprotected |
|
protectedvirtual |
This allocates an array if myMapSize > 0, otherwise an integer hash list.
This method is called by init(), and should not be called directly by the user. It returns false if an error occurs; true otherwise.
|
protectedvirtual |
This creates a string hash list if myUseStringHashlist == true.
This method is called by init(), and should not be called directly by the user. It returns false if an error occurs; true otherwise.
registers a string / integer pair to be mapped.
This call will return false if: an array is being used, and ! (0 < intVal-offset < mapSize-1), or if intVal or stringVal have already been registered as part of different pairing. E.g., if (! addStringMapping("foo", 1)) complainLoudly(); if (! addStringMapping("bar", 1)) complainLoudly(); The second call would generate a complaint, and no entry would be made.
remove a string / integer mapping.
If no current mapping exists, false is returned; true otherwise.
Sets stringVal to the string registered with the specified intVal.
If there is no mapping for this integer registered, false is returned, and stringVal is unchanged.
|
virtual |
Sets intVal to the integer registered with the specified stringVal.
If there is no mapping for this string registered, false is returned, and intVal is unchanged.
|
protected |
utility functions to empty arrays and hashlists.
Non-virtual since they are called from the destructor.
|
protected |
utility functions to empty arrays and hashlists.
Non-virtual since they are called from the destructor.
|
protected |
utility functions to empty arrays and hashlists.
Non-virtual since they are called from the destructor.
|
protectedvirtual |
utility functions for checking data validity
If the string is already in the map, false is returned and it will not be added. If the integer it's supposed to map to doesn't match, this call will also generate a DtWarn().
|
protectedvirtual |
If the integer is already in the map, false is returned and it will not be added.
If the string it's supposed to map to doesn't match, this call will also generate a DtWarn().
utility functions for general error checking
|
protected |
|
protected |
This argument is the total size of the myIntToStringArray array.
Since the integer constants being mapped are used as indices, this must be the largest int to be mapped + 1.
|
protected |
This argument to the constructor indicates whether to use a hash list for string lookup.
It is ignored if mapSize == 0, since in this case a hash list is required.
|
protected |
This argument to the constructor is subtracted from integers on the way in and added on the way out when using an intToString array.
|
protected |
This will be an array allocated to have mapSize entries.
When a string constant is sought, the int 'key' is just an index into this array. If the map is too small to justify using a hash list (probably 3 or 4 entries) then this array will just be searched to get an int from a string.
|
protected |
This is only used if useStringHashlist == true.
In this case, a hashlist of strings will be maintained, with the data item being the desired integer.
|
protected |
This is only used if myMapSize == 0.
Then createIntToStringMap() will allocate this hash list.