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.


[view class]
~IARestrictedAccessCollection
public:
virtual ~IARestrictedAccessCollection()
Destroy the restricted access collection.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
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.


[view class]
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

Side Effects

Return Value

Returns true if the element was added.

Exceptions


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


[view class]
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:

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


[view class]
isBounded
public:
bool isBounded() const
Returns true if the collection is bounded.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
isConsistent
public:
bool isConsistent() const
For internal use only.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
isEmpty
public:
bool isEmpty() const
Returns true if the collection is empty.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
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


[view class]
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


[view class]
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.


[view class]
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:

Side Effects

All cursors of this collection become undefined.

Exceptions

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.


[view class]
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


[view class]
position
public:
IPosition position(ICursor const&) const
Provides the same functionality as positionAt().

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
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


[view class]
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


[view class]
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


[view class]
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


[view class]
setToPosition
public:
void setToPosition(IPosition, ICursor&) const
Sets the cursor to the element at the given position. Position 1 specifies the first element.

Precondition

Exceptions

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
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.


[view class]
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:

  1. 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.
  2. 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.


[view class]
any
public:
Element const& any() const
Provides the same functionality as anyElement().

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
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


[view class]
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


[view class]
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.


[view class]
isFirst
public:
bool isFirst(ICursor const&) const
Provides the same functionality as isFirstAt().

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
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


[view class]
isLast
public:
bool isLast(ICursor const&) const
Provides the same functionality as isLastAt().

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
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.


[view class]
first
public:
Element const& first() const
Provides the same functionality as firstElement().

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
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


[view class]
last
public:
Element const& last() const
Provides the same functionality as lastElement().

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
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.


[view class]
disableNotification
public:
INotifier& disableNotification()
Stops the notifier from sending notifications to its observers.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
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


[view class]
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


[view class]
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


[view class]
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


[view class]
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.


[view class]
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


[view class]
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


[view class]
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


IARestrictedAccessCollection - Inherited Member Functions and Data

Inherited Public Functions

Inherited Public Data

Inherited Protected Functions

IACollectionBase
IARestrictedAccessCollection

Inherited Protected Data