Class Hierarchy
AcArray
C++
template <typename T, typename R = typename AcArrayItemCopierSelector<T, std::is_trivial<T>::value>::allocator > class AcArray;
File
acarray.h
Description
AcArray is a template class, which means other arrays of specific objects use this class to obtain their definition. Since this is a template class, the descriptions for all the other array classes are actually defined here. The signatures are described with the template syntax. Depending on the array class you are working with, replace the type (for example, AcDbObjectIdArray), with the type name T indicator when reading the AcArray descriptions.
The following description applies to all of the dynamic arrays used in ObjectARX. The term "dynamic array" means that the array can grow without bounds unlike declaring an array of items in the usual manner. For example, declaring "AcDbObjectId myArray[10]" is limited to holding only ten AcDbObjectId objects.
There are three key concepts to implement in using the AcArray class:
1. Logical length. The logical length of the array equals the number of entries that have been placed into the array. Initially, this value is always zero. (See AcArray::length(), AcArray::logicalLength(), and AcArray::setLogicalLength().)
2. Physical length. The physical length of the array equals the number of entries that the array will hold before it automatically grows larger. (See AcArray::physicalLength(), and AcArray::setPhysicalLength().)
3. Grow length. The minimum number of elements the array grows by. (See AcArray::growLength() and AcArray::setGrowLength().)
The logical length (AcArray::logicalLength() or AcArray::length()) of the array reflects how many elements of the array type have been placed into the array. Many of the member functions are only valid for indices that are greater than or equal to zero and less than AcArray::logicalLength(). For example, indexing into the array with the AcArray::operator[] is only valid for indices in the range zero to AcArray::logicalLength() - 1.
The logical length is always less than or equal to the physical length. The array will ALWAYS start out empty, meaning that the AcArray::logicalLength() always starts at zero regardless of the initial physical length.
The logical length can be set to any value (with AcArray::setLogicalLength()) greater than zero. If you add an element to the array causing the logical length to become greater than the physical length of the array then additional space is allocated to increase the physical length. The amount of the increase is the larger of: the current grow length, or double the current physical length if the space used is less than 1M bytes, or the number items that will grow the total space by an additional 1M bytes.
If the logical length is explicitly reset to a larger value, then all the entries from the old length up to the new length may contain garbage values. You must explicitly initialize these values after increasing the logical length.
The physical length (AcArray::physicalLength()) of the array is the actual length of the physically allocated array. This includes entries that may not be fully used. For example, the size in bytes of an array of AcDbObjectIds called myArray would be:
sizeof(AcDbObjectId) * myArray.physicalLength()
The grow length (AcArray::growLength()) determines how many additional elements to allocate in the situation where adding an element to the array causes the logical length to become greater than the physical length. When this happens, the physical length will increase by the grow length. The grow length value must be greater than zero.
Note: If the contained class can be safely copied by the memcpy you should use the AcArrayMemCopyReallocator template with the array. If the class you intend to contain requires the use of operator=() for the copying during reallocation you should use the AcArrayObjectCopyReallocator template. The default behavior is to use the AcArrayMemCopyReallocator template.
Note on size values: This class uses a 32-bit signed integer for size and index values. Therefore the highest physical and logical length values are 2G-1.
Links
AcArray Constructor, Enumerations, AcArray Methods, AcArray Operators