LibraryLink Utilities  3.0.1
Modern C++ wrapper over LibraryLink and WSTP
LLU::NumericArray< T > Class Template Reference

Description

template<typename T>
class LLU::NumericArray< T >

This is a class template, where template parameter T is the type of data elements. NumericArray is derived from MArray.

NumericArray<> classes automate creation and deletion of MNumericArrays. They are strongly typed (no void* to underlying memory) and almost all functions from <algorithms> can be used on NumericArray.

Template Parameters
T- type of underlying data
+ Inheritance diagram for LLU::NumericArray< T >:
+ Collaboration diagram for LLU::NumericArray< T >:

#include <NumericArray.h>

Public Types

using value_type = T
 Type of elements stored. More...
 
using iterator = value_type *
 Iterator type. More...
 
using const_iterator = const value_type *
 Constant iterator type. More...
 
using reverse_iterator = std::reverse_iterator< iterator >
 Reverse iterator type. More...
 
using const_reverse_iterator = std::reverse_iterator< const_iterator >
 Constant reverse iterator type. More...
 
using reference = value_type &
 Reference type. More...
 
using const_reference = const value_type &
 Constant reference type. More...
 
using Container = Argument::CType< Type >
 The type of underlying LibraryLink structure (e.g. MTensor, MImage, etc.) will be called "Container". More...
 

Public Member Functions

 NumericArray (std::initializer_list< T > v)
 Constructs flat NumericArray based on a list of elements. More...
 
template<class Container , typename = std::enable_if_t<is_iterable_container_with_matching_type_v<Container, T> && has_size_v<Container>>>
 NumericArray (const Container &c)
 Constructs flat NumericArray with contents copied from a given collection of data. More...
 
template<class Container , typename = std::enable_if_t<is_iterable_container_with_matching_type_v<Container, T>>>
 NumericArray (const Container &c, MArrayDimensions dims)
 Constructs a NumericArray with contents copied from a given collection of data and dimensions passed as parameter. More...
 
template<class InputIt , typename = enable_if_input_iterator<InputIt>>
 NumericArray (InputIt first, InputIt last)
 Constructs flat NumericArray with elements from range [first, last) More...
 
 NumericArray (T init, MArrayDimensions dims)
 Constructs the NumericArray of given shape with all elements initialized to given value. More...
 
template<class InputIt , typename = enable_if_input_iterator<InputIt>>
 NumericArray (InputIt first, InputIt last, MArrayDimensions dims)
 Constructs the NumericArray of given shape with elements from range [first, last) More...
 
 NumericArray (MNumericArray na, Ownership owner)
 Constructs NumericArray based on MNumericArray. More...
 
 NumericArray (GenericNumericArray na)
 Create new NumericArray from a GenericNumericArray. More...
 
 NumericArray (const GenericNumericArray &other, NA::ConversionMethod method, double param=0.0)
 Create NumericArray from generic NumericArray. More...
 
 NumericArray ()=default
 Default constructor, creates a "hollow" NumericArray that does not have underlying MNumericArray. More...
 
NumericArray clone () const
 Clone this NumericArray, performing a deep copy of the underlying MNumericArray. More...
 
mint rank () const noexcept
 Get container rank. More...
 
bool empty () const noexcept
 Check whether container is empty. More...
 
mint dimension (mint index) const
 Get dimension value at position index. More...
 
const MArrayDimensionsdimensions () const
 Get a const reference to dimensions object. More...
 
T & operator[] (const std::vector< mint > &indices)
 Get a reference to the data element at given position in a multidimensional container. More...
 
const T & operator[] (const std::vector< mint > &indices) const
 Get a constant reference to the data element at given position in a multidimensional container. More...
 
reference operator[] (mint index)
 Get a reference to the data element at given position. More...
 
const_reference operator[] (mint index) const
 Get a constant reference to the data element at given position. More...
 
T & at (mint index)
 Get a reference to the data element at given position with bound checking. More...
 
const T & at (mint index) const
 Get a constant reference to the data element at given position with bound checking. More...
 
T & at (const std::vector< mint > &indices)
 Get a reference to the data element at given position in a multidimensional container. More...
 
const T & at (const std::vector< mint > &indices) const
 Get a constant reference to the data element at given position in a multidimensional container. More...
 
value_typedata () noexcept
 Get raw pointer to underlying data. More...
 
const value_typedata () const noexcept
 Get raw pointer to const underlying data. More...
 
mint size () const noexcept
 Get total number of elements in the container. More...
 
iterator begin () noexcept
 Get iterator at the beginning of underlying data. More...
 
const_iterator begin () const noexcept
 Get constant iterator at the beginning of underlying data. More...
 
const_iterator cbegin () const noexcept
 Get constant iterator at the beginning of underlying data. More...
 
iterator end () noexcept
 Get iterator after the end of underlying data. More...
 
const_iterator end () const noexcept
 Get constant iterator after the end of underlying data. More...
 
const_iterator cend () const noexcept
 Get constant iterator after the end of underlying data. More...
 
reverse_iterator rbegin () noexcept
 Get iterator at the beginning of underlying data. More...
 
const_reverse_iterator rbegin () const noexcept
 Get constant iterator at the beginning of underlying data. More...
 
const_reverse_iterator crbegin () const noexcept
 Get constant iterator at the beginning of underlying data. More...
 
reverse_iterator rend () noexcept
 Get iterator after the end of underlying data. More...
 
const_reverse_iterator rend () const noexcept
 Get constant iterator after the end of underlying data. More...
 
const_reverse_iterator crend () const noexcept
 Get constant iterator after the end of underlying data. More...
 
reference front ()
 Get reference to the first element. More...
 
const_reference front () const
 Get constant reference to the first element. More...
 
reference back ()
 Get reference to the last element. More...
 
const_reference back () const
 Get constant reference to the last element. More...
 
std::vector< value_typeasVector () const
 Copy contents of the data to a std::vector of matching type. More...
 
GenericNumericArray convert (numericarray_data_t t, NA::ConversionMethod method, double param) const
 Convert this object to a new GenericNumericArray of given datatype, using specified conversion method. More...
 
mint getRank () const override
 Get rank. More...
 
mint const * getDimensions () const override
 Get dimensions. More...
 
mint getFlattenedLength () const override
 Get length. More...
 
numericarray_data_t type () const override
 Get the data type of this array. More...
 
void * rawData () const noexcept override
 Get access to the raw data. More...
 
Container getContainer () const noexcept
 Get internal container. More...
 
Container abandonContainer () const noexcept
 Give a handle to internal container and stop owning it. More...
 
mint shareCount () const noexcept
 Return share count of internal container, if present and 0 otherwise. More...
 
void pass (MArgument &res) const
 Pass the internal container as result of a LibraryLink function. More...
 
Ownership getOwner () const noexcept
 Get ownership information. More...
 

Protected Member Functions

Container cloneContainer () const
 Clone the raw container, if it's present. More...
 
void disown () const noexcept
 Disown internal container if present. More...
 
void free () const noexcept
 Free internal container if present. More...
 
void reset (Container newCont, Ownership newOwnerMode=Ownership::Library) noexcept
 Set a new internal container safely disposing of the old one. More...
 

Type aliases documentation

◆ const_iterator

template<typename T >
using LLU::IterableContainer< T >::const_iterator = const value_type*
inherited

Constant iterator type.

◆ const_reference

template<typename T >
using LLU::IterableContainer< T >::const_reference = const value_type&
inherited

Constant reference type.

◆ const_reverse_iterator

template<typename T >
using LLU::IterableContainer< T >::const_reverse_iterator = std::reverse_iterator<const_iterator>
inherited

Constant reverse iterator type.

◆ Container

using LLU::MContainerBase< Type >::Container = Argument::CType<Type>
inherited

The type of underlying LibraryLink structure (e.g. MTensor, MImage, etc.) will be called "Container".

◆ iterator

template<typename T >
using LLU::IterableContainer< T >::iterator = value_type*
inherited

Iterator type.

◆ reference

template<typename T >
using LLU::IterableContainer< T >::reference = value_type&
inherited

Reference type.

◆ reverse_iterator

template<typename T >
using LLU::IterableContainer< T >::reverse_iterator = std::reverse_iterator<iterator>
inherited

Reverse iterator type.

◆ value_type

template<typename T >
using LLU::IterableContainer< T >::value_type = T
inherited

Type of elements stored.

Constructor & Destructor Documentation

◆ NumericArray() [1/10]

template<typename T >
LLU::NumericArray< T >::NumericArray ( std::initializer_list< T >  v)

Constructs flat NumericArray based on a list of elements.

Parameters
[in]v- initializer list with NumericArray elements
Exceptions
seeNumericArray<T>::NumericArray(InputIt, InputIt, std::initializer_list<mint>)
Warning
It is user's responsibility to make sure that length of v fits into mint!

◆ NumericArray() [2/10]

template<typename T >
template<class Container , typename = std::enable_if_t<is_iterable_container_with_matching_type_v<Container, T> && has_size_v<Container>>>
LLU::NumericArray< T >::NumericArray ( const Container c)
inlineexplicit

Constructs flat NumericArray with contents copied from a given collection of data.

Template Parameters
Container- any iterable (begin(), end()) collection of data that has a value_type alias member and a size() member function
Parameters
c- const reference to a collection from which data will be copied to the NumericArray

◆ NumericArray() [3/10]

template<typename T >
template<class Container , typename = std::enable_if_t<is_iterable_container_with_matching_type_v<Container, T>>>
LLU::NumericArray< T >::NumericArray ( const Container c,
MArrayDimensions  dims 
)
inline

Constructs a NumericArray with contents copied from a given collection of data and dimensions passed as parameter.

Template Parameters
Container- any iterable (begin(), end()) collection of data that has a value_type alias member
Parameters
c- const reference to a collection from which data will be copied to the NumericArray
dims- dimensions of the NumericArray

◆ NumericArray() [4/10]

template<typename T >
template<class InputIt , typename >
LLU::NumericArray< T >::NumericArray ( InputIt  first,
InputIt  last 
)

Constructs flat NumericArray with elements from range [first, last)

Parameters
[in]first- iterator to the beginning of range
[in]last- iterator past the end of range
Template Parameters
InputIt- any iterator conforming to InputIterator concept
Exceptions
seeNumericArray<T>::NumericArray(InputIt, InputIt, std::initializer_list<mint>)
Warning
It is user's responsibility to make sure that length of range fits into mint!
Note
Be aware that efficiency of this constructor strongly depends on whether the InputIt is also a RandomAccessIterator

◆ NumericArray() [5/10]

template<typename T >
LLU::NumericArray< T >::NumericArray ( init,
MArrayDimensions  dims 
)

Constructs the NumericArray of given shape with all elements initialized to given value.

Parameters
[in]init- value of type T to initialize all elements of the NumericArray
[in]dims- container with NumericArray dimensions

◆ NumericArray() [6/10]

template<typename T >
template<class InputIt , typename >
LLU::NumericArray< T >::NumericArray ( InputIt  first,
InputIt  last,
MArrayDimensions  dims 
)

Constructs the NumericArray of given shape with elements from range [first, last)

Parameters
[in]first- iterator to the beginning of range
[in]last- iterator past the end of range
[in]dims- container with NumericArray dimensions
Template Parameters
Container- any type of container that has member value_type and this type is convertible to mint
Exceptions
ErrorName::NumericArrayNewError- if number of elements in v does not match total NumericArray size indicated by dims
seeNumericArray<T>::createInternal() and MArray<T>::MArray(Container&&)

◆ NumericArray() [7/10]

template<typename T >
LLU::NumericArray< T >::NumericArray ( MNumericArray< T >  na,
Ownership  owner 
)

Constructs NumericArray based on MNumericArray.

Parameters
[in]na- LibraryLink structure to be wrapped
[in]owner- who manages the memory the raw MNumericArray
Exceptions
ErrorName::NumericArrayTypeError- if the NumericArray template type T does not match the actual data type of the MNumericArray

◆ NumericArray() [8/10]

template<typename T >
LLU::NumericArray< T >::NumericArray ( GenericNumericArray< T >  na)
explicit

Create new NumericArray from a GenericNumericArray.

Parameters
[in]na- generic NumericArray to be wrapped into NumericArray class
Exceptions
ErrorName::NumericArrayTypeError- if the NumericArray template type T does not match the actual data type of the generic NumericArray

◆ NumericArray() [9/10]

template<typename T >
LLU::NumericArray< T >::NumericArray ( const GenericNumericArray< T > &  other,
NA::ConversionMethod  method,
double  param = 0.0 
)
explicit

Create NumericArray from generic NumericArray.

Parameters
[in]other- const reference to a generic NumericArray
[in]method- conversion method to be used, when in doubt use NA::ConversionMethod::ClipRound as default
[in]param- conversion tolerance

◆ NumericArray() [10/10]

template<typename T >
LLU::NumericArray< T >::NumericArray ( )
default

Default constructor, creates a "hollow" NumericArray that does not have underlying MNumericArray.

Member Function Documentation

◆ abandonContainer()

Container LLU::MContainerBase< Type >::abandonContainer ( ) const
inlinenoexceptinherited

Give a handle to internal container and stop owning it.

Should be used with caution as it may potentially result with resource leak.

Returns
a handle to the internal container

◆ asVector()

template<typename T >
std::vector<value_type> LLU::IterableContainer< T >::asVector ( ) const
inlineinherited

Copy contents of the data to a std::vector of matching type.

Returns
std::vector with the copy of the data

◆ at() [1/4]

template<typename T >
T & LLU::MArray< T >::at ( const std::vector< mint > &  indices)
inherited

Get a reference to the data element at given position in a multidimensional container.

Parameters
[in]indices- vector with coordinates of desired data element
Exceptions
indexError()- if indices are out-of-bounds

◆ at() [2/4]

template<typename T >
const T & LLU::MArray< T >::at ( const std::vector< mint > &  indices) const
inherited

Get a constant reference to the data element at given position in a multidimensional container.

Parameters
[in]indices- vector with coordinates of desired data element
Exceptions
indexError()- if indices are out-of-bounds

◆ at() [3/4]

template<typename T >
T & LLU::MArray< T >::at ( mint  index)
inherited

Get a reference to the data element at given position with bound checking.

Parameters
[in]index- position of desired data element
Exceptions
indexError()- if index is out-of-bounds

◆ at() [4/4]

template<typename T >
const T & LLU::MArray< T >::at ( mint  index) const
inherited

Get a constant reference to the data element at given position with bound checking.

Parameters
[in]index- position of desired data element
Exceptions
indexError()- if index is out-of-bounds

◆ back() [1/2]

template<typename T >
reference LLU::IterableContainer< T >::back ( )
inlineinherited

Get reference to the last element.

Note
For empty container the behavior is undefined.

◆ back() [2/2]

template<typename T >
const_reference LLU::IterableContainer< T >::back ( ) const
inlineinherited

Get constant reference to the last element.

Note
For empty container the behavior is undefined.

◆ begin() [1/2]

template<typename T >
const_iterator LLU::IterableContainer< T >::begin ( ) const
inlinenoexceptinherited

Get constant iterator at the beginning of underlying data.

◆ begin() [2/2]

template<typename T >
iterator LLU::IterableContainer< T >::begin ( )
inlinenoexceptinherited

Get iterator at the beginning of underlying data.

◆ cbegin()

template<typename T >
const_iterator LLU::IterableContainer< T >::cbegin ( ) const
inlinenoexceptinherited

Get constant iterator at the beginning of underlying data.

◆ cend()

template<typename T >
const_iterator LLU::IterableContainer< T >::cend ( ) const
inlinenoexceptinherited

Get constant iterator after the end of underlying data.

◆ clone()

template<typename T >
NumericArray LLU::NumericArray< T >::clone ( ) const
inline

Clone this NumericArray, performing a deep copy of the underlying MNumericArray.

Note
The cloned MNumericArray always belongs to the library (Ownership::Library) because LibraryLink has no idea of its existence.
Returns
new NumericArray

◆ cloneContainer()

Container LLU::MContainerBase< Type >::cloneContainer ( ) const
inlineprotectedinherited

Clone the raw container, if it's present.

Returns
cloned container or nullptr if there is no internal container

◆ convert()

GenericNumericArray LLU::GenericNumericArray::convert ( numericarray_data_t  t,
NA::ConversionMethod  method,
double  param 
) const
inherited

Convert this object to a new GenericNumericArray of given datatype, using specified conversion method.

Parameters
t- destination data type
method- conversion method
param- conversion method parameter (aka tolerance)
Returns
converted GenericNumericArray owned by the Library
See also
http://reference.wolfram.com/language/LibraryLink/ref/callback/MNumericArray_convertType.html

◆ crbegin()

template<typename T >
const_reverse_iterator LLU::IterableContainer< T >::crbegin ( ) const
inlinenoexceptinherited

Get constant iterator at the beginning of underlying data.

◆ crend()

template<typename T >
const_reverse_iterator LLU::IterableContainer< T >::crend ( ) const
inlinenoexceptinherited

Get constant iterator after the end of underlying data.

◆ data() [1/2]

template<typename T >
const value_type* LLU::IterableContainer< T >::data ( ) const
inlinenoexceptinherited

Get raw pointer to const underlying data.

◆ data() [2/2]

template<typename T >
value_type* LLU::IterableContainer< T >::data ( )
inlinenoexceptinherited

Get raw pointer to underlying data.

◆ dimension()

template<typename T >
mint LLU::MArray< T >::dimension ( mint  index) const
inlineinherited

Get dimension value at position index.

◆ dimensions()

template<typename T >
const MArrayDimensions& LLU::MArray< T >::dimensions ( ) const
inlineinherited

Get a const reference to dimensions object.

◆ disown()

void LLU::MContainerBase< Type >::disown ( ) const
inlineprotectednoexceptinherited

Disown internal container if present.

◆ empty()

template<typename T >
bool LLU::MArray< T >::empty ( ) const
inlinenoexceptinherited

Check whether container is empty.

◆ end() [1/2]

template<typename T >
const_iterator LLU::IterableContainer< T >::end ( ) const
inlinenoexceptinherited

Get constant iterator after the end of underlying data.

◆ end() [2/2]

template<typename T >
iterator LLU::IterableContainer< T >::end ( )
inlinenoexceptinherited

Get iterator after the end of underlying data.

◆ free()

void LLU::MContainerBase< Type >::free ( ) const
inlineprotectednoexceptinherited

Free internal container if present.

◆ front() [1/2]

template<typename T >
reference LLU::IterableContainer< T >::front ( )
inlineinherited

Get reference to the first element.

Note
For empty container the behavior is undefined.

◆ front() [2/2]

template<typename T >
const_reference LLU::IterableContainer< T >::front ( ) const
inlineinherited

Get constant reference to the first element.

Note
For empty container the behavior is undefined.

◆ getContainer()

Container LLU::MContainerBase< Type >::getContainer ( ) const
inlinenoexceptinherited

Get internal container.

Returns
a handle to the internal container

◆ getDimensions()

mint const* LLU::MContainer< MArgumentType::NumericArray >::getDimensions ( ) const
inlineoverridevirtualinherited

Get dimensions.

Returns
raw pointer to dimensions of the array
See also
http://reference.wolfram.com/language/LibraryLink/ref/callback/MNumericArray_getDimensions.html

Implements LLU::NumericArrayInterface.

◆ getFlattenedLength()

mint LLU::MContainer< MArgumentType::NumericArray >::getFlattenedLength ( ) const
inlineoverridevirtualinherited

◆ getOwner()

Ownership LLU::MContainerBase< Type >::getOwner ( ) const
inlinenoexceptinherited

Get ownership information.

Returns
the owner of the internal container

◆ getRank()

mint LLU::MContainer< MArgumentType::NumericArray >::getRank ( ) const
inlineoverridevirtualinherited

◆ operator[]() [1/4]

template<typename T >
T& LLU::MArray< T >::operator[] ( const std::vector< mint > &  indices)
inlineinherited

Get a reference to the data element at given position in a multidimensional container.

Parameters
[in]indices- vector with coordinates of desired data element

◆ operator[]() [2/4]

template<typename T >
const T& LLU::MArray< T >::operator[] ( const std::vector< mint > &  indices) const
inlineinherited

Get a constant reference to the data element at given position in a multidimensional container.

Parameters
[in]indices- vector with coordinates of desired data element

◆ operator[]() [3/4]

template<typename T >
reference LLU::IterableContainer< T >::operator[] ( mint  index)
inlineinherited

Get a reference to the data element at given position.

Parameters
[in]index- position of desired data element

◆ operator[]() [4/4]

template<typename T >
const_reference LLU::IterableContainer< T >::operator[] ( mint  index) const
inlineinherited

Get a constant reference to the data element at given position.

Parameters
[in]index- position of desired data element

◆ pass()

void LLU::MContainerBase< Type >::pass ( MArgument &  res) const
inlineinherited

Pass the internal container as result of a LibraryLink function.

Parameters
res- MArgument which will hold internal container of this MContainerBase

◆ rank()

template<typename T >
mint LLU::MArray< T >::rank ( ) const
inlinenoexceptinherited

Get container rank.

◆ rawData()

void* LLU::MContainer< MArgumentType::NumericArray >::rawData ( ) const
inlineoverridevirtualnoexceptinherited

Get access to the raw data.

Use with caution.

Returns
pointer to the raw data
See also
http://reference.wolfram.com/language/LibraryLink/ref/callback/MNumericArray_getData.html

Implements LLU::NumericArrayInterface.

◆ rbegin() [1/2]

template<typename T >
const_reverse_iterator LLU::IterableContainer< T >::rbegin ( ) const
inlinenoexceptinherited

Get constant iterator at the beginning of underlying data.

◆ rbegin() [2/2]

template<typename T >
reverse_iterator LLU::IterableContainer< T >::rbegin ( )
inlinenoexceptinherited

Get iterator at the beginning of underlying data.

◆ rend() [1/2]

template<typename T >
const_reverse_iterator LLU::IterableContainer< T >::rend ( ) const
inlinenoexceptinherited

Get constant iterator after the end of underlying data.

◆ rend() [2/2]

template<typename T >
reverse_iterator LLU::IterableContainer< T >::rend ( )
inlinenoexceptinherited

Get iterator after the end of underlying data.

◆ reset()

void LLU::MContainerBase< Type >::reset ( Container  newCont,
Ownership  newOwnerMode = Ownership::Library 
)
inlineprotectednoexceptinherited

Set a new internal container safely disposing of the old one.

Parameters
newCont- new internal container
newOwnerMode- owner of the new container

◆ shareCount()

mint LLU::MContainerBase< Type >::shareCount ( ) const
inlinenoexceptinherited

Return share count of internal container, if present and 0 otherwise.

◆ size()

template<typename T >
mint LLU::IterableContainer< T >::size ( ) const
inlinenoexceptinherited

Get total number of elements in the container.

◆ type()

numericarray_data_t LLU::MContainer< MArgumentType::NumericArray >::type ( ) const
inlineoverridevirtualinherited

Get the data type of this array.

Returns
type of elements (see definition of numericarray_data_t)
See also
http://reference.wolfram.com/language/LibraryLink/ref/callback/MNumericArray_getDataType.html

Implements LLU::NumericArrayInterface.