boost::multi::subarray

Mutable D‐dimensional view into part or all of an array

Synopsis

Declared in <boost/multi/array_ref.hpp>

template<
    typename T,
    multi::dimensionality_type D,
    typename ElementPtr = T*,
    class Layout = layout_t<D, std::pointer_traits<ElementPtr>::difference_type>>
class subarray
    : public const_subarray<T, D, ElementPtr, Layout>

Description

Represents a subregion of a larger array without owning the elements. Has reference semantics: cannot be rebound, assignments are deep, and size is immutable. Invalidated if the originating array is destroyed or resized.

Base Classes

Name

Description

const_subarray<T, D, ElementPtr, Layout>

Read‐only D‐dimensional subarray‐reference (view into a subarray)

Type Aliases

Name

Description

const_cursor

Indexable const‐cursor, pointer‐like objects that multidimensionally indexable (type usually returned by .home() const)

const_iterator

Random‐access const‐iterator in the leading dimension (return type of .begin() or .end() from a constant subarray)

const_pointer

For D == 1 it is the pointer type to the elements (as immutables), otherwise it is void

const_reference

Subarray immutable reference after binding first index, multi::const_subarray<T, D ‐ 1, P> or, for D == 1, std::pointer_traits<P>::reference (usually T const&)

cursor

Indexable cursor, pointer‐like objects that multidimensionally indexable (type usually returned by .home())

decay_type

Associated type that this reference decays to (when true copies are needed)

dimensionality_type

Integer type to store dimensionality information (e.g. 1D, 2D, 3D)

element

Element type (T)

element_const_ptr

Pointer to immutable element type (usually T const*)

element_cref

const‐qualified reference type to an element (usually T const&)

element_move_ptr

Pointer‐like type that produces an moved element (r‐value)

element_ptr

Pointer to element type (usually T*)

element_ref

Reference type to an element (usually T&)

element_type [deprecated]

(deprecated, use element)

extension_type [deprecated]

(deprecated) use extent_type

extent_type

A type to store the extent of an array (the range of valid indices in the leading dimension), returned from .extent().

extents_type

A type that stores the extents of the array or subarray (returned from .extents() and used for array constructors)

index

Type to store an index in the leading dimension

index_range

Type that represents a range of indices

indices_type

A tuple type that allows storing D indices to locate an element in the array

iterator

Random‐access iterator in the leading dimension (return type of .begin() or .end() from a constant subarray)

layout_type

type that holds the layout of the subarray or array

move_iterator

Iterator in the leading dimension that mark elements as movable

pointer

For D == 1 it is the pointer type to the elements, otherwise it is void

reference

Subarray reference after binding first index, multi::subarray<T, D ‐ 1, P> or, for D == 1, std::pointer_traits<P>::reference (usually T&)

size_type

A type to hold the size of an array or subarray (size in the leading dimension) (usually signed)

value_type

Array value after evaluation through the first index, an object of lower dimension, multi::array<T, D ‐ 1, P> or, for D == 1, std::pointer_traits<P>::element_type (usually T)

Member Functions

Name

Description

subarray [constructor] [deleted]

Constructors

~subarray [destructor]

Destructor

operator= [deleted]

Assingment operators (disabled because the const‐subarray is immutable)

apply

When evaluated on a tuple object this is equivalent to .operator()(get<0>(tup), get<1>(tup), ...). (The argument type typical has tuple_size<Tuple> == D)

as_const

yields a const‐element view of the subarray, preventing modification of elements.

back

yields the back subarray of leading dimension (or element for D == 1) of a non‐empty array.

base

returns the base pointer of the array (arithmetic base of the layout, generally the first element)

begin

returns an iterator to the beginning (in the leading dimension)

cbase

returns the base const‐pointer of the array (arithmetic base of the layout, generally the first element)

cbegin

returns an const‐iterator to the beginning

cend

returns an const‐iterator to the end

chunked

produces a subarray of higher dimension by chunking in the leading dimension (if count doesn't divide size, so elements are left out at the end)

const_array_cast

creates a view of the array with element references with const‐removed

copy [deprecated]

materializes an independent, owning array copy of this view with the associated array‐value type (use unary prefix + as a shortcut)

decay

materializes an independent, owning array copy of this view with the associated array‐value type (use unary prefix + as a shortcut)

diagonal

Subarray of lower dimension that represents the main diagonal of a square array

dropped

yields a subarray of the same dimensionally in which the first count elements are dropped.

element_moved

An array view in which element references are r‐values

element_transformed

a view with the elements transformed

elements

returns a random‐access range with all the elements of the array

end

returns an iterator to the end (in the leading dimension)

extensions [deprecated]

Deprecated, prefer extents().

extents

Returns the index extensions (structured cartesian product of half‐open ranges) for all dimensions as an extents_type (extents_t<D>), a tuple of D index_extension values each encoding [first, last)]. The result can be passed directly to array constructors or compared for shape equality. Prefer this over the deprecated extensions().

flatted

flattened

front

yields the front subarray of leading dimension (or element for D == 1) of a non‐empty array.

get_allocator

returns the associated allocator

home

returns a cursor pointing to the top corner element of the array

is_compact [deprecated]

is_flattable [deprecated]

layout

returns the internal layout information of the array

mbegin

returns an move‐iterator (moves on dereference) to the beginning in the leading dimension

member_cast

yields a view of the array containing a specific member of original element type

mend

returns an move‐iterator (moves on dereference) to the ending in the leading dimension

move

yields a subarray whose elements are marked for move

operator&

Address‐of operators

operator()

Subarray returning operator (takes multiple parameters, the number of parameters is equal or lower than the number of dimensions, individual arguments can be single indices or ranges)

operator+

materializes an independent, owning array copy of this view with the associated array‐value type

operator[]

Subscript operators

origin [deprecated]

partitioned

yields a subarray of higher dimension by splitting the leading dimension into n equal‐sized partitions (n must divide size())

reindexed

yields an equivalent subarray with a specific starting index

reinterpret_array_cast

yields a view of the subarray where elements are reinterpreted as a different type (elements must have compatible size)

reversed

yields a view of the array with the leading dimension in the reverse order (e.g. a.reversed()[i][j]== a[a.size() ‐ 1 ‐ i][j])

rotated

yields a view of the array where the indices are rotated (to the left) (e.g. a.rotated()[i][j][k]== a[j][k][i])

serialize

serializes data to generic archive (e.g. Boost or Cereal archive)

shape [deprecated]

size

returns the size of the array in the leading dimension

sliced

A subarray‐view from index first to index last (not inclusive) skipping step in the leading dimension

static_array_cast

yields a view of the array in which the internal representation is static_cast to another type (and/or pointer)

strided

A subarray‐view of the array with skipping step in the leading dimension

strides

returns the layout internal strides of an array as a tuple

swap

swaps every corresponding element of the array references, extents must match. O(N) operation

taked

yields an array‐view of the same dimensionality taking the first count subarrays in the leading dimension

transposed

A transpose view , that exchanges the first two indices

unordered

yields a view in which index access is unordered (an arbitrary transposition of indices generally to optimize access)

unrotated

yields a view of the array where the indices are unrotated (to the right, opposite to .rotated()) (e.g. a.unrotated()[i][j][k]== a[k][i][j], a.rotated().unrotated() is the same as a)

operator Range

Conversion to Range

Equality operator

Inequality operator

Less‐than operator

Less‐than‐or‐equal operator

operator>

Greater‐than operator