regina::TableView< Element, dim1, dim > Class Template Reference

A lightweight object that can be used for random access to all elements of a given multi-dimensional table. More...

#include <utilities/tableview.h>

Classes
class	iterator
	The iterator type for this table view. More...

Public Types
using	Subview = typename detail::ConstArrayOf<Element, dim...>::view
	The type returned by the square bracket operator.
using	Subarray = typename detail::ConstArrayOf<Element, dim...>::type
	The type of a slice of the underlying C-style array, when the first array index is fixed.
using	Array
	The type of the underlying C-style array, with all compile-time constant dimensions specified.
using	size_type = size_t
	The native integer type used for array indexing.
using	value_type = Element
	The type of element that is stored in this array.
using	reference = const Element&
	A reference to a single array element.
using	const_reference = const Element&
	A reference to a single array element.
using	const_iterator = iterator
	The iterator type for this table view.

Public Member Functions
constexpr	TableView (Subarray *array)
	Returns a view for the given C-style array.
constexpr	TableView (const TableView &)=default
	Creates a new copy of the given table view.
TableView &	operator= (const TableView &)=default
	Sets this to be a copy of the given table view.
constexpr std::array< size_t, dimension >	size () const
	Returns the size of this array, across all of the array dimensions.
constexpr Subview	operator[] (size_t index) const
	Returns the requested sub-array of a multi-dimensional array, or the requested element of a one-dimensional array.
const_iterator	begin () const
	Returns a C++ iterator pointing to the first sub-array (for a multi-dimensional array), or the first element (for a one-dimensional array).
const_iterator	end () const
	Returns a C++ iterator pointing beyond the last sub-array (for a multi-dimensional array), or the last element (for a one-dimensional array).
auto	__iter__ () const
	Returns a Python iterator over all sub-arrays (for a multi-dimensional array), or all elements (for a one-dimensional array).
constexpr bool	operator== (const TableView &other) const
	Determines whether this and the given table view are accessing the same underlying C-style array.
constexpr bool	operator!= (const TableView &other) const
	Determines whether this and the given table view are accessing different underlying C-style arrays.

Static Public Attributes
static constexpr int	dimension = 1 + sizeof...(dim)
	The dimension of the underlying C-style array.

Detailed Description

template<typename Element, size_t dim1, size_t... dim>
class regina::TableView< Element, dim1, dim >

A lightweight object that can be used for random access to all elements of a given multi-dimensional table.

This access is read-only, in the sense that both the table itself and the table elements are read-only. (Of course, if the table elements are non-const pointers then this means that the pointers cannot be reassigned to point to different objects, but the objects they point to can still be modified.)

This class is in a sense a multi-dimensional analogue to TableView (though it does also support one-dimensional tables).

Where this class differs from ListView is:

• TableView supports multi-dimensional tables, whereas ListView only supports one-dimensional lists.
• TableView offers a smaller set of member functions, whereas ListView has a richer interface.
• TableView is (for now) only designed to work with fixed-size C-style arrays of the form Element[a][b]...[z], where the array dimensions are compile-time constants. In contrast, ListView can also work with rich C++ container classes and variable-sized C-style arrays.
• While ListView has a purpose in C++ (to hide the "real" type used by the underlying implementation), TableView is primary for the Python bindings: its main benefit is to strictly enforce read-only access (since Python loses all knowledge of constness, and sometimes allows users to change things that they should not). Typically TableView would be used to wrap global constant arrays (such as regina::quadDefn, or regina::Edge<3>::edgeNumber).

TableView comes with deduction guides for tables of dimension ≤ 3. This means that you can simply create a TableView using the syntax TableView(array), where array is the underlying C-style array, without having to specify any TableView template arguments.

TableView objects are small enough to pass by value and swap with std::swap(), with no need for any specialised move operations or swap functions.

Python

The TableView classes are deliberately difficult to access: they live within their own private Python namespaces, and are all given the same class name (TableView). You would typically only interact with a TableView when accessing a constant array (e.g., Edge<3>::edgeNumber). In most cases you would simply use array-like operators to access the elements of such a table without ever knowing its exact type.

Template Parameters

Element	the type of element stored in the C-style array. This should not be a const type; the const modifier will be added automatically where necessary through the class interface.
dim	the dimensions of the C-style array. There must always be at least one dimension supplied.

Member Typedef Documentation

Array

template<typename Element , size_t dim1, size_t... dim>

using regina::TableView< Element, dim1, dim >::Array

Initial value:

 typename detail::ConstArrayOf<Element, dim1, dim...>::
            type

The type of the underlying C-style array, with all compile-time constant dimensions specified.

const_iterator

template<typename Element , size_t dim1, size_t... dim>

using regina::TableView< Element, dim1, dim >::const_iterator = iterator

The iterator type for this table view.

Both iterator and const_iterator are the same type, since TableView only offers read-only access to the underlying data. See the TableView::iterator class for further details.

Python

Not present. TableView is an iterable type, but its iter() function returns an object of a different (hidden) iterator class.

const_reference

template<typename Element , size_t dim1, size_t... dim>

using regina::TableView< Element, dim1, dim >::const_reference = const Element&

A reference to a single array element.

Both reference and const_reference are the same, since this class only offers read-only access to the underlying array.

reference

template<typename Element , size_t dim1, size_t... dim>

using regina::TableView< Element, dim1, dim >::reference = const Element&

A reference to a single array element.

Both reference and const_reference are the same, since this class only offers read-only access to the underlying array.

size_type

template<typename Element , size_t dim1, size_t... dim>

using regina::TableView< Element, dim1, dim >::size_type = size_t

The native integer type used for array indexing.

Subarray

template<typename Element , size_t dim1, size_t... dim>

using regina::TableView< Element, dim1, dim >::Subarray = typename detail::ConstArrayOf<Element, dim...>::type

The type of a slice of the underlying C-style array, when the first array index is fixed.

If this array is one-dimensional, then this is simply const Element.

Subview

template<typename Element , size_t dim1, size_t... dim>

using regina::TableView< Element, dim1, dim >::Subview = typename detail::ConstArrayOf<Element, dim...>::view

The type returned by the square bracket operator.

For an array with multiple dimensions, this is a TableView of smaller dimension. For a one-dimensional array, this is a const reference to Element.

See the square bracket operator for further details.

value_type

template<typename Element , size_t dim1, size_t... dim>

using regina::TableView< Element, dim1, dim >::value_type = Element

The type of element that is stored in this array.

Constructor & Destructor Documentation

TableView() [1/2]

template<typename Element , size_t dim1, size_t... dim>

regina::TableView< Element, dim1, dim >::TableView ( Subarray * array )

inlineconstexpr

Returns a view for the given C-style array.

Python

Not present.

Parameters

array

the pointer to the C-style array.

TableView() [2/2]

template<typename Element , size_t dim1, size_t... dim>

regina::TableView< Element, dim1, dim >::TableView ( const TableView< Element, dim1, dim > & )

constexprdefault

Creates a new copy of the given table view.

Member Function Documentation

__iter__()

template<typename Element , size_t dim1, size_t... dim>

auto regina::TableView< Element, dim1, dim >::__iter__

(

)

const

Returns a Python iterator over all sub-arrays (for a multi-dimensional array), or all elements (for a one-dimensional array).

For a TableView t, this iterator will run through the subarrays/elements t[0], t[1], ..., in order from first to last.

In particular, for a multi-dimensional array, a single iterator will not run through the individual array elements; for this you will need t.dimension nested iterations.

C++

Not present. For C++ users, TableView provides the usual begin() and end() functions instead. In particular, you can iterate over the subarrays or elements of this table in the usual way using a range-based for loop.

Returns

an iterator over the subarrays or elements of this table.

begin()

template<typename Element , size_t dim1, size_t... dim>

const_iterator regina::TableView< Element, dim1, dim >::begin ( ) const

inline

Returns a C++ iterator pointing to the first sub-array (for a multi-dimensional array), or the first element (for a one-dimensional array).

For a TableView t, the iterator range from t.begin() to t.end() runs through the subarrays/elements t[0], t[1], ..., in order from first to last.

In particular, for a multi-dimensional array, a single iterator will not run through the individual array elements; for this you will need t.dimension nested iterations.

Python

Not present. For Python users, TableView implements the Python iterable interface. You can iterate over the subarrays or elements of this table in the same way that you would iterate over any native Python container.

Returns

an iterator at the beginning of this table.

end()

template<typename Element , size_t dim1, size_t... dim>

const_iterator regina::TableView< Element, dim1, dim >::end ( ) const

inline

Returns a C++ iterator pointing beyond the last sub-array (for a multi-dimensional array), or the last element (for a one-dimensional array).

For a TableView t, the iterator range from t.begin() to t.end() runs through the subarrays/elements t[0], t[1], ..., in order from first to last.

See begin() for further details.

Python

Not present. For Python users, TableView implements the Python iterable interface. You can iterate over the subarrays or elements of this table in the same way that you would iterate over any native Python container.

Returns

an iterator beyond the end of this table.

operator!=()

template<typename Element , size_t dim1, size_t... dim>

bool regina::TableView< Element, dim1, dim >::operator!= ( const TableView< Element, dim1, dim > & other ) const

inlineconstexpr

Determines whether this and the given table view are accessing different underlying C-style arrays.

To be considered the same array, the two arrays must have the same location in memory (i.e., the pointers that define the C-style arrays must be equal). In particular, it is not enough for the two arrays just to have identical contents.

Parameters

other

the table view to compare with this.

Returns

true if and only if this and the given table use different underlying C-style arrays.

operator=()

template<typename Element , size_t dim1, size_t... dim>

TableView & regina::TableView< Element, dim1, dim >::operator= ( const TableView< Element, dim1, dim > & )

default

Sets this to be a copy of the given table view.

Returns

a reference to this table view.

operator==()

template<typename Element , size_t dim1, size_t... dim>

bool regina::TableView< Element, dim1, dim >::operator== ( const TableView< Element, dim1, dim > & other ) const

inlineconstexpr

Determines whether this and the given table view are accessing the same underlying C-style array.

To be considered the same array, the two arrays must have the same location in memory (i.e., the pointers that define the C-style arrays must be equal). In particular, it is not enough for the two arrays just to have identical contents.

Parameters

other

the table view to compare with this.

Returns

true if and only if this and the given table use the same underlying C-style array.

operator[]()

template<typename Element , size_t dim1, size_t... dim>

Subview regina::TableView< Element, dim1, dim >::operator[] ( size_t index ) const

inlineconstexpr

Returns the requested sub-array of a multi-dimensional array, or the requested element of a one-dimensional array.

If this array is one-dimensional then this operator simply returns the (index)th element, as a const reference.

If this array has more than one dimension then this operator returns a TableView of smaller dimension, by value, representing the slice of the overall table obtained when the first array index is set to the given value.

Typically this operator would just be used to access an individual element using the syntax array[index_1][index_2]...[index_dim], where dim is the dimension of this array.

Parameters

index

indicates which element or sub-array to return; this must be between 0 and (dim1-1) inclusive.

Returns

the (index)th sub-array.

size()

template<typename Element , size_t dim1, size_t... dim>

std::array< size_t, dimension > regina::TableView< Element, dim1, dim >::size ( ) const

inlineconstexpr

Returns the size of this array, across all of the array dimensions.

This returns a sequence (s_1, s_2, ..., s_dim), where dim is the dimension of this array, and where the kth array subscript ranges from 0 to (s_k-1) inclusive.

Python

In Python, the special method len() returns s_1. That is, it indicates the allowed range for the first array subscript.

Returns

the size of this array, across all of the array dimensions.

Member Data Documentation

dimension

template<typename Element , size_t dim1, size_t... dim>

int regina::TableView< Element, dim1, dim >::dimension = 1 + sizeof...(dim)

staticconstexpr

The dimension of the underlying C-style array.

This is the number of subscripts required to access an individual array element.

---

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

• utilities/tableview.h