4.6.2.1 Typed Arrays

Crystal Space currently has several styles of typed arrays. These arrays grow
as needed to accommodate additions and insertions.

csArray<T>: This is a generic, all-purpose dynamic array class. It is
suitable for any C++ type, including basic types (such as ‘int’) and
user-defined types (such as objects). This class guarantees proper
construction and destruction of objects as they are added to, and removed from
the array. The array types described below are all derived from
csArray<T>. See ‘csutil/array.h’.

csDirtyAccessArray<T>: Similar to csArray<T>, this array type can
be used to store arbitrary objects. The difference is that this array allows
access to the raw memory block, via GetArray(), in which the elements
are stored, whereas csArray<T> keeps its internal state private.
Accessing the raw memory containing the elements is considered dangerous and
poor practice, so use of this class should be restricted and avoided. Its main
use is when you absolutely need access to the internal memory containing the
array of items. This can be useful, for instance, if you need to interface
with some external API (such as OpenGL) which does not understand
csArray<>, and which expects a simple pointer to the array elements.
See ‘csutil/dirtyaccessarray.h’.

csRefArray<T>: This is the preferred way to store an array of pointers
to reference-counted objects. This array type automatically invokes each
object's IncRef() method at insertion time, and DecRef() at
removal time. All SCF objects (see section Shared Class Facility (SCF)) support these methods, as do
objects derived from ‘csRefCount’. Since csRefArray<T> is a
templated class, it will also work with any other object which provides
IncRef() and DecRef() methods. See ‘csutil/refarr.h’.

csRefArrayObject<T>: This is a variant of csRefArray<T> which can
hold objects that have a method QueryObject() which returns something
from which you can call GetName(). In practice it means this is useful
for all Crystal Space objects which implement ‘iObject’. In addition to
the features of csRefArray<T> this class adds the ability to find
elements by name. See ‘csutil/nobjvec.h’.

csPDelArray<T>: This is a convenience array class for pointers only. It
will invoke ‘delete’ for elements removed from the array. This is useful
for cases when you need to store raw pointers to objects which have been
allocated with ‘new’, and don't want to worry about having to
‘delete’ the objects when removed from the array or when the array is
destroyed. In other cases where you need to store raw object pointers but don't
want them deleted upon removal from the array, just use the normal
csArray<T*>. See ‘csutil/parray.h’.