Core MATLAB-compatible multidimensional array and scalar value type. More...

#include <value.hpp>

Public Member Functions
	Value ()
	Constructs an empty 0 x 0 double matrix ([]).
	Value (const Value &other)
Value &	operator= (const Value &other)
	Value (Value &&other) noexcept
Value &	operator= (Value &&other) noexcept
void	swap (Value &other) noexcept
	Value (std::initializer_list< double > il, std::pmr::memory_resource *mr=nullptr)
	Row vector from a brace-enclosed list of doubles.
template<class T>
	Value (Span< const T > data, std::pmr::memory_resource *mr=nullptr)
	Row vector from a contiguous span.
template<class T>
	Value (const std::vector< T > &v, std::pmr::memory_resource *mr=nullptr)
	Row vector from std::vector — copies all elements.
template<class T, std::size_t N>
	Value (const std::array< T, N > &a, std::pmr::memory_resource *mr=nullptr)
	Row vector from std::array — copies all elements.
Value	elemAt (size_t linearIdx, std::pmr::memory_resource *mr=nullptr) const
double	elemAsDouble (size_t idx) const
Value	indexGet (const size_t indices, size_t count, std::pmr::memory_resource mr=nullptr) const
Value	reshape (size_t rows, size_t cols, std::pmr::memory_resource *mr=nullptr) const
Value	indexGet2D (const size_t rowIdx, size_t nrows, const size_t colIdx, size_t ncols, std::pmr::memory_resource *mr=nullptr) const
Value	indexGet3D (const size_t rowIdx, size_t nrows, const size_t colIdx, size_t ncols, const size_t pageIdx, size_t npages, std::pmr::memory_resource mr=nullptr) const
Value	indexGetND (const size_t const perDimIdx, const size_t perDimCount, int nd, std::pmr::memory_resource mr=nullptr) const
	ND subscript read for arbitrary rank.
Value	logicalIndex (const uint8_t mask, size_t maskLen, std::pmr::memory_resource mr=nullptr) const
void	elemSet (size_t linearIdx, const Value &val)
void	indexSet (const size_t *indices, size_t count, const Value &val)
void	indexSet2D (const size_t rowIdx, size_t nrows, const size_t colIdx, size_t ncols, const Value &val)
void	indexSet3D (const size_t rowIdx, size_t nrows, const size_t colIdx, size_t ncols, const size_t *pageIdx, size_t npages, const Value &val)
void	indexSetND (const size_t const perDimIdx, const size_t *perDimCount, int nd, const Value &val)
	ND subscript write for arbitrary rank.
void	indexDelete (const size_t indices, size_t count, std::pmr::memory_resource mr=nullptr)
void	indexDelete2D (const size_t rowIdx, size_t nrows, const size_t colIdx, size_t ncols, std::pmr::memory_resource *mr=nullptr)
void	indexDelete3D (const size_t rowIdx, size_t nrows, const size_t colIdx, size_t ncols, const size_t pageIdx, size_t npages, std::pmr::memory_resource mr=nullptr)
void	indexDeleteND (const size_t const perDimIdx, const size_t perDimCount, int nd, std::pmr::memory_resource mr=nullptr)
const std::string &	stringElem (size_t i) const
void	stringElemSet (size_t i, const std::string &s)
ValueType	type () const
const Dims &	dims () const
size_t	numel () const
bool	isScalar () const
bool	isEmpty () const
bool	isNumeric () const
bool	isUnset () const
bool	isDeleted () const
bool	isComplex () const
bool	isLogical () const
bool	isChar () const
bool	isCell () const
bool	isStruct () const
bool	isFuncHandle () const
bool	isString () const
bool	isObject () const
bool	isCsl () const
std::string	objectClassName () const
bool	objectIsHandle () const
size_t	objectCount () const
const ObjectState *	objectStateConst () const
ObjectState *	objectStateMut ()
const ObjectState *	objectStateAt (size_t i) const
ObjectState *	objectStateMutAt (size_t i)
Value	objectSubArray (const std::vector< size_t > &idxs, std::pmr::memory_resource *mr=nullptr) const
Value	objectReshape (const Dims &newDims, std::pmr::memory_resource *mr=nullptr) const
Value	objectTranspose (std::pmr::memory_resource *mr=nullptr) const
Value	objectGather (const size_t srcLinear, const Dims &resultDims, std::pmr::memory_resource mr=nullptr) const
void	objectAssignLinear (const std::vector< size_t > &pos, const Value &rhs, const Value &fill, std::pmr::memory_resource *mr=nullptr)
void	objectAssignND (const std::vector< std::vector< size_t > > &perDim, const Value &rhs, const Value &fill, std::pmr::memory_resource *mr=nullptr)
const void *	rawData () const
size_t	rawBytes () const
size_t	deepBytes () const
const double *	doubleData () const
const uint8_t *	logicalData () const
const char *	charData () const
double	toScalar () const
bool	toBool () const
std::string	toString () const
const float *	singleData () const
const int8_t *	int8Data () const
const int16_t *	int16Data () const
const int32_t *	int32Data () const
const int64_t *	int64Data () const
const uint8_t *	uint8Data () const
const uint16_t *	uint16Data () const
const uint32_t *	uint32Data () const
const uint64_t *	uint64Data () const
const Complex *	complexData () const
Complex	toComplex () const
Complex	complexElem (size_t i) const
Complex	complexElem (size_t r, size_t c) const
double *	doubleDataMut ()
float *	singleDataMut ()
uint8_t *	logicalDataMut ()
char *	charDataMut ()
void *	rawDataMut ()
Complex *	complexDataMut ()
int8_t *	int8DataMut ()
int16_t *	int16DataMut ()
int32_t *	int32DataMut ()
int64_t *	int64DataMut ()
uint8_t *	uint8DataMut ()
uint16_t *	uint16DataMut ()
uint32_t *	uint32DataMut ()
uint64_t *	uint64DataMut ()
double	operator() (size_t i) const
double	operator() (size_t r, size_t c) const
double	operator() (size_t r, size_t c, size_t p) const
double &	elem (size_t i)
double &	elem (size_t r, size_t c)
double &	elem (size_t r, size_t c, size_t p)
char	charElem (size_t i) const
char &	charElemMut (size_t i)
std::string	charRow (size_t r) const
void	resize (size_t newRows, size_t newCols, std::pmr::memory_resource *mr=nullptr)
void	resize3d (size_t newRows, size_t newCols, size_t newPages, std::pmr::memory_resource *mr=nullptr)
void	resizeND (const size_t newDims, int nd, std::pmr::memory_resource mr=nullptr)
void	ensureSize (size_t linearIdx, std::pmr::memory_resource *mr=nullptr)
void	appendScalar (double v, std::pmr::memory_resource *mr=nullptr)
void	appendScalarCol (double v, std::pmr::memory_resource *mr=nullptr)
void	promoteToComplex (std::pmr::memory_resource *mr=nullptr)
Value &	cellAt (size_t i)
const Value &	cellAt (size_t i) const
size_t	cslCount () const
Value &	cslAt (size_t i)
const Value &	cslAt (size_t i) const
size_t	growCellTo (const size_t coords, int nd, std::pmr::memory_resource mr=nullptr)
std::pmr::vector< Value > &	cellDataVec ()
const std::pmr::vector< Value > &	cellDataVec () const
Value &	field (const std::string &name)
const Value &	field (const std::string &name) const
bool	hasField (const std::string &name) const
std::pmr::map< std::string, Value > &	structFields ()
const std::pmr::map< std::string, Value > &	structFields () const
void	setField (size_t linearIdx, const std::string &name, const Value &v)
void	setFieldAll (const std::string &name, const Value &v)
void	removeField (const std::string &name)
std::vector< std::string >	fieldNamesInOrder () const
bool	isStructArray () const
std::pmr::map< std::string, Value > &	structArrayElem (size_t i)
void	growStructArrayTo (size_t idx, std::pmr::memory_resource *mr=nullptr)
size_t	growStructArrayND (const size_t coords, int nd, std::pmr::memory_resource mr=nullptr)
const std::pmr::map< std::string, Value > &	structArrayElem (size_t i) const
std::string	funcHandleName () const
std::string	funcHandleSource () const
	Reconstructed source text of an anonymous-function handle (e.g.
void	setFuncHandleSource (const std::string &source)
	Attach the anonymous-function source text to a freshly-created handle.
std::string	debugString () const
std::string	formatDisplay (const std::string &name) const
bool	isDoubleScalar () const
double	scalarVal () const
void	setScalarVal (double v)
void	setScalarFast (double v)
void	setLogicalFast (bool v)
bool	isLogicalScalar () const
double	fastScalarVal () const
bool	isHeapDouble () const
const Dims &	heapDims () const
int	heapRefCount () const
bool	hasHeap () const
double *	doubleDataMutFast ()
const double *	doubleDataFast () const
void	swapHeapBufferUnchecked (Value &other) noexcept

Static Public Member Functions
static Value	view (const void *data, ValueType type, Dims dims)
	Non-owning view over an externally-owned buffer.
static Value	scalar (double v, std::pmr::memory_resource *mr=nullptr)
static Value	logicalScalar (bool v, std::pmr::memory_resource *mr=nullptr)
static Value	matrix (size_t rows, size_t cols, ValueType t=ValueType::DOUBLE, std::pmr::memory_resource *mr=nullptr)
static Value	matrix3d (size_t rows, size_t cols, size_t pages, ValueType t=ValueType::DOUBLE, std::pmr::memory_resource *mr=nullptr)
static Value	matrixND (const size_t dims, int nd, ValueType t=ValueType::DOUBLE, std::pmr::memory_resource mr=nullptr)
static Value	fromString (const std::string &s, std::pmr::memory_resource *mr=nullptr)
static Value	cell (size_t rows, size_t cols, std::pmr::memory_resource *mr=nullptr)
static Value	cell3D (size_t rows, size_t cols, size_t pages, std::pmr::memory_resource *mr=nullptr)
static Value	cellND (const size_t dims, int nd, std::pmr::memory_resource mr=nullptr)
static Value	csl (size_t n, std::pmr::memory_resource *mr=nullptr)
static Value	structure (std::pmr::memory_resource *mr=nullptr)
static Value	structArray (size_t rows, size_t cols, std::pmr::memory_resource *mr=nullptr)
static Value	funcHandle (const std::string &name, std::pmr::memory_resource *mr=nullptr)
static Value	object (const std::string &className, std::shared_ptr< ObjectState > state, bool isHandle, std::pmr::memory_resource *mr=nullptr)
static Value	objectArray (const std::string &className, const Dims &dims, std::vector< std::shared_ptr< ObjectState > > states, bool isHandle, std::pmr::memory_resource *mr=nullptr)
static Value	empty ()
	Returns a default-constructed (Unset) Value — NOT a MATLAB empty matrix despite the name.
static Value	deleted ()
static Value	colonRange (double start, double stop, std::pmr::memory_resource *mr=nullptr)
static Value	colonRange (double start, double step, double stop, std::pmr::memory_resource *mr=nullptr)
static Value	colonRangeTyped (double start, double stop, ValueType t, std::pmr::memory_resource *mr=nullptr)
static Value	colonRangeTyped (double start, double step, double stop, ValueType t, std::pmr::memory_resource *mr=nullptr)
static size_t	colonCount (double start, double step, double stop)
static Value	horzcat (const Value elems, size_t count, std::pmr::memory_resource mr=nullptr)
static Value	vertcat (const Value elems, size_t count, std::pmr::memory_resource mr=nullptr)
static std::vector< size_t >	resolveIndices (const Value &idx, size_t dimSize)
static std::vector< size_t >	resolveIndicesUnchecked (const Value &idx)
static size_t	checkedScalarIndex (double oneBased)
static Value	complexScalar (Complex v, std::pmr::memory_resource *mr=nullptr)
static Value	complexScalar (double re, double im, std::pmr::memory_resource *mr=nullptr)
static Value	complexMatrix (size_t rows, size_t cols, std::pmr::memory_resource *mr=nullptr)
static Value	stringScalar (const std::string &s, std::pmr::memory_resource *mr=nullptr)
static Value	stringArray (size_t rows, size_t cols, std::pmr::memory_resource *mr=nullptr)
static Value	stringArray3D (size_t rows, size_t cols, size_t pages, std::pmr::memory_resource *mr=nullptr)
static Value	objectConcatN (const Value parts, size_t count, const Dims &outDims, std::pmr::memory_resource mr=nullptr)

Static Public Attributes
static const Value	Empty
	MATLAB-style empty matrix sentinel — a 0×0 DOUBLE value.

Detailed Description

Core MATLAB-compatible multidimensional array and scalar value type.

Represents scalars, matrices, multi-dimensional arrays, strings, cell arrays, and structures with copy-on-write (COW) semantics and polymorphic PMR memory resource allocation.

Definition at line 60 of file value.hpp.

Constructor & Destructor Documentation

◆ Value() [1/4]

nk::Value::Value	(	std::initializer_list< double >	il,
		std::pmr::memory_resource *	mr = nullptr )

Row vector from a brace-enclosed list of doubles.

Value v = {1.0, 2.0, 3.0}; // 1×3 DOUBLE

nk::Value::Value

Value()

Constructs an empty 0 x 0 double matrix ([]).

◆ Value() [2/4]

template<class T>

nk::Value::Value	(	Span< const T >	data,
		std::pmr::memory_resource *	mr = nullptr )

inline

Row vector from a contiguous span.

Definition at line 726 of file value.hpp.

◆ Value() [3/4]

template<class T>

nk::Value::Value	(	const std::vector< T > &	v,
		std::pmr::memory_resource *	mr = nullptr )

inline

Row vector from std::vector — copies all elements.

Definition at line 734 of file value.hpp.

◆ Value() [4/4]

template<class T, std::size_t N>

nk::Value::Value	(	const std::array< T, N > &	a,
		std::pmr::memory_resource *	mr = nullptr )

inline

Row vector from std::array — copies all elements.

Definition at line 742 of file value.hpp.

Member Function Documentation

◆ cslAt() [1/2]

Value & nk::Value::cslAt ( size_t i )

inline

Definition at line 494 of file value.hpp.

◆ cslAt() [2/2]

const Value & nk::Value::cslAt ( size_t i ) const

inline

Definition at line 495 of file value.hpp.

◆ doubleDataFast()

const double * nk::Value::doubleDataFast ( ) const

inline

Definition at line 637 of file value.hpp.

◆ doubleDataMutFast()

double * nk::Value::doubleDataMutFast ( )

inline

Definition at line 629 of file value.hpp.

◆ empty()

Value nk::Value::empty ( )

static

Returns a default-constructed (Unset) Value — NOT a MATLAB empty matrix despite the name.

New code should use Value::Empty for MATLAB-style empty (0×0 DOUBLE) or Value() directly for the unset sentinel.

◆ fastScalarVal()

double nk::Value::fastScalarVal ( ) const

inline

Definition at line 594 of file value.hpp.

◆ funcHandleSource()

std::string nk::Value::funcHandleSource ( ) const

Reconstructed source text of an anonymous-function handle (e.g.

"@(x)x+1"), set at creation; empty for named handles. Used by func2str.

◆ hasHeap()

bool nk::Value::hasHeap ( ) const

inline

Definition at line 622 of file value.hpp.

◆ heapDims()

const Dims & nk::Value::heapDims ( ) const

inline

Definition at line 607 of file value.hpp.

◆ heapRefCount()

int nk::Value::heapRefCount ( ) const

inline

Definition at line 612 of file value.hpp.

◆ indexGetND()

Value nk::Value::indexGetND	(	const size_t const	perDimIdx,
		const size_t *	perDimCount,
		int	nd,
		std::pmr::memory_resource *	mr = nullptr ) const

ND subscript read for arbitrary rank.

perDimIdx[i] points at a 0-based index list of length perDimCount[i] for dim i. nd ≤ 3 delegates to the 1D/2D/3D fast paths. CELL is not yet supported for nd > 3.

◆ indexSetND()

void nk::Value::indexSetND	(	const size_t const	perDimIdx,
		const size_t *	perDimCount,
		int	nd,
		const Value &	val )

ND subscript write for arbitrary rank.

nd ≤ 3 delegates. val is either a scalar (broadcast) or has numel == prod(perDimCount). No auto-expand for nd > 3 — out-of-range indices throw.

◆ isDeleted()

bool nk::Value::isDeleted ( ) const

inline

Definition at line 320 of file value.hpp.

◆ isDoubleScalar()

bool nk::Value::isDoubleScalar ( ) const

inline

Definition at line 568 of file value.hpp.

◆ isHeapDouble()

bool nk::Value::isHeapDouble ( ) const

inline

Definition at line 605 of file value.hpp.

◆ isLogicalScalar()

bool nk::Value::isLogicalScalar ( ) const

inline

Definition at line 590 of file value.hpp.

◆ isUnset()

bool nk::Value::isUnset ( ) const

inline

Definition at line 318 of file value.hpp.

◆ scalarVal()

double nk::Value::scalarVal ( ) const

inline

Definition at line 569 of file value.hpp.

◆ setLogicalFast()

void nk::Value::setLogicalFast ( bool v )

inline

Definition at line 583 of file value.hpp.

◆ setScalarFast()

void nk::Value::setScalarFast ( double v )

inline

Definition at line 576 of file value.hpp.

◆ setScalarVal()

void nk::Value::setScalarVal ( double v )

inline

Definition at line 570 of file value.hpp.

◆ swapHeapBufferUnchecked()

void nk::Value::swapHeapBufferUnchecked ( Value & other )

inlinenoexcept

Definition at line 652 of file value.hpp.

◆ view()

Value nk::Value::view	(	const void *	data,
		ValueType	type,
		Dims	dims )

static

Non-owning view over an externally-owned buffer.

Warning: Caller MUST keep data alive for as long as the returned Value (or any copy of it) is in use. The Value never frees data. Mutating via doubleDataMut etc. silently clones into a fresh owning buffer (COW).

double buf[1024];

Value v = Value::view(buf, ValueType::DOUBLE, Dims{1, 1024});

nk::Value::view

static Value view(const void *data, ValueType type, Dims dims)

Non-owning view over an externally-owned buffer.

nk::Dims

Definition dims.hpp:30

Member Data Documentation

◆ Empty

const Value nk::Value::Empty

static

MATLAB-style empty matrix sentinel — a 0×0 DOUBLE value.

Use as the default for optional const Value & parameters in public library API. Equivalent to MATLAB []. Inside the function, check via x.isEmpty() (or x.numel() == 0) which also catches truly Unset Values, giving uniform MATLAB-style "use default if empty" semantics.

isEmpty() = true isUnset() = false (distinct from default-constructed Value) type() = DOUBLE dims() = {0, 0}

Definition at line 136 of file value.hpp.

The documentation for this class was generated from the following file:

value.hpp

Public Member Functions

Static Public Member Functions

Static Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ Value() [1/4]

◆ Value() [2/4]

◆ Value() [3/4]

◆ Value() [4/4]

Member Function Documentation

◆ cslAt() [1/2]

◆ cslAt() [2/2]

◆ doubleDataFast()

◆ doubleDataMutFast()

◆ empty()

◆ fastScalarVal()

◆ funcHandleSource()

◆ hasHeap()

◆ heapDims()

◆ heapRefCount()

◆ indexGetND()

◆ indexSetND()

◆ isDeleted()

◆ isDoubleScalar()

◆ isHeapDouble()

◆ isLogicalScalar()

◆ isUnset()

◆ scalarVal()

◆ setLogicalFast()

◆ setScalarFast()

◆ setScalarVal()

◆ swapHeapBufferUnchecked()

◆ view()

Member Data Documentation

◆ Empty