BaseArray Manual

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.
intArray.Append(1) iferr_return;
intArray.Append(2) iferr_return;
intArray.Append(3) iferr_return;
stringArray.Append("Hello"_s) iferr_return;
stringArray.Append("World"_s) iferr_return;
Definition: basearray.h:415
MAXON_ATTRIBUTE_FORCE_INLINE ResultRef< T > Append(ARG &&x)
Appends a new element at the end of the array and constructs it using the forwarded value.
Definition: basearray.h:628
#define iferr_return
Definition: resultbase.h:1524

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());
#define DiagnosticOutput(formatString,...)
Definition: debugdiagnostics.h:170

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:

Warning
Avoid to use references to array elements while the array is resized since resizing the array invalidates any reference to its elements.
// This example creates a new maxon::BaseArray and adds and inserts elements.
baseArray.Append(100) iferr_return;
baseArray.Append(200) iferr_return;
baseArray.Append(300) iferr_return;
baseArray.Insert(0, 50) iferr_return;
MAXON_ATTRIBUTE_FORCE_INLINE ResultRef< T > Insert(Int position, ARG &&x)
Inserts a new element at index position and constructs it using the forwarded value.
Definition: basearray.h:821

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);
}
Py_ssize_t i
Definition: abstract.h:645
PyObject * value
Definition: abstract.h:715
MAXON_ATTRIBUTE_FORCE_INLINE Int GetCount() const
Definition: basearray.h:585
Int64 Int
signed 32/64 bit int, size depends on the platform
Definition: apibase.h:202

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;
ResultMem SwapErase(Int position, Int eraseCnt=1)
Definition: basearray.h:1071
MAXON_ATTRIBUTE_FORCE_INLINE Bool Pop(T *dst=nullptr)
Definition: basearray.h:1295

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
itEnd--; // construct iterator position of last element
// swap elements
baseArray.Swap(itBegin, itEnd);
}
// check order
for (const maxon::Int& value : baseArray)
DiagnosticOutput("Value: @", value);
Py_ssize_t count
Definition: abstract.h:640
MAXON_ATTRIBUTE_FORCE_INLINE void Swap(Iterator a, Iterator b)
Definition: basearray.h:1462
MAXON_ATTRIBUTE_FORCE_INLINE ConstIterator Begin() const
Definition: basearray.h:1486
MAXON_ATTRIBUTE_FORCE_INLINE ConstIterator End() const
Definition: basearray.h:1506
Definition: block.h:105

Copy

A maxon::BaseArray can simply be copied with:

// This example copies the content of the given maxon::BaseArray into the new array.
newArray.CopyFrom(baseArray) iferr_return;
DiagnosticOutput("Array Size: @", newArray.GetCount());
MAXON_ATTRIBUTE_FORCE_INLINE Result< void > CopyFrom(COLLECTION2 &&other, COLLECTION_RESIZE_FLAGS resizeFlags=COLLECTION_RESIZE_FLAGS::FIT_TO_SIZE)
Definition: collection.h:261

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
exampleArray.Resize(100) iferr_return;
SimpleClass& exampleElement = exampleArray[0];
ResultMem Resize(Int newCnt, COLLECTION_RESIZE_FLAGS resizeFlags=COLLECTION_RESIZE_FLAGS::DEFAULT)
Definition: basearray.h:1218
Float64 Float
Definition: apibase.h:211
// 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;
};
// the new element is appended using the copy constructor
CopyClass exampleElement(1);
exampleArray.Append(exampleElement) iferr_return;
PyObject * src
Definition: abstract.h:305
// 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;
};
// the new element is appended using CopyFrom()
const CopyFromClass exampleElement(1);
exampleArray.Append(exampleElement) iferr_return;
return OK
Definition: apibase.h:2735
#define MAXON_DISALLOW_COPY_AND_ASSIGN(TypeName)
Definition: classhelpers.h:352
// 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;
};
// the new element is appended using the move constuctor
exampleArray.Append(MoveClass(1)) iferr_return;
#define MAXON_OPERATOR_MOVE_ASSIGNMENT(TypeName)
Definition: classhelpers.h:381

Further Reading