An optimised vector class of elements from a given ring T. More...

#include <maths/vector.h>

Inheritance diagram for regina::Vector< T >:

Public Types
using	value_type = T
	The type of element that is stored in this vector. More...

using	size_type = size_t
	The type used for indexing into this vector. More...

using	reference = T &
	A reference to an element of this vector. More...

using	const_reference = const T &
	A const reference to an element of this vector. More...

using	iterator = T *
	The non-const iterator type for this vector. More...

using	const_iterator = const T *
	The const iterator type for this vector. More...

using	Element = T
	Deprecated alias for the type of element that is stored in this vector. More...

Public Member Functions
	Vector (size_t newVectorSize)
	Creates a new vector. More...

	Vector (size_t newVectorSize, const T &initValue)
	Creates a new vector and initialises every element to the given value. More...

template<typename iterator >
	Vector (iterator begin, iterator end)
	Creates a new vector containing the given sequence of elements. More...

	Vector (std::initializer_list< T > data)
	Creates a new vector containing the given hard-coded elements. More...

	Vector (const Vector< T > &src)
	Creates a new vector that is a clone of the given vector. More...

	Vector (Vector &&src) noexcept
	Moves the given vector into this new vector. More...

	~Vector ()
	Destroys this vector. More...

size_t	size () const
	Returns the number of elements in the vector. More...

const T &	operator[] (size_t index) const
	Returns the element at the given index in the vector. More...

T &	operator[] (size_t index)
	Gives write access to the element at the given index in the vector. More...

void	setElement (size_t index, const T &value)
	Deprecated routine that sets the element at the given index in the vector to the given value. More...

iterator	begin ()
	Returns the beginning of a non-const iterator range that runs through all elements of this vector. More...

const_iterator	begin () const
	Returns the beginning of a const iterator range that runs through all elements of this vector. More...

iterator	end ()
	Returns the end of a non-const iterator range that runs through all elements of this vector. More...

const_iterator	end () const
	Returns the end of a const iterator range that runs through all elements of this vector. More...

bool	operator== (const Vector< T > &compare) const
	Determines if this vector is equal to the given vector. More...

bool	operator!= (const Vector< T > &compare) const
	Determines if this vector is different from the given vector. More...

Vector< T > &	operator= (const Vector< T > &src)
	Sets this vector equal to the given vector. More...

Vector &	operator= (Vector &&src) noexcept
	Moves the given vector into this vector. More...

void	swap (Vector &other) noexcept
	Swaps the contents of this and the given vector. More...

Vector &	operator+= (const Vector< T > &other)
	Adds the given vector to this vector. More...

Vector &	operator-= (const Vector< T > &other)
	Subtracts the given vector from this vector. More...

Vector &	operator*= (const T &factor)
	Multiplies this vector by the given scalar. More...

Vector	operator+ (const Vector< T > &other) const
	Adds the given vector to this vector, and returns the result. More...

Vector	operator- (const Vector< T > &other) const
	Subtracts the given vector from this vector, and returns the result. More...

Vector	operator* (const T &factor) const
	Multiplies this vector by the given scalar, and returns the result. More...

T	operator* (const Vector< T > &other) const
	Calculates the dot product of this vector and the given vector. More...

void	negate ()
	Negates every element of this vector. More...

T	norm () const
	Returns the norm of this vector. More...

T	elementSum () const
	Returns the sum of all elements of this vector. More...

void	addCopies (const Vector< T > &other, const T &multiple)
	Adds the given multiple of the given vector to this vector. More...

void	subtractCopies (const Vector< T > &other, const T &multiple)
	Subtracts the given multiple of the given vector to this vector. More...

bool	isZero () const
	Determines whether this is the zero vector. More...

void	writeTextShort (std::ostream &out) const
	Writes a short text representation of this object to the given output stream. More...

void	scaleDown ()
	Scales this vector down by the greatest common divisor of all its elements. More...

void	writeTextLong (std::ostream &out) const
	A default implementation for detailed output. More...

std::string	str () const
	Returns a short text representation of this object. More...

std::string	utf8 () const
	Returns a short text representation of this object using unicode characters. More...

std::string	detail () const
	Returns a detailed text representation of this object. More...

Static Public Member Functions
static Vector	unit (size_t dimension, size_t coordinate)
	Returns the given unit vector. More...

Static Public Attributes
static const T	zero
	Zero in the underlying number system. More...

static const T	one
	One in the underlying number system. More...

static const T	minusOne
	Negative one in the underlying number system. More...

Protected Attributes
T *	elts_
	The internal array containing all vector elements. More...

T *	end_
	A pointer just beyond the end of the internal array. More...

Detailed Description

template<class T>
class regina::Vector< T >

An optimised vector class of elements from a given ring T.

Various mathematical vector operations are available.

This class is intended for serious computation, and as a result it has a streamlined implementation with no virtual methods. It can be subclassed, but since there are no virtual methods, type information must generally be known at compile time. Nevertheless, in many respects, different subclasses of Vector<T> can happily interact with one another.

This class is written with bulky types in mind (such as arbitrary precision integers), and so creations and operations are kept to a minimum.

As of Regina 7.0, this class explicitly supports zero-length vectors.

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.

Warning: As of Regina 4.90, this class merges the old functionality of NFastVector and the NVector hierarchy from Regina 4.6. As a side-effect, the hierarchy has been compressed into just one class (NVectorUnit, NVectorMatrix and NVectorDense are gone), elements are always stored as dense vectors, and functions are no longer virtual (since the storage model is now fixed). The virtual clone() method is gone completely (since there are no longer virtual functions you should use the copy constructor instead), and the old makeLinComb() method is also gone (just use operator *= and addCopies()).

Precondition: Type T has a copy constructor. That is, if a and b are of type T, then a can be initialised to the value of b using a(b).; Type T has a default constructor. That is, an object of type T can be declared with no arguments. No specific default value is required.; Type T allows for operators =, ==, +=, -=, *=, +, - and *.; Type T has an integer constructor. That is, if a is of type T, then a can be initialised to an integer l using a(l).; An element t of type T can be written to an output stream out using the standard expression out << t.

Python: Not present in general, although the specific types Vector<Integer> and Vector<LargeInteger> are available under the names VectorInt and VectorLarge respectively.

Member Typedef Documentation

◆ const_iterator

template<class T >

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

The const iterator type for this vector.

◆ const_reference

template<class T >

using regina::Vector< T >::const_reference = const T&

A const reference to an element of this vector.

◆ Element

template<class T >

using regina::Vector< T >::Element = T

Deprecated alias for the type of element that is stored in this vector.

Deprecated:: This has been renamed to value_type, for consistency with standard C++ container types.

◆ iterator

template<class T >

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

The non-const iterator type for this vector.

◆ reference

template<class T >

using regina::Vector< T >::reference = T&

A reference to an element of this vector.

◆ size_type

template<class T >

using regina::Vector< T >::size_type = size_t

The type used for indexing into this vector.

◆ value_type

template<class T >

using regina::Vector< T >::value_type = T

The type of element that is stored in this vector.

Constructor & Destructor Documentation

◆ Vector() [1/6]

template<class T >

regina::Vector< T >::Vector ( size_t newVectorSize )

inline

Creates a new vector.

All entries will be initialised using their default constructors. In particular, this means that for Regina's own integer classes (Integer, LargeInteger and NativeInteger), all entries will be initialised to zero.

Warning: If T is a native C++ integer type (such as int or long), then the elements will not be initialised to any particular value.

Parameters

newVectorSize the number of elements in the new vector.

◆ Vector() [2/6]

template<class T >

regina::Vector< T >::Vector	(	size_t	newVectorSize,
		const T &	initValue
	)

inline

Creates a new vector and initialises every element to the given value.

Parameters

newVectorSize	the number of elements in the new vector.
initValue	the value to assign to every element of the vector.

◆ Vector() [3/6]

template<class T >

template<typename iterator >

regina::Vector< T >::Vector	(	iterator	begin,
		iterator	end
	)

inline

Creates a new vector containing the given sequence of elements.

This constructor induces a deep copy of the given range.

Precondition: Objects of type T can be assigned values from dereferenced iterators of type iterator.

Warning: This routine computes the length of the given sequence by subtracting end - begin, and so ideally iterator should be a random access iterator type for which this operation is constant time.

Python: Instead of a pair of iterators, this routine takes a python list of coefficients.

Parameters

begin	the beginning of the sequence of elements.
end	a past-the-end iterator indicating the end of the sequence of elements.

◆ Vector() [4/6]

template<class T >

regina::Vector< T >::Vector ( std::initializer_list< T > data )

inline

Creates a new vector containing the given hard-coded elements.

This constructor can be used (for example) to create hard-coded examples directly in C++ code.

Python: Not available, but there is a Python constructor that takes a list of coefficients (which need not be constant).

Parameters

data	the elements of the vector.

◆ Vector() [5/6]

template<class T >

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

inline

Creates a new vector that is a clone of the given vector.

Parameters

src	the vector to clone.

◆ Vector() [6/6]

template<class T >

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

inlinenoexcept

Moves the given vector into this new vector.

This is a fast (constant time) operation.

The vector that is passed (src) will no longer be usable.

Parameters

src	the vector to move.

◆ ~Vector()

template<class T >

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

inline

Destroys this vector.

Member Function Documentation

◆ addCopies()

template<class T >

void regina::Vector< T >::addCopies	(	const Vector< T > &	other,
		const T &	multiple
	)

inline

Adds the given multiple of the given vector to this vector.

This behaves correctly in the case where other is this.

Precondition: This and the given vector have the same size.

Parameters

other	the vector a multiple of which will be added to this vector.
multiple	the multiple of other to be added to this vector.

◆ begin() [1/2]

template<class T >

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

inline

Returns the beginning of a non-const iterator range that runs through all elements of this vector.

This is safe to use even if this vector has zero length (in which case begin() and end() will be equal).

Python: Vector is an iterable object: instead of providing begin() and end(), it implements the Python iterable interface.

Returns: an iterator pointing to the first element of this vector.

◆ begin() [2/2]

template<class T >

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

inline

Returns the beginning of a const iterator range that runs through all elements of this vector.

This is safe to use even if this vector has zero length (in which case begin() and end() will be equal).

Python: Vector is an iterable object: instead of providing begin() and end(), it implements the Python iterable interface.

Returns: an iterator pointing to the first element of this vector.

◆ detail()

template<class T , bool supportsUtf8 = false>

std::string regina::Output< T, supportsUtf8 >::detail ( ) const

inherited

Returns a detailed text representation of this object.

This text may span many lines, and should provide the user with all the information they could want. It should be human-readable, should not contain extremely long lines (which cause problems for users reading the output in a terminal), and should end with a final newline. There are no restrictions on the underlying character set.

Returns: a detailed text representation of this object.

◆ elementSum()

template<class T >

T regina::Vector< T >::elementSum ( ) const

inline

Returns the sum of all elements of this vector.

Returns: the sum of the elements of this vector.

◆ end() [1/2]

template<class T >

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

inline

Returns the end of a non-const iterator range that runs through all elements of this vector.

This is safe to use even if this vector has zero length (in which case begin() and end() will be equal).

Python: Vector is an iterable object: instead of providing begin() and end(), it implements the Python iterable interface.

Returns: an iterator beyond the last element of this vector.

◆ end() [2/2]

template<class T >

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

inline

Returns the end of a const iterator range that runs through all elements of this vector.

This is safe to use even if this vector has zero length (in which case begin() and end() will be equal).

Python: Vector is an iterable object: instead of providing begin() and end(), it implements the Python iterable interface.

Returns: an iterator beyond the last element of this vector.

◆ isZero()

template<class T >

bool regina::Vector< T >::isZero ( ) const

inline

Determines whether this is the zero vector.

Returns: true if and only if all elements of the vector are zero.

◆ negate()

template<class T >

void regina::Vector< T >::negate ( )

inline

Negates every element of this vector.

◆ norm()

template<class T >

T regina::Vector< T >::norm ( ) const

inline

Returns the norm of this vector.

This is the dot product of the vector with itself.

Returns: the norm of this vector.

◆ operator!=()

template<class T >

bool regina::Vector< T >::operator!= ( const Vector< T > & compare ) const

inline

Determines if this vector is different from the given vector.

It is safe to call this operator if this and the given vector have different sizes (in which case the return value will be true).

Parameters

compare the vector with which this will be compared.

Returns: true if and only if the this and the given vector are not equal.

◆ operator*() [1/2]

template<class T >

Vector regina::Vector< T >::operator* ( const T & factor ) const

inline

Multiplies this vector by the given scalar, and returns the result.

This vector will not be changed.

Parameters

factor the scalar to multiply this vector by.

Returns: the product this * factor.

◆ operator*() [2/2]

template<class T >

T regina::Vector< T >::operator* ( const Vector< T > & other ) const

inline

Calculates the dot product of this vector and the given vector.

Precondition: This and the given vector have the same size.

Parameters

other the vector with which this will be multiplied.

Returns: the dot product of this and the given vector.

◆ operator*=()

template<class T >

Vector & regina::Vector< T >::operator*= ( const T & factor )

inline

Multiplies this vector by the given scalar.

This vector will be changed directly.

Parameters

factor the scalar with which this will be multiplied.

Returns: a reference to this vector.

◆ operator+()

template<class T >

Vector regina::Vector< T >::operator+ ( const Vector< T > & other ) const

inline

Adds the given vector to this vector, and returns the result.

This vector will not be changed.

Precondition: This and the given vector have the same size.

Parameters

other the vector to add to this vector.

Returns: the sum this + other.

◆ operator+=()

template<class T >

Vector & regina::Vector< T >::operator+= ( const Vector< T > & other )

inline

Adds the given vector to this vector.

This vector will be changed directly. This behaves correctly in the case where other is this.

Precondition: This and the given vector have the same size.

Parameters

other the vector to add to this vector.

Returns: a reference to this vector.

◆ operator-()

template<class T >

Vector regina::Vector< T >::operator- ( const Vector< T > & other ) const

inline

Subtracts the given vector from this vector, and returns the result.

This vector will not be changed.

Precondition: This and the given vector have the same size.

Parameters

other the vector to subtract from this vector.

Returns: the difference this - other.

◆ operator-=()

template<class T >

Vector & regina::Vector< T >::operator-= ( const Vector< T > & other )

inline

Subtracts the given vector from this vector.

This vector will be changed directly. This behaves correctly in the case where other is this.

Precondition: This and the given vector have the same size.

Parameters

other the vector to subtract from this vector.

Returns: a reference to this vector.

◆ operator=() [1/2]

template<class T >

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

inline

Sets this vector equal to the given vector.

It does not matter if this and the given vector have different sizes; if they do then this vector will be resized as a result.

Parameters

src	the vector whose value shall be assigned to this vector.

◆ operator=() [2/2]

template<class T >

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

inlinenoexcept

Moves the given vector into this vector.

This is a fast (constant time) operation.

It does not matter if this and the given vector have different sizes; if they do then this vector will be resized as a result.

The vector that is passed (src) will no longer be usable.

Parameters

src	the vector to move.

Returns: a reference to this vector.

◆ operator==()

template<class T >

bool regina::Vector< T >::operator== ( const Vector< T > & compare ) const

inline

Determines if this vector is equal to the given vector.

It is safe to call this operator if this and the given vector have different sizes (in which case the return value will be false).

Parameters

compare the vector with which this will be compared.

Returns: true if and only if the this and the given vector are equal.

◆ operator[]() [1/2]

template<class T >

T & regina::Vector< T >::operator[] ( size_t index )

inline

Gives write access to the element at the given index in the vector.

Precondition: index is between 0 and size()-1 inclusive.

Parameters

index the vector index to access.

Returns: a reference to the vector element at the given index.

◆ operator[]() [2/2]

template<class T >

const T & regina::Vector< T >::operator[] ( size_t index ) const

inline

Returns the element at the given index in the vector.

A constant reference to the element is returned; the element may not be altered.

Precondition: index is between 0 and size()-1 inclusive.

Parameters

index the vector index to examine.

Returns: the vector element at the given index.

◆ scaleDown()

template<class T >

void regina::Vector< T >::scaleDown ( )

inline

Scales this vector down by the greatest common divisor of all its elements.

The resulting vector will be the smallest multiple of the original that maintains integral entries, and these entries will have the same signs as the originals.

In particular, if this vector is being used to represent a ray emanating from the origin, then this routine reduces the ray to its smallest possible integer representation.

This routine poses no problem for vectors containing infinite elements; such elements are simply ignored and left at infinity.

This routine is only available when T is one of Regina's own integer classes (Integer, LargeInteger, or NativeInteger).

◆ setElement()

template<class T >

void regina::Vector< T >::setElement	(	size_t	index,
		const T &	value
	)

inline

Deprecated routine that sets the element at the given index in the vector to the given value.

Deprecated:: Simply use the square bracker operator instead.

Precondition: index is between 0 and size()-1 inclusive.

Parameters

index	the vector index to examine.
value	the new value to assign to the element.

◆ size()

template<class T >

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

inline

Returns the number of elements in the vector.

Returns: the vector size.

◆ str()

template<class T , bool supportsUtf8 = false>

std::string regina::Output< T, supportsUtf8 >::str ( ) const

inherited

Returns a short text representation of this object.

This text should be human-readable, should use plain ASCII characters where possible, and should not contain any newlines.

Within these limits, this short text ouptut should be as information-rich as possible, since in most cases this forms the basis for the Python str() and repr() functions.

Python: The Python "stringification" function str() will use precisely this function, and for most classes the Python repr() function will incorporate this into its output.

Returns: a short text representation of this object.

◆ subtractCopies()

template<class T >

void regina::Vector< T >::subtractCopies	(	const Vector< T > &	other,
		const T &	multiple
	)

inline

Subtracts the given multiple of the given vector to this vector.

This behaves correctly in the case where other is this.

Precondition: This and the given vector have the same size.

Parameters

other	the vector a multiple of which will be subtracted from this vector.
multiple	the multiple of other to be subtracted from this vector.

◆ swap()

template<class T >

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

inlinenoexcept

Swaps the contents of this and the given vector.

Parameters

other the vector whose contents are to be swapped with this.

◆ unit()

template<class T >

static Vector regina::Vector< T >::unit	(	size_t	dimension,
		size_t	coordinate
	)

inlinestatic

Returns the given unit vector.

The vector will have length dimension. The element in position coordinate will be set to 1, and all other elements will be set to 0.

Parameters

dimension	the number of elements in the vector.
coordinate	the coordinate position that should hold the value 1; this must be between 0 and (dimension - 1) inclusive.

Returns: the requested unit vector.

◆ utf8()

template<class T , bool supportsUtf8 = false>

std::string regina::Output< T, supportsUtf8 >::utf8 ( ) const

inherited

Returns a short text representation of this object using unicode characters.

Like str(), this text should be human-readable, should not contain any newlines, and (within these constraints) should be as information-rich as is reasonable.

Unlike str(), this function may use unicode characters to make the output more pleasant to read. The string that is returned will be encoded in UTF-8.

Returns: a short text representation of this object.

◆ writeTextLong()

void regina::ShortOutput< Vector< T > , false >::writeTextLong ( std::ostream & out ) const

inlineinherited

A default implementation for detailed output.

This routine simply calls T::writeTextShort() and appends a final newline.

Python: Not present; instead you can call detail() from the subclass T, which returns this output as a string.

Parameters

out	the output stream to which to write.

◆ writeTextShort()

template<class T >

void regina::Vector< T >::writeTextShort ( std::ostream & out ) const

inline

Writes a short text representation of this object to the given output stream.

Python: Not present; use str() instead.

Parameters

out	the output stream to which to write.

Member Data Documentation

◆ elts_

template<class T >

T* regina::Vector< T >::elts_

protected

The internal array containing all vector elements.

◆ end_

template<class T >

T* regina::Vector< T >::end_

protected

A pointer just beyond the end of the internal array.

The size of the vector can be computed as (end_ - elts_).

◆ minusOne

template<class T >

const T regina::Vector< T >::minusOne

static

Negative one in the underlying number system.

Deprecated:: This constant is deprecated; just use -1 instead.

◆ one

template<class T >

const T regina::Vector< T >::one

static

One in the underlying number system.

Deprecated:: This constant is deprecated; just use 1 instead.

◆ zero

template<class T >

const T regina::Vector< T >::zero

static

Zero in the underlying number system.

Deprecated:: This constant is deprecated; just use 0 instead.

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

maths/matrix.h
maths/vector.h

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Attributes

Detailed Description

Member Typedef Documentation

◆ const_iterator

◆ const_reference

◆ Element

◆ iterator

◆ reference

◆ size_type

◆ value_type

Constructor & Destructor Documentation

◆ Vector() [1/6]

◆ Vector() [2/6]

◆ Vector() [3/6]

◆ Vector() [4/6]

◆ Vector() [5/6]

◆ Vector() [6/6]

◆ ~Vector()

Member Function Documentation

◆ addCopies()

◆ begin() [1/2]

◆ begin() [2/2]

◆ detail()

◆ elementSum()

◆ end() [1/2]

◆ end() [2/2]

◆ isZero()

◆ negate()

◆ norm()

◆ operator!=()

◆ operator*() [1/2]

◆ operator*() [2/2]

◆ operator*=()

◆ operator+()

◆ operator+=()

◆ operator-()

◆ operator-=()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ operator==()

◆ operator[]() [1/2]

◆ operator[]() [2/2]

◆ scaleDown()

◆ setElement()

◆ size()

◆ str()

◆ subtractCopies()

◆ swap()

◆ unit()

◆ utf8()

◆ writeTextLong()

◆ writeTextShort()

Member Data Documentation

◆ elts_

◆ end_

◆ minusOne

◆ one

◆ zero