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

stratax::container::Matrix
Two-dimensional owning array of numeric values.
Definition Matrix.hpp:46

See also: core::ArrayBase; core::Shape

Definition at line 45 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 65 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 61 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 57 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 69 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 53 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 63 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 59 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 55 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 67 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 51 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 49 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 109 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 120 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 134 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::RankError	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 147 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 170 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 213 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 221 of file Matrix.hpp.

◆ cols()

template<typename T >

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

inlinenoexcept

Returns the number of columns.

Complexity: O(1).

Definition at line 187 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 196 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 204 of file Matrix.hpp.

◆ rows()

template<typename T >

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

inlinenoexcept

Returns the number of rows.

Complexity: O(1).

Definition at line 185 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 228 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 235 of file Matrix.hpp.

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

include/stratax/containers/Matrix.hpp

Public Types

Public Member Functions

Friends

Additional Inherited Members

Detailed Description

Member Typedef Documentation

◆ const_iterator

◆ const_pointer

◆ const_reference

◆ const_reverse_iterator

◆ difference_type

◆ iterator

◆ pointer

◆ reference

◆ reverse_iterator

◆ size_type

◆ value_type

Constructor & Destructor Documentation

◆ Matrix() [1/5]

◆ Matrix() [2/5]

◆ Matrix() [3/5]

◆ Matrix() [4/5]

◆ Matrix() [5/5]

Member Function Documentation

◆ at() [1/2]

◆ at() [2/2]

◆ cols()

◆ operator()() [1/2]

◆ operator()() [2/2]

◆ rows()

◆ swap()

Friends And Related Symbol Documentation

◆ swap