matlab::data::ArrayFactory

C++ class to create arrays

Description

Use ArrayFactory to create matlab::data::Array objects.

Class Details

Namespace:	`matlab::data`
Include:	`ArrayFactory.hpp`

Constructors

Default Constructor

Default Constructor

ArrayFactory()

Throws

matlab::data::FailedToLoadLibMatlabDataArrayException

Concrete implementation not loaded.

Destructor

~ArrayFactory()

`createArray`

template <typename T>
TypedArray<T> createArray(ArrayDimensions dims)

template <typename ItType, typename T>
TypedArray<T> createArray(ArrayDimensions dims, 
    ItType begin, 
    ItType end,
    InputLayout inputLayout)

template <typename T>
TypedArray<T> createArray(ArrayDimensions dims, 
    const T* const begin, 
    const T* const end)

template <typename T> 
TypedArray<T> createArray(ArrayDimensions dims, 
    std::initializer_list<T> data)

Description

Creates a TypedArray<T> with the given dimensions. If specified, createArray fills the array with data. The data is copied by default in column-major order. To specify the data layout, use the inputLayout parameter.

Template Parameters

ItType - Iterator types, specified as std::iterator.

T - Element types, specified as one of the following C++ data types.

`bool`	`int8_t`	`int16_t`	`int32_t`	`int64_t`	`uint8_t`
`uint16_t`	`uint32_t`	`uint64_t`	`float`	`double`	`char16_t`
`matlab::data::String`	`std::complex<double>`	`std::complex<float>`	`std::complex<int8_t>`	`std::complex<uint8_t>`	`std::complex<int16_t>`
`std::complex<uint16_t>`	`std::complex<int32_t>`	`std::complex<uint32_t>`	`std::complex<int64_t>`	`std::complex<uint64_t>`	`matlab::data::MATLABString`

To create an array of matlab::data::Object element types, use the TypedArray<T> createArray(ArrayDimensions dims, ItType begin, ItType end) syntax.

Parameters

`ArrayDimensions dims`	Dimensions for the array.
`ItType begin` `ItType end`	Start and end of the user supplied data. The `value_type` of the iterator determines the data type.
`InputLayout inputLayout`	The layout of the input data. The values for `InputLayout` are `COLUMN_MAJOR` or `ROW_MAJOR`.
`const T* const begin` `const T* const end`	Start and end of the user supplied data specified as C-style pointer. This syntax supports all primitive types, complex types, and string types.
`std::initializer_list<T>`	Initializer list containing the data.

Throws

`matlab::OutOfMemoryException`	Unable to allocate the array.
`matlab::data::NumberOfElementsExceedsMaximumException`	Number of elements is greater than `size_t`.
`matlab::data::InvalidArrayTypeException`	Input type of `matlab::data::ObjectArray` does not match the type of `TypedArray<T>`.

`createScalar`

template <typename T>
TypedArray<T> createScalar(const T val)

TypedArray<MATLABString> createScalar(const String val)

TypedArray<MATLABString> createScalar(const std::string val)

ObjectArray createScalar(const Object& val);

Description

Creates a scalar TypedArray<T> with the given value. This method supports arithmetic types, complex types, and string types.

Parameters

`const T val`	Value to be inserted into the scalar. For `std::string` parameters, if `val` is 7-bit ASCII data, then the method converts it to UTF16.
`const String val`
`const std::string val`
`const Object& val`

Throws

`matlab::OutOfMemoryException`	Unable to allocate the array.
`matlab::data::NonAsciiCharInInputDataException`	Input is `std::string` and contains non-ASCII characters.

Examples

#include "MatlabDataArray.hpp"

int main() {
    matlab::data::ArrayFactory factory;

    // Create a vector containing two scalar values    
    std::vector<matlab::data::Array> args({
	factory.createScalar<int16_t>(100),
	factory.createScalar<int16_t>(60)});
    return 0;
}

`createCellArray`

CellArray createCellArray(ArrayDimensions dims)

template <typename ...Targs>
CellArray createCellArray(ArrayDimensions dims, Targs... data)

Description

Creates a CellArray with the specified data. The data is in column-major order.

Template Parameters

...Targs

Variadic template of:

arithmetic type
complex type
matlab::data::String
std::string
matlab::data::Array

Parameters

`ArrayDimensions dims`	Dimensions of the cell array.
`Targs... data`	Elements to be inserted into the cell array, specified as a primitive type, complex type, string, or `Array`.

Throws

`matlab::OutOfMemoryException`	Unable to allocate the array.
`matlab::data::NonAsciiCharInInputDataException`	Input is `std::string` and contains non-ASCII characters.
`matlab::data::NumberOfElementsExceedsMaximumException`	Number of elements is greater than `size_t`.

Examples

Create a two element cell array containing an std::string and a double.

#include "MatlabDataArray.hpp"

int main()
{
	using namespace matlab::data;
	ArrayFactory f;
	CellArray myArray = f.createCellArray({ 1,2 },
		std::string("MATLAB Cell Array"), 5.5);

	return 0;
}

`createCharArray`

CharArray createCharArray(String str)

CharArray createCharArray(std::string str)

Description

Creates a 1xn CharArray from the specified input, where n is the string length.

Parameters

`matlab::data::String str`	Data to be filled into the array.
`std::string str`

Throws

`matlab::OutOfMemoryException`	Unable to allocate the array.
`matlab::data::NonAsciiCharInInputDataException`	Input is `std::string` and contains non-ASCII characters.

Examples

#include "MatlabDataArray.hpp"

int main() {
    using namespace matlab::data;
    ArrayFactory factory;
    CharArray A = factory.createCharArray("This is a char array");
    return 0;
}

`createCharArrayFromUTF8`

CharArray createCharArray(const std::string& str)

Description

Creates a 1xn CharArray from the specified std::string of UTF8 characters, where n is the string length.

Parameters

std::string str

Data to be filled into the array.

Throws

`matlab::OutOfMemoryException`	Unable to allocate the array.
`matlab::data::InvalidUTF8InputException`	Input string contains a non-UTF8 character.
`matlab::data::FeatureNotSupportedException`	Code is running a version older than R2024b.

Examples

#include "MatlabDataArray.hpp"

int main() {
    using namespace matlab::data;
    ArrayFactory factory;
    // "UTF8 string"
    std::string utf8str = "\x55\x54\x46\x20\x73\x74\x72\x69\x6e\x67";
    CharArray A = factory.createCharArrayFromUTF8(utf8str);
    return 0;
}

`createStructArray`

StructArray createStructArray(ArrayDimensions dims, 
    std::vector<std::string> fieldNames)

Description

Creates a StructArray with the given dimensions and field names.

Parameters

`ArrayDimensions dims`	Dimensions for the array.
`std::vector<std::string> fieldNames`	Vector of the field names for the structure.

Throws

`matlab::OutOfMemoryException`	Unable to allocate the array.
`matlab::data::DuplicateFieldNameInStructArrayException`	Duplicate field names specified.
`matlab::data::NumberOfElementsExceedsMaximumException`	Number of elements is greater than `size_t`.

Examples

#include "MatlabDataArray.hpp"

int main() {
    using namespace matlab::data;
    ArrayFactory f;

    // Create StructArray equivalent to MATLAB structure s:
    // s = struct('loc', {'east', 'west'}, 'data', {[1, 2, 3], [4., 5., 6., 7., 8.]})
    StructArray S = f.createStructArray({ 1,2 }, { "loc", "data" });
    S[0]["loc"] = f.createCharArray("east");
    S[0]["data"] = f.createArray<uint8_t>({ 1, 3 }, { 1, 2, 3 });
    S[1]["loc"] = f.createCharArray("west");
    S[1]["data"] = f.createArray<double>({ 1, 5 }, { 4., 5., 6., 7., 8. });

    // Access the value defined by the MATLAB statement:
    // s(1).data
    Reference<Array> val = S[0]["data"];
	
    return 0;
}

`createEnumArray`

EnumArray createEnumArray(ArrayDimensions dims, 
    std::string className, 
    std::vector<std::string> enums)

EnumArray createEnumArray(ArrayDimensions dims, 
    std::string className)

Description

Creates an EnumArray of type className, which is a defined class. If specified, the method initializes the array with the list of enumeration names.

Parameters

`ArrayDimensions dims`	Dimensions for the array.
`std::string className`	Class name of the enumeration array.
`std::vector<std::string> enums`	List of the enumeration names.

Throws

`matlab::OutOfMemoryException`	Unable to allocate the array.
`matlab::data::MustSpecifyClassNameException`	Class name not specified.
`matlab::data::WrongNumberOfEnumsSuppliedException`	Wrong number of enumerations provided.
`matlab::data::NumberOfElementsExceedsMaximumException`	Number of elements is greater than `size_t`.

Examples

Create a matlab::data::EnumArray object for the TextColor.Blue enumeration argument defined in this class.

classdef TextColor
   enumeration
       Red
       Green
       Blue
   end
end

Move the value into an argument vector.

#include "MatlabDataArray.hpp"
#include <vector>

int main()
{
	using namespace matlab::data;
	ArrayFactory f;
	auto blue = f.createEnumArray({ 1,1 }, "TextColor", { "Blue" });

	// Create an argument vector
	std::vector<Array> args({ f.createCharArray("My text"), std::move(blue) });

	return 0;
}

For more examples, see Pass Enumerations to MATLAB from C++.

`createSparseArray`

template <typename T>
SparseArray<T> createSparseArray(ArrayDimensions dims, 
    size_t nnz,
    buffer_ptr_t<T> data, 
    buffer_ptr_t<size_t> rows, 
    buffer_ptr_t<size_t> cols)

Description

Creates a SparseArray<T> with rows-by-cols dimensions. You can only have two dimensions for sparse arrays. The method does not copy the buffer and the array takes ownership of the memory.

Template Parameters

`T`	Element types, specified as `double`, `bool`, or `std::complex<double>`.

Parameters

`ArrayDimensions dims`	Dimensions for the array.
`size_t nnz`	Number of nonzero elements.
`buffer_ptr_t<T> data`	Buffer containing the nonzero elements.
`buffer_ptr_t<size_t> rows`	Buffer containing the row value for each element.
`buffer_ptr_t<size_t> cols`	Buffer containing the column value for each element.

Throws

`matlab::OutOfMemoryException`	Unable to allocate the array.
`matlab::data::InvalidDimensionsInSparseArrayException`	More than two dimensions specified.
`matlab::data::NumberOfElementsExceedsMaximumException`	Number of elements is greater than `size_t`.

Examples

#include "MatlabDataArray.hpp"

int main() {
	std::vector<double> data = { 3.5, 12.98, 21.76 };
	std::vector<size_t> rows = { 0,0,1 };
	std::vector<size_t> cols = { 0,4,8 };
	size_t nnz = 3;

	matlab::data::ArrayFactory factory;
	auto data_p = factory.createBuffer<double>(nnz);
	auto rows_p = factory.createBuffer<size_t>(nnz);
	auto cols_p = factory.createBuffer<size_t>(nnz);

	double* dataPtr = data_p.get();
	size_t* rowsPtr = rows_p.get();
	size_t* colsPtr = cols_p.get();
	std::for_each(data.begin(), data.end(), [&](const double& e) { *(dataPtr++) = e; });
	std::for_each(rows.begin(), rows.end(), [&](const size_t& e) { *(rowsPtr++) = e; });
	std::for_each(cols.begin(), cols.end(), [&](const size_t& e) { *(colsPtr++) = e; });

	matlab::data::SparseArray<double> arr =
		factory.createSparseArray<double>({ 2,9 }, nnz, std::move(data_p),
			std::move(rows_p), std::move(cols_p));
	return 0;
}

`createEmptyArray`

Array createEmptyArray()

Descriptions

Creates an empty Array containing no elements.

Returns

Array

Empty array.

Throws

matlab::OutOfMemoryException

Unable to allocate the array.

`createBuffer`

template <typename T>
buffer_ptr_t<T> createBuffer(size_t numberOfElements)

Description

Creates an uninitialized buffer to pass to the createArrayFromBuffer method.

Template Parameters

`T`	Primitive types.

Parameters

size_t numberOfElements

Number of elements, not the actual buffer size.

Returns

buffer_ptr_t<T>

Unique_ptr containing the buffer.

Throws

matlab::OutOfMemoryException

Unable to allocate the array.

`createArrayFromBuffer`

template <typename T>
TypedArray<T> createArrayFromBuffer(ArrayDimensions dims, 
    buffer_ptr_t<T> buffer,
    MemoryLayout memoryLayout = MemoryLayout::COLUMN_MAJOR)

Description

Creates a TypedArray<T> using the given buffer. You can specify a custom deleter function of type buffer_deleter_t to manage the buffer. (since R2024b)

Template Parameters

`T`	Primitive types.

Parameters

ArrayDimensions dims

Dimensions for the array.

buffer_ptr_t<T> buffer

Buffer containing the data. The buffer is not copied. The TypedArray<T> object takes ownership of the buffer.

MemoryLayout memoryLayout

Memory layout for the input buffer and the created array, specified as MemoryLayout::COLUMN_MAJOR or as MemoryLayout::ROW_MAJOR. The default layout is COLUMN_MAJOR.

When using matlab::data::TypedIterator<T> on an array created with createArrayFromBuffer, MemoryLayout affects the order of returned elements.

This parameter is optional.

Throws

`matlab::OutOfMemoryException`	Unable to allocate the array.
`matlab::data::InvalidArrayTypeException`	Buffer type not valid.
`matlab::data::InvalidMemoryLayoutException`	Invalid memory layout.
`matlab::data::InvalidDimensionsInRowMajorArrayException`	Dimensions not valid. This exception occurs for arrays created with MATLAB^® R2019a and R2019b if a row-major array is not 2-D.
`matlab::data::NumberOfElementsExceedsMaximumException`	Number of elements is greater than `size_t`.

Version History

Introduced in R2017b

expand all

R2024b: MATLAB Data API: Create `matlab::data::CharArray` from UTF8 input

Use the createCharArrayFromUTF8 method to create a matlab::data::CharArray from an std::string, where the string contains only 7-bit ASCII data.

matlab::data::ArrayFactory

Description

Class Details

Constructors

Default Constructor

Destructor

Member Functions

createArray

createScalar

createCellArray

createCharArray

createCharArrayFromUTF8

createStructArray

createEnumArray

createSparseArray

createEmptyArray

createBuffer

createArrayFromBuffer

Version History

R2024b: MATLAB Data API: Create matlab::data::CharArray from UTF8 input

`createArray`

`createScalar`

`createCellArray`

`createCharArray`

`createCharArrayFromUTF8`

`createStructArray`

`createEnumArray`

`createSparseArray`

`createEmptyArray`

`createBuffer`

`createArrayFromBuffer`

R2024b: MATLAB Data API: Create `matlab::data::CharArray` from UTF8 input