IARestrictedAccessCollection
- Because Restricted Access Collection is an abstract class, it cannot be used to create any objects.
Restricted Access Collection defines the interfaces for the restricted access collections stack, queue,
and deque.
IARestrictedAccessCollection - Member Functions and Data by Group
Constructors & Destructor
You can construct and destruct objects of this class.
- ~IARestrictedAccessCollection
public:
virtual ~IARestrictedAccessCollection()
- Destroy the restricted access collection.
- Supported Platforms
Windows |
OS/2 |
AIX |
Yes |
Yes |
Yes |
- IARestrictedAccessCollection
- Construct and destruct restricted access collection objects.
Overload 1
public:
IARestrictedAccessCollection(INotifier&)
- Use this constructor to create a collection with support for notification.
- Supported Platforms
Windows |
OS/2 |
AIX |
Yes |
Yes |
Yes |
Overload 2
protected:
IARestrictedAccessCollection( IARestrictedAccessCollection < Element > const& )
- Copy constructor, which is hidden
- Supported Platforms
Windows |
OS/2 |
AIX |
Yes |
Yes |
Yes |
Overload 3
protected:
IARestrictedAccessCollection()
- The default constructor. It is hidden.
- Supported Platforms
Windows |
OS/2 |
AIX |
Yes |
Yes |
Yes |
Add or Remove Elements
Use these methods to add elements to the collection.
- add
- If the collection is unique (with respect to elements or keys) and the element or key is already contained in the collection,
sets the cursor to the existing element in the collection without adding the element. Otherwise, it adds the element to the collection
and sets the cursor to the added element. In sequential collections, the given element is added as the last element. In sorted collections,
the element is added at a position determined by the element or key value. Adding an element will either use the element's copy constructor
or the assignment operator provided for the element type, depending on the implementation variant you choose. See
IAEqualityCollection::contains for the definition of element or key
containment.
Preconditions
- The cursor must belong to the collection.
- If the collection is bounded and unique, the element or key must exist or (numberOfElements() < maxNumberOfElements()).
- If the collection is bounded and nonunique, (numberOfElements() < maxNumberOfElements()).
- If the collection is a map or a sorted map and contains an element with the same key as the given element, this element must be
equal to the given element.
Side Effects
- If an element was added, all cursors of this collection, except the given cursor, become undefined.
- If an element was added, collection classes supporting Visual Builder send an addedId notification.
Return Value
Returns true if the element was added.
Exceptions
- IOutOfMemory
- ICursorInvalidException
- IFullException, if the collection is bounded
- IKeyAlreadyExistsException, if the collection is a map or a sorted map
Overload 1
public:
virtual bool add(Element const&, ICursor&)
- Supported Platforms
Windows |
OS/2 |
AIX |
Yes |
Yes |
Yes |
Overload 2
public:
virtual bool add(Element const&)
- Supported Platforms
Windows |
OS/2 |
AIX |
Yes |
Yes |
Yes |
- addAllFrom
public:
virtual void
addAllFrom( IARestrictedAccessCollection < Element > const& )
- Adds (copies) all elements of the given collection to the collection. The elements are added in the iteration order of the given collection.
The contents of the elements, not the pointers to the elements, are copied. The elements are added according to the definition of add
for this collection. The given collection is not changed.
Preconditions
Because the elements are added one by one, the following preconditions are tested for each individual add operation:
- If the collection is bounded and unique, the element or key must exist or (numberOfElements() < maxNumberOfElements()).
- If the collection is bounded and nonunique, (numberOfElements() < maxNumberOfElements()).
- If the collection is a map or a sorted map and contains an element with the same key as the given element, this element must be
equal to the given element.
Side Effects
If any elements were added, all cursors of this collection become undefined.
Exceptions
- IOutOfMemory
- IIdenticalCollectionException
- IFullException, if the collection is bounded
- IKeyAlreadyExistsException, if the collection is a map or a sorted map
- Supported Platforms
Windows |
OS/2 |
AIX |
Yes |
Yes |
Yes |
- removeAll
public:
virtual INumber removeAll()
- Removes all elements from the collection. Element destructors are called as described in
IACollection::removeAt.
Side Effects
All cursors of this collection become undefined.
- Supported Platforms
Windows |
OS/2 |
AIX |
Yes |
Yes |
Yes |
Collection Status
These methods return status information about the collection.
- isBounded
public:
bool isBounded() const
- Returns true if the collection is bounded.
- Supported Platforms
Windows |
OS/2 |
AIX |
Yes |
Yes |
Yes |
- isConsistent
public:
bool isConsistent() const
- For internal use only.
- Supported Platforms
Windows |
OS/2 |
AIX |
Yes |
Yes |
Yes |
- isEmpty
public:
bool isEmpty() const
- Returns true if the collection is empty.
- Supported Platforms
Windows |
OS/2 |
AIX |
Yes |
Yes |
Yes |
- isFull
public:
bool isFull() const
- Returns true if the collection is bounded and contains the maximum number of elements;
that is, if (numberOfElements() == maxNumberOfElements()).
- Supported Platforms
Windows |
OS/2 |
AIX |
Yes |
Yes |
Yes |
- maxNumberOfElements
public:
INumber maxNumberOfElements() const
- Returns the maximum number of elements the collection can contain.
Precondition
The collection is bounded.
Exceptions
INotBoundedException
- Supported Platforms
Windows |
OS/2 |
AIX |
Yes |
Yes |
Yes |
- numberOfElements
public:
INumber numberOfElements() const
- Returns the number of elements in the collection.
- Supported Platforms
Windows |
OS/2 |
AIX |
Yes |
Yes |
Yes |
Copy Elements
Use these methods to copy elements from another collection.
- copy
public:
virtual void
copy( IARestrictedAccessCollection < Element > const& )
- Copies the given collection to this collection. copy() removes all elements from this collection, and adds the
elements from the given collection. For information on how adding is done, see IACollection::addAllFrom.
Note: The given collection may be of a concrete type other than the collection itself. In this case, copying implicitly performs
a conversion. If, for example, the given collection is a bag and the collection itself is a set, elements with multiple occurrences
in the copied bag will only occur once in the resulting set.
Preconditions
Because the elements are copied one by one, the following preconditions are tested for each individual copy operation:
- If the collection is bounded and unique, the element or key must exist or (numberOfElements() < maxNumberOfElements()).
- If the collection is bounded and nonunique, (numberOfElements() < maxNumberOfElements()).
- If the collection is a map or a sorted map and contains an element with the same key as the given element, this element must
be equal to the given element.
Side Effects
All cursors of this collection become undefined.
Exceptions
- IOutOfMemory
- IFullException, if the collection is bounded
- IKeyAlreadyException, if the collection has unique keys. This exception may be thrown, for example, when copying a bag into
a map.
- Supported Platforms
Windows |
OS/2 |
AIX |
Yes |
Yes |
Yes |
Cursor Support
Use these methods to point cursors at particular elements or to create new cursors for the collection.
- newCursor
public:
virtual ICursor* newCursor() const
- Creates a cursor for the collection and returns a pointer to the cursor. The cursor is initially not valid.
Exception
IOutOfMemory
- Supported Platforms
Windows |
OS/2 |
AIX |
Yes |
Yes |
Yes |
- position
public:
IPosition position(ICursor const&) const
- Provides the same functionality as positionAt().
- Supported Platforms
Windows |
OS/2 |
AIX |
Yes |
Yes |
Yes |
- positionAt
public:
IPosition positionAt(ICursor const&) const
- Determines the position of the current element. position 1 specifies the position of the first element.
Preconditions
The cursor must belong to the collection, and the cursor must point to an element of the collection.
Exceptions
- Supported Platforms
Windows |
OS/2 |
AIX |
Yes |
Yes |
Yes |
- setToFirst
public:
bool setToFirst(ICursor&) const
- Sets the cursor to the first element of the collection in iteration order. If the collection is empty (if no first element exists),
it invalidates the given cursor.
Precondition
The cursor must belong to the collection.
Return Value
Returns true if the collection is not empty.
Exception
ICursorInvalidException
- Supported Platforms
Windows |
OS/2 |
AIX |
Yes |
Yes |
Yes |
- setToLast
public:
bool setToLast(ICursor&) const
- Sets the cursor to the last element of the collection in iteration order. If the collection is empty (if no last element exists),
the given cursor is no longer valid.
Precondition
The cursor must belong to the collection.
Return Value
Returns true if the collection is not empty.
Exceptions
ICursorInvalidException
- Supported Platforms
Windows |
OS/2 |
AIX |
Yes |
Yes |
Yes |
- setToNext
public:
bool setToNext(ICursor&) const
- Sets the cursor to the next element in the collection in iteration order. If no more elements are left to be visited,
the given cursor will no longer be valid.
Precondition
The cursor must belong to the collection and must point to an element.
Return Value
Returns true if there is a next element.
Exceptions
ICursorInvalidException
- Supported Platforms
Windows |
OS/2 |
AIX |
Yes |
Yes |
Yes |
- setToPosition
public:
void setToPosition(IPosition, ICursor&) const
- Sets the cursor to the element at the given position. Position 1 specifies the first element.
Precondition
- The cursor must belong to the collection.
- Position must be a valid position in the collection; that is, (1 <= position <= numberOfElements()).
Exceptions
- ICursorInvalidException
- IPositionInvalidException
- Supported Platforms
Windows |
OS/2 |
AIX |
Yes |
Yes |
Yes |
- setToPrevious
public:
bool setToPrevious(ICursor&) const
- Sets the cursor to the previous element in iteration order, or invalidates the cursor if no such element exists.
Preconditions
The cursor must belong to the collection and must point to an element of the collection.
Return Value
Returns true if a previous element exists.
Exception
ICursorInvalidException
- Supported Platforms
Windows |
OS/2 |
AIX |
Yes |
Yes |
Yes |
Do For All Elements
Use these methods to apply some access to all elements of the cursor.
- allElementsDo
- Calls the given function for all elements in the collection until the given function returns false.
The elements are visited in iteration order. Additional arguments can be passed to the given function using
additionalArgument. The additional argument defaults to zero if no additional argument is given.
Note:
- The given function must not remove elements from or add them to the collection. If you want to remove
elements, you can use the removeAll() function with a property argument. For further information see
removeAll.
- For the non-const version of allElementsDo(), the given function must not manipulate the
element in the collection in a way that changes the positioning property of the element.
Return Value
Returns true if the given function returns true for every element it is applied to.
Overload 1
public:
bool allElementsDo(IConstantApplicator < Element >&) const
- Supported Platforms
Windows |
OS/2 |
AIX |
Yes |
Yes |
Yes |
Overload 2
public:
bool
allElementsDo( IBoolean ( * applicatorFunction ) ( Element const&,
void * ) , void* additionalArgument = 0 ) const
- Supported Platforms
Windows |
OS/2 |
AIX |
Yes |
Yes |
Yes |
Element Access
Use these methods to access elements in the collection.
- any
public:
Element const& any() const
- Provides the same functionality as anyElement().
- Supported Platforms
Windows |
OS/2 |
AIX |
Yes |
Yes |
Yes |
- anyElement
public:
Element const& anyElement() const
- Returns a reference to an arbitrary element of the collection.
Precondition
The collection must not be empty.
Exception
IEmptyException
- Supported Platforms
Windows |
OS/2 |
AIX |
Yes |
Yes |
Yes |
- elementAt
public:
Element const& elementAt(ICursor const&) const
- Returns a reference to the element pointed to by the given cursor.
Note: For the version of IACollection::elementAtwithout
the const suffix, do not manipulate the element or the key of the element in the collection in a way
that changes the positioning property of the element.
Precondition
The cursor must belong to the collection and must point to an element of the collection.
Exception
ICursorInvalidException
- Supported Platforms
Windows |
OS/2 |
AIX |
Yes |
Yes |
Yes |
- elementAtPosition
public:
Element const& elementAtPosition(IPosition) const
- Returns a reference to the element at the given position in the collection.
Position 1 specifies the first element.
Position must be a valid position in the collection; that is, (1 <= position <= numberOfElements()).
Precondition
(1 <= position <= numberOfElements()).
Exception
IPositionInvalidException
- Supported Platforms
Windows |
OS/2 |
AIX |
Yes |
Yes |
Yes |
Element Position Testing
Use these methods to test whether elements are at particular positions.
- isFirst
public:
bool isFirst(ICursor const&) const
- Provides the same functionality as isFirstAt().
- Supported Platforms
Windows |
OS/2 |
AIX |
Yes |
Yes |
Yes |
- isFirstAt
public:
bool isFirstAt(ICursor const&) const
- Returns true if the given cursor points to the first element of the collection.
Preconditions
The cursor must belong to the collection and must point to an element of the collection.
Exception
ICursorInvalidException
- Supported Platforms
Windows |
OS/2 |
AIX |
Yes |
Yes |
Yes |
- isLast
public:
bool isLast(ICursor const&) const
- Provides the same functionality as isLastAt().
- Supported Platforms
Windows |
OS/2 |
AIX |
Yes |
Yes |
Yes |
- isLastAt
public:
bool isLastAt(ICursor const&) const
- Returns true if the given cursor points to the last element of the collection.
Preconditions
The cursor must belong to the collection and must point to an element of the collection.
Exception
ICursorInvalidException
- Supported Platforms
Windows |
OS/2 |
AIX |
Yes |
Yes |
Yes |
First and Last Element Access
Use these methods to access the first and last elements of the collection.
- first
public:
Element const& first() const
- Provides the same functionality as firstElement().
- Supported Platforms
Windows |
OS/2 |
AIX |
Yes |
Yes |
Yes |
- firstElement
public:
Element const& firstElement() const
- Returns a reference to the first element of the collection.
Precondition
The collection must not be empty.
Exception
IEmptyException
- Supported Platforms
Windows |
OS/2 |
AIX |
Yes |
Yes |
Yes |
- last
public:
Element const& last() const
- Provides the same functionality as lastElement().
- Supported Platforms
Windows |
OS/2 |
AIX |
Yes |
Yes |
Yes |
- lastElement
public:
Element const& lastElement() const
- Returns a reference to the last element of the collection.
Precondition
The collection must not be empty.
Exception
IEmptyException
- Supported Platforms
Windows |
OS/2 |
AIX |
Yes |
Yes |
Yes |
Notification Support
Use these methods to manage the notification capabilities of the collection.
- disableNotification
public:
INotifier& disableNotification()
- Stops the notifier from sending notifications to its observers.
- Supported Platforms
Windows |
OS/2 |
AIX |
Yes |
Yes |
Yes |
- enableNotification
public:
INotifier& enableNotification(bool = true)
- Starts the notifier sending notifications to its observers. This function can be overridden by derived classes to
perform customized notification that your application might need. For instance, one of your function methods may
require that a database be accessible before processing a retrieve function.
- Supported Platforms
Windows |
OS/2 |
AIX |
Yes |
Yes |
Yes |
- isEnabledForNotification
public:
bool isEnabledForNotification() const
- Returns true if a notifier can send notifications to its observers.
- Supported Platforms
Windows |
OS/2 |
AIX |
Yes |
Yes |
Yes |
- notifier
- Returns a reference to the notifier object.
Overload 1
public:
INotifier const& notifier() const
- Supported Platforms
Windows |
OS/2 |
AIX |
Yes |
Yes |
Yes |
Overload 2
public:
INotifier& notifier()
- Supported Platforms
Windows |
OS/2 |
AIX |
Yes |
Yes |
Yes |
- notifyObservers
public:
INotifier& notifyObservers(INotificationEvent const&)
- Notifies all observers in a notifier's list of observers. Each observer receives a
notification event containing the identity of the notifier, the notification ID, and any
optional data provided by the specific notifier object.
Note:
A public and a protected version of notifyObservers are provided for convenience.
The protected version does not require the caller to construct an INotificationEvent to
call it. In this case, the construction of the INotificationEvent occurs in the code of the
protected notifyObservers function.
- Supported Platforms
Windows |
OS/2 |
AIX |
Yes |
Yes |
Yes |
- operator INotifier &
public:
operator INotifier &() const
- Returns the notifier object for this collection.
- Supported Platforms
Windows |
OS/2 |
AIX |
Yes |
Yes |
Yes |
Streaming
Use these members to stream the collection to an IDataStream object.
- adoptStreamer
public:
void adoptStreamer(IACollectionStreamer*)
- Adopts a streamer object which will handle streaming the elements to and from a data stream.
- Supported Platforms
Windows |
OS/2 |
AIX |
Yes |
Yes |
Yes |
- operator <<=
public:
virtual void operator <<=(IDataStream&)
- Streams the stored elements in from the passed data stream into this collection. It uses the adopted
streamer object to do the element streaming work.
- Supported Platforms
Windows |
OS/2 |
AIX |
Yes |
Yes |
Yes |
- operator >>=
public:
virtual void operator >>=(IDataStream&)
- Streams the elements of this collection out to the passed data stream.
- Supported Platforms
Windows |
OS/2 |
AIX |
Yes |
Yes |
Yes |
Inherited Public Functions
Inherited Public Data
Inherited Protected Functions
- IACollectionBase
-
~IACollectionBase()
static ICursorImpl const& CrsrImplOf(ICursor const& cursor)
static ICursorImpl& CrsrImplOf(ICursor& cursor)
IACollectionBase(IACollectionBase const&)
IACollectionBase()
static ICursor* InterfaceFor(ICursorImpl* cursor)
- IARestrictedAccessCollection
-
Inherited Protected Data