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);
Creates a copy of theList.
OTC_List(OTC_List<T>& theList, OTC_ShallowCopy);
Creates a copy of theList.
ASSIGNMENT
OTC_List<T>& operator=(OTC_List<T> const& theList);
Replaces the contents of this list with
items contained in theList.
QUERY
inline u_int population() const;
Returns the number of items in the
list.
inline OTC_Boolean isEmpty() const;
Returns OTCLIB_TRUE if the the list
is empty.
ADDITION
inline void addFirst(T const& theItem);
Inserts theItem at the head of the list.
inline void addLast(T const& theItem);
Appends theItem to the tail of the list.
inline void addBeforeItem(T const& theItem, u_int theIndex);
Adds theItem into the list before
the item at location theIndex.
If theIndex is equal to the population
of the list, then theItem is added
at the end of the list. If theIndex
is greater than the population of the
list, an exception is raised.
ACCESS
inline T& first();
Returns a reference to the first item in
the list. If the list is empty, an
exception is raised.
inline T const& first() const;
Returns a reference to the first item in
the list. If the list is empty, an
exception is raised.
inline T& last();
Returns a reference to the last item in
the list. If the list is empty, an
exception is raised.
inline T const& last() const;
Returns a reference to the last item in
the list. If the list is empty, an
exception is raised.
inline T& item(u_int theIndex);
Returns a reference to the item in this
list at the location theIndex. If the
list is empty, or the index is outside the
bounds of the list, an exception is
raised.
inline T const& item(u_int theIndex) const;
Returns a reference to the item in this
list at the location theIndex. If the
list is empty, or the index is outside the
bounds of the list, an exception is
raised.
REMOVAL
inline void removeAll();
Removes all items from the list.
inline void removeFirst();
Removes the first item in the list. If
the list is empty, an exception is
raised.
inline void removeLast();
Removes the last item in the list. If
the list is empty, an exception is
raised.
inline void removeItem(u_int theIndex);
Removes the item at location theIndex.
Raises an exception if there is no item at
location theIndex.
inline void removeRange(u_int theStart, u_int theLength);
Removes theLength items starting at
location theStart.
inline void removeRange(OTC_Range theRange);
Removes theLength items starting at
location theStart.
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;
Returns an iterator over the list.
inline OTC_Modifier<T> items(
OTC_Direction theDirection=OTCLIB_FORWARD,
OTC_Protection theProtection=OTCLIB_SAFE
);
Returns an iterator over the list.
inline OTC_Iterator<T> items(
OTC_Range const& theRange,
OTC_Direction theDirection=OTCLIB_FORWARD,
OTC_Protection theProtection=OTCLIB_SAFE
) const;
Returns an iterator over a range of
items in the list.
inline OTC_Modifier<T> items(
OTC_Range const& theRange,
OTC_Direction theDirection=OTCLIB_FORWARD,
OTC_Protection theProtection=OTCLIB_SAFE
);
Returns an iterator over a range of
items in the list.
inline OTC_Iterator<T> items(
u_int theStart,
u_int theLength,
OTC_Direction theDirection=OTCLIB_FORWARD,
OTC_Protection theProtection=OTCLIB_SAFE
) const;
Returns an iterator over a range of
items in the list.
inline OTC_Modifier<T> items(
u_int theStart,
u_int theLength,
OTC_Direction theDirection=OTCLIB_FORWARD,
OTC_Protection theProtection=OTCLIB_SAFE
);
Returns an iterator over a range of
items in the list.
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