Lists types

Intro

• tpodlist - dynamic array of POD objects
• tobjlist - dynamic array of pointers to arbitrary objects
• tstrlist - dynamic list and associative array of string/object pairs
• textmap - associative array of textual key/value pairs

PTypes offers a set of list templates/classes that were designed to eliminate the template 'code bloat' problem and also to allow reallocating of dynamic arrays in the most efficient way.

Why not STL containers? Or, why there is no universal container for arbitrary types, like std::vector, in PTypes There are 3 main reasons for this:

• A universal container template would require the item type to be either a POD-type or a copyable class, since it copies items during reallocation of the dynamic array. Otherwise, if its implementation would use fragmentation to avoid copying, the indexed access would become a costly operation. As a result, you are forced to provide copy constructors (often bulky, non-trivial code) for many classes in your program, even though it wouldn't be necessary otherwise. Such container would be (and in real world it is) very inefficient for the same reason: each reallocation of the dynamic array requires items to be copied instead of just moved. Possibly a built-in reallocation operator in C++ would solve this problem.
• The 'code bloat' problem: containers like std:vector usually produce enormous amount of automatically generated code (sometimes duplicate code) during instantiation of templates.

Overview of PTypes list templates. As a replacement of a universal vector-like container PTypes offers two separate templates: tpodlist and tobjlist. Each of them have certain limitations in return for the following advantages: dynamic arrays are reallocated in the most efficient way, templates produce no or very little code during instantiation.

The tpodlist template is intended for use with small POD (plain-old-data) objects. For bigger structures or for arbitrary non-POD types in general the library offers a list of pointers, tobjlist, that has the ability to automatically destroy objects when they are removed from the list. Tobjlist never reallocates items themselves, instead, it only deals with pointers.

As a universal way of holding string/object pairs in an indexed list the library offers the tstrlist template. When constructed as a sorted list, this template can also serve as a map indexed by textual keys. And finally, the textmap class provides a simple interface for mapping strings to strings, i.e. textual keys to values.

Historically, PTypes was using list classes that required the list item to be derived from unknown. These list classes (objlist, strlist and strmap) are still present in the library for backward compatibility. There is no such limitation in the newer versions of the library, however, deriving your classes from unknown can still give you an advantage of automatically detecting memory leaks in your program.

Bounds checking. All list operations that involve indexes can be checked for validity at run-time. If an index value is invalid, the library generates an unrecoverable (fatal) error. Bounds checking is done when compiling your code in debug mode (i.e. if macro DEBUG is defined). You may also enable it explicitly for your release builds by defining CHECK_BOUNDS. Note that the bounds checking code is fully inlined and the library itself is not affected by these macros.

The list class family is declared in <ptypes.h>.