StringDictionary Class

The StringDictionary class is useful to count and sort a collection of unique strings. GenoPro uses the StringDictionary to create an index of last names.

Method	Description
`Add(strKey [,strValue])`	Adds a unique key to the dictionary. If the key is already there, increase its counter without modifying its value.
`Added(strKey [,strValue])`	Same as the `Add` method, however returns `true` if the key was added, and returns `false` if the key was already there.
`SortByKey()`	Sorts the keys alphabetically.
`SortByCounter()`	Sorts the keys from the smallest to the largest counter. In other words, the key having the largest counter will be found at the end of the collection.
`SortByValue()`	Sorts the keys by their values.
`Reverse()`	Reverses the order of the keys in the dictionary.
`Clear()`	Empties the dictionary.

Property	Description
`Count`	Returns the number of unique keys in the dictionary.
`Key(iKey)`	Gets the key name at a given position. Raises an error if the index `iKey` is negative or out of range.
`KeyCounter(iKey \| strKey)`	Gets the number of instances a key has been added. The counter may be accessed by index or by the key name. The `KeyCounter` is also a write property. As a result, you can tweak the counter if necessary. Example: `oStringDictionary.KeyCounter("A") = 65`Raises an error if the index is out of range or if the key name is not present in the dictionary.
`KeyValue(iKey \| strKey)`	Gets/Sets set the value of a given key. The value may be accessed by index or by the key name. The key will be added to the dictionary if not already present. This property does not modify the instance counter.

By default, the keys are stored in the order in which they have been added, unless the collection has been sorted or reversed.

For readability, accuracy and reliability, the keys are case sensitive. In other words, StringDictionary.Add("abc") and StringDictionary.Add("ABC") would add two distinct keys to the dictionary. If you want the keys to be independent of case, accents or punctuation, you are welcome to use any combination of the utility methods StrStripAccents, StrStripAccentsLCase, StrStripAccentsUCase or StrStripPunctuation.

Usage:
Counting unique keys is can be useful for computing statistics or displaying most and least popular items. For instance, using the StringDictionary object, you can determine the top 20 most popular first name, or occupations.

Example:
The following sample code shows the use of the StringDictionary. In this example, the value of each key is unused. Please notice the output produced four unique keys. This is because the lowercase "b" key is distinct from its uppercase "B". There are two entries under the key "A" and one entry for the other keys. If we were to get the key values, we would get "Automobile", "Bicycle", "Car" and "Bogey" respectively. The key value "Airplane" would has been discarded because the key "A" was already there when added.

Dim oStringDictionary Set oStringDictionary = Util.NewStringDictionary() oStringDictionary.Add "A", "Automobile"

    oStringDictionary.Add "B", "Bicycle"

    oStringDictionary.Add "C", "Car"

    oStringDictionary.Add "A", "Airplane"

    oStringDictionary.Add "b", "Bus"

    'oStringDictionary.SortByValue()
    

    Report.WriteFormattedBr "Number of Unique Keys: {}", oStringDictionary.Count

      iKeyLast = oStringDictionary.Count - 1 ' Index of the last key

      For iKey = 0 To iKeyLast Report.WriteFormattedBr " The dictionary key {} at index {} has a counter of {}", oStringDictionary.Key(iKey),
      iKey, oStringDictionary.KeyCounter(iKey) Next

The output is:

Number of Unique Keys: 4
The dictionary key A at index 0 has a counter of 2
The dictionary key B at index 1 has a counter of 1
The dictionary key C at index 2 has a counter of 1
The dictionary key b at index 3 has a counter of 1

What's Next?
In the example above, we have discovered the key values are discarded. If we want to keep (or group) the key values under a given key, we need to use the ObjectRepertory rather than the StringDictionary. The ObjectRepertory does keep all key values, and is therefore capable of producing the following output:

Number of Unique Keys: 4
The dictionary key A at index 0 has a counter of 2 containing { "Automobile", "Airplane" }
The dictionary key B at index 1 has a counter of 1 containing { "Bicycle" }
The dictionary key C at index 2 has a counter of 1 containing { "Car" }
The dictionary key b at index 3 has a counter of 1 containing { "Bus" }

See Also:
ObjectRepertory