The List class is a templated container with auto resizing capabilities.
Synopsis
#include <lyric/List.hpp>
template <class LIT>
class List
{
public:
~List ();
List (Size initsize=0, Size resize=1)
List (const List& list)
throw (Exception::Memory::Alloc);
List& operator = (const List& list)
throw (Exception::Memory::Alloc);
LIT& operator [] (Size index)
throw (Exception::Memory::Range);
const LIT& operator [] (Size index) const
throw (Exception::Memory::Range);
Size size () const;
void create (Size initsize=0, Size resize=1)
throw (Exception::Memory::Alloc);
void clear ();
void clean ();
void append (const LIT& item)
throw (Exception::Memory::Alloc, Exception::List::Resize);
void append (const List& list)
throw (Exception::Memory::Alloc, Exception::List::Resize);
void insert (Size index, const LIT& item)
throw (Exception::Memory::Alloc, Exception::Memory::Range,
Exception::List::Resize);
void insert (Size index, const List& list)
void remove (Size index)
throw (Exception::Memory::Range);
void remove (Size index, Size size)
throw (Exception::Memory::Range);
bool member (const LIT& item);
Size index (const LIT& item)
throw (Exception::List::NotFound);
};
Description
-
˜List () -
Destroy this list, releasing eventually reserved memory. All stored items are
destroyed.
-
List (Size initsize = 0, Size resize = 1) -
Construct this list with a starting memory size initsize and a given resize factor.
This resizing factor is used to allocate memory when new items are added or
inserted. In some cases (the String class is such an example), a default resizing
factor of 1 item is not optimal. The resize argument can be set to a higher value
than 1 (the default) to speed up list handling. Indeed, every time this list
needs fresh space it ask the system for the current list size plus the needed
space. It then copies the current content to the new memory space, and
gives the old memory back to the system. This process, when repeated
many times, eats up considerable amount of computing resources. Thus
with a sensible resize argument the amount of allocate-copy-free memory
processes can be reduced. The price to pay is a coarser memory usage
granularity.
Normal lists contain no space for data at start, thus the default 0 initsize.
But for some lists (for example built from a fixed size data container)
a sensible initial memory requirement is known. A newly constructed
list will always show a size of 0. The initsize only specifies how much
memory is to be prefetched from the system resources to speed up list
initialisation.
-
Exception::Memory::Alloc
- is thrown if not enough memory is found for the
initial size.
-
List (const List& list) -
Construct this list from the given list. All properties and data are copied from the
given list into this list. Since this copy constructor copies all data from list into this
list the process can be slow. Indeed, in LYRIC not the data pointer is copied, but
the compelte data set.
-
Exception::Memory::Alloc
- is thrown if not enough memory is found to store
list in this list.
-
List& operator = (const List& list) -
Assign the rvalue list to this list. All properties and data are copied from the given
list into this list. A reference to this list is returned for assignment chaining
operations.
-
Exception::Memory::Alloc
- is thrown if not enough memory is found to store
list in this list.
-
LIT& operator [...] (Size index) -
Return a reference to the item stored at position index in this container. This
operator can be used as left or right hand value. This means one can as well read as
write an item in this container.
-
Exception::Memory::Range
- is thrown if the given index is out of this
container’s size, and only if the -DO_RANGE_CHECK is given to the
compiler, resp. if O_RANGE_CHECK is defined.
-
const LIT& operator [...] (Size index) const -
Return an immutable reference to the item stored at position index in this
container. This operator can only be used as right hand value. This means one can
only read an item from this container.
-
Exception::Memory::Range
- is thrown if the given index is out of this
container’s size, and only if the -DO_RANGE_CHECK is given to the
compiler, resp. if O_RANGE_CHECK is defined.
-
Size size () const -
Return the size of this list.
-
void create (Size initsize = 0, Size resize = 0) -
Create this list with the given initial size initsize, and the given resize. This
function has the same effect as the constructor taking the same arguments.
Warning This function is destructive. All previously stored items in this list
are deleted before the creation is executed.
-
Exception::Memory::Alloc
- is thrown if not enough memory is found for the
initial size.
-
void clear () - Set
the size of this list to zero. Eventually complex items stored in this list are
previously removed. This function is faster than List::clean since no actual
memory resizing is done. Further use of this list already has a memory chunk to
store new data in.
-
void clean () -
Clean this list. Eventually complex items stored in this list are deleted and the
internal data this list grabed from the system memory is returned to the system.
Finally the size of this list is set to zero. This function realy cleans this
list, but is slower than List::clear since memory is returned to the
system, which in an eventual reuse of this list must then be allocated
again.
-
void append (const LIT& item) -
Append the given item at the end of this list. The given item is cloned into a new
item created on the fly in this list.
-
Exception::Memory::Alloc
- is thrown if not enough memory is found to resize
this list to store the additional item.
-
Exception::List::Resize
- is thrown if this list was constructed with a resize
factor of 0, e.g. is un unresizeable list.
-
void append (const List& list) -
Append the given list at the end of this list. All items stored in list are cloned into
the new items created on the fly in this list.
-
Exception::Memory::Alloc
- is thrown if not enough memory is found to resize
this list to store the additional item.
-
Exception::List::Resize
- is thrown if this list was constructed with a resize
factor of 0, e.g. is un unresizeable list.
-
void insert (Size index, const LIT& item) -
Insert the given item at index in this list. If needed this list is first resized to store
the aditional item.
-
Exception::Memory::Alloc
- is thrown if not enough memory is found to resize
this list to store the additional item.
-
Exception::Memory::Range
- is thrown if the insertion index is not in the
range [0...this->size()].
-
Exception::List::Resize
- is thrown if this list was constructed with a resize
factor of 0, e.g. is un unresizeable list.
-
void insert (Size index, const List& list) -
Insert the given list at index in this list. If needed this list is first resized
to store the items stored in list. All items stored in list are cloned into
this.
-
Exception::Memory::Alloc
- is thrown if not enough memory is found to resize
this list to store the items of the list to be inserted.
-
Exception::Memory::Range
- is thrown if the insertion index is not in the
range [0...this->size()].
-
Exception::List::Resize
- is thrown if this list was constructed with a resize
factor of 0, e.g. is an unresizeable list.
-
void remove (Size index) -
Remove the item located at the given index from this list. The item at the given
location index is deleted if needed, and this list is shrinked to the new size, so that
all items in this list remain contiguous.
-
Exception::Memory::Range
- is thrown if the given index is not in the range
[0...this->size()[.
-
void remove (Size index, Size size) -
Remove size items starting at index from this list. The items to removed are
deleted if needed, and this list is shrinked to the new size, so that all items in this
list remain contiguous.
-
Exception::Memory::Range
- is thrown if index is not in the range
[0...this->size()[, or if index+size is not in the range [0...this->size()].
-
bool member (const LIT& item) -
Returns true if this list contains the given item, false if not.
-
Size index (const LIT& item) -
Returns the location of the given item in this list.
-
Exception::List::NotFound
- is thrown if the given item is not member of this
list.
-
const LIT& last () const -
Returns a reference to the last item in this list.
-
Exception::List::Emtpy
- is thrown if this list is empty and thus has no last
item.