Adding elements

For nonkeyed collections, the TO2_add function places the element identified by its argument into the collection. For keyed collections, the TO2_atNewKeyPut function places the element identified by its key into the collection. See z/TPF C/C++ Language Support User's Guide for more information about the TO2_add and TO2_atNewKeyPut functions. For binary large objects (BLOBs), you can operate on elements using the TO2_atRBAPut function. In general, you can copy one collection to another collection that is initially empty by iterating through the elements of the first collection and calling TO2_add or TO2_atNewKeyPut with each element as an argument.

For sequence collections, elements can be added at a given position using TO2_addAtIndex.

Table 1 describes how the TO2_add and TO2_atNewKeyPut APIs function with unique and nonunique collections:

Table 1. Adding elements to a collection
Type of collection	Description
Unique collections without keys	The `TO2_add` function will not add an element that is equal to an element that is already in the collection.
Nonunique collections without keys	The `TO2_add` function adds elements regardless of whether they are equal to any existing elements.
Unique collections with keys	The `TO2_atNewKeyPut` function will not add a key that is equal to a key that is already in the collection.
Nonunique collections with keys	The `TO2_atNewKeyPut` function adds keys regardless of whether they are equal to any existing keys.