NAME

OTC_List - A collection class based on a list.

SYNOPSIS


#include <OTC/collctn/list.hh>

template<class T>
class OTC_List
{
  public:
    static os_typespec* get_os_typespec();
    typedef OTC_Modifier<T> type1;
    type1 dummy1();
    inline ~OTC_List();
    inline OTC_List();
    OTC_List(OTC_List<T> const& theList);
    OTC_List(OTC_List<T>& theList, OTC_ShallowCopy);
    OTC_List<T>& operator=(OTC_List<T> const& theList);
    inline u_int population() const;
    inline OTC_Boolean isEmpty() const;
    inline void addFirst(T const& theItem);
    inline void addLast(T const& theItem);
    inline void addBeforeItem(T const& theItem, u_int theIndex);
    inline T& first();
    inline T const& first() const;
    inline T& last();
    inline T const& last() const;
    inline T& item(u_int theIndex);
    inline T const& item(u_int theIndex) const;
    inline void removeAll();
    inline void removeFirst();
    inline void removeLast();
    inline void removeItem(u_int theIndex);
    inline void removeRange(u_int theStart, u_int theLength);
    inline void removeRange(OTC_Range theRange);
    inline OTC_Iterator<T> items(
      OTC_Direction theDirection=OTCLIB_FORWARD,
      OTC_Protection theProtection=OTCLIB_SAFE
    ) const;
    inline OTC_Modifier<T> items(
      OTC_Direction theDirection=OTCLIB_FORWARD,
      OTC_Protection theProtection=OTCLIB_SAFE
    );
    inline OTC_Iterator<T> items(
      OTC_Range const& theRange,
      OTC_Direction theDirection=OTCLIB_FORWARD,
      OTC_Protection theProtection=OTCLIB_SAFE
    ) const;
    inline OTC_Modifier<T> items(
      OTC_Range const& theRange,
      OTC_Direction theDirection=OTCLIB_FORWARD,
      OTC_Protection theProtection=OTCLIB_SAFE
    );
    inline OTC_Iterator<T> items(
      u_int theStart,
      u_int theLength,
      OTC_Direction theDirection=OTCLIB_FORWARD,
      OTC_Protection theProtection=OTCLIB_SAFE
    ) const;
    inline OTC_Modifier<T> items(
      u_int theStart,
      u_int theLength,
      OTC_Direction theDirection=OTCLIB_FORWARD,
      OTC_Protection theProtection=OTCLIB_SAFE
    );
  protected:
    OTC_Cursor<T>* _items(
      OTC_Direction theDirection,
      OTC_Protection theProtection
    ) const;
    OTC_Cursor<T>* _items(
      int theStart,
      u_int theLength,
      OTC_Direction theDirection=OTCLIB_FORWARD,
      OTC_Protection theProtection=OTCLIB_SAFE
    ) const;
    OTC_Link* _link(T const& theItem);
};

CLASS TYPE

Concrete

DESCRIPTION

Class implementing a list of objects. Objects can be accessed at the ends of the list, or by their location in the list. Location indexes start at 0.

INITIALISATION

inline OTC_List();
OTC_List(OTC_List<T> const& theList);
OTC_List(OTC_List<T>& theList, OTC_ShallowCopy);

ASSIGNMENT

OTC_List<T>& operator=(OTC_List<T> const& theList);

QUERY

inline u_int population() const;
inline OTC_Boolean isEmpty() const;

ADDITION

inline void addFirst(T const& theItem);
inline void addLast(T const& theItem);
inline void addBeforeItem(T const& theItem, u_int theIndex);

ACCESS

inline T& first();
inline T const& first() const;
inline T& last();
inline T const& last() const;
inline T& item(u_int theIndex);
inline T const& item(u_int theIndex) const;

REMOVAL

inline void removeAll();
inline void removeFirst();
inline void removeLast();
inline void removeItem(u_int theIndex);
inline void removeRange(u_int theStart, u_int theLength);
inline void removeRange(OTC_Range theRange);

ITERATION

By default, iterators will perform reference counts on the buckets in the collection as the iterator moves over the items. Performing the reference counts ensures that the iterator is not corrupted by additions or removals to the collection. If an unsafe iterator is required, for example, to avoid grabbing a write lock when using ObjectStore, a second argument can be passed to the following functions. The value of this argument is either OTCLIB_SAFE or OTCLIB_UNSAFE. To get an unsafe iterator, the OTCLIB_UNSAFE argument should be used. The first argument to the following functions indicates the direction of traversal of the iterator. Traversal in the direction of first to last item is indicated by a value of OTCLIB_FORWARD. Traversal in the reverse direction is indicated by a value of OTCLIB_BACKWARD. The default value is OTCLIB_FORWARD.
inline OTC_Iterator<T> items(
  OTC_Direction theDirection=OTCLIB_FORWARD,
  OTC_Protection theProtection=OTCLIB_SAFE
) const;
inline OTC_Modifier<T> items(
  OTC_Direction theDirection=OTCLIB_FORWARD,
  OTC_Protection theProtection=OTCLIB_SAFE
);
inline OTC_Iterator<T> items(
  OTC_Range const& theRange,
  OTC_Direction theDirection=OTCLIB_FORWARD,
  OTC_Protection theProtection=OTCLIB_SAFE
) const;
inline OTC_Modifier<T> items(
  OTC_Range const& theRange,
  OTC_Direction theDirection=OTCLIB_FORWARD,
  OTC_Protection theProtection=OTCLIB_SAFE
);
inline OTC_Iterator<T> items(
  u_int theStart,
  u_int theLength,
  OTC_Direction theDirection=OTCLIB_FORWARD,
  OTC_Protection theProtection=OTCLIB_SAFE
) const;
inline OTC_Modifier<T> items(
  u_int theStart,
  u_int theLength,
  OTC_Direction theDirection=OTCLIB_FORWARD,
  OTC_Protection theProtection=OTCLIB_SAFE
);

NOTES

Indexes are not an inherent part of the list structure, but are implemented by a height balanced AVL tree. This means that the space consumed by the list is twice that of a list which doesn't allow access by indexes. Thus, if access is not required by index it is suggested that OTC_Deque be used instead. The OTC_Bucket class is used internally to hold items in the list. Thus the OTC_BaseActions class may be used to provide actions to be performed, when items are inserted or removed from the list. Common functionality for lists holding items of any type, is factored out into the OTC_BList base class. The base class should be consulted as to additional functions which are available.

SEE ALSO

OTC_Iterator, OTC_Modifier, OTC_Bucket, OTC_BaseActions, OTC_BList

LIBRARY

OTC

AUTHOR(S)

Graham Dumpleton

COPYRIGHT

Copyright 1991 1992 1993 OTC LIMITED
Copyright 1994 DUMPLETON SOFTWARE CONSULTING PTY LIMITED