IARelation

A relation is an unordered collection of zero or more elements that have a key. Element equality is supported, and the values of the elements are relevant.

The keys of the elements are not unique. You can add an element whether or not there is already an element in the collection with the same key.


IARelation - Member Functions and Data by Group

Constructors & Destructor

Construct and destruct IARelation objects.


[view class]
~IARelation
public:
~IARelation()
Removes all elements from the collection. Destructors are called for all elements contained in the collection and for elements that have been constructed in advance.

Side Effects

All cursors of the collection become undefined.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
IARelation
Constructs a collection.


Note: The collection constructor does not define whether any elements are constructed when the collection is constructed. For some classes, the element's default constructor may be invoked when the collection's constructor is invoked. This happens if a tabular or a diluted sequence implementation variant is used for a collection. The element's default constructor is used to allocate the required storage and initialize the elements. Therefore, a default constructor must be available for elements in such cases.

Exception

IOutOfMemory


Overload 1
public:
IARelation(INotifier&)
Use this constructor to create a collection with support for notification.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
protected:
IARelation(IARelation < Element, Key > const&)
The copy constructor

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
protected:
IARelation()
The default constructor.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Add Elements

Add elements to this collection.


[view class]
addDifference
public:
virtual void addDifference( IARelation < Element, Key > const&, IARelation < Element, Key > const& )
Creates the difference between the two given collections, and adds this difference to the collection. The contents of the added elements, not the pointers to those elements, are copied.

For a definition of the difference between two collections, see IABag::differenceWith.

Preconditions

Because the elements are added one by one, the following preconditions are tested for each individual addition.

Side Effects

If any elements were added, all cursors of this collection become undefined.

Exceptions

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
addIntersection
public:
virtual void addIntersection( IARelation < Element, Key > const&, IARelation < Element, Key > const& )

Creates the intersection of the two given collections, and adds this intersection to the collection. The contents of the added elements, not the pointers to those elements, are copied.

For a definition of the intersection of two collections, see IABag::intersectionWith.

Preconditions

Because the elements are added one by one, the following preconditions are tested for each individual addition.

Side Effects

If any elements were added, all cursors of this collection become undefined.

Exceptions

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
addUnion
public:
virtual void addUnion( IARelation < Element, Key > const&, IARelation < Element, Key > const& )
Creates the union of the two given collections, and adds this union to the collection. The contents of the added elements, not the pointers to those elements, are copied.

For a definition of the union of two collections, see IABag::unionWith.

Preconditions

Because the elements are added one by one, the following preconditions are tested for each individual addition.

Side Effects

If any elements were added, all cursors of this collection become undefined.

Exceptions

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Equality Operators

Compare IARelation objects.


[view class]
operator !=
public:
bool operator !=(IARelation < Element, Key > const&) const
Returns true if the given collection is not equal to the collection. For a definition of equality for collections, see ICursor::operator ==.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
operator ==
public:
bool operator ==(IARelation < Element, Key > const&) const
Returns true if the given collection is equal to the collection. Two collections are equal if the number of elements in each collection is the same, and if the condition for the collection is described in the following list:
Unique Elements
If the collections have unique elements, any element that occurs in one collection must occur in the other collection.
Non-Unique Elements
If an element has n occurrences in one collection, it must have exactly n occurrences in the other collection.
Sequential
The ordering of the elements is the same for both collections.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Logical Operations

Perform difference, intersection, and union operations on this IARelation object and another one, leaving the results in this object.


[view class]
differenceWith
public:
virtual void differenceWith( IARelation < Element, Key > const& )
Makes the collection the difference between the collection and the given collection. The difference of A and B (A minus B) is the set of elements that are contained in A but not in B.

The following rule applies for bags with duplicate elements: If bag P contains the element X m times and bag Q contains the element X n times, the difference of P and Q contains the element X m-n times if m > n, and zero times if m<=n.

Side Effects

If any elements were removed, all cursors of this collection become undefined.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
intersectionWith
public:
virtual void intersectionWith( IARelation < Element, Key > const& )
Makes the collection the intersection of the collection and the given collection. The intersection of A and B is the set of elements that is contained in both A and B.

The following rule applies for bags with duplicate elements: If bag P contains the element X m times and bag Q contains the element X n times, the intersection of P and Q contains the element X MIN(m,n): times.

Side Effects

If any elements were removed, all cursors of this collection become undefined.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
unionWith
public:
virtual void unionWith(IARelation < Element, Key > const&)
Makes the collection the union of the collection and the given collection. The union of A and B is the set of elements that are members of A or B or both.

The following rule applies for bags with duplicate elements: If bag P contains the element X m times and bag Q contains the element X n times, the union of P and Q contains the element X m+n times.

Preconditions

Because the elements from the given collection are added to the collection one by one, the following preconditions are tested for each individual add operation :

Side Effects

If any elements were added to the collection, all cursors of this collection become undefined.

Exceptions

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Remove Elements

Remove elements from the collection.


[view class]
removeAllOccurrences
protected:
INumber removeAllOccurrences(Element const&)
Removes all elements from the collection that are equal to the given element, and returns the number of elements removed. Element destructors are called as described in IACollection::removeAt.

Side Effects

If any elements were removed, all cursors of this collection become undefined.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Searching

Find elements in the collection that match a particular value.


[view class]
locateNext
protected:
bool locateNext(Element const&, ICursor&) const
Locates the next element in iteration order in the collection that is equal to the given element, starting at the element next to the one pointed to by the given cursor. Sets the cursor to point to the element in the collection. The cursor is invalidated if the end of the collection is reached and no more occurrences of the given element are left to be visited.


Note: If you code a call to IAEqualitySequence::locateFirst and a set of calls to IACollection::locateNext, each occurrence of an element will be visited exactly once in iteration order.

Precondition

The cursor must belong to the collection and must point to an element of the collection.

Return Value

Returns true if an element was found.

Exception

ICursorInvalidException

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
numberOfOccurrences
protected:
INumber numberOfOccurrences(Element const&) const
Returns the number of occurrences of the given element in the collection.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


IARelation - Inherited Member Functions and Data

Inherited Public Functions

IACollection
IAEqualityKeyCollection
IAKeyCollection

Inherited Public Data

Inherited Protected Functions

IACollectionBase
IACollection
IAEqualityKeyCollection
IAKeyCollection

Inherited Protected Data