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;

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:

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;

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
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.
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
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;
};
// 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;
};
// 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;
};
// the new element is appended using the move constuctor
exampleArray.Append(MoveClass(1)) iferr_return;

Further Reading

maxon::BaseArray::End
MAXON_ATTRIBUTE_FORCE_INLINE ConstIterator End() const
Definition: basearray.h:1352
maxon::BaseArray::Pop
MAXON_ATTRIBUTE_FORCE_INLINE Bool Pop(T *dst=nullptr)
Definition: basearray.h:1154
maxon::OK
return OK
Definition: apibase.h:2518
maxon::BaseArray::Resize
ResultMem Resize(Int newCnt, COLLECTION_RESIZE_FLAGS resizeFlags=COLLECTION_RESIZE_FLAGS::DEFAULT)
Definition: basearray.h:1077
iferr_return
#define iferr_return
Definition: resultbase.h:1434
maxon::Float
Float64 Float
Definition: apibase.h:193
maxon::BaseArray
Definition: basearray.h:366
DiagnosticOutput
#define DiagnosticOutput(formatString,...)
Definition: debugdiagnostics.h:166
maxon::BaseArray::Swap
MAXON_ATTRIBUTE_FORCE_INLINE void Swap(Iterator a, Iterator b)
Definition: basearray.h:1308
MAXON_DISALLOW_COPY_AND_ASSIGN
#define MAXON_DISALLOW_COPY_AND_ASSIGN(TypeName)
Definition: classhelpers.h:293
maxon::src
const T & src
Definition: apibase.h:2511
maxon::Result< void >
maxon::BaseArray::GetCount
MAXON_ATTRIBUTE_FORCE_INLINE Int GetCount() const
Definition: basearray.h:527
maxon::BaseArray::Append
MAXON_ATTRIBUTE_FORCE_INLINE ResultRef< T > Append()
Definition: basearray.h:569
maxon::BaseIterator
Definition: block.h:104
maxon::Int
Int64 Int
signed 32/64 bit int, size depends on the platform
Definition: apibase.h:184
MAXON_OPERATOR_MOVE_ASSIGNMENT
#define MAXON_OPERATOR_MOVE_ASSIGNMENT(TypeName)
Definition: classhelpers.h:322
maxon::BaseArray::Begin
MAXON_ATTRIBUTE_FORCE_INLINE ConstIterator Begin() const
Definition: basearray.h:1332
maxon::BaseArray::SwapErase
ResultMem SwapErase(Int position, Int eraseCnt=1)
Definition: basearray.h:930
maxon::BaseArray::Insert
MAXON_ATTRIBUTE_FORCE_INLINE ResultRef< T > Insert(Int position)
Definition: basearray.h:694
maxon::BaseCollection< BaseArray< T, BASEARRAY_DEFAULT_CHUNK_SIZE, BASEARRAYFLAGS::NONE, DefaultAllocator >, BaseArrayData< T, DefaultAllocator, STD_IS_REPLACEMENT(empty, DefaultAllocator)> >::CopyFrom
MAXON_ATTRIBUTE_FORCE_INLINE Result< void > CopyFrom(COLLECTION2 &&other, COLLECTION_RESIZE_FLAGS resizeFlags=COLLECTION_RESIZE_FLAGS::FIT_TO_SIZE)
Definition: collection.h:252