Main Page   Class Hierarchy   Alphabetical List   Compound List   Compound Members  

util::List< T > Class Template Reference

#include <List.h>

Inheritance diagram for util::List< T >:

util::Iterator< T > util::Object util::Fifo< T > util::Heap< T, comparator > util::SortedList< T, comparator > util::Stack< T > List of all members.

Detailed Description

template<class T>
class util::List< T >

List is the default implementation of a growing list that allocates new memory as needed.

The method implementations provide direct access to the internal array of the list.


Public Methods

 List (int initialSlots=16, int blockSize=16)
 Constructs a new list with the given initial capacity and block size.

 List (const List &other)
 Create a copy of a list.

template<class U>  List (const List< U > &other)
 Create a typecasted copy of a list.

 List (T *data, int len, bool release=false)
 Initialize a list with the given data.

virtual ~List ()
 Release all resources.

virtual void addElement (const T &element)
 Add an element to the end of the list.

virtual void removeElement (const T &element)
 Remove the given element from the list.

virtual void addElements (const List &other)
 Add all elements in a list to this list.

void addElements (int count,...)
 A template specialization for string lists.

virtual void removeElements (const List &other)
 Remove all elements in a list from this list.

virtual int indexOf (const T &element) const
 Find the index of the given element.

virtual bool contains (const T &element) const
 Returns indexOf(element) != -1.

virtual void insertElementAt (const T &element, int index)
 Insert an element in the middle of the list.

virtual T removeElementAt (int index)
 Remove an element at the given index.

virtual T & elementAt (int index)
 Get a reference to the object at the given index.

virtual const T & elementAt (int index) const
 Get a reference to the object at the given index.

virtual T getElementAt (int index) const
 Get the object at the given index.

void setElementAt (const T &element, int index)
 Set the element at a given index.

void clear (void)
 Make the list empty and resize the internal array to its original size.

int getLength (void) const
 Get the current number of stored entries in the list.

const T * getData (void) const
 Get a pointer to the first item of the internal data array.

T * getData (void)
 Get a pointer to the first item of the internal data array.

T * releaseData (void)
 Take the ownership of the internal element array.

void setLength (int length)
 Set the length of this vector to 'length'.

void setLength (int length, T value)
 Set the length of this vector to length.

void setCapacity (int size)
 Set the maximum number of items this list will be able to hold without allocating new memory.

void fix (void)
 Set the capacity of this list to the current number of etries so that no unnecessary memory is allocated.

int getBlockSize (void) const
 Get the number of items this list expands each time its internal array becomes full.

int getCapacity (void) const
 Get the number of items this list will hold without expanding.

int getInitialSize (void) const
 Get the size this list was initialized with.

void add (const List &other)
 Add the values in other to the corresponding values in this list.

void subtract (const List &other)
 Subtract the values in other from the corresponding values in this list.

void multiply (const List &other)
 Multiply the values in other from the corresponding values in this list.

void divide (const List &other)
 Divide the values in other from the corresponding values in this list.

List getSublist (int startIndex, int length=MAXINT) const
 Get a sub-list from this list.

List & operator= (const List &other)
 Create a copy of a list.

template<class U> List & operator= (const List< U > &other)
 Create a typecasted copy of a list.

List & operator= (const T &value)
 Make all entries in a list equal to value.

void operator *= (const T &value)
 Multiply each value in the list by value.

void operator/= (const T &value)
 Divide each value in the list by value.

void operator+= (const T &element)
 Add an element to the list.

void operator-= (const T &element)
 Remove an element from the list.

void operator+= (const List &other)
 Add elements to the list.

void operator-= (const List &other)
 Remove elements from the list.

List operator() (int startIndex, int length=MAXINT) const
 Get a sub-list.

template<class U>  operator List ()
 Return a list with all elements cast to a new type.

const T & operator[] (int index) const
 Return the list element at the given index.

T & operator[] (int index)
 Return the list element at the given index.

void reset (void)
 Reset the internal iterator.

T * next (void)
 Get the next item in the array.

bool hasNext (void) const
 Check if the list has more data to be fetched.

std::string toString () const
 Convert a list to a string.

Objectclone () const throw (NotCloneableException&)
 Clone a list.


Protected Methods

template<class U> void copy (const List< U > &other)
void enlargeArray (void)
 Enlarge the internal array by blockSize.

void enlargeArray (int newSize)
 Define a new size for the internal array.


Protected Attributes

T * _internalArray
 The contents of the list.

int _iSize
int _iInitialSize
int _iBlockSize
int _iCurrentItems

Friends

template<class U> bool operator== (const List< U > &lst1, const List< U > &lst2)
 Compare two lists.

template<class U> std::ostream & operator<< (std::ostream &sout, const List< U > &lst)
 Write a list into a stream in XML format.

template<class U> std::istream & operator>> (std::istream &sin, List< U > &lst)
 Read an XML-formatted list from an input stream.


Constructor & Destructor Documentation

template<class T>
util::List< T >::List int    initialSlots = 16,
int    blockSize = 16
 

Constructs a new list with the given initial capacity and block size.

Parameters:
initialSlots  the number of items that can the list can initially hold without expanding
blockSize  the number of slots the list will expand each time its capacity is exceeded

template<class T>
template<class U>
util::List< T >::List const List< U > &    other
 

Create a typecasted copy of a list.

The iterator of the typecasted copy is reset to 0.

template<class T>
util::List< T >::List T *    data,
int    len,
bool    release = false
 

Initialize a list with the given data.

If the release flag is true, the memory pointed by data is used as the internal storage and deleted upon the destruction of the list. If the release flag is true, one cannot rely on the data pointer any more as it might change when adding new elements to the list. If the release flag is false, the data is copied.

Parameters:
data  a pointer to the data to be used as an internal array or to be copied.
len  the number of entries in data
release  if true, list will take the ownership of the pointer.


Member Function Documentation

template<class T>
void util::List< T >::add const List< T > &    other
 

Add the values in other to the corresponding values in this list.

List lengths must be equal to each other. Operator += must be defined for the content type.

Parameters:
other  the list whose contents are to be added to the corresponding items in this list

template<class T>
void util::List< T >::addElement const T &    element [virtual]
 

Add an element to the end of the list.

Parameters:
element  the element to be added

Reimplemented in util::Fifo< T >, util::Heap< T, comparator >, and util::SortedList< T, comparator >.

void util::List<>::addElements int    count,
...   
 

A template specialization for string lists.

An example:

 List<int> lst;
 lst.addElements(5,1,2,3,4,5);
 

This method calls addElement(const T&) for each element encountered. If the count or the type of the elements is not correct, the behavior is undefined.

Note that only elementary types can be used with this method. Complex types (except for strings) cause a compile-time error. For strings, there is a template specialization that takes const char* parameters.

Warning! Take extreme care to ensure that the elements you give in the parameter list are of correct type. Make sure that the compiler understands what you mean. Examples:

 List<float> lst;
 lst.addElements(3,1,2,3);          //WRONG! values are passed as ints
 lst.addElements(3,1.0,2.0,3.0);    //WRONG! values are passed as doubles
 lst.addElements(3,1.0f,2.0f,3.0f); //correct
 
Parameters:
count  the number of elements to add
...  the elements to add, all of type T

template<class T>
void util::List< T >::addElements const List< T > &    other [virtual]
 

Add all elements in a list to this list.

This method goes through the list and calls addElement(element) for each list item.

Parameters:
other  a list of elements to be added to this list

template<class T>
void util::List< T >::divide const List< T > &    other
 

Divide the values in other from the corresponding values in this list.

List lengths must be equal to each other. Operator /= must be defined for the content type.

Parameters:
other  the list whose contents are to be divided from the corresponding items in this list

template<class T>
void util::List< T >::enlargeArray int    newSize [protected]
 

Define a new size for the internal array.

Depending on the new value, memory will be either released or allocated.

template<class T>
List< T > util::List< T >::getSublist int    startIndex,
int    length = MAXINT
const
 

Get a sub-list from this list.

The returned list will include length (or as many as possible) items from this list starting at startIndex. If startIndex is negative, it is treated relative to the end of the list. Thus, -1 refers to the last list item. If length is negative, it is treated as a negative offset from the end of the list. Therefore, getSublist(-3,-2) will return the two items next to the last one.

Parameters:
startIndex  the start of the sub-list
length  the length of the sub-list

template<class T>
bool util::List< T >::hasNext void    const [inline, virtual]
 

Check if the list has more data to be fetched.

Returns:
true iff there is still some data to be read

Implements util::Iterator< T >.

template<class T>
int util::List< T >::indexOf const T &    element const [virtual]
 

Find the index of the given element.

Parameters:
element  the element to be found
Returns:
the index of the element, or -1 if it was not found

Reimplemented in util::SortedList< T, comparator >.

template<class T>
void util::List< T >::insertElementAt const T &    element,
int    index
[virtual]
 

Insert an element in the middle of the list.

All elements at or after the given index are shifted to right.

Parameters:
element  the element to be inserted
index  the index of the element

template<class T>
void util::List< T >::multiply const List< T > &    other
 

Multiply the values in other from the corresponding values in this list.

List lengths must be equal to each other. Operator *= must be defined for the content type.

Parameters:
other  the list whose contents are to be multiplyed from the corresponding items in this list

template<class T>
T* util::List< T >::next void    [inline, virtual]
 

Get the next item in the array.

Successive calls to next return the contents of the list from index zero up to the length of the array.

Returns:
a pointer to the next data in the list

Implements util::Iterator< T >.

template<class T>
List util::List< T >::operator() int    startIndex,
int    length = MAXINT
const [inline]
 

Get a sub-list.

Calls getSublist(startIndex,length).

Parameters:
startIndex  the starting index of the sub-list, inclusive
length  the number of items to copy

template<class T>
void util::List< T >::operator+= const List< T > &    other [inline]
 

Add elements to the list.

Calls addElements(element).

template<class T>
void util::List< T >::operator+= const T &    element [inline]
 

Add an element to the list.

Calls addElement(element).

template<class T>
void util::List< T >::operator-= const List< T > &    other [inline]
 

Remove elements from the list.

Calls removeElements(element).

template<class T>
void util::List< T >::operator-= const T &    element [inline]
 

Remove an element from the list.

Calls removeElement(element).

template<class T>
template<class U>
List< T > & util::List< T >::operator= const List< U > &    other
 

Create a typecasted copy of a list.

The iterator of the typecasted copy is reset to 0.

template<class T>
T& util::List< T >::operator[] int    index [inline]
 

Return the list element at the given index.

Note that no bound checking is performed. One must ensure that the list is large enough so that memory outside the internal buffer is not referenced.

See also:
setLength(int) , getElementAt(int)

Reimplemented in util::Fifo< T >.

template<class T>
const T& util::List< T >::operator[] int    index const [inline]
 

Return the list element at the given index.

Note that no bound checking is performed. One must ensure that the list is large enough so that memory outside the internal buffer is not referenced.

See also:
setLength(int) , getElementAt(int)

Reimplemented in util::Fifo< T >.

template<class T>
T* util::List< T >::releaseData void    [inline]
 

Take the ownership of the internal element array.

When calling this method, the length of the list will be set to zero, and the pointer to the internal data to NULL. A pointer to the internal data array is returned, and it must be deleted by the caller (with delete[]).

template<class T>
void util::List< T >::removeElement const T &    element [virtual]
 

Remove the given element from the list.

This method calls the indexOf(element) method to obtain the element's index in the list and then removes it by calling removeElementAt(index).

Parameters:
element  the element to be removed

template<class T>
T util::List< T >::removeElementAt int    index [virtual]
 

Remove an element at the given index.

The elements following the removed one are shifted to left.

Parameters:
index  the element's index
Returns:
the removed element

Reimplemented in util::Heap< T, comparator >.

template<class T>
void util::List< T >::removeElements const List< T > &    other [virtual]
 

Remove all elements in a list from this list.

This method goes through the list and calls removeElement(element) for each list item.

Parameters:
other  a list of elements to be removed from this list

template<class T>
void util::List< T >::reset void    [inline, virtual]
 

Reset the internal iterator.

After reset(), the next call to next() returns a pointer to the first item in the list.

Implements util::Iterator< T >.

template<class T>
void util::List< T >::setCapacity int    size
 

Set the maximum number of items this list will be able to hold without allocating new memory.

If 'size' is smaller than the current length of the list, the capacity will be set to the current length.

Parameters:
size  the new capacity.

template<class T>
void util::List< T >::setLength int    length,
  value
 

Set the length of this vector to length.

Fill newly allocated entries (if any) with value.

Parameters:
length  the new length
value  value for new entries

template<class T>
void util::List< T >::setLength int    length
 

Set the length of this vector to 'length'.

If the new length is smaller than the current one, the list will be truncated. If the new length is larger than the current one, the list will grow, but the new entries will be in undefined state. For class types the state will be that defined by its default constructor.

Parameters:
length  the new length

template<class T>
void util::List< T >::subtract const List< T > &    other
 

Subtract the values in other from the corresponding values in this list.

List lengths must be equal to each other. Operator -= must be defined for the content type.

Parameters:
other  the list whose contents are to be subtracted from the corresponding items in this list


Friends And Related Function Documentation

template<class T>
template<class U>
std::istream& operator>> std::istream &    sin,
List< U > &    lst
[friend]
 

Read an XML-formatted list from an input stream.

Exceptions:
IOException  & on an input error
XMLException  & on an XML format error


The documentation for this class was generated from the following file:
Documentation generated on 11.09.2003 with Doxygen.
The documentation is copyrighted material.
Copyright © Topi Mäenpää 2003. All rights reserved.