Qx::Index< T > Class Template Reference

The Index template class provides a wrapper for integers with the notion of 'first', 'last' and 'null'. More...

#include <qx/core/qx-index.h>

Public Member Functions
constexpr	Index ()
constexpr	Index (Extent e)
constexpr	Index (T value)
bool	isLast () const
bool	isNull () const
T &	operator* ()
Index	operator* (const Index &other)
Index &	operator*= (const Index &other)
Index	operator+ (const Index &other)
Index &	operator++ ()
Index	operator++ (int)
Index &	operator+= (const Index &other)
Index	operator- (const Index &other)
Index &	operator-- ()
Index	operator-- (int)
Index &	operator-= (const Index &other)
Index	operator/ (const Index &other)
Index &	operator/= (const Index &other)
std::strong_ordering	operator<=> (const Index &other) const noexcept
bool	operator== (const Index &other) const noexcept

Detailed Description

template<typename T>
requires std::signed_integral<T>
class Qx::Index< T >

When working with contiguous data that must be referenced by index, it is often helpful to be able to refer to the last value of a dataset without necessarily knowing its size. Since integers only intrinsically support purely numerical values, this is often achieved by using the value -1, but this can be prone to error and require awkward handling of arithmetic, especially since implementations that use this approach also tend to simultaneously use -1 to mean 'none' in the context of searches.

The Index type is designed to remedy this issue by providing a more distinct representation of a set's final index via the constructor Index(Extent), which can also be used to more explicitly reference the first index. The type also can be null, providing further clarity for the 'none' case.

To minimize unintentional interactions, Index<T> only has comparison and arithmetic operators defined for when both operands are instances of the class and the underlying raw value must otherwise be accessed explicitly with Index<T>::operator*().

Arithmetic:

Arithmetic with indices mirrors standard integer arithmetic with the following two exceptions:

1) 'last' indices are treated as pseudo-infinite values

Index<int>(Qx::Last) + 10 // = Index<int>(Qx::Last)
Index<int>(Qx::Last) - 10 // = Index<int>(Qx::Last)
Index<int>(5) + Index<int>(Qx::Last) // = Index<int>(Qx::Last)
Index<int>(1087) - Index<int>(Qx::Last) // = 0
Index<int>(Qx::Last) * 130 // = Index<int>(Qx::Last)
Index<int>(Qx::Last) / 58 // = Index<int>(Qx::Last)
Index<int>(Qx::Last) / Index<int>(Qx::Last) // = 1
Index<int>(98) / Index<int>(Qx::Last) // = 0

2) Null indices are equivalent to 0.

All arithmetic for this class is constrained such that an instance's value can never be negative, nor can it underflow or overflow.

Comparison:

Comparison between indices mirrors standard integer comparison with the following two exceptions:

• 1) Null indices are less than everything except other null indices (lowest possible value)
• 2) 'last' indices are greater than everything except other 'last' indices (highest possible value)

Constructor & Destructor Documentation

Index() [1/3]

template<typename T >

Qx::Index< T >::Index ( )

inlineconstexpr

Creates an null index.

Index() [2/3]

template<typename T >

Qx::Index< T >::Index ( Extent e )

inlineconstexpr

Creates an index at the given extent e.

Index() [3/3]

template<typename T >

Qx::Index< T >::Index ( T value )

inlineconstexpr

Creates an index with the underlying value.

A value < 0 will result in a null index.

Member Function Documentation

isLast()

template<typename T >

bool Qx::Index< T >::isLast ( ) const

inline

Returns true if the index represents the last index of an arbitrary dataset; otherwise returns false.

This is equivalent to *this == Index<T>(Qx::Last).

isNull()

template<typename T >

bool Qx::Index< T >::isNull ( ) const

inline

Returns true if the index is null; otherwise returns false.

operator*() [1/2]

template<typename T >

T Qx::Index< T >::operator* ( )

inline

Returns the underlying value of the index.

Warning

The resulting value is std::numeric_limits<T>::max() and for 'last' indices and 0 for null indices respectively, and therefore can cause unexpected results if this operator is used blindly. Using this operator is essentially an acknowledgment that the null and 'last' states have already been checked/accounted for, or that this conversion behavior is desirable in a given context.

operator*() [2/2]

template<typename T >

Index< T > Qx::Index< T >::operator* ( const Index< T > & other )

inline

Returns an index that is the product of this index and other.

operator*=()

template<typename T >

Index< T > & Qx::Index< T >::operator*= ( const Index< T > & other )

inline

Multiplies other with this index and returns a reference to this index.

operator+()

template<typename T >

Index< T > Qx::Index< T >::operator+ ( const Index< T > & other )

inline

Returns an index that is the sum between this index and other.

operator++() [1/2]

template<typename T >

Index< T > & Qx::Index< T >::operator++ ( )

inline

Increases the index by 1, unless its 'last' or null, and returns a reference to the index.

operator++() [2/2]

template<typename T >

Index< T > Qx::Index< T >::operator++ ( int )

inline

Increases the index by 1, unless its 'last' or null, and returns a pre-increment copy of the index.

operator+=()

template<typename T >

Index< T > & Qx::Index< T >::operator+= ( const Index< T > & other )

inline

Adds other from this index and returns a reference to this index.

operator-()

template<typename T >

Index< T > Qx::Index< T >::operator- ( const Index< T > & other )

inline

Returns an index that is the difference between this index and other.

operator--() [1/2]

template<typename T >

Index< T > & Qx::Index< T >::operator-- ( )

inline

Decreases the index by 1, unless its 'last' or null, and returns a reference to the index.

operator--() [2/2]

template<typename T >

Index< T > Qx::Index< T >::operator-- ( int )

inline

Decreases the index by 1, unless its 'last' or null, and returns a pre-decrement copy of the index.

operator-=()

template<typename T >

Index< T > & Qx::Index< T >::operator-= ( const Index< T > & other )

inline

Subtracts other from this index and returns a reference to this index.

operator/()

template<typename T >

Index< T > Qx::Index< T >::operator/ ( const Index< T > & other )

inline

Returns an index that is the quotient of this index and other.

operator/=()

template<typename T >

Index< T > & Qx::Index< T >::operator/= ( const Index< T > & other )

inline

Divides other from this index and returns a reference to this index.

operator<=>()

template<typename T >

std::strong_ordering Qx::Index< T >::operator<=> ( const Index< T > & other ) const

inlinenoexcept

Performs a three-way comparison between this index and other.

Returns:

• <0 if this index is less than other
• 0 if this index is equal to other
• >0 if this index is greater than other

operator==()

template<typename T >

bool Qx::Index< T >::operator== ( const Index< T > & other ) const

inlinenoexcept

Returns true if this index and other are both null, 'last', or have the same underlying value; otherwise returns false.

---

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

• qx-index.h
• qx-index.dox