BaseArray Manual

Table of Contents

About

maxon::BaseArray is a generic array class template used to stored any kind of data. It is based on maxon::BaseCollection and maxon::Collection.

Note
One should always use maxon::BaseArray or other array classes of the MAXON API instead of low level C-arrays. For an overview see Arrays Manual.

Create

A new maxon::BaseArray can simply be created on the stack.

Note
See also maxon::ArrayFactory for some utility functions.
// This example creates two new maxon::BaseArray objects and adds some elements.
maxon::BaseArray<maxon::Int> intArray;
intArray.Append(1) iferr_return;
intArray.Append(2) iferr_return;
intArray.Append(3) iferr_return;
maxon::BaseArray<maxon::String> stringArray;
stringArray.Append("Hello"_s) iferr_return;
stringArray.Append("World"_s) iferr_return;

A maxon::BaseArray can be cleared with:

// This example prints the number of stored elements of the given
// maxon::BaseArray before and after a reset.
// check count
DiagnosticOutput("Count: @", baseArray.GetCount());
// reset
baseArray.Reset();
// check count
DiagnosticOutput("Count: @", baseArray.GetCount());

Data Access

A maxon::BaseArray holds a certain amount of memory to store an array of elements. The amount of allocated memory (capacity) may be bigger than the memory needed to hold the currently stored element (count).

// This example checks the capacity of the given maxon::BaseArray.
// If needed the capacity is increased.
if (baseArray.GetCapacityCount() < targetCnt)
{
baseArray.EnsureCapacity(targetCnt) iferr_return;
}

New elements can be added to the array with:

// This example creates a new maxon::BaseArray and adds and inserts elements.
maxon::BaseArray<maxon::Int> baseArray;
baseArray.Append(100) iferr_return;
baseArray.Append(200) iferr_return;
baseArray.Append(300) iferr_return;
baseArray.Insert(0, 50) iferr_return;

The elements stored in the array are easily accessed with:

Note
maxon::BaseArray::GetFirst() is typically used if a function asks for the start address of a simple C-array.
// This example loops through all elements stored in the given maxon::BaseArray.
const maxon::Int cnt = baseArray.GetCount();
for (maxon::Int i = 0; i < cnt; ++i)
{
const maxon::Int value = baseArray[i];
DiagnosticOutput("Value: @", value);
}

Elements can be removed from the array with:

// This example removes elements from the given maxon::BaseArray.
baseArray.Pop(nullptr);
baseArray.SwapErase(2, 2) iferr_return;

Iterate

It is simple to iterate over all elements stored in a maxon::BaseArray:

// This example switches the first and last element stored in the given maxon::BaseArray.
const maxon::Int count = baseArray.GetCount();
if (count >= 2)
{
// switch first and last element
maxon::BaseArray<maxon::Int>::Iterator itBegin = baseArray.Begin();
maxon::BaseArray<maxon::Int>::Iterator itEnd = baseArray.End();
itEnd--; // construct iterator position of last element
// swap elements
baseArray.Swap(itBegin, itEnd);
}
// check order
for (const maxon::Int& value : baseArray)
DiagnosticOutput("Value: @", value);

Copy

A maxon::BaseArray can simply be copied with:

// This example copies the content of the given maxon::BaseArray into the new array.
maxon::BaseArray<maxon::Int> newArray;
newArray.CopyFrom(baseArray) iferr_return;
DiagnosticOutput("Array Size: @", newArray.GetCount());

Memory

The internal memory of the maxon::BaseArray is accessed with these functions. A third-party developer should typically not have to use these functions.

For special allocators see Allocators.

Classes

A class that should be used with a maxon::BaseArray must provide some functionality:

When elements are added or removed from the array, the maxon::BaseArray will copy or move elements around. To support this, a data type class that should be used with a maxon::BaseArray must provide certain functionality:

  • The class may not be copyable, but then it has to support std::move.
  • The class may not support the copy constructor and operator, but CopyFrom().
  • The class may not support std::move, but then copy has to be available.
// A primitive class based on POD can simply be copied and moved in a BaseArray.
// primitive class
class SimpleClass
{
public:
maxon::Float _x, _y, _z;
};
// using the primitive class with maxon::BaseArray
maxon::BaseArray<SimpleClass> exampleArray;
exampleArray.Resize(100) iferr_return;
SimpleClass& exampleElement = exampleArray[0];
// A class can provide a copy contructor to be used with a BaseArray.
// class with copy constructor
class CopyClass
{
public:
CopyClass() { };
CopyClass(maxon::Int value) : _value(value) { }
CopyClass(const CopyClass& src) : _value(src._value) { }
private:
maxon::Int _value = 0;
};
maxon::BaseArray<CopyClass> exampleArray;
// the new element is appended using the copy constructor
CopyClass exampleElement(1);
exampleArray.Append(exampleElement) iferr_return;
// A class with CopyFrom() allows to insert or add const elements to a BaseArray.
// It also allows to copy arrays.
class CopyFromClass
{
MAXON_DISALLOW_COPY_AND_ASSIGN(CopyFromClass) // no copy constructor, no "=" operator
public:
CopyFromClass() { };
CopyFromClass(maxon::Int value) : _value(value) { }
CopyFromClass(CopyFromClass&& src) = default;
maxon::Result<void> CopyFrom(const CopyFromClass& src)
{
// CopyFrom() is invoked when adding/inserting a const element to a BaseArray
_value = src._value;
return maxon::OK;
}
private:
maxon::Int _value = 0;
};
maxon::BaseArray<CopyFromClass> exampleArray;
// the new element is appended using CopyFrom()
const CopyFromClass exampleElement(1);
exampleArray.Append(exampleElement) iferr_return;
// A class can provide a move constructor/operator to be used with a BaseArray.
class MoveClass
{
MAXON_DISALLOW_COPY_AND_ASSIGN(MoveClass) // no copy constructor, no "=" operator
public:
MoveClass() { };
MoveClass(maxon::Int value) : _value(value) { }
MoveClass(MoveClass&& src)
{
_value = src._value;
}
MAXON_OPERATOR_MOVE_ASSIGNMENT(MoveClass); // move assignment based on move constructor
private:
maxon::Int _value = 0;
};
maxon::BaseArray<MoveClass> exampleArray;
// the new element is appended using the move constuctor
exampleArray.Append(MoveClass(1)) iferr_return;

Further Reading