Regina 7.4 Calculation Engine
regina::Base64SigDecoder< Iterator > Class Template Reference

A helper class for reading signatures that use base64 encodings. More...

#include <utilities/sigutils.h>

Public Member Functions

 Base64SigDecoder (Iterator encoding, Iterator end, bool skipInitialWhitespace=true)
 Creates a new decoder for the given encoded string.
 
void skipWhitespace ()
 Moves the current position past any whitespace.
 
bool done (bool ignoreWhitespace=true) const
 Determines whether the current position has reached the end of the string.
 
char peek () const
 Returns the character at the current position in the encoded string.
 
void skip ()
 Advances to the next position in the encoded string.
 
template<typename IntType >
IntType decodeSingle ()
 Decodes the 6-bit integer value represented by the next single base64 character.
 
std::pair< size_t, int > decodeSize ()
 Decodes the next non-negative integer value (typically representing the size of some object), without knowing in advance how many base64 characters were used to encode it.
 
template<typename IntType >
IntType decodeInt (int nChars)
 Decodes the next non-negative integer value, assuming this uses a fixed number of base64 characters.
 
template<typename OutputIterator >
void decodeInts (OutputIterator output, size_t count, int nChars)
 Decodes a sequence of non-negative integer values, assuming that each individual value uses a fixed number of base64 characters.
 
template<typename IntType >
FixedArray< IntType > decodeInts (size_t count, int nChars)
 Decodes a sequence of non-negative integer values, assuming that each individual value uses a fixed number of base64 characters.
 
template<typename OutputIterator >
void decodeTrits (OutputIterator result)
 Decodes three trits from a single base64 character, and returns these using an output iterator.
 
std::array< uint8_t, 3 > decodeTrits ()
 Decodes three trits from a single base64 character, and returns these as a fixed-size array.
 
 Base64SigDecoder (const Base64SigDecoder &)=delete
 
Base64SigDecoderoperator= (const Base64SigDecoder &)=delete
 

Static Public Member Functions

static constexpr bool isValid (char c)
 Is the given character one of the printable base64 characters recognised by this class?
 

Detailed Description

template<typename Iterator>
class regina::Base64SigDecoder< Iterator >

A helper class for reading signatures that use base64 encodings.

These are (in particular) used in the default encodings for Regina's own isomorphism signatures and knot signatures.

To use this class: create a new Base64SigDecoder by passing details of the encoded string to its constructor, and then call its decode...() member functions to read values sequentially from the encoding.

This class will keep track of a current position in the encoded string. Each call to a decode...() member function will advance this position accordingly (but never beyond the end of the string).

This base64 encoding uses the characters: a..zA..Z0..9+-

Baes64 decoders are single-use objects: they cannot be copied, moved or swapped.

Warning
Note that this base64 encoding uses a different set of printable symbols from the encoding used in utilities/base64.h. This should not be a problem: Regina uses this encoding exclusively for signatures, and uses utilities/base64.h exclusively for encoding files.
Python
The type Iterator is an implementation detail, and is hidden from Python users. Just use the unadorned type name Base64SigDecoder.
Template Parameters
Iteratora forward iterator whose associated value type is char.

Constructor & Destructor Documentation

◆ Base64SigDecoder()

template<typename Iterator >
regina::Base64SigDecoder< Iterator >::Base64SigDecoder ( Iterator encoding,
Iterator end,
bool skipInitialWhitespace = true )
inline

Creates a new decoder for the given encoded string.

The string itself should be passed as an iterator range. This iterator range must remain valid for the entire lifespan of this decoder.

Python
Instead of an iterator range, this constructor takes a Python string. In Python (but not C++), the decoder will also keep a deep copy of the string, to ensure the lifespan requirements.
Parameters
encodingan iterator pointing to the beginning of the encoded string.
enda past-the-end iterator that marks the end of the encoded string.
skipInitialWhitespacetrue if the current position should immediately advance past any initial whitespace in the given string.

Member Function Documentation

◆ decodeInt()

template<typename Iterator >
template<typename IntType >
IntType regina::Base64SigDecoder< Iterator >::decodeInt ( int nChars)
inline

Decodes the next non-negative integer value, assuming this uses a fixed number of base64 characters.

This integer value would typically have been encoded using Base64SigEncoder::encodeInt(), with the same nChars argument.

Specifically, it will be assumed that the integer has been broken into nChars 6-bit blocks, with each block encoded as a single base64 character, and with the blocks presented in order from lowest to highest significance.

The inverse to this routine is Base64SigEncoder::encodeInt().

Exceptions
InvalidInputThere are fewer than nChars characters available in the encoded string, or a character was encountered that was not a valid base64 character.
Python
The template argument IntType is taken to be a native C++ long.
Template Parameters
IntTypea native C++ integer type. The result will be assembled using bitwise OR and bitwise shift lefts, and it is assumed that the programmer has chosen an integer type large enough to contain whatever values they expect to read.
Parameters
nCharsthe number of base64 characters to read.
Returns
the integer that was decoded.

◆ decodeInts() [1/2]

template<typename Iterator >
template<typename OutputIterator >
void regina::Base64SigDecoder< Iterator >::decodeInts ( OutputIterator output,
size_t count,
int nChars )
inline

Decodes a sequence of non-negative integer values, assuming that each individual value uses a fixed number of base64 characters.

Each such integer value would typically have been encoded using Base64SigEncoder::encodeInt() or Base64SigEncoder::encodeInts(), with the same nChars argument.

Specifically, it will be assumed that each integer has been broken into nChars 6-bit blocks, with each block encoded as a single base64 character, and with the blocks presented in order from lowest to highest significance.

The inverse to this routine is Base64SigEncoder::encodeInts().

Exceptions
InvalidInputThere are fewer than `count × nChars` characters available in the encoded string, or a character was encountered that was not a valid base64 character.
Python
Not present. Instead you can use the variant of this routine that does not take an output iterator, but instead returns the sequence of integers that were decoded.
Template Parameters
OutputIteratoran output iterator whose associated value type is a native C++ integer type. Each integer that is decoded will be assembled using bitwise OR and bitwise shift lefts, and it is assumed that the programmer has chosen an integer type large enough to contain whatever values they expect to read.
Parameters
outputan iterator to use for output. Each integer that is decoded will be passed to this iterator using the usual dereference-assign-increment pattern (*output++ = value). It is assumed that this output iterator is able to accept count values in this way.
countthe number of integers to decode.
nCharsthe number of base64 characters to read.

◆ decodeInts() [2/2]

template<typename Iterator >
template<typename IntType >
FixedArray< IntType > regina::Base64SigDecoder< Iterator >::decodeInts ( size_t count,
int nChars )
inline

Decodes a sequence of non-negative integer values, assuming that each individual value uses a fixed number of base64 characters.

Each such integer value would typically have been encoded using Base64SigEncoder::encodeInt() or Base64SigEncoder::encodeInts(), with the same nChars argument.

Specifically, it will be assumed that each integer has been broken into nChars 6-bit blocks, with each block encoded as a single base64 character, and with the blocks presented in order from lowest to highest significance.

The inverse to this routine is Base64SigEncoder::encodeInts().

Exceptions
InvalidInputThere are fewer than `count × nChars` characters available in the encoded string, or a character was encountered that was not a valid base64 character.
Python
The template argument IntType is taken to be a native C++ long. This routine returns a Python list of integers.
Template Parameters
IntTypea native C++ integer type. The result will be assembled using bitwise OR and bitwise shift lefts, and it is assumed that the programmer has chosen an integer type large enough to contain whatever values they expect to read.
Parameters
countthe number of integers to decode.
nCharsthe number of base64 characters to read.
Returns
the sequence of integers that were decoded.

◆ decodeSingle()

template<typename Iterator >
template<typename IntType >
IntType regina::Base64SigDecoder< Iterator >::decodeSingle ( )
inline

Decodes the 6-bit integer value represented by the next single base64 character.

The inverse to this routine is Base64SigEncoder::encodeSingle().

Exceptions
InvalidInputThere are no more characters remaining in the encoded string, or the next character is not a valid base64 character.
Python
The template argument IntType is taken to be a native C++ long.
Template Parameters
IntTypea native C++ integer type.
Returns
the corresponding integer, which will be between 0 and 63 inclusive.

◆ decodeSize()

template<typename Iterator >
std::pair< size_t, int > regina::Base64SigDecoder< Iterator >::decodeSize ( )
inline

Decodes the next non-negative integer value (typically representing the size of some object), without knowing in advance how many base64 characters were used to encode it.

This integer value must have been encoded using Base64SigEncoder::encodeSize().

A typical use case would be where size represents the number of top-dimensional simplices in a triangulation, or the number of crossings in a link diagram.

This routine also returns the smallest integer b with the property that any integer x between 0 and size inclusive can be encoded using b base64 characters. Typically these x would be indices into an object (e.g., top-dimensional simplex numbers, or crossing numbers). More precisely, b is the same integer that was returned when size was encoded using encodeSize(). Typically you would pass b to subsequent calls to decodeInt().

The inverse to this routine is Base64SigEncoder::encodeSize().

Exceptions
InvalidInputThere are not enough characters available in the encoded string, or a character was encountered that was not a valid base64 character.
Returns
a pair (size, b), where size is the integer that was decoded, and b is the number of base64 characters described above.

◆ decodeTrits() [1/2]

template<typename Iterator >
std::array< uint8_t, 3 > regina::Base64SigDecoder< Iterator >::decodeTrits ( )
inline

Decodes three trits from a single base64 character, and returns these as a fixed-size array.

A trit is either 0, 1 or 2.

The inverse to this routine is Base64SigEncoder::encodeTrits(); see that routine for details of the encoding.

Exceptions
InvalidInputThere are no more characters remaining in the encoded string, or the next character is not a valid base64 character.
Returns
an array containing the three trits that were decoded.

◆ decodeTrits() [2/2]

template<typename Iterator >
template<typename OutputIterator >
void regina::Base64SigDecoder< Iterator >::decodeTrits ( OutputIterator result)
inline

Decodes three trits from a single base64 character, and returns these using an output iterator.

A trit is either 0, 1 or 2.

The inverse to this routine is Base64SigEncoder::encodeTrits(); see that routine for details of the encoding.

Exceptions
InvalidInputThere are no more characters remaining in the encoded string, or the next character is not a valid base64 character.
Python
Not present. Instead you can use the variant of this routine that takes no arguments and returns a fixed-size array.
Parameters
resultan output iterator pointing to the location where the resulting trits will be stored; it must be possible to write and advance this iterator at least three times. Each trit will be written as a uint8_t.

◆ done()

template<typename Iterator >
bool regina::Base64SigDecoder< Iterator >::done ( bool ignoreWhitespace = true) const
inline

Determines whether the current position has reached the end of the string.

Parameters
ignoreWhitespacetrue if we should ignore any trailing whitespace. If there is whitespace at the current position, the current position will not be changed; this will merely make the test succeed if only whitespace characters remain.
Returns
true if and only if the current position is the end of the string.

◆ isValid()

template<typename Iterator >
static constexpr bool regina::Base64SigDecoder< Iterator >::isValid ( char c)
inlinestaticconstexpr

Is the given character one of the printable base64 characters recognised by this class?

Parameters
cthe character to examine.
Returns
true if and only if c is one of the 64 printable characters described in the class notes.

◆ peek()

template<typename Iterator >
char regina::Base64SigDecoder< Iterator >::peek ( ) const
inline

Returns the character at the current position in the encoded string.

The current position will not move.

Returns
the character at the current position, or 0 if there are no more characters available.

◆ skip()

template<typename Iterator >
void regina::Base64SigDecoder< Iterator >::skip ( )
inline

Advances to the next position in the encoded string.

Precondition
The current position has not yet reached the end of the string.

◆ skipWhitespace()

template<typename Iterator >
void regina::Base64SigDecoder< Iterator >::skipWhitespace ( )
inline

Moves the current position past any whitespace.

The movement will stop upon reaching either a non-whitespace character or the end of the string.


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