Container Concepts

Vector

Description

A Vector describes common aspects of dense, packed and sparse vectors.

Refinement of

DefaultConstructible, Vector Expression [1].

Associated types

In addition to the types defined by Vector Expression

Public base

vector_container<V>

V must be derived from this public base type.

Storage array

V::array_type

Dense Vector ONLY. The type of underlying storage array used to store the elements. The array_type must model the Storage concept.

Notation

V

A type that is a model of Vector

v

Objects of type V

n, i

Objects of a type convertible to size_type

t

Object of a type convertible to value_type

p

Object of a type convertible to bool

Definitions

Valid expressions

In addition to the expressions defined in DefaultConstructible, Vector Expression the following expressions must be valid.

Name Expression Type requirements Return type

Sizing constructor

V v (n)

 

V

Insert

v.insert_element (i, t)

v is mutable.

void

Erase

v.erase_element (i)

v is mutable.

void

Clear

v.clear ()

v is mutable.

void

Resize

v.resize (n)
v.resize (n, p)

v is mutable.

void

Storage

v.data()

v is mutable and Dense.

array_type& if v is mutable, const array_type& otherwise

Expression semantics

Semantics of an expression is defined only where it differs from, or is not defined in Vector Expression .

Name Expression Precondition Semantics Postcondition

Sizing constructor

V v (n)

n >= 0

Allocates a vector of n elements.

v.size () == n.

Element access [2]

v[n]

0<n>v.size()

returns the n-th element in v

 

Insert

v.insert_element (i, t)

0 < = i < v.size ().

Inserts an element at v (i) with value t. The storage requirement of the Vector may be increased.

v (i) is equal to t.

Erase

v.erase_element (i)

0 < = i < v.size ()

Destroys the element as v (i) and replaces it with the default value_type (). The storage requirement of the Vector may be decreased.

v (i) is equal to value_type ().

Clear

v.clear ()

 

Equivalent to
for (i = 0; i < v.size (); ++ i)
  v.erase_element (i);

 

Resize

v.resize (n) v.resize (n, p)

 

Reallocates the vector so that it can hold n elements.
Erases or appends elements in order to bring the vector to the prescribed size. Appended elements copies of value_type().
When p == false then existing elements are not preserved and elements will not appended as normal. Instead the vector is in the same state as that after an equivalent sizing constructor.

v.size () == n.

Storage

v.data()

Returns a reference to the underlying dense storage.

 

Complexity guarantees

The run-time complexity of the sizing constructor is linear in the vector’s size.

The run-time complexity of insert_element and erase_element is specific for the Vector model and it depends on increases/decreases in storage requirements.

The run-time complexity of resize is linear in the vector’s size.

Invariants

Models

  • vector, bounded_vector, c_vector

  • unit_vector, zero_vector, scalar_vector

  • mapped_vector;, compressed_vector, coordinate_vector

Notes

[1] As a user you need not care about Vector being a refinement of the VectorExpression. Being a refinement of the VectorExpression is only important for the template-expression engine but not the user.

[2] The operator[] is added purely for convenience and compatibility with the std::vector. In uBLAS however, generally operator() is used for indexing because this can be used for both vectors and matrices.

Matrix

Description

A Matrix describes common aspects of dense, packed and sparse matrices.

Refinement of

DefaultConstructible, Matrix Expression [1] .

Associated types

In addition to the types defined by Matrix Expression

Public base

matrix_container<M>

M must be derived from this public base type.

Storage array

M::array_type

Dense Matrix ONLY. The type of underlying storage array used to store the elements. The array_type must model the Storage concept.

Notation

M

A type that is a model of Matrix

m

Objects of type M

n1, n2, i, j

Objects of a type convertible to size_type

t

Object of a type convertible to value_type

p

Object of a type convertible to bool

Definitions

Valid expressions

In addition to the expressions defined in Matrix Expression the following expressions must be valid.

Name Expression Type requirements Return type

Sizing constructor

M m (n1, n2)

 

M

Insert

m.insert_element (i, j, t)

m is mutable.

void

Erase

m.erase_element (i, j)

m is mutable.

void

Clear

m.clear ()

m is mutable.

void

Resize

m.resize (n1, n2)
m.resize (n1, n2, p)

m is mutable.

void

Storage

m.data()

m is mutable and Dense.

array_type& if m is mutable, const array_type& otherwise

Expression semantics

Semantics of an expression is defined only where it differs from, or is not defined in Matrix Expression .

Name Expression Precondition Semantics Postcondition

Sizing constructor

M m (n1, n2)

n1 >= 0 and n2 >= 0

Allocates a matrix of n1 rows and n2 columns.

m.size1 () == n1 and m.size2 () == n2.

Insert

m.insert_element (i, j, t)

0 < = i < m.size1 (), + 0 < = j < m.size2 ().

Inserts an element at m (i, j) with value t. The storage requirement of the Matrix may be increased. m (i, j) is equal to t.

m(i,j) is equal to t.

Erase

m.erase_element (i, j)

0 ⇐ i < m.size1 ()`and ` 0 ⇐ j < m.size2

Destroys the element as m (i, j) and replaces it with the default value_type (). The storage requirement of the Matrix may be decreased.

m (i, j) is equal to value_type ().

Clear

m.clear ()

Equivalent to
for (i = 0; i < m.size1 (); i) +   for (j = 0; j < m.size2 (); j)
    m.erase_element (i, j);

Resize

m.resize (n1, n2) m.resize (n1, n2, p)

Reallocate the matrix so that it can hold n1 rows and n2 columns.
Erases or appends elements in order to bring the matrix to the prescribed size. Appended elements are value_type() copies.
When p == false then existing elements are not preserved and elements will not appended as normal. Instead the matrix is in the same state as that after an equivalent sizing constructor.

m.size1 () == n1 and m.size2 () == n2.

Storage

m.data()

Returns a reference to the underlying dense storage.

 

Complexity guarantees

The run-time complexity of the sizing constructor is quadratic in the matrix’s size.

The run-time complexity of insert_element and erase_element is specific for the Matrix model and it depends on increases/decreases in storage requirements.

The run-time complexity of resize is quadratic in the matrix’s size.

Invariants

Models

  • matrix, bounded_matrix, c_matrix

  • identity_matrix , zero_matrix , scalar_matrix

  • triangular_matrix , symmetric_matrix , banded_matrix

  • mapped_matrix , compressed_matrix , coordinate_matrix

Notes

[1] As a user you need not care about Matrix being a refinement of the MatrixExpression. Being a refinement of the MatrixExpression is only important for the template-expression engine but not the user.

Tensor

Description

A Tensor describes common aspects of dense multidimensional arrays.

Refinement of

DefaultConstructible, Tensor Expression [1] .

Associated types

In addition to the types defined by Tensor Expression

Public base

tensor_container<tensor_t>

tensor_t must be derived from this public base type.

Storage array

tensor_t::array_type

Dense tensor ONLY. The type of underlying storage array used to store the elements. The array_type must model the Storage concept.

Notation

tensor_t A type that is a model of Tensor

t

Objects of type tensor_t

`n1, n2, np, m1, m2, mq `

Dimension objects of a type convertible to size_type

`i1, i2, ip, j, k `

Index objects of a type convertible to size_type

v

Object of a type convertible to value_type

Definitions

Valid expressions

In addition to the expressions defined in Tensor Expression the following expressions must be valid.

Name Expression Type requirements Return type

Sizing constructor

T t(n1, n2, …​, np)

 

T

Write

t.at(i1, i2, …​, ip)

t is mutable.

void

Read

t.at(i1, i2, …​, ip)

t is mutable.

v

Clear

t.clear ()

t is mutable.

void

Resize

t.resize(m1, m2, …​ , mq)

t is mutable.

void

Storage

t.data()

t is mutable and dense.

pointer if t is mutable, const_pointer otherwise

Expression semantics

Semantics of an expression is defined only where it differs from, or is not defined in Tensor Expression .

Name Expression Precondition Semantics Postcondition

Sizing constructor

T t(n1, n2, …​, np)

nr > =1 for 1< = 1 < = p

Allocates a p -order tensor with dimension extents n1, n2, …​. np.

t.size(r)==nr for 1 < = r < = p.

Write

t.at(i1,i2,…​,ip)=v

0 < = ir < nr for 1 < = r < = p.

Writes an element at multi-index position i1, i2, …​ ip with value v.

t(i1,i2,…​,ip) is equal to v.

Read

v=t.at(i1,i2,…​,ip)

0 < = ir < nr for 1 < = r < = p.

Reads the element at multi-index position i1, i2, …​ ip and returns a value v.

t(i1,i2,…​,ip) is equal to v.

Clear

t.clear()

Removes all elements from the container.

Resize

t.resize(m1, m2, …​, mq)

mr > = 1 for 1 < = 1 < = q

Reallocate the matrix so that it can hold m1 x m2 x …​ mq elements. + Erases or appends elements in order to bring the matrix to the prescribed size. Appended elements are value_type() copies.

t.size(r) == mr for 1 < = r < = q.

Storage

m.data()

Returns a reference to the underlying dense storage.

Complexity guarantees

The run-time complexity of contructor is linear in the tensor’s size n1 x n2 x …​ np.

The run-time complexity of write() and read() is linear in the order of the tensor.

The run-time complexity of resize is at most linear in the tensor’s size m1 x m2 x …​ nq.

Invariants

Models

  • tensor

Notes

[1] As a user you need not care about Tensor being a refinement of the TensorExpression. Being a refinement of the TensorExpression is only important for the template-expression engine but not the user.

Copyright (©) 2000-2002 Joerg Walter, Mathias Koch
Copyright (©) 2018 Cem Bassoy
Copyright (©) 2021 Shikhar Vashistha
Use, modification and distribution are subject to the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt ).