stratax::container::Matrix< T > Class Template Reference

Two-dimensional owning array of numeric values. More...

#include <Matrix.hpp>

Inheritance diagram for stratax::container::Matrix< T >:

Collaboration diagram for stratax::container::Matrix< T >:

Public Types
using	value_type = typename core::ArrayBase<T>::value_type
	Stored element type inherited from ArrayBase.
using	size_type = typename core::ArrayBase<T>::size_type
	Unsigned type used for element counts and indices.
using	difference_type = typename core::ArrayBase<T>::difference_type
	Signed type used for checked indices and iterator distances.
using	reference = typename core::ArrayBase<T>::reference
	Mutable element reference type.
using	const_reference = typename core::ArrayBase<T>::const_reference
	Read-only element reference type.
using	pointer = typename core::ArrayBase<T>::pointer
	Mutable element pointer type.
using	const_pointer = typename core::ArrayBase<T>::const_pointer
	Read-only element pointer type.
using	iterator = typename core::ArrayBase<T>::iterator
	Mutable contiguous random-access iterator type.
using	const_iterator = typename core::ArrayBase<T>::const_iterator
	Read-only contiguous random-access iterator type.
using	reverse_iterator = typename core::ArrayBase<T>::reverse_iterator
	Mutable reverse iterator type.
using	const_reverse_iterator = typename core::ArrayBase<T>::const_reverse_iterator
	Read-only reverse iterator type.
Public Types inherited from stratax::core::ArrayBase< T >
using	value_type = typename Buffer<T>::value_type
	Stored element type.
using	size_type = typename Buffer<value_type>::size_type
	Unsigned type used for element counts and indices.
using	difference_type = typename Buffer<value_type>::difference_type
	Signed type used for checked indices and iterator distances.
using	reference = typename Buffer<value_type>::reference
	Mutable element reference type.
using	const_reference = typename Buffer<value_type>::const_reference
	Read-only element reference type.
using	pointer = typename Buffer<value_type>::pointer
	Mutable element pointer type.
using	const_pointer = typename Buffer<value_type>::const_pointer
	Read-only element pointer type.
using	iterator = typename Buffer<value_type>::iterator
	Mutable contiguous random-access iterator type.
using	const_iterator = typename Buffer<value_type>::const_iterator
	Read-only contiguous random-access iterator type.
using	reverse_iterator = typename Buffer<value_type>::reverse_iterator
	Mutable reverse iterator type.
using	const_reverse_iterator = typename Buffer<value_type>::const_reverse_iterator
	Read-only reverse iterator type.

Public Member Functions
	Matrix ()
	Constructs an empty matrix with shape {0, 0}.
	Matrix (size_type rows, size_type cols)
	Constructs a value-initialized matrix with the requested dimensions.
	Matrix (size_type rows, size_type cols, const_reference value)
	Constructs a matrix filled with copies of value.
	Matrix (const core::Shape &shape)
	Constructs a value-initialized matrix from a rank-two shape.
	Matrix (std::initializer_list< std::initializer_list< value_type > > list)
	Constructs a matrix by copying a rectangular nested initializer.
size_type	rows () const noexcept
	Returns the number of rows.
size_type	cols () const noexcept
	Returns the number of columns.
reference	operator() (size_type row, size_type col)
	Returns an element using unchecked row and column indices.
const_reference	operator() (size_type row, size_type col) const
	Returns an element using unchecked row and column indices.
reference	at (difference_type row, difference_type col)
	Returns an element using checked, Python-style indices.
const_reference	at (difference_type row, difference_type col) const
	Returns an element using checked, Python-style indices.
void	swap (Matrix &other) noexcept
	Exchanges storage and layout metadata with other.
Public Member Functions inherited from stratax::core::ArrayBase< T >
size_type	size () const noexcept
	Returns the number of stored elements.
bool	empty () const noexcept
	Reports whether no elements are stored.
size_type	rank () const noexcept
	Returns the number of logical dimensions.
const Shape &	shape () const noexcept
	Returns the logical shape metadata.
const Shape &	strides () const noexcept
	Returns the row-major stride metadata.
pointer	data () noexcept
	Returns a pointer to contiguous mutable element storage.
const_pointer	data () const noexcept
	Returns a pointer to contiguous read-only element storage.
reference	front ()
	Returns the first element.
const_reference	front () const
	Returns the first element.
reference	back ()
	Returns the final element.
const_reference	back () const
	Returns the final element.
reference	operator[] (size_type index) noexcept
	Returns an element without bounds checking.
const_reference	operator[] (size_type index) const noexcept
	Returns an element without bounds checking.
reference	at (difference_type index)
	Returns an element using checked, Python-style flat indexing.
const_reference	at (difference_type index) const
	Returns an element using checked, Python-style flat indexing.
iterator	begin () noexcept
	Returns a mutable iterator to the first element.
const_iterator	begin () const noexcept
	Returns a const iterator to the first element.
const_iterator	cbegin () const noexcept
	Returns a const iterator to the first element.
iterator	end () noexcept
	Returns a mutable iterator past the final element.
const_iterator	end () const noexcept
	Returns a const iterator past the final element.
const_iterator	cend () const noexcept
	Returns a const iterator past the final element.
reverse_iterator	rbegin () noexcept
	Returns a mutable reverse iterator to the final element.
const_reverse_iterator	rbegin () const noexcept
	Returns a const reverse iterator to the final element.
const_reverse_iterator	crbegin () const noexcept
	Returns a const reverse iterator to the final element.
reverse_iterator	rend () noexcept
	Returns the past-the-end mutable reverse iterator.
const_reverse_iterator	rend () const noexcept
	Returns the past-the-end const reverse iterator.
const_reverse_iterator	crend () const noexcept
	Returns the past-the-end const reverse iterator.
void	fill (const_reference value)
	Assigns value to every stored element.
void	swap (ArrayBase &other) noexcept
	Exchanges storage and layout metadata with other.

Friends
void	swap (Matrix &lhs, Matrix &rhs) noexcept
	Exchanges two matrices using argument-dependent lookup.

Additional Inherited Members
Static Public Member Functions inherited from stratax::core::ArrayBase< T >
static constexpr std::string_view	dtype () noexcept
	Returns the canonical name of the stored element dtype.
Protected Member Functions inherited from stratax::core::ArrayBase< T >
	ArrayBase (const Shape &shape)
	Constructs value-initialized storage for shape.
	ArrayBase (const Shape &shape, const_reference value)
	Constructs storage filled with value for shape.
	ArrayBase (const Shape &shape, Buffer< value_type > &&buffer)
	Adopts an existing buffer for shape.
template<typename IndexContainer>
size_type	normalized_flat_offset (const IndexContainer &raw_indices, const char *rank_mismatch_message="Multi-index rank must match array rank.", const char *component_oob_message=nullptr) const
	Converts checked signed multidimensional indices to a flat offset.

Detailed Description

template<typename T>
requires DType<T>
class stratax::container::Matrix< T >

Two-dimensional owning array of numeric values.

Forward declaration of the rank-two dtype array container.

Matrix specializes core::ArrayBase for rank-two data arranged in row-major order. It adds row and column metadata queries plus two-dimensional checked and unchecked access while retaining the base class's flat container API.

Template Parameters

T	Element type satisfying the DType concept.

Invariants

• rank() == 2, including when either dimension is zero.
• shape() == Shape{rows(), cols()}.
• size() == rows() * cols() when that product is representable.
• Elements are contiguous in row-major order.

Example

stratax::container::Matrix<double> matrix{
    {1.0, 2.0, 3.0},
    {4.0, 5.0, 6.0}
};
 
matrix(1, 2);   // 6.0; unchecked access
matrix.at(-1, 0); // 4.0; checked access with negative indices

See also

core::ArrayBase

core::Shape

Definition at line 46 of file Matrix.hpp.

Member Typedef Documentation

const_iterator

template<typename T>

using stratax::container::Matrix< T >::const_iterator = typename core::ArrayBase<T>::const_iterator

Read-only contiguous random-access iterator type.

Definition at line 66 of file Matrix.hpp.

const_pointer

template<typename T>

using stratax::container::Matrix< T >::const_pointer = typename core::ArrayBase<T>::const_pointer

Read-only element pointer type.

Definition at line 62 of file Matrix.hpp.

const_reference

template<typename T>

using stratax::container::Matrix< T >::const_reference = typename core::ArrayBase<T>::const_reference

Read-only element reference type.

Definition at line 58 of file Matrix.hpp.

const_reverse_iterator

template<typename T>

using stratax::container::Matrix< T >::const_reverse_iterator = typename core::ArrayBase<T>::const_reverse_iterator

Read-only reverse iterator type.

Definition at line 70 of file Matrix.hpp.

difference_type

template<typename T>

using stratax::container::Matrix< T >::difference_type = typename core::ArrayBase<T>::difference_type

Signed type used for checked indices and iterator distances.

Definition at line 54 of file Matrix.hpp.

iterator

template<typename T>

using stratax::container::Matrix< T >::iterator = typename core::ArrayBase<T>::iterator

Mutable contiguous random-access iterator type.

Definition at line 64 of file Matrix.hpp.

pointer

template<typename T>

using stratax::container::Matrix< T >::pointer = typename core::ArrayBase<T>::pointer

Mutable element pointer type.

Definition at line 60 of file Matrix.hpp.

reference

template<typename T>

using stratax::container::Matrix< T >::reference = typename core::ArrayBase<T>::reference

Mutable element reference type.

Definition at line 56 of file Matrix.hpp.

reverse_iterator

template<typename T>

using stratax::container::Matrix< T >::reverse_iterator = typename core::ArrayBase<T>::reverse_iterator

Mutable reverse iterator type.

Definition at line 68 of file Matrix.hpp.

size_type

template<typename T>

using stratax::container::Matrix< T >::size_type = typename core::ArrayBase<T>::size_type

Unsigned type used for element counts and indices.

Definition at line 52 of file Matrix.hpp.

value_type

template<typename T>

using stratax::container::Matrix< T >::value_type = typename core::ArrayBase<T>::value_type

Stored element type inherited from ArrayBase.

Definition at line 50 of file Matrix.hpp.

Constructor & Destructor Documentation

Matrix() [1/5]

template<typename T>

stratax::container::Matrix< T >::Matrix ( )

inline

Constructs an empty matrix with shape {0, 0}.

Complexity

O(1).

Definition at line 127 of file Matrix.hpp.

Matrix() [2/5]

template<typename T>

stratax::container::Matrix< T >::Matrix ( size_type rows, size_type cols )

inline

Constructs a value-initialized matrix with the requested dimensions.

Parameters

rows	Number of rows.
cols	Number of columns.

Exceptions

Exceptions::DimensionError	If the element or stride count overflows.
std::bad_alloc	If storage allocation fails.
Any	exception thrown while value-initializing a value_type.

Complexity

O(rows * cols).

Definition at line 138 of file Matrix.hpp.

Matrix() [3/5]

template<typename T>

stratax::container::Matrix< T >::Matrix ( size_type rows, size_type cols, const_reference value )

inline

Constructs a matrix filled with copies of value.

Parameters

rows	Number of rows.
cols	Number of columns.
value	Value copied into every element.

Exceptions

Exceptions::DimensionError	If the element or stride count overflows.
std::bad_alloc	If storage allocation fails.
Any	exception thrown by value_type's copy constructor.

Complexity

O(rows * cols).

Definition at line 152 of file Matrix.hpp.

Matrix() [4/5]

template<typename T>

stratax::container::Matrix< T >::Matrix ( const core::Shape & shape )

inlineexplicit

Constructs a value-initialized matrix from a rank-two shape.

Parameters

shape

Shape whose dimensions specify rows and columns.

Exceptions

Exceptions::ShapeError	If shape.rank() != 2.
Exceptions::DimensionError	If the element or stride count overflows.
std::bad_alloc	If storage allocation fails.
Any	exception thrown while value-initializing a value_type.

Complexity

O(shape.elements()).

Definition at line 165 of file Matrix.hpp.

Matrix() [5/5]

template<typename T>

stratax::container::Matrix< T >::Matrix ( std::initializer_list< std::initializer_list< value_type > > list )

inline

Constructs a matrix by copying a rectangular nested initializer.

Rows retain their input order and each row occupies one contiguous segment of the resulting row-major storage. An empty outer list creates shape {0, 0}; non-empty rows may consistently contain zero columns.

Parameters

list	Rectangular sequence of matrix rows.

Exceptions

Exceptions::ShapeError	If the rows have different lengths.
Exceptions::DimensionError	If the element or stride count overflows.
std::bad_alloc	If storage allocation fails.
Any	exception thrown while constructing or assigning value_type.

Complexity

O(rows * cols).

Definition at line 183 of file Matrix.hpp.

Member Function Documentation

at() [1/2]

template<typename T>

reference stratax::container::Matrix< T >::at ( difference_type row, difference_type col )

inline

Returns an element using checked, Python-style indices.

Parameters

row	Row index in [-rows(), rows()).
col	Column index in [-cols(), cols()).

Exceptions

Exceptions::IndexError

If either index is out of bounds.

Complexity

O(1).

Definition at line 226 of file Matrix.hpp.

at() [2/2]

template<typename T>

const_reference stratax::container::Matrix< T >::at ( difference_type row, difference_type col ) const

inline

Returns an element using checked, Python-style indices.

Parameters

row	Row index in [-rows(), rows()).
col	Column index in [-cols(), cols()).

Exceptions

Exceptions::IndexError

If either index is out of bounds.

Complexity

O(1).

Definition at line 234 of file Matrix.hpp.

cols()

template<typename T>

size_type stratax::container::Matrix< T >::cols ( ) const

inlinenodiscardnoexcept

Returns the number of columns.

Complexity

O(1).

Definition at line 200 of file Matrix.hpp.

operator()() [1/2]

template<typename T>

reference stratax::container::Matrix< T >::operator() ( size_type row, size_type col )

inline

Returns an element using unchecked row and column indices.

Parameters

row	Zero-based row index.
col	Zero-based column index.

Precondition

row < rows() and col < cols().

Complexity

O(1).

Definition at line 209 of file Matrix.hpp.

operator()() [2/2]

template<typename T>

const_reference stratax::container::Matrix< T >::operator() ( size_type row, size_type col ) const

inline

Returns an element using unchecked row and column indices.

Parameters

row	Zero-based row index.
col	Zero-based column index.

Precondition

row < rows() and col < cols().

Complexity

O(1).

Definition at line 217 of file Matrix.hpp.

rows()

template<typename T>

size_type stratax::container::Matrix< T >::rows ( ) const

inlinenodiscardnoexcept

Returns the number of rows.

Complexity

O(1).

Definition at line 198 of file Matrix.hpp.

swap()

template<typename T>

void stratax::container::Matrix< T >::swap ( Matrix< T > & other )

inlinenoexcept

Exchanges storage and layout metadata with other.

Parameters

other

Matrix to exchange with this matrix.

Complexity

O(1).

Definition at line 241 of file Matrix.hpp.

Friends And Related Symbol Documentation

swap

template<typename T>

void swap ( Matrix< T > & lhs, Matrix< T > & rhs )

friend

Exchanges two matrices using argument-dependent lookup.

Parameters

lhs	First matrix.
rhs	Second matrix.

Complexity

O(1).

Definition at line 248 of file Matrix.hpp.

---

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

• include/stratax/containers/Matrix.hpp