### 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:

  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.

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::elementAt without 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

### IARestrictedAccessCollection - Inherited Member Functions and Data

#### Inherited Public Functions

  - None

#### Inherited Public Data

  - None

#### 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

  -     static Implementation&
          ImplOf( IARestrictedAccessCollection < Element > const& )

#### Inherited Protected Data

  - None