ObjectRepertory Class

The ObjectRepertory class is the most versatile data structure of the report generator. In summary, the ObjectRepertory is an improved version of the StringDictionary capable to store objects rather than strings. In addition, the ObjectRepertory is capable of storing multiple objects under a single key, making it the ideal data structure for grouping data to produce statistics. For instance, you may use the ObjectRepertory to group individuals by last name. The ObjectRepertory would maintain a list of individual under each unique last name, so you can perform additional processing for improved reporting.

ObjectRepertory Methods	Description
`Add(strKey, oObject)`	Adds an object to the repertory at a given key. If the key does not exists, the method will create a new key before adding the object.
`Added(strKey, oObject)`	Same as the `Add` method, however returns `true` if the key was added, and returns `false` if the key was already there.
`AddObjectRepertory(strKey)`	Adds a new AddObjectRepertory to the ObjectRepertory if none existed for the key. Returns the ObjectRepertory corresponding to the key.
`SortByComment()`
`SortByCounter()`	Sorts the keys from the smallest to the largest number of objects. In other words, the key having the largest number of objects will be found at the end of the collection.
`SortByKey()`	Sorts the keys alphabetically.
`Reverse()`	Reverses the order of the keys in the object repertory.
`Clear()`	Empties the object repertory.

ObjectRepertory Properties	Description
`Entry(index \| strKey)`	Read-Only: Returns a reference to an `ObjectRepertoryEntry` which contains a key and a collection of objects. This property is vital to access the collection of data objects for a given key. In the future, this property will be read-write, so entries (keys) could be merged together.
`Count`	Return the number of unique keys in the object repertory.
`Key(iKey)`	Gets the key name at a given position. Raises an error if the index `iKey` is negative or out of range. This property is provided for code orthogonally with the `StringDictionary`. This property is the same as `Entry(iKey).Key`.
`KeyCounter(index \| strKey)`	Returns the number of objects under a given key. Raises an error if the index is out of range or if the key name is not present in the object repertory. This property is provided for code orthogonally with the `StringDictionary`. This property is the same as `Entry(iKey).Count` or `Entry(strKey).Count`.
`Object(index \| strKey)`	Gets/Sets set the first object at a given key. This is the default property, so the name of the method is rarely seen. For instance, the `Session` object is an instance of the `ObjectRepertory` class, so the following lines of code are identical: `Session(strKey) = oObject Session.Object(strKey) = oObject`

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

ObjectRepertoryEntry Class

What distinguishes the ObjectRepertory from the StringDictionary is the presence of an "entry" object. The word "entry" and "key" are used interchangeably in this section.

Properties and Methods	Description
`Key`	Gets the name of the key of a repertory entry.
`Count`	Returns the number of objects of a repertory entry. This is different from `ObjectRepertory.Count` which returns the number of keys in the repertory.
`Object(iObject)`	Gets the object at a given position from the entry's collection.
`Clear`	Empties the collection of a repertory entry.
`Add`	Adds an object to the repertory entry.
`AddObjects(oCollection)`	Adds the objects from a collection to the repertory entry. This is different than the `Add` method; the `Add` method would add the collection object to the repertory entry, while the `AddObjects` appends the objects from the collection to the repertory entry. If the collection is empty, the method `AddObjects` does nothing, while the `Add` method would add an empty collection to the repertory entry.
`ToGenoCollection`	Returns a new collection of GenoPro objects from the entry's collection. Since the `GenoCollection` must contain only valid GenoPro objects, any empty object in the repertory entry are ignored. On the other hand, this method raises an exception "type mismatch" if there are objects incompatible to the `GenoCollection` such as a string or a number.
`SortBy`	To be done. Sort the objects in the entry's collection. The implementation of this code is bit complicated, because the collection may contain anything, from strings to numbers to objects such as individuals, families, pictures, and more. In the meantime, you can use the method `ToGenoCollection`, sort the collection, clear the repertory entry, and re-insert the collection back to the repertory entry using the `AddObjects` method.

Example #1:
The following code groups all the individuals in the genealogy tree by last name, and then displays a list of all unique last names.

Set oRepertory = Util.NewObjectRepertory
For Each ind In Individuals
    oRepertory.Add ind.name.last, ind
Next 
For Each oEntry in oRepertory
    Report.WriteTextBr oEntry.key
Next

Example #2:
In our previous example, we used StringDictionary to count the number of instances of a given key. This time, we use the ObjectRepertory to keep a complete list of each object for each key. In this example, the object is a string, such as "Automobile", however it could be an individual, picture or anything else. Since we are using a For Each loop, we do not need to use the property Count and Object to access the objects of oEntry.


Dim oObjectRepertory
Set oObjectRepertory = Util.NewObjectRepertory()
oObjectRepertory.Add "A", "Automobile"
oObjectRepertory.Add "B", "Bicycle"
oObjectRepertory.Add "C", "Car"
oObjectRepertory.Add "A", "Airplane"
oObjectRepertory.Add "b", "Bus"
' oObjectRepertory.SortByKey()

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

iKeyLast = oObjectRepertory.Count - 1   ' Index of the last key
For iKey = 0 To iKeyLast
    Set oEntry =  oObjectRepertory.Entry(iKey)
   Report.WriteFormatted " The dictionary key {} at index {} has {} objects: {{ ", oEntry.Key, iKey, oEntry.Count
    strSeparator = ""
    For Each o In oEntry
        Report.WriteFormatted "{}'{&t}'", strSeparator, o
        strSeparator = ", "
    Next
    Report.WriteBr " }"
Next

The output is:

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

Example #2:
The following code displays a list of individuals grouped by last name, and sorted by first name (in descending order).


Dim oObjectRepertory
Set oObjectRepertory = Util.NewObjectRepertory()
For Each ind In Individuals
    oObjectRepertory.Add ind.Name.Last, ind
Next
oObjectRepertory.SortByKey()	' Sort the last names

iKeyLast = oObjectRepertory.Count - 1   ' Index of the last key
For iKey = 0 To iKeyLast
    Set oEntry = oObjectRepertory.Entry(iKey)
   Report.WriteFormatted "{} {&t}: {{ ", oEntry.Count, oEntry.Key
    Set oColl = oEntry.ToGenoCollection
    oColl.SortBy("-Name.First")
    oEntry.Clear
    oEntry.AddObjects oColl
    strSeparator = ""
    For Each o In oEntry
        Report.WriteFormatted "{}'{&t}'", strSeparator, o.Name.First
        strSeparator = ", "
    Next
    Report.WriteBr " }"
Next

This code was written to show the use of the GenoCollection to sort the individuals by first name. Please notice the minus sign at the beginning of the sort key to sort the first names in descending order. Once the collection is sorted, re-insert the sorted objects using the method AddObjects. Of course, if the purpose was to display the list, we could have written the following code:


For iKey = 0 To iKeyLast
   Set oEntry = oObjectRepertory.Entry(iKey)
   Report.WriteFormatted "{} {&t}: {{ ", oEntry.Count, oEntry.Key
    strSeparator = ""
    For Each o In oEntry.ToGenoCollection.SortBy("-Name.First")
        Report.WriteFormatted "{}'{&t}'", strSeparator, o.Name.First
        strSeparator = ", "
    Next
    Report.WriteBr " }"
Next

What's Next?
In the future, there will be several new methods and properties to sort and manipulate data. Due to time constraints, only essential methods and properties have been added for the first draft of the report generator.

See Also:
DataSorter StringDictionary