regina::ListView< Container > Class Template Reference

A lightweight object that can be used for iteration and random access to all elements of a given list. More...

#include <utilities/listview.h>

Public Types
using	value_type = typename Container::value_type
	The type of element that is stored in this list. More...
using	size_type = typename Container::size_type
	The type used for indexing into this list. More...
using	reference = typename Container::const_reference
	A reference to a list element. More...
using	const_reference = typename Container::const_reference
	A reference to a list element. More...
using	iterator = typename Container::const_iterator
	The iterator type for this list view. More...
using	const_iterator = typename Container::const_iterator
	The iterator type for this list view. More...

Public Member Functions
	ListView (const Container &list)
	Returns a view for the given list. More...
	ListView (const ListView &)=default
	Creates a new copy of the given list view. More...
ListView &	operator= (const ListView &)=default
	Sets this to be a copy of the given list view. More...
bool	empty () const
	Determines if this list is empty. More...
size_type	size () const
	Returns the number of elements in this list. More...
const_reference	operator[] (size_type index) const
	Returns the requested element of this list. More...
const_reference	front () const
	Returns the first element of this list. More...
const_reference	back () const
	Returns the last element of this list. More...
const_iterator	begin () const
	Returns a C++ iterator pointing to the first element of this list. More...
const_iterator	end () const
	Returns a C++ iterator pointing beyond the last element of this list. More...
auto	__iter__ () const
	Returns a Python iterator over the elements of this list. More...
bool	operator== (const ListView &other) const
	Determines whether this and the given list view are accessing the same underlying container. More...
bool	operator!= (const ListView &other) const
	Determines whether this and the given list view are accessing different underlying containers. More...

Detailed Description

template<class Container>
class regina::ListView< Container >

A lightweight object that can be used for iteration and random access to all elements of a given list.

This access is read-only, in the sense that both the list itself and the list elements are read-only. (Of course, if the list 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.)

Typically a ListView would be returned from a class member function to grant the user some basic read-only access to a much richer private data structure, in a way that allows the internal data structure to change at some later date without affecting the public API.

The ListView class supports several different ways of representing a list:

• If your list is stored using a container class (e.g., std::vector or regina::MarkedVector), then you can create a ListView directly from the container using the syntax ListView(container). This uses the generic ListView<Container> class template. There is no need to explicitly specify the ListView template arguments.
• If your list is stored using a C-style array whose size is not known at compile-time, you can create a ListView using either the syntax ListView(array, size) or ListView(begin, end). Here array is a pointer to the beginning of the array, and begin and end behave as an iterator pair (so begin == array and end == array + size). This syntax uses the specialised ListView<Element*> class template. Again, there is no need to explicitly specify the ListView template arguments.
• If your list is stored using a C-style array whose size is fixed at compile-time (i.e., the type is Element[n] for some constant n), you can create a ListView using the syntax ListView(array). Once again, there is no need to explicitly specify the ListView template arguments.

End users should always store ListView objects using auto, not by explicitly writing out the full ListView type. One reason for this is that, if/when Regina moves to C++20, the ListView class will most likely be removed completely (in favour of the new C++20 ranges library).

ListView 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 ListView classes are deliberately difficult to access: they live within their own private Python namespaces, and are all give the same class name (ListView). You would typically only interact with a ListView when it is returned from a function (e.g., Link.crossings()), and in most cases you would simply iterate over this resulting ListView without ever knowing its exact type.

Template Parameters

Container

the internal type of the list that this object grants access to. This type must support at least the same operations as this class itself, except for the copy semantics. In particular, both std::vector and regina::MarkedVector types (as well as many other standard container types) are suitable.

Member Typedef Documentation

const_iterator

template<class Container >

using regina::ListView< Container >::const_iterator = typename Container::const_iterator

The iterator type for this list view.

Both iterator and const_iterator are the same, since this class only offers read-only access to the underlying list.

const_reference

template<class Container >

using regina::ListView< Container >::const_reference = typename Container::const_reference

A reference to a list element.

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

iterator

template<class Container >

using regina::ListView< Container >::iterator = typename Container::const_iterator

The iterator type for this list view.

Both iterator and const_iterator are the same, since this class only offers read-only access to the underlying list.

reference

template<class Container >

using regina::ListView< Container >::reference = typename Container::const_reference

A reference to a list element.

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

size_type

template<class Container >

using regina::ListView< Container >::size_type = typename Container::size_type

The type used for indexing into this list.

value_type

template<class Container >

using regina::ListView< Container >::value_type = typename Container::value_type

The type of element that is stored in this list.

Constructor & Destructor Documentation

ListView() [1/2]

template<class Container >

regina::ListView< Container >::ListView ( const Container &  list )

inline

Returns a view for the given list.

Python

Not present.

Parameters

list	the list that this object will access. Internally, this object will store a reference to list (which means list needs to exist for at least as long as this object).

ListView() [2/2]

template<class Container >

regina::ListView< Container >::ListView ( const ListView< Container > &  )

default

Creates a new copy of the given list view.

Member Function Documentation

__iter__()

template<class Container >

auto regina::ListView< Container >::__iter__

(

)

const

Returns a Python iterator over the elements of this list.

C++

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

Returns

an iterator over the elements of this list.

back()

template<class Container >

ListView< Container >::const_reference regina::ListView< Container >::back

inline

Returns the last element of this list.

Precondition

This list is not empty.

Returns

the last element in this list.

begin()

template<class Container >

ListView< Container >::const_iterator regina::ListView< Container >::begin

inline

Returns a C++ iterator pointing to the first element of this list.

The iterator range from begin() to end() runs through all the elements of this list in order from first to last.

Python

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

Returns

an iterator at the beginning of this list.

empty()

template<class Container >

bool regina::ListView< Container >::empty

inline

Determines if this list is empty.

Returns

true if and only if this list is empty.

end()

template<class Container >

ListView< Container >::const_iterator regina::ListView< Container >::end

inline

Returns a C++ iterator pointing beyond the last element of this list.

The iterator range from begin() to end() runs through all the elements of this list in order from first to last.

Python

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

Returns

an iterator beyond the end of this list.

front()

template<class Container >

ListView< Container >::const_reference regina::ListView< Container >::front

inline

Returns the first element of this list.

Precondition

This list is not empty.

Returns

the first element in this list.

operator!=()

template<class Container >

bool regina::ListView< Container >::operator!= ( const ListView< Container > &  other ) const

inline

Determines whether this and the given list view are accessing different underlying containers.

Here the containers are compared by reference (i.e., to be considered equal they must be the same container object at the same location in memory; it is not enough to be two containers with identical contents).

Parameters

other

the list view to compare with this.

Returns

true if and only if this and the given list use different underlying containers.

operator=()

template<class Container >

ListView & regina::ListView< Container >::operator= ( const ListView< Container > &  )

default

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

Returns

a reference to this list view.

operator==()

template<class Container >

bool regina::ListView< Container >::operator== ( const ListView< Container > &  other ) const

inline

Determines whether this and the given list view are accessing the same underlying container.

Here the containers are compared by reference (i.e., they must be the same container object at the same location in memory; it is not enough to be two containers with identical contents).

Parameters

other

the list view to compare with this.

Returns

true if and only if this and the given list use the same underlying container.

operator[]()

template<class Container >

ListView< Container >::const_reference regina::ListView< Container >::operator[] ( size_type  index ) const

inline

Returns the requested element of this list.

Parameters

index

indicates which element to return; this must be between 0 and size()-1 inclusive.

Returns

the (index)th element in this list.

size()

template<class Container >

ListView< Container >::size_type regina::ListView< Container >::size

inline

Returns the number of elements in this list.

Python

This is also used to implement the Python special method len().

Returns

the number of elements.

---

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

• utilities/listview.h