regina::LightweightSequence< T > Class Template Reference

A lightweight class for storing a random-access sequence of objects. More...

#include <utilities/sequence.h>

Classes
class	SubsequenceCompareFirst
	A binary function object for comparing subsequences, for use in associative containers whose keys are sequences. More...

Public Types
using	iterator = T*
	An iterator type for read-write access to the elements of a sequence.
using	const_iterator = const T*
	An iterator type for read-only access to the elements of a sequence.

Public Member Functions
	LightweightSequence ()
	Creates a new empty sequence; that is, a sequence of size zero.
	LightweightSequence (size_t size)
	Create a new sequence containing the given number of elements.
	LightweightSequence (std::initializer_list< T > elements)
	Create a new sequence containing the given elements.
template<typename... Args>
	LightweightSequence (size_t size, Args &&... elements)
	Create a new sequence containing the given elements, which may be given through a combination of individual elements and iterator pairs.
	LightweightSequence (const LightweightSequence &src)
	Create a copy of the given sequence.
	LightweightSequence (LightweightSequence &&src) noexcept
	Moves the contents of the given sequence to this new sequence.
	~LightweightSequence ()
	Destroys this sequence and all of its elements.
void	init (size_t size=0)
	Resizes this sequence to contain the given number of elements.
size_t	size () const
	Returns the number of elements in this sequence.
bool	empty () const
	Determines whether this sequence is empty.
T	operator[] (size_t pos) const
	Returns a copy of the element at the given index in the sequence.
T &	operator[] (size_t pos)
	Returns a reference to the element at the given index in the sequence.
iterator	begin ()
	Returns a read-write iterator that points to the first element of the sequence.
const_iterator	begin () const
	Returns a read-only iterator that points to the first element of the sequence.
iterator	end ()
	Returns a read-write iterator that points beyond the last element of the sequence.
const_iterator	end () const
	Returns a read-only iterator that points beyond the last element of the sequence.
T	front () const
	Returns a copy of the first element in this sequence.
T &	front ()
	Returns a reference to the first element in this sequence.
T	back () const
	Returns a copy of the last element in this sequence.
T &	back ()
	Returns a reference to the last element in this sequence.
LightweightSequence< T > &	operator= (const LightweightSequence &src)
	Converts this into a copy of the given sequence.
LightweightSequence< T > &	operator= (LightweightSequence &&src) noexcept
	Moves the contents of the given sequence to this sequence.
void	swap (LightweightSequence< T > &other) noexcept
	Swaps the contents of this and the given sequence.
bool	operator== (const LightweightSequence &rhs) const
	Tests whether this and the given sequence are identical.
auto	operator<=> (const LightweightSequence &rhs) const
	Compares two sequences lexicographically.

Detailed Description

template<typename T>
class regina::LightweightSequence< T >

A lightweight class for storing a random-access sequence of objects.

This class is intended as a lightweight substitute for std::vector, especially when working with temporary sequences that are frequently created and destroyed, such as sequence-valued keys or values in maps. The underlying storage just uses a native C-style array, and the C++ class wrapper provides the usual mechanisms for safe and simple memory management.

The size (number of elements) of a sequence can be changed, but this should not be done lightly. Unlike std::vector, resizing a sequence is an expensive operation that deletes all existing contents of the sequence and forces a reallocation of the underlying storage. See init() for details.

This class is very similar in nature to FixedArray, but was born from different needs. It is possible that these two classes will be unified in some future version of Regina.

This class implements C++ move semantics and adheres to the C++ Swappable requirement. It is designed to avoid deep copies wherever possible, even when passing or returning objects by value.

Python

Not present.

Member Typedef Documentation

const_iterator

template<typename T >

using regina::LightweightSequence< T >::const_iterator = const T*

An iterator type for read-only access to the elements of a sequence.

Such a type can be dereferenced (yielding a const reference to type T), and manipulated using the usual pointer arithmetic (such as p++, --p, p += n, and so on).

iterator

template<typename T >

using regina::LightweightSequence< T >::iterator = T*

An iterator type for read-write access to the elements of a sequence.

Such a type can be dereferenced (yielding a reference to type T), and manipulated using the usual pointer arithmetic (such as p++, --p, p += n, and so on).

Constructor & Destructor Documentation

LightweightSequence() [1/6]

template<typename T >

regina::LightweightSequence< T >::LightweightSequence ( )

inline

Creates a new empty sequence; that is, a sequence of size zero.

This sequence can be resized by calling init().

LightweightSequence() [2/6]

template<typename T >

regina::LightweightSequence< T >::LightweightSequence ( size_t size )

inlineexplicit

Create a new sequence containing the given number of elements.

The elements themselves will be initialised using the default constructor for type T.

Parameters

size	the number of elements in the new sequence.

LightweightSequence() [3/6]

template<typename T >

regina::LightweightSequence< T >::LightweightSequence ( std::initializer_list< T > elements )

inline

Create a new sequence containing the given elements.

Parameters

elements

the elements to place in the new sequence.

LightweightSequence() [4/6]

template<typename T >

template<typename... Args>

regina::LightweightSequence< T >::LightweightSequence ( size_t size, Args &&... elements )

inlineexplicit

Create a new sequence containing the given elements, which may be given through a combination of individual elements and iterator pairs.

Specifically, this constructor will step through the elements arguments in turn:

• If the next argument is of type T (or can be implicitly converted to type T), then the corresponding value will be added onto the end of the sequence.
• If the next argument is a LightweightSequence iterator, then this must be followed by another LightweightSequence iterator. The range defined by this iterator pair will be copied onto the end of the sequence.

The routine requires you to pass the entire length of the sequence in advance; this is so the necessary memory can be pre-allocated without requiring any unnecessary arithmetic.

Precondition

The argument size is precisely the sum of the lengths of all iterator ranges plus the number of standalone elements in the argument list elements.

Parameters

size	the number of elements in the new sequence.
elements	the elements and/or iterator ranges with which to fill the sequence, as described above.

LightweightSequence() [5/6]

template<typename T >

regina::LightweightSequence< T >::LightweightSequence ( const LightweightSequence< T > & src )

inline

Create a copy of the given sequence.

This induces a deep copy of src, in that all of the elements of src will be copied into the new sequence.

Parameters

src	the sequence to copy.

LightweightSequence() [6/6]

template<typename T >

regina::LightweightSequence< T >::LightweightSequence ( LightweightSequence< T > && src )

inlinenoexcept

Moves the contents of the given sequence to this new sequence.

This is a fast (constant time) operation.

The sequence that was passed (src) will no longer be usable.

Parameters

src	the sequence to move.

~LightweightSequence()

template<typename T >

regina::LightweightSequence< T >::~LightweightSequence ( )

inline

Destroys this sequence and all of its elements.

All elements of the sequence will be destroyed using the destructor for type T. If the elements are pointers whose pointee objects need to be deleted also, you must do this separately before destroying the sequence itself.

Member Function Documentation

back() [1/2]

template<typename T >

T & regina::LightweightSequence< T >::back ( )

inline

Returns a reference to the last element in this sequence.

Precondition

This sequence is non-empty.

Returns

a reference to the last element.

back() [2/2]

template<typename T >

T regina::LightweightSequence< T >::back ( ) const

inline

Returns a copy of the last element in this sequence.

Precondition

This sequence is non-empty.

Returns

a copy of the last element.

begin() [1/2]

template<typename T >

LightweightSequence< T >::iterator regina::LightweightSequence< T >::begin ( )

inline

Returns a read-write iterator that points to the first element of the sequence.

Note that an iterator is simply a pointer to an element of the sequence, and so by dereferencing an iterator you can change the corresponding element of the sequence directly.

Returns

a read-write begin iterator.

begin() [2/2]

template<typename T >

LightweightSequence< T >::const_iterator regina::LightweightSequence< T >::begin ( ) const

inline

Returns a read-only iterator that points to the first element of the sequence.

Note that a const_iterator is simply a const pointer to an element of the sequence, and so by dereferencing a const_iterator you can access (but not change) the corresponding element of the sequence.

Returns

a read-only begin iterator.

empty()

template<typename T >

bool regina::LightweightSequence< T >::empty ( ) const

inline

Determines whether this sequence is empty.

This is true if and only if size() == 0.

Returns

true if and only if this sequence is empty.

end() [1/2]

template<typename T >

LightweightSequence< T >::iterator regina::LightweightSequence< T >::end ( )

inline

Returns a read-write iterator that points beyond the last element of the sequence.

Note that, because this iterator is past-the-end, it must not be dereferenced.

Returns

a read-write past-the-end iterator.

end() [2/2]

template<typename T >

LightweightSequence< T >::const_iterator regina::LightweightSequence< T >::end ( ) const

inline

Returns a read-only iterator that points beyond the last element of the sequence.

Note that, because this iterator is past-the-end, it must not be dereferenced.

Returns

a read-only past-the-end iterator.

front() [1/2]

template<typename T >

T & regina::LightweightSequence< T >::front ( )

inline

Returns a reference to the first element in this sequence.

Precondition

This sequence is non-empty.

Returns

a reference to the first element.

front() [2/2]

template<typename T >

T regina::LightweightSequence< T >::front ( ) const

inline

Returns a copy of the first element in this sequence.

Precondition

This sequence is non-empty.

Returns

a copy of the first element.

init()

template<typename T >

void regina::LightweightSequence< T >::init ( size_t size = 0 )

inline

Resizes this sequence to contain the given number of elements.

All existing elements in this sequence will be destroyed, using the default destructor for type T. If the elements are pointers whose pointee objects need to be deleted also, you must do this separately before calling init().

The elements of the sequence after this routine is called will be initialised using the default constructor for type T.

Warning

Calling init() is an expensive operation, in that it will always force a reallocation of the underlying storage (even if the new size is smaller than the old).

Parameters

size	the number of elements that the sequence will contain after this routine is called.

operator<=>()

template<typename T >

auto regina::LightweightSequence< T >::operator<=> ( const LightweightSequence< T > & rhs ) const

inline

Compares two sequences lexicographically.

The sequences need not be the same size.

This generates all of the usual comparison operators, including <, <=, >, and >=.

Parameters

rhs	the sequence to compare this with.

Returns

The result of the lexicographical comparison between this and the given sequence. This will be of the strongest possible comparison category type for comparing objects of type T (so, for example, the return type will be std::strong_ordering when working with sequences of integers).

operator=() [1/2]

template<typename T >

LightweightSequence< T > & regina::LightweightSequence< T >::operator= ( const LightweightSequence< T > & src )

inline

Converts this into a copy of the given sequence.

Any existing elements of this sequence will be deleted.

This induces a deep copy of src, in that all of the elements of src will be copied into the new sequence.

Parameters

src	the sequence to copy.

Returns

a reference to this sequence.

operator=() [2/2]

template<typename T >

LightweightSequence< T > & regina::LightweightSequence< T >::operator= ( LightweightSequence< T > && src )

inlinenoexcept

Moves the contents of the given sequence to this sequence.

This is a fast (constant time) operation.

The sequence that was passed (src) will no longer be usable.

Parameters

src	the sequence to move.

Returns

a reference to this sequence.

operator==()

template<typename T >

bool regina::LightweightSequence< T >::operator== ( const LightweightSequence< T > & rhs ) const

inline

Tests whether this and the given sequence are identical.

The sequences need not be the same size, though if the sizes are different then this routine will return false immediately.

Parameters

rhs	the sequence to compare with this.

Returns

true if and only if this and the given sequence are identical.

operator[]() [1/2]

template<typename T >

T & regina::LightweightSequence< T >::operator[] ( size_t pos )

inline

Returns a reference to the element at the given index in the sequence.

Parameters

pos	the index of the requested element; this must be between 0 and size()-1 inclusive.

Returns

a reference to the requested element.

operator[]() [2/2]

template<typename T >

T regina::LightweightSequence< T >::operator[] ( size_t pos ) const

inline

Returns a copy of the element at the given index in the sequence.

Parameters

pos	the index of the requested element; this must be between 0 and size()-1 inclusive.

Returns

a copy of the requested element.

size()

template<typename T >

size_t regina::LightweightSequence< T >::size ( ) const

inline

Returns the number of elements in this sequence.

This can be changed (in a destructive way) by calling init().

swap()

template<typename T >

void regina::LightweightSequence< T >::swap ( LightweightSequence< T > & other )

inlinenoexcept

Swaps the contents of this and the given sequence.

Parameters

other

the sequence whose contents are to be swapped with this.

---

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

• utilities/sequence.h