Regina 7.0 Calculation Engine
Classes | Public Types | Public Member Functions | List of all members
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. More...
 
using const_iterator = const T *
 An iterator type for read-only access to the elements of a sequence. More...
 

Public Member Functions

 LightweightSequence ()
 Creates a new empty sequence; that is, a sequence of size zero. More...
 
 LightweightSequence (size_t size)
 Create a new sequence containing the given number of elements. More...
 
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. More...
 
 LightweightSequence (const LightweightSequence &src)
 Create a copy of the given sequence. More...
 
 LightweightSequence (LightweightSequence &&src) noexcept
 Moves the contents of the given sequence to this new sequence. More...
 
 ~LightweightSequence ()
 Destroys this sequence and all of its elements. More...
 
void init (size_t size=0)
 Resizes this sequence to contain the given number of elements. More...
 
size_t size () const
 Returns the number of elements in this sequence. More...
 
operator[] (size_t pos) const
 Returns a copy of the element at the given index in the sequence. More...
 
T & operator[] (size_t pos)
 Returns a reference to the element at the given index in the sequence. More...
 
iterator begin ()
 Returns a read-write iterator that points to the first element of the sequence. More...
 
const_iterator begin () const
 Returns a read-only iterator that points to the first element of the sequence. More...
 
iterator end ()
 Returns a read-write iterator that points beyond the last element of the sequence. More...
 
const_iterator end () const
 Returns a read-only iterator that points beyond the last element of the sequence. More...
 
LightweightSequence< T > & operator= (const LightweightSequence &src)
 Converts this into a copy of the given sequence. More...
 
LightweightSequence< T > & operator= (LightweightSequence &&src) noexcept
 Moves the contents of the given sequence to this sequence. More...
 
void swap (LightweightSequence< T > &other) noexcept
 Swaps the contents of this and the given sequence. More...
 
bool operator== (const LightweightSequence &rhs) const
 Tests whether this and the given sequence are identical. More...
 
bool operator< (const LightweightSequence &rhs) const
 Tests whether this sequence is lexicographically smaller than the given sequence. More...
 

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. 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 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/5]

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/5]

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
sizethe number of elements in the new sequence.

◆ LightweightSequence() [3/5]

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
sizethe number of elements in the new sequence.
elementsthe elements and/or iterator ranges with which to fill the sequence, as described above.

◆ LightweightSequence() [4/5]

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
srcthe sequence to copy.

◆ LightweightSequence() [5/5]

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
srcthe 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

◆ 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
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.

◆ 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
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.

◆ 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
sizethe number of elements that the sequence will contain after this routine is called.

◆ operator<()

template<typename T >
bool regina::LightweightSequence< T >::operator< ( const LightweightSequence< T > &  rhs) const
inline

Tests whether this sequence is lexicographically smaller than the given sequence.

The sequences need not be the same size.

Parameters
rhsthe sequence to compare with this.
Returns
true if this is strictly lexicographically smaller than rhs, or false if this is either lexicographically greater than or equal to rhs.

◆ 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
srcthe 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
srcthe 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
rhsthe 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
posthe 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
posthe 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
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
otherthe sequence whose contents are to be swapped with this.

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

Copyright © 1999-2021, The Regina development team
This software is released under the GNU General Public License, with some additional permissions; see the source code for details.
For further information, or to submit a bug or other problem, please contact Ben Burton (bab@maths.uq.edu.au).