Miscellaneous helper classes and functions. More...

Classes
class	regina::BitManipulatorByType< T >
	Contains implementation details for BitManipulator where we optimise according to the underlying data type. More...

class	regina::Bitmask
	A bitmask that can store arbitrarily many true-or-false bits. More...

class	regina::Bitmask1< T >
	A small but extremely fast bitmask class that can store up to 8 * sizeof(T) true-or-false bits. More...

class	regina::Bitmask2< T, U >
	A small but extremely fast bitmask class that can store up to 8 * sizeof(T) + 8 * sizeof(U) true-or-false bits. More...

class	regina::BoolSet
	A set of booleans. More...

class	regina::ReginaException
	A base class for all of the exceptions that are thrown by Regina's native mathematical code. More...

class	regina::FailedPrecondition
	An exception thrown when a function detects that its preconditions have been violated. More...

class	regina::InvalidArgument
	An exception thrown when invalid or unsupported arguments are passed into a function. More...

class	regina::InvalidInput
	An exception thrown when a function reads unexpected or incomplete data from an input stream. More...

class	regina::NotImplemented
	An exception thrown when some functionality is not yet implemented. More...

class	regina::FileError
	An exception thrown when trying to access data from the filesystem. More...

class	regina::NoSolution
	An exception thrown when Regina has certified that a mathematical problem has no solution. More...

class	regina::UnsolvedCase
	An exception thrown when a mathematical function is not able to solve a particular instance of a problem. More...

class	regina::Flags< T >
	A class representing a bitwise combination of flags defined by an enumeration type. More...

class	regina::i18n::Locale
	A simple class with static routines for querying information about the current locale. More...

class	regina::i18n::IConvStreamBuffer
	An output stream buffer that translates between character encodings. More...

class	regina::i18n::IConvStream
	An output stream that converts between character encodings. More...

struct	regina::IsReginaInteger< T >
	Determines if the type T is one of Regina's own integer types (either arbitrary precision or fixed size). More...

struct	regina::IsReginaArbitraryPrecisionInteger< T >
	Determines if the type T is one of Regina's arbitrary precision integer types. More...

struct	regina::IntOfSize< bytes >
	Gives access to native integer types that hold exactly k bytes, where k may be any compile-time constant. More...

struct	regina::IntOfMinSize< bytes >
	Gives access to native integer types that hold at least k bytes, where k may be any compile-time constant. More...

struct	regina::FaithfulAssignment< From, To >
	Determines if an integer of type From can always be assigned to an integer of type To with no loss of information. More...

class	regina::ListView< Container >
	A lightweight object that can be used for iteration and random access to all elements of a given list. More...

class	regina::ListView< Element * >
	A specialisation of ListView for working with lists stored in a C-style array. More...

class	regina::MarkedElement
	A base class for elements of MarkedVector. More...

class	regina::MarkedVector< T >
	A vector of objects with fast, space-efficient reverse lookup of array indices. More...

class	regina::mem_istream
	An input stream that reads an array of characters in memory. More...

class	regina::mem_streambuf
	A stream buffer that provides the implementation details for mem_istream. More...

class	regina::Qitmask1< T >
	A small but extremely fast "base 4 bitmask" class that can store up to 8 * sizeof(T) "qits", each equal to 0, 1, 2 or 3. More...

class	regina::Qitmask2< T, U >
	A small but extremely fast "base 4 bitmask" class that can store up to 8 * sizeof(T) + 8 * sizeof(U) "qits", each equal to 0, 1, 2 or 3. More...

class	regina::RandomEngine
	Offers threadsafe access to Regina's global uniform random bit generator. More...

class	regina::LightweightSequence< T >
	A lightweight class for storing a random-access sequence of objects. More...

class	regina::ShortArray< T, maxSize >
	A short stack-based array of bounded size. More...

struct	regina::Base64SigEncoding
	General helper tools for signatures that use base64 encodings. More...

class	regina::SnapshotWriteError
	An exception thrown when someone tries to modify the read-only deep copy taken by a snapshot. More...

class	regina::Snapshot< T >
	Keeps a snapshot of an object of type T as it was at a particular moment in time. More...

class	regina::Snapshottable< T >
	A base class for images of type T that can be snapshotted at a particular moment in time. More...

class	regina::SnapshotRef< T >
	A reference to an image of type T that has been snapshotted at a particular moment in time. More...

class	regina::TrieSet
	A trie-like data structure for storing and retriving sets. More...

struct	regina::EnableIf< condition, T, defaultValue >
	A struct that holds either a single value of type T or nothing at all, depending on whether the given compile-time condition holds. More...

Macros
#define	ENABLE_MEMBER_FOR_REGINA_INTEGER(T, returnType)
	Conditionally enables a member function for a template class only when the type T is one of Regina's own integer classes. More...

Typedefs
using	regina::BitmaskLen8 = Bitmask1< uint8_t >
	A deprecated type alias that gives a small and extremely fast bitmask class capable of holding at least 8 true-or-false bits. More...

using	regina::BitmaskLen16 = Bitmask1< uint16_t >
	A deprecated type alias that gives a small and extremely fast bitmask class capable of holding at least 16 true-or-false bits. More...

using	regina::BitmaskLen32 = Bitmask1< uint32_t >
	A deprecated type alias that gives a small and extremely fast bitmask class capable of holding at least 32 true-or-false bits. More...

using	regina::BitmaskLen64 = Bitmask1< uint64_t >
	A deprecated type alias that gives a small and extremely fast bitmask class capable of holding at least 64 true-or-false bits. More...

using	regina::QitmaskLen8 = Qitmask1< uint8_t >
	A deprecated type alias that gives a small and extremely fast qitmask class capable of holding at least 8 true-or-false bits. More...

using	regina::QitmaskLen16 = Qitmask1< uint16_t >
	A deprecated type alias that gives a small and extremely fast qitmask class capable of holding at least 16 true-or-false bits. More...

using	regina::QitmaskLen32 = Qitmask1< uint32_t >
	A deprecated type alias that gives a small and extremely fast qitmask class capable of holding at least 32 true-or-false bits. More...

using	regina::QitmaskLen64 = Qitmask1< uint64_t >
	A deprecated type alias that gives a small and extremely fast qitmask class capable of holding at least 64 true-or-false bits. More...

Functions
size_t	regina::base64Length (size_t bytes)
	Returns the number of base64 characters required to encode the given number of bytes. More...

bool	regina::isBase64 (char ch)
	Determines whether the given character is a base64 printable character as used by the base64 routines in Regina. More...

void	regina::base64Encode (const char in, size_t inlen, char out, size_t outlen)
	Encodes the given sequence of raw bytes in base64, and writes the results into a preallocated output buffer. More...

size_t	regina::base64Encode (const char in, size_t inlen, char *out)
	Encodes the given sequence of raw bytes in base64, and passes back a newly allocated array containing the results. More...

bool	regina::base64Decode (const char in, size_t inlen, char out, size_t *outlen)
	Decodes the given sequence of base64 characters, and writes the resulting raw bytes into a preallocated output buffer. More...

bool	regina::base64Decode (const char in, size_t inlen, char out, size_t outlen)
	Decodes the given sequence of base64 characters, and passes back a newly allocated array containing the results. More...

void	regina::swap (Bitmask &a, Bitmask &b) noexcept
	Swaps the contents of the two given bitmasks. More...

std::ostream &	regina::operator<< (std::ostream &out, const Bitmask &mask)
	Writes the given bitmask to the given output stream as a sequence of zeroes and ones. More...

template<typename T >
std::ostream &	regina::operator<< (std::ostream &out, const Bitmask1< T > &mask)
	Writes the given bitmask to the given output stream as a sequence of zeroes and ones. More...

template<typename T , typename U >
std::ostream &	regina::operator<< (std::ostream &out, const Bitmask2< T, U > &mask)
	Writes the given bitmask to the given output stream as a sequence of zeroes and ones. More...

std::ostream &	regina::operator<< (std::ostream &out, BoolSet set)
	Writes the given boolean set to the given output stream. More...

std::string::const_iterator	regina::i18n::utf8ValidTo (const std::string &s)
	Identifies the longest prefix of the given string that is valid UTF-8. More...

const char *	regina::i18n::utf8ValidTo (const char *s)
	Identifies the longest prefix of the given string that is valid UTF-8. More...

template<typename IntType >
constexpr int	regina::bitsRequired (IntType n)
	Returns the number of bits required to store integers in the range 0,...,n-1. More...

template<typename IntType >
constexpr IntType	regina::nextPowerOfTwo (IntType n)
	Returns the smallest integer power of two that is greater than or equal to the given argument n. More...

template<typename T >
void	regina::swap (MarkedVector< T > &a, MarkedVector< T > &b) noexcept
	Swaps the contents of the given vectors. More...

std::tuple< unsigned long, unsigned long, unsigned long >	regina::resUsage ()
	Returns time and memory usage for the current process, for use on Linux systems. More...

template<typename T >
std::ostream &	regina::operator<< (std::ostream &out, const Qitmask1< T > &mask)
	Writes the given qitmask to the given output stream as a sequence of digits (0, 1, 2 and/or 3). More...

template<typename T , typename U >
std::ostream &	regina::operator<< (std::ostream &out, const Qitmask2< T, U > &mask)
	Writes the given qitmask to the given output stream as a sequence of digits (0, 1, 2 and/or 3). More...

template<typename T >
std::ostream &	regina::operator<< (std::ostream &out, const LightweightSequence< T > &s)
	Writes the given sequence to the given output stream. More...

template<typename T >
void	regina::swap (LightweightSequence< T > &a, LightweightSequence< T > &b) noexcept
	Swaps the contents of the given sequences. More...

template<class T >
void	regina::swap (SnapshotRef< T > &a, SnapshotRef< T > &b) noexcept
	Swaps the given references so that they refer to each others' snapshots. More...

bool	regina::startsWith (const std::string &str, const std::string &prefix)
	Determines whether the given C++ string begins with the given prefix. More...

std::string	regina::stripWhitespace (const std::string &str)
	Strips all whitespace from the beginning and end of the given C++ string. More...

bool	regina::valueOf (const std::string &str, int8_t &dest)
	Converts the entire given string to an 8-bit integer and reports whether this conversion was successful. More...

bool	regina::valueOf (const std::string &str, uint8_t &dest)
	Converts the entire given string to an unsigned 8-bit integer and reports whether this conversion was successful. More...

bool	regina::valueOf (const std::string &str, short &dest)
	Converts the entire given string to a short integer and reports whether this conversion was successful. More...

bool	regina::valueOf (const std::string &str, unsigned short &dest)
	Converts the entire given string to an unsigned short integer and reports whether this conversion was successful. More...

bool	regina::valueOf (const std::string &str, int &dest)
	Converts the entire given string to an integer and reports whether this conversion was successful. More...

bool	regina::valueOf (const std::string &str, unsigned &dest)
	Converts the entire given string to an unsigned integer and reports whether this conversion was successful. More...

bool	regina::valueOf (const std::string &str, long &dest)
	Converts the entire given string to a long integer and reports whether this conversion was successful. More...

bool	regina::valueOf (const std::string &str, unsigned long &dest)
	Converts the entire given string to an unsigned long integer and reports whether this conversion was successful. More...

bool	regina::valueOf (const std::string &str, long long &dest)
	Converts the entire given string to a long long integer and reports whether this conversion was successful. More...

bool	regina::valueOf (const std::string &str, unsigned long long &dest)
	Converts the entire given string to an unsigned long long integer and reports whether this conversion was successful. More...

template<bool supportInfinity>
bool	regina::valueOf (const std::string &str, IntegerBase< supportInfinity > &dest)
	Deprecated routine that converts the entire given string to an arbitrary precision integer and reports whether this conversion was successful. More...

bool	regina::valueOf (const std::string &str, double &dest)
	Converts the entire given string to a double precision real number and reports whether this conversion was successful. More...

bool	regina::valueOf (const std::string &str, bool &dest)
	Converts the entire given string to a boolean and reports whether this conversion was successful. More...

bool	regina::valueOf (const std::string &str, BoolSet &dest)
	Converts the entire given string to a set of booleans and reports whether this conversion was successful. More...

std::vector< std::string >	regina::basicTokenise (const std::string &str)
	Decomposes the given string into tokens. More...

template<class OutputIterator >
unsigned	regina::basicTokenise (OutputIterator results, const std::string &str)
	Deprecated routine to decompose a string into tokens. More...

std::string	regina::stringToToken (std::string str)
	Returns a token derived from the given string. More...

template<typename T >
std::string	regina::superscript (T value)
	Converts the given C++ integer into a unicode superscript string. More...

template<typename T >
std::string	regina::subscript (T value)
	Converts the given C++ integer into a unicode subscript string. More...

void	regina::tightEncode (std::ostream &out, int value)
	Writes the tight encoding of the given signed integer to the given output stream. More...

std::string	regina::tightEncoding (int value)
	Returns the tight encoding of the given signed integer. More...

void	regina::tightEncode (std::ostream &out, long value)
	Writes the tight encoding of the given signed long integer to the given output stream. More...

std::string	regina::tightEncoding (long value)
	Returns the tight encoding of the given signed long integer. More...

void	regina::tightEncode (std::ostream &out, long long value)
	Writes the tight encoding of the given signed long long integer to the given output stream. More...

std::string	regina::tightEncoding (long long value)
	Returns the tight encoding of the given signed long long integer. More...

void	regina::tightEncode (std::ostream &out, unsigned value)
	Writes the tight encoding of the given unsigned integer to the given output stream. More...

std::string	regina::tightEncoding (unsigned value)
	Returns the tight encoding of the given unsigned integer. More...

void	regina::tightEncode (std::ostream &out, unsigned long value)
	Writes the tight encoding of the given unsigned long integer to the given output stream. More...

std::string	regina::tightEncoding (unsigned long value)
	Returns the tight encoding of the given unsigned long integer. More...

void	regina::tightEncode (std::ostream &out, unsigned long long value)
	Writes the tight encoding of the given unsigned long long integer to the given output stream. More...

std::string	regina::tightEncoding (unsigned long long value)
	Returns the tight encoding of the given unsigned long long integer. More...

template<typename Int >
void	regina::detail::tightEncodeInteger (std::ostream &out, Int value)
	Internal function that writes the tight encoding of the given integer to the given output stream. More...

void	regina::swap (TrieSet &a, TrieSet &b) noexcept
	Swaps the contents of the two given collections. More...

std::string	regina::xml::xmlEncodeSpecialChars (const std::string &original)
	Returns the given string with special characters converted to XML entities. More...

std::string	regina::xml::xmlEncodeComment (const std::string &comment)
	Returns the given string encoded so it is suitable for use inside an XML comment. More...

template<class T >
std::string	regina::xml::xmlValueTag (const std::string &tagName, const T &value)
	Returns an XML tag with a single property containing the given value. More...

Variables
constexpr char	regina::base64Table []
	The table of all base64 printable characters, as used by the base64 routines in Regina. More...

constexpr char	regina::base64Spare [] = "_-."
	A table of printable characters that are not amongst the base64 printable characters used by Regina. More...

Detailed Description

Miscellaneous helper classes and functions.

Macro Definition Documentation

◆ ENABLE_MEMBER_FOR_REGINA_INTEGER

#define ENABLE_MEMBER_FOR_REGINA_INTEGER	(	T,
		returnType
	)

Value:

template <typename... Args, typename Return = returnType> \

std::enable_if_t<IsReginaInteger<T>::value, Return>

Conditionally enables a member function for a template class only when the type T is one of Regina's own integer classes.

This macro should be used as the return type for such a member function. If T is one of Regina's own integer classes (Integer, LargeInteger or NativeInteger), then the actual return type for the member function will be the argument returnType. Otherwise the member function will be disabled, will not appear in the class at all, and will not generate compile errors if it uses operations that T does not support.

The implementation uses SFINAE to remove the member function without compile errors. A side-effect of this is that the member function will now be a template member function. The user should never specify their own template arguments, and indeed the template parameter pack Args in the implementation is there precisely to stop users from doing this.

Precondition: The member function this macro is applied to is not a template member function (though, as noted above, this macro will silently make it one).

Warning: The API for this class has not yet been finalised. This means that the class interface may change in new versions of Regina, without maintaining backward compatibility. If you use this class directly in your own code, please watch the detailed changelogs upon new releases to see if you need to make changes to your code.

Typedef Documentation

◆ BitmaskLen16

using regina::BitmaskLen16 = typedef Bitmask1<uint16_t>

A deprecated type alias that gives a small and extremely fast bitmask class capable of holding at least 16 true-or-false bits.

This bitmask class is guaranteed to be an instantiation of the template class Bitmask1.

The particular instantiation is subject to change between different platforms, different compilers and/or different versions of Regina.

Deprecated:: This type alias is deprecated; just use Bitmask1<uint16_t> instead.

Python: Not present, but in Python you can access essentially the same optimised bitmask class via the name Bitmask16.

◆ BitmaskLen32

using regina::BitmaskLen32 = typedef Bitmask1<uint32_t>

A deprecated type alias that gives a small and extremely fast bitmask class capable of holding at least 32 true-or-false bits.

This bitmask class is guaranteed to be an instantiation of the template class Bitmask1.

The particular instantiation is subject to change between different platforms, different compilers and/or different versions of Regina.

Deprecated:: This type alias is deprecated; just use Bitmask1<uint32_t> instead.

Python: Not present, but in Python you can access essentially the same optimised bitmask class via the name Bitmask32.

◆ BitmaskLen64

using regina::BitmaskLen64 = typedef Bitmask1<uint64_t>

A deprecated type alias that gives a small and extremely fast bitmask class capable of holding at least 64 true-or-false bits.

This bitmask class is guaranteed to be an instantiation of either the template class Bitmask1 or the template class Bitmask2.

The particular instantiation is subject to change between different platforms, different compilers and/or different versions of Regina.

Deprecated:: This type alias is deprecated; just use Bitmask1<uint64_t> instead.

Python: Not present, but in Python you can access essentially the same optimised bitmask class via the name Bitmask64.

◆ BitmaskLen8

using regina::BitmaskLen8 = typedef Bitmask1<uint8_t>

A deprecated type alias that gives a small and extremely fast bitmask class capable of holding at least 8 true-or-false bits.

This bitmask class is guaranteed to be an instantiation of the template class Bitmask1.

The particular instantiation is subject to change between different platforms, different compilers and/or different versions of Regina.

Deprecated:: This type alias is deprecated; just use Bitmask1<uint8_t instead.

Python: Not present, but in Python you can access essentially the same optimised bitmask class via the name Bitmask8.

◆ QitmaskLen16

using regina::QitmaskLen16 = typedef Qitmask1<uint16_t>

A deprecated type alias that gives a small and extremely fast qitmask class capable of holding at least 16 true-or-false bits.

This qitmask class is guaranteed to be an instantiation of the template class Qitmask1.

The particular instantiation is subject to change between different platforms, different compilers and/or different versions of Regina.

Deprecated:: This type alias is deprecated; just use Qitmask1<uint16_t> instead.

Python: Not present, but in Python you can access essentially the same optimised qitmask class via the name Qitmask16.

◆ QitmaskLen32

using regina::QitmaskLen32 = typedef Qitmask1<uint32_t>

A deprecated type alias that gives a small and extremely fast qitmask class capable of holding at least 32 true-or-false bits.

This qitmask class is guaranteed to be an instantiation of the template class Qitmask1.

The particular instantiation is subject to change between different platforms, different compilers and/or different versions of Regina.

Deprecated:: This type alias is deprecated; just use Qitmask1<uint32_t> instead.

Python: Not present, but in Python you can access essentially the same optimised qitmask class via the name Qitmask32.

◆ QitmaskLen64

using regina::QitmaskLen64 = typedef Qitmask1<uint64_t>

A deprecated type alias that gives a small and extremely fast qitmask class capable of holding at least 64 true-or-false bits.

This qitmask class is guaranteed to be an instantiation of either the template class Qitmask1 or the template class Qitmask2.

The particular instantiation is subject to change between different platforms, different compilers and/or different versions of Regina.

Deprecated:: This type alias is deprecated; just use Qitmask1<uint64_t> instead.

Python: Not present, but in Python you can access essentially the same optimised qitmask class via the name Qitmask64.

◆ QitmaskLen8

using regina::QitmaskLen8 = typedef Qitmask1<uint8_t>

A deprecated type alias that gives a small and extremely fast qitmask class capable of holding at least 8 true-or-false bits.

This qitmask class is guaranteed to be an instantiation of the template class Qitmask1.

The particular instantiation is subject to change between different platforms, different compilers and/or different versions of Regina.

Deprecated:: This type alias is deprecated; just use Qitmask1<uint8_t> instead.

Python: Not present, but in Python you can access essentially the same optimised qitmask class via the name Qitmask8.

Function Documentation

◆ base64Decode() [1/2]

bool regina::base64Decode	(	const char *	in,
		size_t	inlen,
		char **	out,
		size_t *	outlen
	)

Decodes the given sequence of base64 characters, and passes back a newly allocated array containing the results.

The out pointer will be set to this new array, and outlen will be set to the number of raw bytes in this output array. This array will be allocated using new[], and the caller is responsible for destroying it using delete[].

The given base64 sequence should not contain any unexpected characters; even whitespace will cause the decoding procedure to abort.

The length of the output buffer is passed as the argument outlen. If an unexpected or invalid character is found or the output buffer is exhausted, this routine will return false, set out to null, and leave outlen undefined. Otherwise (on success) it will return true and set outlen to the total number of output bytes.

If the user is not interested in the length of the output array, a null pointer may be passed in the outlen argument. Note however that the output array is not terminated in any special way.

Python: These base64 decoding routines are made available to Python in the form base64Decode(input_string). In Python 3, this routine takes a base64 string as input and returns a Python bytes object; in Python 2 it takes a base64 string as input and returns a string of bytes. You do not need to supply any input or output buffer lengths. If the decoding is unsuccessful, this routine will return None.

Parameters

in	the input sequence of base64 characters; this does not need to be terminated in any special way.
inlen	the length of the input sequence.
out	the address of a pointer which will be set to the output array of raw bytes (or which will be set to `null` on failure).
outlen	the address of an integer which will be set to the length of the output array (or which will be left undefined on failure).

Returns: true if decoding was successful, or false if an unexpected input character was found or some other error occurred.

Author: This routine is based on the Base64 project at base64.sourceforge.net. The original was written by Bob Trower, and is licensed under the MIT license. See the base64.h notes for details.

◆ base64Decode() [2/2]

bool regina::base64Decode	(	const char *	in,
		size_t	inlen,
		char *	out,
		size_t *	outlen
	)

Decodes the given sequence of base64 characters, and writes the resulting raw bytes into a preallocated output buffer.

The given base64 sequence should not contain any unexpected characters; even whitespace will cause the decoding procedure to abort.

The length of the output buffer is passed as the argument outlen. If an unexpected or invalid character is found, or the output buffer is exhausted, this routine will write as many output bytes as it can and then return false. Otherwise (on success) it will return true. Either way, it will reset outlen to the total number of bytes that were written.

The total number of output bytes is important to know, since the output array is not terminated in any special way.

Python: These base64 decoding routines are made available to Python in the form base64Decode(input_string). In Python 3, this routine takes a base64 string as input and returns a Python bytes object; in Python 2 it takes a base64 string as input and returns a string of bytes. You do not need to supply any input or output buffer lengths. If the decoding is unsuccessful, this routine will return None.

Parameters

in	the input sequence of base64 characters; this does not need to be terminated in any special way.
inlen	the length of the input sequence.
out	the output buffer into which the resulting raw bytes will be written.
outlen	must contain the length of the output buffer on entry, and on exit contains the number of output bytes that were successfully written.

Returns: true if decoding was successful, or false if the output buffer was exhausted or an unexpected input character was found.

Author: This routine is based on the Base64 project at base64.sourceforge.net. The original was written by Bob Trower, and is licensed under the MIT license. See the base64.h notes for details.

◆ base64Encode() [1/2]

size_t regina::base64Encode	(	const char *	in,
		size_t	inlen,
		char **	out
	)

Encodes the given sequence of raw bytes in base64, and passes back a newly allocated array containing the results.

The out pointer will be set to this new array, which will be null-terminated. This array will be allocated using new[], and the caller is responsible for destroying it using delete[].

If the output array is too large (in particular, the expected size will overflow a size_t), the out pointer will be set to null.

Python: These base64 encoding routines are made available to Python in the form base64Encode(input_bytes). In Python 3, this routine takes a single Python bytes object as input and returns a string; in Python 2 it takes the input bytes as a byte string and returns a unicode string. You do not need to supply any input or output buffer lengths.

Parameters

in	the sequence of input bytes; this does not need to be terminated in any special way.
inlen	the length of the input sequence.
out	the address of a pointer which will be set to the output array of base64 characters.

Returns: the length of the output array, not counting the terminating null.

Author: This routine is based on the Base64 project at base64.sourceforge.net. The original was written by Bob Trower, and is licensed under the MIT license. See the base64.h notes for details.

◆ base64Encode() [2/2]

void regina::base64Encode	(	const char *	in,
		size_t	inlen,
		char *	out,
		size_t	outlen
	)

Encodes the given sequence of raw bytes in base64, and writes the results into a preallocated output buffer.

The length of the output buffer is passed as the argument outlen. If the number of base64 characters required is less than outlen, a terminating null will be written to the end of the output sequence. If the number of base64 characters is outlen or greater, this routine will output as many base64 characters as possible, up to a maximum of outlen.

The routine base64Length() can be used to precalculate precisely how many output characters will be required.

Python: These base64 encoding routines are made available to Python in the form base64Encode(input_bytes). In Python 3, this routine takes a single Python bytes object as input and returns a string; in Python 2 it takes the input bytes as a byte string and returns a unicode string. You do not need to supply any input or output buffer lengths.

Parameters

in	the sequence of input bytes; this does not need to be terminated in any special way.
inlen	the length of the input sequence.
out	the output buffer into which the resulting base64 characters will be written.
outlen	the length of the output buffer.

Author: This routine is based on the Base64 project at base64.sourceforge.net. The original was written by Bob Trower, and is licensed under the MIT license. See the base64.h notes for details.

◆ base64Length()

size_t regina::base64Length ( size_t bytes )

inline

Returns the number of base64 characters required to encode the given number of bytes.

This is the number of characters used (excluding the null terminator) by the routine base64Encode(const char*, size_t, char**).

Parameters

bytes the number of raw input bytes.

Returns: the corresponding number of base64 printable output characters.

◆ basicTokenise() [1/2]

std::vector< std::string > regina::basicTokenise ( const std::string & str )

Decomposes the given string into tokens.

This is an extremely simple tokeniser; tokens are defined to be separated by arbitrary blocks of whitespace. Any leading or trailing whitespace will be ignored.

Warning: This routine treats all strings as plain ASCII. In particular, characters are examined one at a time, and the C routine isspace() is used to identify whitespace. Use it on strings with international characters at your own peril.

Parameters

str	the string to decompose.

Returns: the resulting list of tokens.

◆ basicTokenise() [2/2]

template<class OutputIterator >

unsigned regina::basicTokenise	(	OutputIterator	results,
		const std::string &	str
	)

Deprecated routine to decompose a string into tokens.

This is an extremely simple tokeniser; tokens are defined to be separated by arbitrary blocks of whitespace. Any leading or trailing whitespace will be ignored.

Warning: This routine treats all strings as plain ASCII. In particular, characters are examined one at a time, and the C routine isspace() is used to identify whitespace. Use it on strings with international characters at your own peril.

Deprecated:: This routine has been rewritten to return the list of tokens as a std::vector. Use that variant of basicTokenise() instead.

Python: Not present; instead use the one-argument variant of basicTokenise(), which returns the list of tokens.

Parameters

results	the output iterator to which the resulting tokens will be written; this must accept objects of type `const std::string&`.
str	the string to decompose.

Returns: the number of tokens found.

◆ bitsRequired()

template<typename IntType >

constexpr int regina::bitsRequired ( IntType n )

constexpr

Returns the number of bits required to store integers in the range 0,...,n-1.

This is simply the number of bits in the binary expansion of n-1.

If n is non-positive then this function will return 0.

Python: In Python, this routine fixes the integer type IntType to be long.

Parameters

n	any integer.

Returns: the number of bits required to store 0,...,n-1.

Template Parameters

IntType any integer type, such as int, long, and so on.

◆ isBase64()

bool regina::isBase64 ( char ch )

inline

Determines whether the given character is a base64 printable character as used by the base64 routines in Regina.

The base64 printable characters are the letters (both upper-case and lower-case), digits, plus (+), and forward slash (/).

Note that the equals sign (=) is padding, and is not considered by this routine to be a base64 printable character.

Parameters

ch	any character.

Returns: true if the given character is one of the base64 printable characters used in Regina, or false if it is not.

◆ nextPowerOfTwo()

template<typename IntType >

constexpr IntType regina::nextPowerOfTwo ( IntType n )

constexpr

Returns the smallest integer power of two that is greater than or equal to the given argument n.

If n is non-positive then this function will return 1.

Python: In Python, this routine fixes the integer type IntType to be long.

Warning: Even though the return value is the same type as the argument n, this routine may still overflow. For example, if IntType is a signed char then nextPowerOfTwo(127) will return -128, and if IntType is an unsigned char then nextPowerOfTwo(255) will return 0. Be sure that IntType is large enough for your requirements.

Parameters

n	any integer.

Returns: the smallest integer power of two that is ≥ n.

Template Parameters

IntType any integer type, such as int, long, and so on.

◆ operator<<() [1/7]

std::ostream & regina::operator<<	(	std::ostream &	out,
		BoolSet	set
	)

Writes the given boolean set to the given output stream.

The set will be written in the form { true, false }, { true }, { false } or { }.

Parameters

out	the output stream to which to write.
set	the boolean set to write.

Returns: a reference to out.

◆ operator<<() [2/7]

std::ostream & regina::operator<<	(	std::ostream &	out,
		const Bitmask &	mask
	)

inline

Writes the given bitmask to the given output stream as a sequence of zeroes and ones.

Since the length of the bitmask is not stored, the number of bits written might be greater than the length initially assigned to this bitmask (specifically, the length will be rounded up to the next "raw unit of storage").

Parameters

out	the output stream to which to write.
mask	the bitmask to write.

Returns: a reference to the given output stream.

◆ operator<<() [3/7]

template<typename T >

std::ostream & regina::operator<<	(	std::ostream &	out,
		const Bitmask1< T > &	mask
	)

Writes the given bitmask to the given output stream as a sequence of zeroes and ones.

Since the length of the bitmask is not stored, the number of bits written will be 8 * sizeof(T).

Parameters

out	the output stream to which to write.
mask	the bitmask to write.

Returns: a reference to the given output stream.

◆ operator<<() [4/7]

template<typename T , typename U >

std::ostream & regina::operator<<	(	std::ostream &	out,
		const Bitmask2< T, U > &	mask
	)

Writes the given bitmask to the given output stream as a sequence of zeroes and ones.

Since the length of the bitmask is not stored, the number of bits written will be 8 * sizeof(T) + 8 * sizeof(U).

Parameters

out	the output stream to which to write.
mask	the bitmask to write.

Returns: a reference to the given output stream.

◆ operator<<() [5/7]

template<typename T >

std::ostream & regina::operator<<	(	std::ostream &	out,
		const LightweightSequence< T > &	s
	)

inline

Writes the given sequence to the given output stream.

No newline will be written.

The sequence will be written in the form (a, b, c, ...).

Precondition: An object x of type T can be written to an output stream using the syntax out << x.

Parameters

out	the output stream to which to write.
s	the sequence to write.

Returns: a reference to the given output stream.

◆ operator<<() [6/7]

template<typename T >

std::ostream & regina::operator<<	(	std::ostream &	out,
		const Qitmask1< T > &	mask
	)

Writes the given qitmask to the given output stream as a sequence of digits (0, 1, 2 and/or 3).

Since the length of the qitmask is not stored, the number of qits written will be 8 * sizeof(T).

Parameters

out	the output stream to which to write.
mask	the qitmask to write.

Returns: a reference to the given output stream.

◆ operator<<() [7/7]

template<typename T , typename U >

std::ostream & regina::operator<<	(	std::ostream &	out,
		const Qitmask2< T, U > &	mask
	)

Writes the given qitmask to the given output stream as a sequence of digits (0, 1, 2 and/or 3).

Since the length of the qitmask is not stored, the number of qits written will be 8 * sizeof(T) + 8 * sizeof(U).

Parameters

out	the output stream to which to write.
mask	the qitmask to write.

Returns: a reference to the given output stream.

◆ resUsage()

std::tuple< unsigned long, unsigned long, unsigned long > regina::resUsage ( )

Returns time and memory usage for the current process, for use on Linux systems.

Information is gathered from the /proc filesystem; if this is run on a non-Linux system (or a Linux system where /proc is not mounted), then this routine will throw an exception.

More precisely, this routine reads information on the running process from /proc/self/stat, and returns a tuple (utime, stime, vsize). These three fields reperesent:

the number jiffies that this process has been scheduled in user mode (the utime field);
the number jiffies that this process has been scheduled in kernel mode (the stime field);
the the virtual memory size in bytes (the vsize field).

The description of these three fields is taken directly from the proc(5) manpage. Note that the length of a jiffy can differ from system to system; see the time(7) manpage for details.

Exceptions

FileError Either /proc/self/stat cannot be read, or it contains unexpected information.

Warning: Currently this routine allows at most 255 characters for the comm field in /proc/self/stat (which stores the executable filename along with surrounding parentheses). If the comm field is too long (i.e., the executable filename is too long), then this routine will not be able to parse /proc/self/stat, and will throw an exception. If you encounter this problem, you should be able to fix it by renaming your executable to something shorter.

◆ startsWith()

bool regina::startsWith	(	const std::string &	str,
		const std::string &	prefix
	)

Determines whether the given C++ string begins with the given prefix.

Parameters

str	the full C++ string to examine.
prefix	the prefix whose presence we are testing for.

Returns: true if and only if str begins with prefix.

◆ stringToToken()

std::string regina::stringToToken ( std::string str )

Returns a token derived from the given string.

All whitespace characters in the given string will be replaced with an underscore.

Parameters

str	the string on which to base the token.

Returns: the corresponding token.

◆ stripWhitespace()

std::string regina::stripWhitespace ( const std::string & str )

Strips all whitespace from the beginning and end of the given C++ string.

The new stripped string is returned; the original string is not altered.

Warning: This routine treats all strings as plain ASCII. In particular, characters are examined one at a time, and the C routine isspace() is used to identify whitespace. Use it on strings with international characters at your own peril.

Parameters

str	the string to be stripped.

Returns: the resulting stripped string.

◆ subscript()

template<typename T >

std::string regina::subscript ( T value )

Converts the given C++ integer into a unicode subscript string.

The resulting string will be encoded using UTF-8.

Precondition: The template argument T is either (i) a native C++ integer type, for which the standard C++11 library routine std::to_string(T) is defined; or (ii) a const reference to Integer or LargeInteger.

Python: This template function is instantiated in Python for types T = long, as well as const references to Integer and LargeInteger.

◆ superscript()

template<typename T >

std::string regina::superscript ( T value )

Converts the given C++ integer into a unicode superscript string.

The resulting string will be encoded using UTF-8.

Precondition: The template argument T is either (i) a native C++ integer type, for which the standard C++11 library routine std::to_string(T) is defined; or (ii) a const reference to Integer or LargeInteger.

Python: This template function is instantiated in Python for types T = long, as well as const references to Integer and LargeInteger.

◆ swap() [1/5]

void regina::swap	(	Bitmask &	a,
		Bitmask &	b
	)

inlinenoexcept

Swaps the contents of the two given bitmasks.

This global routine simply calls Bitmask::swap(); it is provided so that Bitmask meets the C++ Swappable requirements.

Parameters

a	the first bitmask whose contents should be swapped.
b	the second bitmask whose contents should be swapped.

◆ swap() [2/5]

template<typename T >

void regina::swap	(	LightweightSequence< T > &	a,
		LightweightSequence< T > &	b
	)

inlinenoexcept

Swaps the contents of the given sequences.

This global routine simply calls LightweightSequence<T>::swap(); it is provided so that LightweightSequence<T> meets the C++ Swappable requirements.

Parameters

a	the first sequence whose contents should be swapped.
b	the second sequence whose contents should be swapped.

◆ swap() [3/5]

template<typename T >

void regina::swap	(	MarkedVector< T > &	a,
		MarkedVector< T > &	b
	)

inlinenoexcept

Swaps the contents of the given vectors.

This global routine simply calls MarkedVector<T>::swap(); it is provided so that MarkedVector<T> meets the C++ Swappable requirements.

Parameters

a	the first vector whose contents should be swapped.
b	the second vector whose contents should be swapped.

◆ swap() [4/5]

template<class T >

void regina::swap	(	SnapshotRef< T > &	a,
		SnapshotRef< T > &	b
	)

noexcept

Swaps the given references so that they refer to each others' snapshots.

This global routine simply calls SnapshotRef<T>::swap(); it is provided so that SnapshotRef<T> meets the C++ Swappable requirements.

See the Snapshot documentation for a full explanation of how Regina's snapshotting machinery works.

Parameters

a	the first snapshot reference to swap.
b	the second snapshot reference to swap.

◆ swap() [5/5]

void regina::swap	(	TrieSet &	a,
		TrieSet &	b
	)

inlinenoexcept

Swaps the contents of the two given collections.

Parameters

a	the first collection of sets whose contents should be swapped.
b	the second collection of sets whose contents should be swapped.

◆ tightEncode() [1/6]

void regina::tightEncode	(	std::ostream &	out,
		int	value
	)

inline

Writes the tight encoding of the given signed integer to the given output stream.

See the page on tight encodings for details.

Python: Not present; use regina::tightEncoding(int) instead.

Parameters

out	the output stream to which the encoded string will be written.
value	the integer to encode.

◆ tightEncode() [2/6]

void regina::tightEncode	(	std::ostream &	out,
		long long	value
	)

inline

Writes the tight encoding of the given signed long long integer to the given output stream.

See the page on tight encodings for details.

Python: Not present; use regina::tightEncoding(long long) instead.

Parameters

out	the output stream to which the encoded string will be written.
value	the integer to encode.

◆ tightEncode() [3/6]

void regina::tightEncode	(	std::ostream &	out,
		long	value
	)

inline

Writes the tight encoding of the given signed long integer to the given output stream.

See the page on tight encodings for details.

Python: Not present; use regina::tightEncoding(long) instead.

Parameters

out	the output stream to which the encoded string will be written.
value	the integer to encode.

◆ tightEncode() [4/6]

void regina::tightEncode	(	std::ostream &	out,
		unsigned long long	value
	)

inline

Writes the tight encoding of the given unsigned long long integer to the given output stream.

See the page on tight encodings for details.

Python: Not present; use regina::tightEncoding(long long) instead.

Parameters

out	the output stream to which the encoded string will be written.
value	the integer to encode.

◆ tightEncode() [5/6]

void regina::tightEncode	(	std::ostream &	out,
		unsigned long	value
	)

inline

Writes the tight encoding of the given unsigned long integer to the given output stream.

See the page on tight encodings for details.

Python: Not present; use regina::tightEncoding(long) instead.

Parameters

out	the output stream to which the encoded string will be written.
value	the integer to encode.

◆ tightEncode() [6/6]

void regina::tightEncode	(	std::ostream &	out,
		unsigned	value
	)

inline

Writes the tight encoding of the given unsigned integer to the given output stream.

See the page on tight encodings for details.

Python: Not present; use regina::tightEncoding(int) instead.

Parameters

out	the output stream to which the encoded string will be written.
value	the integer to encode.

◆ tightEncodeInteger()

template<typename Int >

void regina::detail::tightEncodeInteger	(	std::ostream &	out,
		Int	value
	)

Internal function that writes the tight encoding of the given integer to the given output stream.

This should not be called directly; its purpose is to provide a common implementation for tightEncode() and tightEncoding() for all integer types.

This routine does support passing infinity as the given value (which is only relevant when the integer type Int is regina::LargeInteger).

Python: Not present; use regina::tightEncoding(...) instead.

Template Parameters

Int	The type of integer to encode; this must be either (i) a native C++ integer type, or (ii) one of Regina's arbitrary precision integer types (i.e., regina::Integer or regina::LargeInteger).

Parameters

out	the output stream to which the encoded string will be written.
value	the integer to encode.

◆ tightEncoding() [1/6]

std::string regina::tightEncoding ( int value )

inline

Returns the tight encoding of the given signed integer.

See the page on tight encodings for details.

Parameters

value the integer to encode.

Returns: the resulting encoded string.

◆ tightEncoding() [2/6]

std::string regina::tightEncoding ( long long value )

inline

Returns the tight encoding of the given signed long long integer.

See the page on tight encodings for details.

Parameters

value the integer to encode.

Returns: the resulting encoded string.

◆ tightEncoding() [3/6]

std::string regina::tightEncoding ( long value )

inline

Returns the tight encoding of the given signed long integer.

See the page on tight encodings for details.

Parameters

value the integer to encode.

Returns: the resulting encoded string.

◆ tightEncoding() [4/6]

std::string regina::tightEncoding ( unsigned long long value )

inline

Returns the tight encoding of the given unsigned long long integer.

See the page on tight encodings for details.

Parameters

value the integer to encode.

Returns: the resulting encoded string.

◆ tightEncoding() [5/6]

std::string regina::tightEncoding ( unsigned long value )

inline

Returns the tight encoding of the given unsigned long integer.

See the page on tight encodings for details.

Parameters

value the integer to encode.

Returns: the resulting encoded string.

◆ tightEncoding() [6/6]

std::string regina::tightEncoding ( unsigned value )

inline

Returns the tight encoding of the given unsigned integer.

See the page on tight encodings for details.

Parameters

value the integer to encode.

Returns: the resulting encoded string.

◆ utf8ValidTo() [1/2]

const char * regina::i18n::utf8ValidTo ( const char * s )

Identifies the longest prefix of the given string that is valid UTF-8.

The substring from s until just before the pointer that is returned is guaranteed to be valid UTF-8. If the entire string is valid UTF-8, then this routine will return a pointer to the null terminator of s.

Python: This routine returns the length of the longest valid UTF-8 prefix. The length is measured in raw bytes (not unicode characters).

Returns: a pointer marking the end of the longest valid UTF-8 prefix.

◆ utf8ValidTo() [2/2]

std::string::const_iterator regina::i18n::utf8ValidTo ( const std::string & s )

Identifies the longest prefix of the given string that is valid UTF-8.

The substring from s.begin() to the iterator that is returned is guaranteed to be valid UTF-8. If the entire string is valid UTF-8, then this routine will return s.end().

Python: This routine returns the length of the longest valid UTF-8 prefix. The length is measured in raw bytes (not unicode characters).

Returns: an iterator marking the end of the longest valid UTF-8 prefix.

◆ valueOf() [1/14]

bool regina::valueOf	(	const std::string &	str,
		bool &	dest
	)

Converts the entire given string to a boolean and reports whether this conversion was successful.

If the given string begins with T, t or 1, then the string will be successfully converted to true. If the given string begins with F, f or 0, then the string will be successfully converted to false. Otherwise the conversion will be unsuccessful and argument dest will be set to false.

Python: None of Regina's valueOf() functions are wrapped in Python, since these tailored to the many different native C++ numeric types. Instead, use Python's own native string-to-number mechanisms.

Parameters

str	the string to convert.
dest	the variable in which to store the resulting boolean.

Returns: true if the conversion was completely successful or false otherwise.

◆ valueOf() [2/14]

bool regina::valueOf	(	const std::string &	str,
		BoolSet &	dest
	)

Converts the entire given string to a set of booleans and reports whether this conversion was successful.

A set of booleans is represented by one of the four string codes –, T-, -F or TF, as returned by BoolSet::stringCode(). If the conversion is unsuccessful, argument dest will be set to the empty set and false will be returned.

Python: Not present, since none of Regina's valueOf() functions are available to Python. Instead you can use BoolSet::setStringCode(), which performs the same task (with the minor difference that it does not change dest if the conversion is unsuccessful).

Parameters

str	the string to convert.
dest	the variable in which to store the resulting set of booleans.

Returns: true if the conversion was successful or false otherwise.

◆ valueOf() [3/14]

bool regina::valueOf	(	const std::string &	str,
		double &	dest
	)

Converts the entire given string to a double precision real number and reports whether this conversion was successful.

The given string should contain no whitespace or other characters that are not a part of the real number that the string represents. If any unexpected characters are encountered, the routine will convert the string as best it can but false will be returned.

Python: None of Regina's valueOf() functions are wrapped in Python, since these tailored to the many different native C++ numeric types. Instead, use Python's own native string-to-number mechanisms.

Parameters

str	the string to convert.
dest	the variable in which to store the resulting real number.

Returns: true if the conversion was completely successful or false otherwise.

◆ valueOf() [4/14]

bool regina::valueOf	(	const std::string &	str,
		int &	dest
	)

Converts the entire given string to an integer and reports whether this conversion was successful.

The given string should contain no whitespace or other characters that are not a part of the integer that the string represents. If any unexpected characters are encountered, the routine will convert the string as best it can but false will be returned.

Python: None of Regina's valueOf() functions are wrapped in Python, since these tailored to the many different native C++ numeric types. Instead, use Python's own native string-to-number mechanisms.

Parameters

str	the string to convert.
dest	the variable in which to store the resulting integer.

Returns: true if the conversion was completely successful or false otherwise.

◆ valueOf() [5/14]

bool regina::valueOf	(	const std::string &	str,
		int8_t &	dest
	)

Converts the entire given string to an 8-bit integer and reports whether this conversion was successful.

The given string should contain no whitespace or other characters that are not a part of the integer that the string represents. If any unexpected characters are encountered, the routine will convert the string as best it can but false will be returned.

Python: None of Regina's valueOf() functions are wrapped in Python, since these tailored to the many different native C++ numeric types. Instead, use Python's own native string-to-number mechanisms.

Parameters

str	the string to convert.
dest	the variable in which to store the resulting 8-bit integer.

Returns: true if the conversion was completely successful or false otherwise.

◆ valueOf() [6/14]

template<bool supportInfinity>

bool regina::valueOf	(	const std::string &	str,
		IntegerBase< supportInfinity > &	dest
	)

Deprecated routine that converts the entire given string to an arbitrary precision integer and reports whether this conversion was successful.

The given string should contain no whitespace or other characters that are not a part of the integer that the string represents. If any unexpected characters are encountered, the routine will convert the string as best it can but false will be returned.

Deprecated:: Simply use the string constructor or string assignment operator for Integer / LargeInteger (but note that these throw exceptions on error).

Python: Not present; instead use the Integer / LargeInteger string constructor as noted above.

Parameters

str	the string to convert.
dest	the variable in which to store the resulting arbitrary precision integer.

Returns: true if the conversion was completely successful or false otherwise.

◆ valueOf() [7/14]

bool regina::valueOf	(	const std::string &	str,
		long &	dest
	)

Converts the entire given string to a long integer and reports whether this conversion was successful.

The given string should contain no whitespace or other characters that are not a part of the integer that the string represents. If any unexpected characters are encountered, the routine will convert the string as best it can but false will be returned.

Python: None of Regina's valueOf() functions are wrapped in Python, since these tailored to the many different native C++ numeric types. Instead, use Python's own native string-to-number mechanisms.

Parameters

str	the string to convert.
dest	the variable in which to store the resulting long integer.

Returns: true if the conversion was completely successful or false otherwise.

◆ valueOf() [8/14]

bool regina::valueOf	(	const std::string &	str,
		long long &	dest
	)

Converts the entire given string to a long long integer and reports whether this conversion was successful.

The given string should contain no whitespace or other characters that are not a part of the integer that the string represents. If any unexpected characters are encountered, the routine will convert the string as best it can but false will be returned.

Python: None of Regina's valueOf() functions are wrapped in Python, since these tailored to the many different native C++ numeric types. Instead, use Python's own native string-to-number mechanisms.

Parameters

str	the string to convert.
dest	the variable in which to store the resulting long long integer.

Returns: true if the conversion was completely successful or false otherwise.

◆ valueOf() [9/14]

bool regina::valueOf	(	const std::string &	str,
		short &	dest
	)

Converts the entire given string to a short integer and reports whether this conversion was successful.

The given string should contain no whitespace or other characters that are not a part of the integer that the string represents. If any unexpected characters are encountered, the routine will convert the string as best it can but false will be returned.

Python: None of Regina's valueOf() functions are wrapped in Python, since these tailored to the many different native C++ numeric types. Instead, use Python's own native string-to-number mechanisms.

Parameters

str	the string to convert.
dest	the variable in which to store the resulting short integer.

Returns: true if the conversion was completely successful or false otherwise.

◆ valueOf() [10/14]

bool regina::valueOf	(	const std::string &	str,
		uint8_t &	dest
	)

Converts the entire given string to an unsigned 8-bit integer and reports whether this conversion was successful.

The given string should contain no whitespace or other characters that are not a part of the integer that the string represents. If any unexpected characters are encountered, the routine will convert the string as best it can but false will be returned.

Python: None of Regina's valueOf() functions are wrapped in Python, since these tailored to the many different native C++ numeric types. Instead, use Python's own native string-to-number mechanisms.

Parameters

str	the string to convert.
dest	the variable in which to store the resulting unsigned 8-bit integer.

Returns: true if the conversion was completely successful or false otherwise.

◆ valueOf() [11/14]

bool regina::valueOf	(	const std::string &	str,
		unsigned &	dest
	)

Converts the entire given string to an unsigned integer and reports whether this conversion was successful.

The given string should contain no whitespace or other characters that are not a part of the integer that the string represents. If any unexpected characters are encountered, the routine will convert the string as best it can but false will be returned.

Python: None of Regina's valueOf() functions are wrapped in Python, since these tailored to the many different native C++ numeric types. Instead, use Python's own native string-to-number mechanisms.

Parameters

str	the string to convert.
dest	the variable in which to store the resulting unsigned integer.

Returns: true if the conversion was completely successful or false otherwise.

◆ valueOf() [12/14]

bool regina::valueOf	(	const std::string &	str,
		unsigned long &	dest
	)

Converts the entire given string to an unsigned long integer and reports whether this conversion was successful.

The given string should contain no whitespace or other characters that are not a part of the integer that the string represents. If any unexpected characters are encountered, the routine will convert the string as best it can but false will be returned.

Python: None of Regina's valueOf() functions are wrapped in Python, since these tailored to the many different native C++ numeric types. Instead, use Python's own native string-to-number mechanisms.

Parameters

str	the string to convert.
dest	the variable in which to store the resulting unsigned long integer.

Returns: true if the conversion was completely successful or false otherwise.

◆ valueOf() [13/14]

bool regina::valueOf	(	const std::string &	str,
		unsigned long long &	dest
	)

Converts the entire given string to an unsigned long long integer and reports whether this conversion was successful.

The given string should contain no whitespace or other characters that are not a part of the integer that the string represents. If any unexpected characters are encountered, the routine will convert the string as best it can but false will be returned.

Python: None of Regina's valueOf() functions are wrapped in Python, since these tailored to the many different native C++ numeric types. Instead, use Python's own native string-to-number mechanisms.

Parameters

str	the string to convert.
dest	the variable in which to store the resulting unsigned long long integer.

Returns: true if the conversion was completely successful or false otherwise.

◆ valueOf() [14/14]

bool regina::valueOf	(	const std::string &	str,
		unsigned short &	dest
	)

Converts the entire given string to an unsigned short integer and reports whether this conversion was successful.

The given string should contain no whitespace or other characters that are not a part of the integer that the string represents. If any unexpected characters are encountered, the routine will convert the string as best it can but false will be returned.

Python: None of Regina's valueOf() functions are wrapped in Python, since these tailored to the many different native C++ numeric types. Instead, use Python's own native string-to-number mechanisms.

Parameters

str	the string to convert.
dest	the variable in which to store the resulting unsigned short integer.

Returns: true if the conversion was completely successful or false otherwise.

◆ xmlEncodeComment()

std::string regina::xml::xmlEncodeComment ( const std::string & comment )

Returns the given string encoded so it is suitable for use inside an XML comment.

As well as converting special characters to XML entities, this routine will replace dashes with underscores to avoid double-hyphens (which are illegal in XML comments).

Parameters

comment the string to convert; this string will not be changed.

Returns: the string converted to be usable inside an XML comment.

◆ xmlEncodeSpecialChars()

std::string regina::xml::xmlEncodeSpecialChars ( const std::string & original )

Returns the given string with special characters converted to XML entities.

For instance, the string "a \< b" would be converted to "a \< b".

Parameters

original the string to convert; this string will not be changed.

Returns: the converted string with special characters replaced by XML entities.

◆ xmlValueTag()

template<class T >

std::string regina::xml::xmlValueTag	(	const std::string &	tagName,
		const T &	value
	)

inline

Returns an XML tag with a single property containing the given value.

The tag will be of the form <tagName value="..."/>.

The value itself will be written to the tag string using the standard output stream operator <<.

Precondition: The property value when written to an output stream does not contain any special characters (such as < or &) that need to be encoded as XML entities.

Python: Not present.

Parameters

tagName	the name of the XML tag to create.
value	the value to assign to the value property of the tag.

Returns: the corresponding XML tag.

Variable Documentation

◆ base64Spare

constexpr char regina::base64Spare[] = "_-."

inlineconstexpr

A table of printable characters that are not amongst the base64 printable characters used by Regina.

These characters could be used (for example) to mark the boundaries of base64 blocks.

These characters are presented as a string of length at least 3. Future versions of Regina may append new characters to the end of this string, but the existing characters base64Spare[0], base64Spare[1], etc. will not change.

◆ base64Table

constexpr char regina::base64Table[]

inlineconstexpr

Initial value:

=

"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/"

The table of all base64 printable characters, as used by the base64 routines in Regina.

This is the translation table as described in RFC1113. It is presented as a string of length 64.

Classes

Macros

Typedefs

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ ENABLE_MEMBER_FOR_REGINA_INTEGER

Typedef Documentation

◆ BitmaskLen16

◆ BitmaskLen32

◆ BitmaskLen64

◆ BitmaskLen8

◆ QitmaskLen16

◆ QitmaskLen32

◆ QitmaskLen64

◆ QitmaskLen8

Function Documentation

◆ base64Decode() [1/2]

◆ base64Decode() [2/2]

◆ base64Encode() [1/2]

◆ base64Encode() [2/2]

◆ base64Length()

◆ basicTokenise() [1/2]

◆ basicTokenise() [2/2]

◆ bitsRequired()

◆ isBase64()

◆ nextPowerOfTwo()

◆ operator<<() [1/7]

◆ operator<<() [2/7]

◆ operator<<() [3/7]

◆ operator<<() [4/7]

◆ operator<<() [5/7]

◆ operator<<() [6/7]

◆ operator<<() [7/7]

◆ resUsage()

◆ startsWith()

◆ stringToToken()

◆ stripWhitespace()

◆ subscript()

◆ superscript()

◆ swap() [1/5]

◆ swap() [2/5]

◆ swap() [3/5]

◆ swap() [4/5]

◆ swap() [5/5]

◆ tightEncode() [1/6]

◆ tightEncode() [2/6]

◆ tightEncode() [3/6]

◆ tightEncode() [4/6]

◆ tightEncode() [5/6]

◆ tightEncode() [6/6]

◆ tightEncodeInteger()

◆ tightEncoding() [1/6]

◆ tightEncoding() [2/6]

◆ tightEncoding() [3/6]

◆ tightEncoding() [4/6]

◆ tightEncoding() [5/6]

◆ tightEncoding() [6/6]

◆ utf8ValidTo() [1/2]

◆ utf8ValidTo() [2/2]

◆ valueOf() [1/14]

◆ valueOf() [2/14]

◆ valueOf() [3/14]

◆ valueOf() [4/14]

◆ valueOf() [5/14]

◆ valueOf() [6/14]

◆ valueOf() [7/14]

◆ valueOf() [8/14]

◆ valueOf() [9/14]

◆ valueOf() [10/14]

◆ valueOf() [11/14]

◆ valueOf() [12/14]

◆ valueOf() [13/14]

◆ valueOf() [14/14]

◆ xmlEncodeComment()

◆ xmlEncodeSpecialChars()

◆ xmlValueTag()

Variable Documentation

◆ base64Spare