BaseArray Manual

Table of Contents

• About
• Create
• Data Access
• Iterate
• Copy
• Memory
• Classes
• Further Reading

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.

• maxon::BaseArray::BaseArray(): Creates a new maxon::BaseArray for the given type.

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:

• maxon::BaseArray::Reset(): Deletes all stored elements.
• maxon::BaseArray::Flush(): Deletes all stored elements but does not free internal memory.

    // 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).

• maxon::BaseArray::GetCount(): Returns the number of array elements.
• maxon::BaseArray::GetCapacityCount(): Returns the number of elements for which has been memory allocated.
• maxon::BaseArray::Resize(): Resizes the array to the given number of elements.
• maxon::BaseArray::EnsureCapacity(): Increases the capacity to the given number of elements.
• maxon::BaseArray::SetCapacityHint(): Prepares the maxon::BaseArray to store the given number of elements.
• maxon::BaseArray::IncreaseCapacity(): Appends uninitialized element(s) at the end of the array.

    // 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:

• maxon::BaseArray::Append(): Adds a new element to the end of the array.
• maxon::BaseArray::Insert(): Inserts an element at the given position into the array.
• maxon::BaseArray::InsertWithoutConstructor(): Inserts uninitialized element(s) at the specified index. Should typically not be used.

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.
 
    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:

• maxon::BaseArray::operator[](): Returns the element stored at the given index.
• maxon::BaseArray::GetFirst(): Returns the first element of the array.
• maxon::BaseArray::GetLast(): Returns the last element of the array.
• maxon::BaseArray::GetIndex(): Returns the index of the given element.

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:

• maxon::BaseArray::Erase(): Erases the given number of elements from the given index.
• maxon::BaseArray::SwapErase(): Erases elements within the array and moves elements from the end to the erased gap. This will change the order of elements.
• maxon::BaseArray::Pop(): Deletes the last element.

    // 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:

• maxon::BaseArray::Begin(): Returns the begin iterator.
• maxon::BaseArray::End(): Returns the end iterator.
• maxon::BaseArray::Swap(): Swaps two elements at the given iterator positions.

    // 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:

• maxon::BaseArray::CopyFrom(): Copies the data from the given maxon::BaseArray.

    // 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.

• maxon::BaseArray::Connect(): Sets the array's memory buffer to the given block.
• maxon::BaseArray::Disconnect(): Disconnects the array's memory buffer and returns its content as a block.
• maxon::BaseArray::GetAllocator(): Returns the allocator as reference.
• maxon::BaseArray::GetBlock(): Determines a contiguous block of array elements which contains the element at the given index.
• maxon::BaseArray::GetMemorySize(): Calculates the memory usage for this array if the element class provides a GetMemorySize() function.

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

• Data Containers & Collections
• Maxon API Containers & Data Collections
• BaseSort Manual
• Arrays Manual
• Memory Allocation