This file contains information about the following subjects:
The add function places the element identified by its argument into the collection. It has two general properties:
Operations that contradict these properties are not valid. You cannot add an element to a map or sorted map that has the same key as an element that is already contained in the collection, but is not equal to this element (as a whole). In the case of a map and sorted map, an exception is thrown. Note that both map and sorted map are unique collections. The functions locateOrAddElementWithKey and addOrReplaceElementWithKey specify what happens if you try to add an element to a collection that already contains an element with the same key.
The figure below shows the result of adding a series of four elements to a map, a relation, a key set, and a key bag. The elements are pairs of a character and an integer. The character in the pair is the key. An element equality relation, if defined, holds between two elements if both the character and the integer in each pair are equal. The first row shows what each collection looks like after the element <a,1> has been added to each collection. Each following row shows what the collections look like after the element in the leftmost column is added to each.
Behavior of add for Unique and Multiple Collections
| add | Map or sorted map | Relation or sorted relation | Key set or key sorted set | Key bag or key sorted bag |
| <a,1> | <a,1> | <a,1> | <a,1> | <a,1> |
| <b,1> | <a,1>, <b,1> | <a,1>, <b,1> | <a,1>, <b,1> | <a,1>, <b,1> |
| <a,1> | <a,1>, <b,1> | <a,1>, <b,1> | <a,1>, <b,1> | <a,1>, <b,1>, <a,1> |
| <a,2> | exception: Key Already Exists | <a,1>, <b,1>, <a,2> | <a,1>, <b,1> | <a,1>, <b,1>, <a,1>, <a,2> |
The add function behaves differently depending on the properties of the collection:
For sequential collections, elements can be added at a given position using add functions other than add, such as addAtPosition, addAsFirst, and addAsNext. Elements after and including the given position are shifted. Positions can be specified by a number, with 1 for the first element, by using the addAtPosition function. Positions can also be specified relative to another element by using the addAsNext or addAsPrevious functions, or relative to the collection as a whole by using the addAsFirst or addAsLast functions.
In the Collection Classes, you can remove an element that is pointed to by a given cursor by using the removeAt function. All other removal functions operate on the model of first generating a cursor that refers to the desired position and then removing the element to which the cursor refers. There is an important difference between element values and element occurrences. An element value may, for non-unique collections, occur more than once. The basic remove function always removes only one occurrence of an element.
For collections with key equality or element equality, removal functions remove one or all occurrences of a given key or element. These functions include remove, removeElementWithKey, removeAllOccurrences, and removeAllElementsWithKey. Ordered collections provide functions for removing an element at a given numbered position. Ordered collections also allow you to remove the first or last element of a collection using the removeFirst or removeLast functions.
After you have removed one element with the property, the entire collection would have to be searched for the next element with the property. Because all cursors of the collection become undefined when elements are removed, removing all elements with a given property from a collection cannot be done efficiently using cursors. If you want to remove all of the elements in a collection that have a given property, you should use the function removeAll and provide a predicate function as its argument. This predicate function has an element as argument and returns an IBoolean value. The IBoolean result tells whether the element will be removed.
Sometimes you may want to pass more information to the predicate function. You can use an additional argument of type void*. The pointer then can be used to access a structure containing further information.
It is possible to modify collections by replacing the value of an element occurrence. Adding and removing elements usually changes the internal structure of the collection. Replacing an element leaves the internal structure unchanged. If an element of a collection is replaced, the cursors in the collection do not become undefined.
For collections that are organized according to element properties, such as an ordering relation or a hash function, the replace function must not change this element property. For key collections, the new key must be equal to the key that is replaced. For non-key collections with element equality, the new element must be equal to the old element as defined by the element equality relation. The key or element value that must be preserved is called the positioning property of the element in the given collection type.
Sequential collections and heaps do not have a positioning property. Element values in sequences and heaps can be changed freely. Replacing element values involves copying the whole value. If only a small part of the element is to be changed, it is more efficient to use the elementAt access function . The replaceAt function checks whether the replacing element has the same positioning property as the replaced element. (See for more details on preconditions.) When you use the elementAt function to replace part of the element value, this check is not performed. If you want to ensure safe replacement (a replacement that does not change the positioning property), use replaceAt rather than elementAt.
Introduction to the
Collection Classes
Collection Class
Hierarchy
Overall
Implementation Structure
Element
Functions and Key-Type Functions
Collection Class
Polymorphism
Collection
Characteristics
Ordering of
Collection Elements
Access by Key
Equality
Relation
Uniqueness
of Entries
Flat Collections
Trees
Support for
Notifications
Adding an
Element to a Collection
Removing an
Element from a Collection
Using
allElementsDo and Applicators to Iterate Over a Collection
Using Cursors to
Locate and Access Elements
Taking
Advantage of the Abstract Class Hierarchy
Instantiating
the Collection Classes
