2.4 List

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.