PTypes: lists: tobjlist

Top: Basic types: Lists: tobjlist

>     template <class X> class tobjlist {
>         tobjlist(bool ownobjects = false);
>         ~tobjlist();

>         int   get/set_count(int);
>         int   get/set_capacity(int);
>         bool  get/set_ownobjects(bool);

>         void  ins(int index, X* obj);
>         void  add(X* obj);
>         X*    operator [](int index) const;
>         X*    top() const;
>         void  put(int index, X* obj);
>         void  del(int index);
>         X*    pop();

>         void  clear();
>         void  pack();

>         bool  search(const void* key, int& index) const;
>         virtual int compare(const void* key, const void* obj) const;
>     }

The tobjlist template implements a dynamic array of pointers to objects of an arbitrary type X. Since the list itself only holds pointers to objects, the element type can be any structure, including a class with constructors and destructors. The element type is not required to have a copy constructor. A list can contain objects of any derivative class of X as well.

Tobjlist can optionally (with ownobjects = true) be responsible for freeing objects whenever they are removed from a list, in which case the objects are required to be dynamically allocated with operator new. Objects can be automatically freed by the following methods: set_count() if the new value is less than the old one, also del(), clear(), put() and ~tobjlist().

tobjlist::tobjlist(bool ownobjects = false) constructs a tobjlist object. See note for the parameter ownobjects above.

tobjlist::~tobjlist() calls clear() and destroys the list object.

int tobjlist::get/set_count(int) gets or sets the number of items in a list. If the new value for count is greater than the old one, all new slots are filled with NULL pointers. If it's smaller and if ownobjects is true, extra objects are freed.

int tobjlist::get/set_capacity(int) gets or sets the capacity of a list. The capacity property reflects the number of slots actually allocated for a list and is set automatically by other methods whenever necessary. Like tpodlist, tobjlist uses a 'lazy allocation' technique (see also tpodlist::get/set_capacity).

bool tobjlist::get/set_ownobjects(bool) returns or sets the ownobjects flag.

void tobjlist::ins(int index, X* obj) inserts the object obj into a list at the position index. All pointers with greater indexes are moved up to make room for the new pointer.

void tobjlist::add(X* obj) adds the object obj to the end of a list.

X* tobjlist::operator [](int index) returns the pointer to an object at the position index.

X* tobjlist::top() returns the last pointer in a list.

void tobjlist::put(int index, X* obj) replaces the pointer at the position index with obj. Can free the old object if ownobjects is true.

void tobjlist::del(int index) deletes the pointer at the position index and moves all pointers with greater indexes down. Can also free the object if ownobjects is true.

X* tobjlist::pop() returns the last pointer in a list and deletes it from a list.

void tobjlist::clear() deletes all pointers from a list. Can also free all objects if ownobjects is true.

void tobjlist::pack() sets capacity equal to count. You can call pack() after deleting multiple pointers from a list to optimize memory usage.

bool tobjlist::search(const void* key, int& index) performs binary search on a list. The virtual method compare() (below) must be overridden in order for search() to work.

virtual int tobjlist::compare(const void* key, const void* obj) override this method in a descendant class to be able to perform binary search on a list. The value of key is the same as in the call to search(). Obj is a pointer to an object that must be compared against key. The return value must be -1, 0 or 1, similarly to the function strcmp().

See also: tpodlist, tstrlist

PTypes home