|
The Simons
|
|
|
The Simons
|
#include <Relation.h>
Inheritance diagram for Relation:
A Relation is a kind of dictionary, in which Objects may be looked up against other Objects, which serve as search keys. The search keys are called the domain of the Relation, and the corresponding values are called the range. A Relation may also be considered a Bag, whose elements are all of the type Entry with non-unique domain keys. An Entry is a single mapping from a domain Object to a range Object and is stored non-uniquely in the Relation, according to the value of its domain Object, which serves as the search key. Adding an Entry with the same search key will result in multiple Entries with the same key. However, each Entry is inserted uniquely under the deep comparison of both its domain and range, such that each distinct key-value combination occurs only once in the Relation.
A Relation is implemented as a chained hash-table. It locates chains of EQUAL entries by hashing on an entry with an average seek time of 1.3 lookups. In the rare event of a collision, entry chains are relocated. When the last entry in a chain is removed, the table is compacted in an average time of 2.3 lookups. The hash table is never more than 2/3 full for optimum performance.
Public Member Functions | |
| Relation () | |
| Construct an empty Relation. | |
| virtual | ~Relation () |
| Release an unused Relation. | |
| Relation (CollectionID) | |
| Copy a Relation from another Collection. | |
| virtual ObjectID | clone () const |
| Clone a shallow copy of this Relation. | |
| virtual Void | add (ObjectID) |
| Add an Object to this Relation. | |
| virtual Void | remove (ObjectID) |
| Remove an Object from this Relation. | |
| virtual Void | retainAll (CollectionID) |
| Retain only the elements present in another Collection. | |
| Void | addAt (ObjectID, ObjectID) |
| Add a new Entry to this Relation. | |
| Void | removeAt (ObjectID) |
| Remove all Entries with a given key from this Relation. | |
| SetID | getAt (ObjectID) const |
| Seek the Set of range values at a domain key. | |
| SetID | domain () const |
| Return the domain of this Relation as a Set. | |
| SetID | range () const |
| Return the range of this Relation as a Set. | |
| ObjectID | domain (Integer) const |
| Select a domain Object in this Relation. | |
| ObjectID | range (Integer) const |
| Return the ith range value in this Relation. | |
| RelationID | compose (RelationID) const |
| Compose this Relation with another Relation. | |
Protected Member Functions | |
| Relation (const Relation &) | |
| Copy another Relation. | |
|
|
Copy another Relation. Required by C++ to ensure that copying a Relation faithfully copies the underlying Bag. Takes a shallow copy of the other Relation by allocating a hash table with the same capacity, then transferring all the other Relation's entries to the same hashed locations. Transferred entries will be shared until they are replaced. This method is more efficient than the constructor to build a Relation from a Collection.
|
|
|
Construct an empty Relation. The size() of the Relation is zero, but a hash table of the default capacity is constructed and every entry is initialised to null.
|
|
|
Release an unused Relation. Deletes the hash table used to store the Relation's entries. |
|
|
Copy a Relation from another Collection. Allocates a hash table with enough capacity to hold all the elements of the other Collection. Inserts the elements of the other Collection using addAll(), which iterates using item() and inserts each element using add(). If an element is an Entry, it is added. If an element is some other Object, a new Entry is created mapping from the Object to itself. Transferred entries will be shared until they are replaced.
|
|
|
Add an Object to this Relation. If the Object is an Entry, adds the Entry to this Relation. Otherwise, creates a new Entry mapping from the Object to itself and adds it to this Relation.
Reimplemented from Bag. |
|
||||||||||||
|
Add a new Entry to this Relation. Creates a new Entry mapping from the domain Object to the range Object and adds it to this Relation. The Entry is added uniquely to the Relation, such that only one Entry with the same domain and range objects exists in the Relation. |
|
|
Clone a shallow copy of this Relation.
Reimplemented from Bag. |
|
|
Compose this Relation with another Relation. Returns a new Relation, which is the forward composition of this Relation with another Relation. The resulting Relation contains entries whose domain keys come from this Relation and whose range values come from the other Relation. An Entry exists in the result for each value associated with each key in this Relation, which is also a key in the other Relation and for each value in the other Relation associated with that key. The result contains as many, or fewer keys than this Relation. The result may contain more, or fewer Entries, according to all possible mappings.
|
|
|
Select a domain Object in this Relation. Provided for convenience, this is equivalent to selecting the domain of the Entry accessible at the given index. Each distinct index is guaranteed to access a different location in this Relation. Iterating over the domain will visit each domain Object once for each time it appears in the Relation and may visit the identical Object many times.
|
|
|
Return the domain of this Relation as a Set. Builds a Set of the domain keys of each Entry in this Relation. Multiple occurrences of each domain key in this Relation will therefore be eliminated. The result contains the same, or fewer elements than this Relation. To visit the unique domain elements of a Relation, iterate using item() on the result.
|
|
|
Seek the Set of range values at a domain key. Searches this Relation for the domain Object and returns the corresponding Set of range Objects. If no such domain key exists in this Relation, returns an empty Set.
|
|
|
Return the ith range value in this Relation. Provided for convenience, this is equivalent to selecting the range of the Entry accessible at the given index. Each distinct index is guaranteed to access a different location in this Relation. Iterating over the range will visit each range Object once for each time it appears in the Relation and may visit the identical Object many times.
|
|
|
Return the range of this Relation as a Set. Builds a Set of the range values of each Entry in this Relation. Multiple occurrences of each range value in this Relation will therefore be eliminated. The result contains the same, or fewer elements than this Relation. To visit the unique range elements of a Relation, iterate using item() on the result.
|
|
|
Remove an Object from this Relation. If the Object is an Entry, removes an Entry from this Relation only if its domain and range are both EQUAL to the domain and range of the Entry. Otherwise, removes all the Entries whose domains are EQUAL to the given Object, treating it as a domain key. This semantics allows removeAll() to behave like domain anti-restriction and retainAll() to behave like domain restriction.
Reimplemented from Bag. |
|
|
Remove all Entries with a given key from this Relation. Removes all Entries mapping from the domain Object to whatever range Objects exist in the Relation. Has no effect if the domain Object is not in the domain of this Relation.
|
|
|
Retain only the elements present in another Collection. If the other Collection consists of Entries, this is equivalent to Set intersection, retaining all those Entries from this Relation that are deep EQUAL, under deepCompare(), to some Entry in the Collection. Otherwise, this is equivalent to domain restriction, retaining all those Entries from this Relation that are judged EQUAL, under compare(), to a domain key in the Collection.
Reimplemented from Unordered. |
1.3