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

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

Object * clone () const throw (NotCloneableException&)

Clone a list.

Protected Methods

template<class U> void copy (const List &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 &lst1, const List &lst2)

Compare two lists.

template<class U> std::ostream & operator<< (std::ostream &sout, const List &lst)

Write a list into a stream in XML format.

template<class U> std::istream & operator>> (std::istream &sin, List &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 & 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 & 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,

T 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 & 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:

List.h

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.
Object *	clone () 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.

util::List< T > Class Template Reference

Detailed Description

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

Public Methods

Protected Methods

Protected Attributes

Friends

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

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