HP Integrity NonStop J-Series - Manual (Page 161)

remove() Functions
To search for and remove particular items, you can use the functions remove() and
removeAndDestroy():
virtual RWCollectable* remove(const RWCollectable*);
virtual void removeAndDestroy(const RWCollectable*);
The function remove() looks for an item that is equal to its argument and removes it from the
collection, returning a pointer to it. It returns nil if no item is found.
The function removeAndDestroy() is similar except it deletes the item instead of returning it,
using the virtual destructor inherited by all
RWCollectable items. You must be careful when using
this function that the item was actually allocated off the heap, not the stack, and that it is not
shared with another collection. Also note that RWnilCollectable references a cached default
RWCollectable; be careful not to destroy it!
The following example, which expands on the previous one, demonstrates the use of the virtual
function removeAndDestroy():
RWCollectable* oust = sc.remove(&dummy); //17
delete oust; //18
sc.removeAndDestroy(&dummy); //19
//17 Removes the first occurrence of the string containing Mary and returns a pointer to it. This
pointer will be nil if there is no such item.
//18 Deletes the item, which was originally allocated off the heap. There is no need to check the
pointer against nil because the language guarantees that it is always OK to delete a nil
pointer.
//19 In this statement, the remaining occurrence of Mary is both removed and deleted.
apply() Functions
To efficiently examine the members of a Smalltalk-like collection, use the member function
apply():
virtual void apply(RWapplyCollectable ap, void* x);
The first argument, RWapplyCollectable, is a typedef:
typedef void (*RWapplyCollectable)(RWCollectable*, void*);
In other words, RWapplyCollectable is a pointer to a function with prototype:
void yourApplyFunction(RWCollectable* item, void* x)
where yourApplyFunction is the name of the function. You must supply this function. It will be
called for each item in the collection, in whatever order is appropriate for the collection, and
passed as a pointer to the item as its first argument. The second argument x is passed through from
the call to apply(), and is available for your use. For example, you could use it to hold a handle to