This is machine translation

Translated by Microsoft
Mouseover text to see original. Click the button below to return to the English version of the page.

Note: This page has been translated by MathWorks. Click here to see
To view all translated materials including this page, select Country from the country navigator on the bottom of this page.

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

ArrayFactory()

Throws

matlab::FailedToLoadLibMatlabDataArrayException

Concrete implementation not loaded.

Destructor

~ArrayFactory()

Member Functions

createArray

template <typename T>
TypedArray<T> createArray(ArrayDimensions dims)
template <typename ItType, typename T>
TypedArray<T> createArray(ArrayDimensions dims, 
    ItType begin, 
    ItType end)
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 and must be in column-major order.

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

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.

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

Number of elements is greater than size_t.

createScalar

template <typename T>
TypedArray<T> createScalar(const T val)
TypedArray<String> createScalar(const String val)
TypedArray<String> createScalar(const std::string 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. If val is 7-bit ASCII data, then the method converts it to UTF16.

const String val

const std::string val

Throws

matlab::OutOfMemoryException

Unable to allocate the array.

matlab::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 complex type, string, or Array.

Throws

matlab::OutOfMemoryException

Unable to allocate the array.

matlab::NonAsciiCharInInputDataException

Input is std::string and contains non-ASCII characters.

matlab::NumberOfElementsExceedsMaximumException

Number of elements is greater than size_t.

Examples

#include "MatlabDataArray.hpp"

int main()
{
	using namespace matlab::data;
	ArrayFactory f;
	CellArray myArray = f.createCellArray({ 1,2 },
		f.createCharArray("MATLAB Cell Array"),
		f.createArray<double>({ 2,2 }, { 1.2, 2.2, 3.2, 4.2 }));

	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::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;
}

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

Duplicate field names specified.

matlab::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::MustSpecifyClassNameException

Class name not specified.

matlab::WrongNumberOfEnumsSuppliedException

Wrong number of enumerations provided.

matlab::NumberOfElementsExceedsMaximumException

Number of elements is greater than size_t.

Examples

#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;
}

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

More than two dimensions specified.

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

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 input buffer, specified as MemoryLayout::COLUMN_MAJOR or as MemoryLayout::ROW_MAJOR for 2D arrays. The default layout is COLUMN_MAJOR. This parameter is optional.

Throws

matlab::OutOfMemoryException

Unable to allocate the array.

matlab::InvalidArrayTypeException

Buffer type not valid.

matlab::InvalidMemoryLayout

Invalid memory layout.

matlab::InvalidDimensionsInRowMajorArrayException

Buffer size not valid.

matlab::NumberOfElementsExceedsMaximumException

Number of elements is greater than size_t.

Introduced in R2017b