|
| 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 |
|
Base64SigDecoder & | operator= (const Base64SigDecoder &)=delete |
|
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
-
Iterator | a forward iterator whose associated value type is char . |
template<typename Iterator >
template<typename IntType >
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
-
InvalidInput | There 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
-
IntType | a 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
-
nChars | the number of base64 characters to read. |
- Returns
- the integer that was decoded.
template<typename Iterator >
template<typename OutputIterator >
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
-
InvalidInput | There 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
-
OutputIterator | an 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
-
output | an 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. |
count | the number of integers to decode. |
nChars | the number of base64 characters to read. |
template<typename Iterator >
template<typename IntType >
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
-
InvalidInput | There 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
-
IntType | a 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
-
count | the number of integers to decode. |
nChars | the number of base64 characters to read. |
- Returns
- the sequence of integers that were decoded.
template<typename Iterator >
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
-
InvalidInput | There 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.
template<typename Iterator >
template<typename OutputIterator >
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
-
InvalidInput | There 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
-
result | an 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 . |