IASortedMap

A sorted map is an ordered collection of zero or more elements that have a key. Element equality is supported and the values of the elements are relevant. Elements are sorted by the value of their keys.

Only elements with unique keys are supported. A request to add an element whose key already exists in another element of the collection causes an exception to be thrown. A request to add a duplicate element is ignored.


IASortedMap - Member Functions and Data by Group

Constructors & Destructor

Use these members to construct or destruct objects of the class.


[view class]
~IASortedMap
public:
~IASortedMap()

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]
IASortedMap


Overload 1
public:
IASortedMap(INotifier&)

Use this constructor to create a collection with support for notification.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
protected:
IASortedMap(IASortedMap < Element, Key > const&)

Constructs a collection. The collection is unbounded and is initially empty.
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

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
protected:
IASortedMap()

This is the default constructor.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Comparison

Use these members as comparison operators.


[view class]
compare
public:
long compare( IASortedMap < Element, Key > const&, long ( * comparisonFunction ) ( Element const & , Element const & ) ) const

Compares the collection with the given collection. Comparison yields <0 if the collection is less than the given collection, 0 if the collection is equal to the given collection, and >0 if the collection is greater than the given collection. Comparison is defined by the first pair of corresponding elements, in both collections, that are not equal. If such a pair exists, the collection with the greater element is the greater one. Otherwise, the collection with more elements is the greater one.
Note:

  1. The given comparison function must return a result according to the following rules:
    >0
    if (element1 > element2)
    0
    if (element1 == element2)
    <0
    if (element1 < element2)
  2. For elements of type char*, compare() is not locale-sensitive by default. Because it uses strcmp() and not strcoll(), it compares the binary values representing the characters, and is not based on the LC_COLLATE category of the current locale. Its results are reliable only for code pages and character sets in which the collating sequence matches the sequence of binary representations. If you need a comparison based on the LC_COLLATE cateogory, then you must implement your own compare() function as described in :Using Separate Functions in the Class Library User's Guide.

Return Value

Returns the result of the collection comparison.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Miscellaneous

Use these members to execute miscellaneous tasks.


[view class]
addDifference
public:
virtual void addDifference( IASortedMap < Element, Key > const&, IASortedMap < 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 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( IASortedMap < Element, Key > const&, IASortedMap < 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 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( IASortedMap < Element, Key > const&, IASortedMap < 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 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


[view class]
differenceWith
public:
virtual void differenceWith( IASortedMap < 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( IASortedMap < 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]
operator !=
public:
IBoolean operator !=( IASortedMap < Element, Key > const& ) const

Returns true if the cursor does not point to the same element (of the same collection) as the given cursor.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
operator ==
public:
IBoolean operator ==( IASortedMap < Element, Key > const& ) const

Returns true if the cursor points to the same element (of the same collection) as the given cursor.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
unionWith
public:
virtual void unionWith(IASortedMap < 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


[view class]
numberOfDifferentKeys
protected:
INumber numberOfDifferentKeys() const

Returns the number of different keys in the collection.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
numberOfElementsWithKey
protected:
INumber numberOfElementsWithKey(Key const&) const

Returns the number of elements in the collection with the given key.

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


[view class]
removeAllElementsWithKey
protected:
INumber removeAllElementsWithKey(Key const&)

Removes all elements from the collection with the same key as the given key. Element destructors are called as described in removeAt.

Side Effects

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

Return Value

The number of elements removed.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[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 removeAt.

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]
setToNextWithDifferentKey
protected:
IBoolean setToNextWithDifferentKey(ICursor&) const

Sets the cursor to the next element in the collection in iteration order with a key different from the key of the element pointed to by the given cursor. If no such element exists, the given cursor is no longer valid.

Preconditions

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

Return Value

Returns true if a subsequent element was found whose key is different from the current key.

Exception

ICursorInvalidException

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


IASortedMap - Inherited Member Functions and Data

Inherited Public Functions

IACollection
IAEqualityKeySortedCollection
IAOrderedCollection
IASortedCollection

Inherited Public Data

Inherited Protected Functions

IACollectionBase
IACollection
IAEqualityKeySortedCollection
IAOrderedCollection
IASortedCollection

Inherited Protected Data