mdds
Loading...
Searching...
No Matches
mdds::multi_type_matrix< Traits > Class Template Reference

#include <multi_type_matrix.hpp>

Classes

struct  size_pair_type
struct  element_block_node_type

Public Types

using numeric_block_type = typename traits_type::numeric_element_block
using numeric_type = typename numeric_block_type::value_type
using size_type = std::size_t
using position_type = typename store_type::position_type
using const_position_type = typename store_type::const_position_type
using element_block_type = typename mtv::base_element_block

Public Member Functions

 multi_type_matrix () noexcept(nothrow_default_constructible_v)
 multi_type_matrix (size_type rows, size_type cols)
template<typename _T>
 multi_type_matrix (size_type rows, size_type cols, const _T &value)
template<typename _T>
 multi_type_matrix (size_type rows, size_type cols, const _T &it_begin, const _T &it_end)
 multi_type_matrix (const multi_type_matrix &other)
 multi_type_matrix (multi_type_matrix &&other)=default
 ~multi_type_matrix ()=default
bool operator== (const multi_type_matrix &other) const noexcept(nothrow_eq_comparable_v)
multi_type_matrix & operator= (const multi_type_matrix &other)=default
multi_type_matrix & operator= (multi_type_matrix &&other)=default
position_type position (size_type row, size_type col)
position_type position (const position_type &pos_hint, size_type row, size_type col)
const_position_type position (size_type row, size_type col) const
const_position_type position (const const_position_type &pos_hint, size_type row, size_type col) const
size_pair_type matrix_position (const const_position_type &pos) const
position_type end_position ()
const_position_type end_position () const
mtm::element_t get_type (const const_position_type &pos) const
mtm::element_t get_type (size_type row, size_type col) const
numeric_type get_numeric (size_type row, size_type col) const
numeric_type get_numeric (const const_position_type &pos) const
template<typename T>
T get (size_type row, size_type col) const
template<typename T>
T get (const const_position_type &pos) const
template<mtm::detail::referenceable_value_type< typename mtm::detail::block_list_of< Traits >::type > T>
const T & get_ref (size_type row, size_type col) const
template<mtm::detail::referenceable_value_type< typename mtm::detail::block_list_of< Traits >::type > T>
const T & get_ref (const const_position_type &pos) const
void set_empty (size_type row, size_type col)
void set_empty (size_type row, size_type col, size_type length)
position_type set_empty (const position_type &pos)
void set_column_empty (size_type col)
void set_row_empty (size_type row)
void set (size_type row, size_type col, numeric_type val)
position_type set (const position_type &pos, numeric_type val)
template<mtm::detail::listed_value_type< typename mtm::detail::element_blocks_of< Traits >::type > T>
void set (size_type row, size_type col, const T &val)
template<mtm::detail::listed_value_type< typename mtm::detail::element_blocks_of< Traits >::type > T>
position_type set (const position_type &pos, const T &val)
template<typename _T>
void set (size_type row, size_type col, const _T &it_begin, const _T &it_end)
template<typename _T>
position_type set (const position_type &pos, const _T &it_begin, const _T &it_end)
template<typename _T>
void set_column (size_type col, const _T &it_begin, const _T &it_end)
size_pair_type size () const
multi_type_matrix & transpose ()
void copy (const multi_type_matrix &src)
template<typename _T>
void copy (size_type rows, size_type cols, const _T &it_begin, const _T &it_end)
void resize (size_type rows, size_type cols)
template<typename _T>
void resize (size_type rows, size_type cols, const _T &value)
void clear ()
bool numeric () const
template<typename... Blks>
bool all_of () const
bool empty () const
void swap (multi_type_matrix &r)
template<typename FuncT>
FuncT walk (FuncT func) const
template<typename FuncT>
FuncT walk (FuncT func, const size_pair_type &start, const size_pair_type &end) const
template<typename FuncT>
FuncT walk (FuncT func, const multi_type_matrix &right) const
template<typename FuncT>
FuncT walk (FuncT func, const multi_type_matrix &right, const size_pair_type &start, const size_pair_type &end) const

Static Public Member Functions

static position_type next_position (const position_type &pos)
static const_position_type next_position (const const_position_type &pos)

Static Public Attributes

static constexpr mtm::element_t element_empty = mtm::element_empty
static constexpr mtm::element_t element_numeric = numeric_block_type::block_type

Detailed Description

template<mtm::matrix_traits Traits>
class mdds::multi_type_matrix< Traits >

Matrix that can store numeric and empty elements, plus elements of any other type specified in the matrix traits template parameter. The matrix traits type specifies the element block type that stores the numeric elements, and the list of element block types that store all the other element types. See mdds::mtm::matrix_traits for the details. To store double, boolean, 32-bit integer and std::string values, use mdds::mtm::std_string_traits.

Internally it uses mdds::multi_type_vector as its value store. The element values are linearly stored in column-major order.

Constructor & Destructor Documentation

◆ multi_type_matrix() [1/6]

template<mtm::matrix_traits Traits>
mdds::multi_type_matrix< Traits >::multi_type_matrix ( ) const
noexcept

Default constructor.

◆ multi_type_matrix() [2/6]

template<mtm::matrix_traits Traits>
mdds::multi_type_matrix< Traits >::multi_type_matrix ( size_type rows,
size_type cols )

Construct a matrix of specified size.

Parameters
rowssize of rows.
colssize of columns.

◆ multi_type_matrix() [3/6]

template<mtm::matrix_traits Traits>
template<typename _T>
mdds::multi_type_matrix< Traits >::multi_type_matrix ( size_type rows,
size_type cols,
const _T & value )

Construct a matrix of specified size and initialize all its elements with specified value.

Parameters
rowssize of rows.
colssize of columns.
valuevalue to initialize all its elements with.

◆ multi_type_matrix() [4/6]

template<mtm::matrix_traits Traits>
template<typename _T>
mdds::multi_type_matrix< Traits >::multi_type_matrix ( size_type rows,
size_type cols,
const _T & it_begin,
const _T & it_end )

Construct a matrix of specified size and initialize its elements with specified values. The values are assigned to 2-dimensional matrix layout in column-major order. The size of the value array must equal rows x cols.

Parameters
rowssize of rows.
colssize of columns.
it_beginiterator that points to the value of the first element.
it_enditerator that points to the position after the last element value.

◆ multi_type_matrix() [5/6]

template<mtm::matrix_traits Traits>
mdds::multi_type_matrix< Traits >::multi_type_matrix ( const multi_type_matrix< Traits > & other)

Copy constructor.

◆ multi_type_matrix() [6/6]

template<mtm::matrix_traits Traits>
mdds::multi_type_matrix< Traits >::multi_type_matrix ( multi_type_matrix< Traits > && other)
default

Move constructor.

◆ ~multi_type_matrix()

template<mtm::matrix_traits Traits>
mdds::multi_type_matrix< Traits >::~multi_type_matrix ( )
default

Destructor.

Member Function Documentation

◆ all_of()

template<mtm::matrix_traits Traits>
template<typename... Blks>
bool mdds::multi_type_matrix< Traits >::all_of ( ) const

Check whether or not every element block of this matrix is one of the specified element block types. An empty element never matches, so a matrix that contains an empty element returns false. An empty matrix also returns false.

Each specified block type must be an element block of this matrix.

Returns
True if every element block is one of the specified block types, or false otherwise.

◆ clear()

template<mtm::matrix_traits Traits>
void mdds::multi_type_matrix< Traits >::clear ( )

Empty the matrix.

◆ copy() [1/2]

template<mtm::matrix_traits Traits>
void mdds::multi_type_matrix< Traits >::copy ( const multi_type_matrix< Traits > & src)

Copy values from the passed matrix instance. If the size of the passed matrix is smaller, then the element values are copied by their positions, while the rest of the elements that fall outside the size of the passed matrix instance will remain unmodified. If the size of the passed matrix instance is larger, then only the elements within the size of this matrix instance will get copied.

Parameters
srcpassed matrix object to copy element values from.

◆ copy() [2/2]

template<mtm::matrix_traits Traits>
template<typename _T>
void mdds::multi_type_matrix< Traits >::copy ( size_type rows,
size_type cols,
const _T & it_begin,
const _T & it_end )

Copy values from an array or array-like container, to a specified sub-matrix range. The length of the array must match the number of elements in the destination range, else it will throw a mdds::size_error.

Parameters
rowsrow size of the destination range.
colscolumn size of the destination range.
it_beginiterator pointing to the beginning of the input array.
it_enditerator pointing to the end position of the input array.

◆ empty()

template<mtm::matrix_traits Traits>
bool mdds::multi_type_matrix< Traits >::empty ( ) const

Check whether or not this matrix is empty.

Returns
true if this matrix is empty, or false otherwise.

◆ end_position() [1/2]

template<mtm::matrix_traits Traits>
position_type mdds::multi_type_matrix< Traits >::end_position ( )

Return a position type that represents an end position. This can be used to compare with another position object to see if it is past the last element position.

Returns
end position object.

◆ end_position() [2/2]

template<mtm::matrix_traits Traits>
const_position_type mdds::multi_type_matrix< Traits >::end_position ( ) const

Return a position type that represents an end position. This can be used to compare with another position object to see if it is past the last element position.

Returns
end position object.

◆ get() [1/2]

template<mtm::matrix_traits Traits>
template<typename T>
T mdds::multi_type_matrix< Traits >::get ( const const_position_type & pos) const

Get the value of element from a position object. The caller must explicitly specify the value type. If the element is empty, the empty value of the specified type is returned. If the element is of a different type, a mdds::type_error exception is thrown.

Parameters
posPosition object of an element.
Returns
Value of the element.

◆ get() [2/2]

template<mtm::matrix_traits Traits>
template<typename T>
T mdds::multi_type_matrix< Traits >::get ( size_type row,
size_type col ) const

Get the value of element at specified position. The caller must explicitly specify the value type. If the element is empty, the empty value of the specified type is returned. If the element is of a different type, a mdds::type_error exception is thrown.

Parameters
rowRow position of the element.
colColumn position of the element.
Returns
Value of the element.

◆ get_numeric() [1/2]

template<mtm::matrix_traits Traits>
numeric_type mdds::multi_type_matrix< Traits >::get_numeric ( const const_position_type & pos) const

Get the numeric value of the element from a position object. If the element is of numeric type, its value is returned. If it's empty, 0 is returned. If it's of any other type, a mdds::type_error exception is thrown.

Parameters
posPosition object of an element.
Returns
Numeric value of the element.

◆ get_numeric() [2/2]

template<mtm::matrix_traits Traits>
numeric_type mdds::multi_type_matrix< Traits >::get_numeric ( size_type row,
size_type col ) const

Get the numeric value of the element. If the element is of numeric type, its value is returned. If it's empty, 0 is returned. If it's of any other type, a mdds::type_error exception is thrown.

Parameters
rowRow position of the element.
colColumn position of the element.
Returns
Numeric value of the element.

◆ get_ref() [1/2]

template<mtm::matrix_traits Traits>
template<mtm::detail::referenceable_value_type< typename mtm::detail::block_list_of< Traits >::type > T>
const T & mdds::multi_type_matrix< Traits >::get_ref ( const const_position_type & pos) const

Get a reference to the value of element from a position object. The caller must explicitly specify the value type. Unlike get(), this method throws a mdds::type_error exception when the element is empty, since there is no stored value to reference. It also throws when the element is of a different type.

The reference stays valid until the matrix is next modified.

This method is disabled via requires clause for a value type whose element block does not provide references to its elements, such as a block backed by std::vector<bool>.

Parameters
posPosition object of an element.
Returns
Reference to the value of the element.

◆ get_ref() [2/2]

template<mtm::matrix_traits Traits>
template<mtm::detail::referenceable_value_type< typename mtm::detail::block_list_of< Traits >::type > T>
const T & mdds::multi_type_matrix< Traits >::get_ref ( size_type row,
size_type col ) const

Get a reference to the value of element at specified position. The caller must explicitly specify the value type. Unlike get(), this method throws a mdds::type_error exception when the element is empty, since there is no stored value to reference. It also throws when the element is of a different type.

The reference stays valid until the matrix is next modified.

This method is disabled via requires clause for a value type whose element block does not provide references to its elements, such as a block backed by std::vector<bool>.

Parameters
rowRow position of the element.
colColumn position of the element.
Returns
Reference to the value of the element.

◆ get_type() [1/2]

template<mtm::matrix_traits Traits>
mtm::element_t mdds::multi_type_matrix< Traits >::get_type ( const const_position_type & pos) const

Get the type of element from a position object. The type is either element_empty or the block type id of the element block that stores the element.

Parameters
posPosition object of an element.
Returns
Element type.

◆ get_type() [2/2]

template<mtm::matrix_traits Traits>
mtm::element_t mdds::multi_type_matrix< Traits >::get_type ( size_type row,
size_type col ) const

Get the type of element specified by its position. The type is either element_empty or the block type id of the element block that stores the element.

Parameters
rowRow position of the element.
colColumn position of the element.
Returns
Element type.

◆ matrix_position()

template<mtm::matrix_traits Traits>
size_pair_type mdds::multi_type_matrix< Traits >::matrix_position ( const const_position_type & pos) const

Get the row and column positions of the current element from a position object.

Parameters
posposition object.
Returns
0-based row and column positions.

◆ next_position() [1/2]

template<mtm::matrix_traits Traits>
const_position_type mdds::multi_type_matrix< Traits >::next_position ( const const_position_type & pos)
static

Move to the next logical position. The movement is in the top-to-bottom then left-to-right direction.

Parameters
posposition object.
Returns
non-mutable position object that references the element at the next logical position.

◆ next_position() [2/2]

template<mtm::matrix_traits Traits>
position_type mdds::multi_type_matrix< Traits >::next_position ( const position_type & pos)
static

Move to the next logical position. The movement is in the top-to-bottom then left-to-right direction.

Parameters
posposition object.
Returns
position object that references the element at the next logical position.

◆ numeric()

template<mtm::matrix_traits Traits>
bool mdds::multi_type_matrix< Traits >::numeric ( ) const

Check whether or not this matrix is numeric. A numeric matrix contains only numeric elements. An empty matrix is not numeric.

Returns
True if the matrix contains only numeric elements, or false otherwise.

◆ position() [1/4]

template<mtm::matrix_traits Traits>
const_position_type mdds::multi_type_matrix< Traits >::position ( const const_position_type & pos_hint,
size_type row,
size_type col ) const

Get an immutable reference of an element (position object) at specified position. The position object can then be passed to an additional method to get the type or value of the element it references.

Parameters
pos_hintposition object to be used as a position hint for faster lookup.
rowrow position of the referenced element.
colcolumn position of the referenced element.
Returns
reference object of element at specified position.

◆ position() [2/4]

template<mtm::matrix_traits Traits>
position_type mdds::multi_type_matrix< Traits >::position ( const position_type & pos_hint,
size_type row,
size_type col )

Get a mutable reference of an element (position object) at specified position. The position object can then be passed to an additional method to get the type or value of the element it references, or set a new value to it.

Parameters
pos_hintposition object to be used as a position hint for faster lookup.
rowrow position of the referenced element.
colcolumn position of the referenced element.
Returns
reference object of element at specified position.

◆ position() [3/4]

template<mtm::matrix_traits Traits>
position_type mdds::multi_type_matrix< Traits >::position ( size_type row,
size_type col )

Get a mutable reference of an element (position object) at specified position. The position object can then be passed to an additional method to get the type or value of the element it references, or set a new value to it.

Parameters
rowrow position of the referenced element.
colcolumn position of the referenced element.
Returns
reference object of element at specified position.

◆ position() [4/4]

template<mtm::matrix_traits Traits>
const_position_type mdds::multi_type_matrix< Traits >::position ( size_type row,
size_type col ) const

Get an immutable reference of an element (position object) at specified position. The position object can then be passed to an additional method to get the type or value of the element it references.

Parameters
rowrow position of the referenced element.
colcolumn position of the referenced element.
Returns
reference object of element at specified position.

◆ resize() [1/2]

template<mtm::matrix_traits Traits>
void mdds::multi_type_matrix< Traits >::resize ( size_type rows,
size_type cols )

Resize the matrix to specified size. This method supports resizing to zero-sized matrix; however, either specifying the row or column size to zero will resize the matrix to 0 x 0. When resizing the matrix larger, empty elements will be inserted in the region where no elements existed prior to the call.

Parameters
rowsnew row size
colsnew column size

◆ resize() [2/2]

template<mtm::matrix_traits Traits>
template<typename _T>
void mdds::multi_type_matrix< Traits >::resize ( size_type rows,
size_type cols,
const _T & value )

Resize the matrix to specified size and initial value. The initial value will be applied to new elements created when the specified size is larger than the current one.

Parameters
rowsnew row size
colsnew column size
valueinitial value for new elements

◆ set() [1/6]

template<mtm::matrix_traits Traits>
template<typename _T>
position_type mdds::multi_type_matrix< Traits >::set ( const position_type & pos,
const _T & it_begin,
const _T & it_end )

Set values of multiple elements at once, starting at specified element position following the direction of columns. When the new value series does not fit in the first column, it gets wrapped into the next column(s).

Parameters
posposition of the first element.
it_beginiterator that points to the begin position of the values being set.
it_enditerator that points to the end position of the values being set.
Returns
position of the first element that has been modified.

◆ set() [2/6]

template<mtm::matrix_traits Traits>
template<mtm::detail::listed_value_type< typename mtm::detail::element_blocks_of< Traits >::type > T>
position_type mdds::multi_type_matrix< Traits >::set ( const position_type & pos,
const T & val )

Set a value to an element at specified position. The type of the value must be the value type of one of the element blocks listed in the element_blocks member of the matrix traits type.

Parameters
posPosition of the element to update.
valNew value to set.
Returns
Position of the element block where the new value has been set.

◆ set() [3/6]

template<mtm::matrix_traits Traits>
position_type mdds::multi_type_matrix< Traits >::set ( const position_type & pos,
numeric_type val )

Set a numeric value to an element at specified position.

Parameters
posposition of the element to update.
valnew value to set.
Returns
position of the element block where the new value has been set.

◆ set() [4/6]

template<mtm::matrix_traits Traits>
template<typename _T>
void mdds::multi_type_matrix< Traits >::set ( size_type row,
size_type col,
const _T & it_begin,
const _T & it_end )

Set values of multiple elements at once, starting at specified element position following the direction of columns. When the new value series does not fit in the first column, it gets wrapped into the next column(s).

The method will throw an std::out_of_range exception if the specified position is outside the current container range.

Parameters
rowrow position of the start element.
colcolumn position of the start element.
it_beginiterator that points to the begin position of the values being set.
it_enditerator that points to the end position of the values being set.

◆ set() [5/6]

template<mtm::matrix_traits Traits>
template<mtm::detail::listed_value_type< typename mtm::detail::element_blocks_of< Traits >::type > T>
void mdds::multi_type_matrix< Traits >::set ( size_type row,
size_type col,
const T & val )

Set a value to an element at specified position. The type of the value must be the value type of one of the element blocks listed in the element_blocks member of the matrix traits type.

Parameters
rowRow index of the element.
colColumn index of the element.
valNew value to set.

◆ set() [6/6]

template<mtm::matrix_traits Traits>
void mdds::multi_type_matrix< Traits >::set ( size_type row,
size_type col,
numeric_type val )

Set a numeric value to an element at specified position.

Parameters
rowrow index of the element.
colcolumn index of the element.
valnew value to set.

◆ set_column()

template<mtm::matrix_traits Traits>
template<typename _T>
void mdds::multi_type_matrix< Traits >::set_column ( size_type col,
const _T & it_begin,
const _T & it_end )

Set values of multiple elements at once in a single column. When the length of passed elements exceeds that of the column, it gets truncated to the column size.

Parameters
colcolumn position
it_beginiterator that points to the begin position of the values being set.
it_enditerator that points to the end position of the values being set.

◆ set_column_empty()

template<mtm::matrix_traits Traits>
void mdds::multi_type_matrix< Traits >::set_column_empty ( size_type col)

Set the entire column empty.

Parameters
colindex of the column to empty.

◆ set_empty() [1/3]

template<mtm::matrix_traits Traits>
position_type mdds::multi_type_matrix< Traits >::set_empty ( const position_type & pos)

Set element referenced by the position object empty.

Parameters
posposition object that references element.
Returns
position of the element that has just been made empty.

◆ set_empty() [2/3]

template<mtm::matrix_traits Traits>
void mdds::multi_type_matrix< Traits >::set_empty ( size_type row,
size_type col )

Set specified element position empty.

Parameters
rowrow position of the element.
colcolumn position of the element.

◆ set_empty() [3/3]

template<mtm::matrix_traits Traits>
void mdds::multi_type_matrix< Traits >::set_empty ( size_type row,
size_type col,
size_type length )

Set a range of elements empty. The range starts from the position specified by the row and col, and extends downward first then to the right.

Parameters
rowrow position of the first element.
colcolumn position of the first element.
lengthlength of the range to set empty. When the length is greater than 1, the range extends downward first then to the right.

◆ set_row_empty()

template<mtm::matrix_traits Traits>
void mdds::multi_type_matrix< Traits >::set_row_empty ( size_type row)

Set the entire row empty.

Parameters
rowindex of the row to empty.

◆ size()

template<mtm::matrix_traits Traits>
size_pair_type mdds::multi_type_matrix< Traits >::size ( ) const

Return the size of matrix as a pair. The first value is the row size, while the second value is the column size.

Returns
matrix size as a value pair.

◆ swap()

template<mtm::matrix_traits Traits>
void mdds::multi_type_matrix< Traits >::swap ( multi_type_matrix< Traits > & r)

Swap the content of the matrix with another instance.

◆ transpose()

template<mtm::matrix_traits Traits>
multi_type_matrix & mdds::multi_type_matrix< Traits >::transpose ( )

Transpose the stored matrix data.

Returns
reference to this matrix instance.

◆ walk() [1/4]

template<mtm::matrix_traits Traits>
template<typename FuncT>
FuncT mdds::multi_type_matrix< Traits >::walk ( FuncT func) const

Walk all element blocks that consist of the matrix.

Parameters
funcfunction object whose operator() gets called on each element block.
Returns
function object passed to this method.

◆ walk() [2/4]

template<mtm::matrix_traits Traits>
template<typename FuncT>
FuncT mdds::multi_type_matrix< Traits >::walk ( FuncT func,
const multi_type_matrix< Traits > & right ) const

Walk through all element blocks in parallel with another matrix instance. It stops at the block boundaries of both matrix instances during the walk.

Parameters
funcfunction object whose operator() gets called on each element block.
rightanother matrix instance to parallel-walk with.

◆ walk() [3/4]

template<mtm::matrix_traits Traits>
template<typename FuncT>
FuncT mdds::multi_type_matrix< Traits >::walk ( FuncT func,
const multi_type_matrix< Traits > & right,
const size_pair_type & start,
const size_pair_type & end ) const

Walk through the element blocks in a sub-matrix range in parallel with another matrix instance. It stops at the block boundaries of both matrix instances during the walk. The sub-matrix range is defined by start and end positions passed to this method.

Parameters
funcfunction object whose operator() gets called on each element block.
rightanother matrix instance to parallel-walk with.
startthe column/row position of the upper-left corner of the sub-matrix.
endthe column/row position of the lower-right corner of the sub-matrix. Both column and row must be greater or equal to those of the start position.

◆ walk() [4/4]

template<mtm::matrix_traits Traits>
template<typename FuncT>
FuncT mdds::multi_type_matrix< Traits >::walk ( FuncT func,
const size_pair_type & start,
const size_pair_type & end ) const

Walk through the element blocks in a sub-matrix range defined by start and end positions passed to this method.

Parameters
funcfunction object whose operator() gets called on the element block.
startthe column/row position of the upper-left corner of the sub-matrix.
endthe column/row position of the lower-right corner of the sub-matrix. Both column and row must be greater or equal to those of the start position.
Returns
function object passed to this method.

Member Data Documentation

◆ element_empty

template<mtm::matrix_traits Traits>
mtm::element_t mdds::multi_type_matrix< Traits >::element_empty = mtm::element_empty
staticconstexpr

Element type value for an empty element.

◆ element_numeric

template<mtm::matrix_traits Traits>
mtm::element_t mdds::multi_type_matrix< Traits >::element_numeric = numeric_block_type::block_type
staticconstexpr

Element type value for a numeric element. It is the block type id of the numeric element block.