The PList Class

Derived from: None

Declared in: PList.h


Overview

This class can handle any number of items. The class is created as a template class, which means you can create a list of all kind of objects you like. When you construct the list, you tell the class what type of elements you want to store in the list.

In some of the functions, you can give an index as argument. If this index is out of range to the number of items in the list, a PBoundsException will be thrown.

The list is not thread safe as it is. If you have more than one thread to access the list, you can use any of the synchronize classes to do that.


Constructor and Destructor


PList()

          PList(int32 blockSize = 10);

The constructor will create an empty list ready to be used. The argument indicates how many items you want to be allocated when more memory is needed.


~PList()

          ~PList(void);

Remove all the items in the list and destroy it.


Member Functions


AddHead()

          void AddHead(TYPE item);

This function will insert the item in the front of the list.


AddTail()

          int32 AddTail(TYPE item);

This function will insert the item at the end of the list. It will return the position in the list the new item is inserted at.


CountItems()

          int32 CountItems(void) const;

This function will return the number of items in the list.


FindAndRemoveItem()

          int32 FindAndRemoveItem(TYPE item);
             throw(PBoundsException);

This function will search through the list to see if it can find the item you give. If it found the item, it will be removed and the index the item was found at will be returned. If it couldn't find the item, -1 will be returned. If more than one instance of the item are stored in the list, the first one found will be removed.


GetAndRemoveItem()

          TYPE GetAndRemoveItem(int32 index);
             throw(PBoundsException);

This function will remove the item at the index you give and return the item.


GetAndSetItem()

          TYPE GetAndSetItem(TYPE item, int32 index);
             throw(PBoundsException);

This function will not insert a new item in the list. It will change the item at the index you give. The index start with 0 and increments by one for each item. If will then return the old item at the index.


GetHead()

          TYPE GetHead(void) const;
             throw(PBoundsException);

This function will return the first item in the list. If the list is empty, a PBoundsException will be thrown.


GetItem()

          TYPE GetItem(int32 index) const;
             throw(PBoundsException);

This function will return the item at the index given.


GetItemIndex()

          int32 GetItemIndex(TYPE item, int32 startPos = 0) const;
             throw(PBoundsException);

If you want to check the list to see if it contains a special item, you can use this function. It will go through the list to see if the item you give is stored in the list. If it found it, it will return the index the item has, else it will return -1. You can also give a start position to start the search at.


GetTail()

          TYPE GetTail(void) const;
             throw(PBoundsException);

This function will return the last item in the list. If the list is empty, a PBoundsException will be thrown.


HasItem()

          bool HasItem(TYPE item, int32 startPos = 0) const;
             throw(PBoundsException);

If you want to check the list to see if it contains a special item, you can use this function. It will go through the list to see if the item you give is stored in the list. If it found it, it will return true, else it will return false. You can also give a start position to start the search at.


InsertItem()

          void InsertItem(TYPE item, int32 index);
             throw(PBoundsException);

This function will insert the item at the index given. The index start with 0 and increments by one for each item. Adding an item will never remove another item from the list. It will move the items to make room for the new one and insert it in the space.


InsertList()

          void InsertList(const PList<TYPE> &list, int32 index = -1);
             throw(PBoundsException);

Will copy the list given as the argument into the index of the current list. If the index is -1, the new list will be appended to the current list.


IsEmpty()

          bool IsEmpty(void) const;

This function will check the list to see if it's empty. If the list is empty, it will return true and it will return false if the list is not empty.


MakeEmpty()

          void MakeEmpty(void);

This function will remove all the items in the list.


RemoveItem()

          void RemoveItem(int32 index);
             throw(PBoundsException);

This function will remove the item at the index you give.


RemoveItems()

          void RemoveItems(int32 index, int32 count);
             throw(PBoundsException);

This function will remove any number of items from the list. The arguments are the start index and the number of items you want to remove. If you try to remove more items than stored in the list, it will only remove the items it can. By this, I mean it's safe to give a count bigger than the number of items in the list. After the items has been removed, the list will be compacted.


SetItem()

          void SetItem(TYPE item, int32 index);
             throw(PBoundsException);

This function will not insert a new item in the list. It will change the item at the index you give. The index start with 0 and increments by one for each item.


Operators


operator =

          const PList<TYPE> & operator = (const PList<TYPE> &list);

Clears the current list and add all the elements from the list given into the current list. As the result, you will get a copy of the argument list. Note that, if your list holds pointers to some elements, it's only the pointers that will be copied. That means, you now have two lists that points to the same elements.


The PolyKit developer documentation.
This documentation was written by Thomas Neumann.
© Copyright 1998-1999 by PolyCode.