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 whose size is not known at compile-time. More...

class	regina::ListView< Element[n]>
	A specialisation of ListView for working with lists stored in a C-style array whose size is fixed at compile-time. 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::TableView< Element, dim1, dim >
	A lightweight object that can be used for random access to all elements of a given multi-dimensional table. More...

struct	regina::TightEncodable< T >
	A base class that assists with support for tight encodings and corresponding decodings. 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...

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...

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...

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...

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

std::string	regina::tightEncoding (bool value)
	Returns the tight encoding of the given boolean. 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...

template<typename Int , typename iterator >
Int	regina::detail::tightDecodeInteger (iterator start, iterator limit, bool noTrailingData)
	Internal function that reconstructs an integer from its given tight encoding. More...

template<typename Int >
void	regina::detail::tightEncodeIndex (std::ostream &out, Int value)
	Internal function that writes the tight encoding of an integer whose value is either non-negative or -1. More...

void	regina::detail::tightEncodeNoIndex (std::ostream &out)
	Internal function that writes the tight encoding of -1, using an encoding that is compatible with tightEncodeIndex(). More...

template<typename Int >
Int	regina::detail::tightDecodeIndex (std::istream &input)
	Internal function that reconstructs an integer that was encoded using tightEncodeIndex(). More...

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

template<int from, int to, class Action >
constexpr void	regina::for_constexpr (Action &&action)
	Implements a compile-time `for` loop over a range of integers. More...

template<int from, int to, typename Return , class Action >
constexpr Return	regina::select_constexpr (int value, Action &&action)
	Implements a compile-time selection, where the runtime argument must belong to a compile-time range of integers, and the value of the argument determines what is returned. More...

template<int from, int to, class Action >
constexpr auto	regina::select_constexpr_as_variant (int value, Action &&action)
	A variant of select_constexpr() where the return type is a variant, built from the return types for all integers in the given compile-time range. 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...

template<typename IntType , IntType coeff>
constexpr IntType	regina::maxSafeFactor
	The largest integer of the given type that can be multiplied by coeff without overflowing. More...

template<typename IntType , IntType coeff>
constexpr IntType	regina::minSafeFactor
	The largest integer of the given type that can be multiplied by coeff without overflowing. 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 or function has not yet been finalised. This means that the interface may change in new versions of Regina, without maintaining backward compatibility. If you use this class directly in your own code, please check the detailed changelog with each new release to see if you need to make changes to your code.

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), where input_string is a base64 string, and the return value is a Python bytes object. 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), where input_string is a base64 string, and the return value is a Python bytes object. 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), where input_bytes is a a Python bytes object, and the return value is a Python 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), where input_bytes is a a Python bytes object, and the return value is a Python 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()

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.

◆ 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.

Template Parameters

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

Parameters

n	any integer.

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

◆ for_constexpr()

template<int from, int to, class Action >

constexpr void regina::for_constexpr ( Action && action )

constexpr

Implements a compile-time for loop over a range of integers.

This function will call action for each integer i in the range from, ..., (to-1) inclusive.

The action should be a templated callable object (e.g., a generic lambda) that takes a single argument whose type depends on the value of i. Any return value will be ignored. For each integer i, the argument will be of type std::integral_constant<int, i>, which means that i is accessible as a compile-time constant.

If from is not less than to, then this routine safely does nothing.

Parameters

action the body of the for loop; that is, the action to perform for each integer i. See above for the interface that action should adhere to.

◆ 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.

Template Parameters

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

Parameters

n	any integer.

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

◆ 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.

◆ select_constexpr()

template<int from, int to, typename Return , class Action >

constexpr Return regina::select_constexpr	(	int	value,
		Action &&	action
	)

constexpr

Implements a compile-time selection, where the runtime argument must belong to a compile-time range of integers, and the value of the argument determines what is returned.

The action should be a templated callable object (e.g., a generic lambda) that takes a single argument. If value is equal to the integer i, for some i in the range from, ..., (to-1) inclusive, then this function will return action(i). The argument i will be passed using the type std::integral_constant<int, i>, which means that the value of i will be accessible to action as a compile-time constant.

Exceptions

std::runtime_error The given runtime value is not within the range from, ..., (to-1).

Template Parameters

Return the type to be returned from this function. Typically this will be the same as the return type from action, but it may differ (particuarly if the return type of action depends upon its integer argument).

Parameters

value	the runtime value that determines the selection; that is, the argument that will be passed to the given action as a compile-time constant.
action	the action to perform for whichever integer i matches the given runtime value. See above for the interface that action should adhere to.

Returns: the value returned from action.

◆ select_constexpr_as_variant()

template<int from, int to, class Action >

constexpr auto regina::select_constexpr_as_variant	(	int	value,
		Action &&	action
	)

constexpr

A variant of select_constexpr() where the return type is a variant, built from the return types for all integers in the given compile-time range.

See select_constexpr() for an overview of how Regina's compile-time selection function works. This routine behaves exactly the same as select_constexpr(), except that you do not need to explicitly give the return type. Instead, the return type will be std::variant<R(from), R(from+1), ..., R(to-1)>, where each R(i) denotes the type returned by the corresponding call to action(i).

This is useful when the return type from action (not just the return value) depends on i. An example of this is Triangulation::face(subdim, index), whose return type would normally be Face<subdim>*, except for the fact that subdim is not known until runtime. Therefore this function needs to return a std::variant, and so select_constexpr_as_variant() can be used for its internal implementation.

See select_constexpr() for further details.

Precondition: All of the possible return types R(from), R(from+1), ..., R(to-1) are different.

Exceptions

std::runtime_error The given runtime value is not within the range from, ..., (to-1).

Parameters

value	the runtime value that determines the selection; that is, the argument that will be passed to the given action as a compile-time constant.
action	the action to perform for whichever integer i matches the given runtime value. See above for the interface that action should adhere to.

Returns: the value returned from action, given as a variant that encapsulates all (to - from) possible return types.

◆ 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.

Python: Not present. The SnapshotRef classes are not accessible to Python users.

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.

◆ tightDecodeIndex()

template<typename Int >

Int regina::detail::tightDecodeIndex ( std::istream & input )

Internal function that reconstructs an integer that was encoded using tightEncodeIndex().

This encoding method is used for integers that are either non-negative or -1, and is not compatible with Regina's general integer encodings.

The tight encoding will be read from the given input stream. If the input stream contains leading whitespace then it will be treated as an invalid encoding (i.e., this routine will throw an exception). The input routine may contain further data: if this routine is successful then the input stream will be left positioned immediately after the encoding, without skipping any trailing whitespace.

Exceptions

InvalidInput The given input stream does not begin with a tight encoding of an integer of type Int using the encoding scheme defined by tightEncodeIndex(). This includes the case where the encoding is a valid non-negative integer encoding but the integer itself is outside the allowed range for the Int type.

Python: Not present.

Template Parameters

Int	The type of integer to reconstruct. Currently this must be either `ssize_t` (the only allowed signed type), or one of the unsigned native C++ integer types that holds at least 16 bits. This list of types may be expanded in future versions of Regina.

Parameters

input an input stream that begins with a tight encoding.

Returns: the integer represented by the given tight encoding.

◆ tightDecodeInteger()

template<typename Int , typename iterator >

Int regina::detail::tightDecodeInteger	(	iterator	start,
		iterator	limit,
		bool	noTrailingData
	)

Internal function that reconstructs an integer from its given tight encoding.

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

The tight encoding will be extracted one character at a time beginning with the iterator start, in a single pass, without skipping any leading whitespace. If the iterator ever reaches limit before the encoding is complete then the encoding is treated as invalid (i.e., this routine will throw an exception).

If noTrailingData is true then the iterator is required to finish at limit, or else the encoding will be considered invalid also; if noTrailingData is false then there is no constraint on the final state of the iterator.

Exceptions

InvalidInput The given iterator does not point to a tight encoding of an integer of type Int. This includes the case where the encoding is a valid integer encoding but the integer itself is outside the allowed range for the Int type.

This routine does recognise infinity in the case where Int is the type regina::LargeInteger.

Python: Not present. Use regina::tightDecoding() instead.

Template Parameters

Int	The type of integer to reconstruct; 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). In particular, `bool` is not allowed here.
iterator	an input iterator type.

Parameters

start	an iterator that points to the beginning of a tight encoding.
limit	an iterator that, if reached, indicates that no more characters are available.
noTrailingData	`true` if iteration should reach limit immediately after the encoding is read, or `false` if there is allowed to be additional unread data.

Returns: the integer represented by the given tight encoding.

◆ tightEncode() [1/7]

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

inline

Writes the tight encoding of the given boolean to the given output stream.

See the page on tight encodings for details.

The booleans true and false are guaranteed to have the same tight encodings as the integers 1 and 0 respectively.

Python: Not present. Use regina::tightEncoding(bool) instead, which returns a string.

Parameters

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

◆ tightEncode() [2/7]

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, which returns a string.

Parameters

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

◆ tightEncode() [3/7]

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, which returns a string.

Parameters

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

◆ tightEncode() [4/7]

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, which returns a string.

Parameters

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

◆ tightEncode() [5/7]

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, which returns a string.

Parameters

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

◆ tightEncode() [6/7]

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, which returns a string.

Parameters

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

◆ tightEncode() [7/7]

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, which returns a string.

Parameters

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

◆ tightEncodeIndex()

template<typename Int >

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

Internal function that writes the tight encoding of an integer whose value is either non-negative or -1.

This should not be used for encoding standalone integers, since it uses a more compact format that is not compatible with Regina's general integer encodings. Instead, it is intended to be used as part of the encoding for larger objects (e.g., triangulations or isomorphisms).

Exceptions

InvalidArgument The given integer is less than -1.

Python: Not present.

Template Parameters

Int	The type of integer to encode. Currently this must be either `ssize_t` (the only allowed signed type), or one of the unsigned native C++ integer types that holds at least 16 bits. This list of types may be expanded in future versions of Regina.

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). In particular, `bool` is not allowed here.

Parameters

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

◆ tightEncodeNoIndex()

void regina::detail::tightEncodeNoIndex ( std::ostream & out )

inline

Internal function that writes the tight encoding of -1, using an encoding that is compatible with tightEncodeIndex().

Note that this is not compatible with Regina's general integer encodings.

This is identical to calling tightEncodeIndex<ssize_t>(out, -1).

Python: Not present.

Parameters

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

◆ tightEncoding() [1/7]

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

inline

Returns the tight encoding of the given boolean.

See the page on tight encodings for details.

The booleans true and false are guaranteed to have the same tight encodings as the integers 1 and 0 respectively.

Parameters

value the boolean to encode.

Returns: the resulting encoded string.

◆ tightEncoding() [2/7]

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() [3/7]

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() [4/7]

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() [5/7]

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() [6/7]

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() [7/7]

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/13]

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: Not present. 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/13]

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. None of Regina's valueOf() functions are wrapped in Python. For this variant, you can instead 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/13]

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: Not present. 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/13]

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: Not present. 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/13]

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: Not present. 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/13]

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: Not present. 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() [7/13]

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: Not present. 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() [8/13]

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: Not present. 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() [9/13]

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: Not present. 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() [10/13]

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: Not present. 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() [11/13]

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: Not present. 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() [12/13]

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: Not present. 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() [13/13]

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: Not present. 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.

◆ maxSafeFactor

template<typename IntType , IntType coeff>

constexpr IntType regina::maxSafeFactor

inlineconstexpr

Initial value:

=

std::numeric_limits<IntType>::max() / coeff

The largest integer of the given type that can be multiplied by coeff without overflowing.

The template parameter IntType may be any native C++ integer type, such as int, long, and so on. This type may be either signed or unsigned, but it must be supported by std::numeric_limits.

The template parameter coeff can be any positive integer.

Python: Not present. This is because Python does not support templates.

◆ minSafeFactor

template<typename IntType , IntType coeff>

constexpr IntType regina::minSafeFactor

inlineconstexpr

Initial value:

=

std::numeric_limits<IntType>::min() / coeff

The largest integer of the given type that can be multiplied by coeff without overflowing.

The template parameter IntType may be any native C++ integer type, such as int, long, and so on. This type may be either signed or unsigned, but it must be supported by std::numeric_limits.

The template parameter coeff can be any positive integer.

Python: Not present. This is because Python does not support templates.

Classes

Macros

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ ENABLE_MEMBER_FOR_REGINA_INTEGER

Function Documentation

◆ base64Decode() [1/2]

◆ base64Decode() [2/2]

◆ base64Encode() [1/2]

◆ base64Encode() [2/2]

◆ base64Length()

◆ basicTokenise()

◆ bitsRequired()

◆ for_constexpr()

◆ isBase64()

◆ nextPowerOfTwo()

◆ operator<<() [1/7]

◆ operator<<() [2/7]

◆ operator<<() [3/7]

◆ operator<<() [4/7]

◆ operator<<() [5/7]

◆ operator<<() [6/7]

◆ operator<<() [7/7]

◆ resUsage()

◆ select_constexpr()

◆ select_constexpr_as_variant()

◆ startsWith()

◆ stringToToken()

◆ stripWhitespace()

◆ subscript()

◆ superscript()

◆ swap() [1/5]

◆ swap() [2/5]

◆ swap() [3/5]

◆ swap() [4/5]

◆ swap() [5/5]

◆ tightDecodeIndex()

◆ tightDecodeInteger()

◆ tightEncode() [1/7]

◆ tightEncode() [2/7]

◆ tightEncode() [3/7]

◆ tightEncode() [4/7]

◆ tightEncode() [5/7]

◆ tightEncode() [6/7]

◆ tightEncode() [7/7]

◆ tightEncodeIndex()

◆ tightEncodeInteger()

◆ tightEncodeNoIndex()

◆ tightEncoding() [1/7]

◆ tightEncoding() [2/7]

◆ tightEncoding() [3/7]

◆ tightEncoding() [4/7]

◆ tightEncoding() [5/7]

◆ tightEncoding() [6/7]

◆ tightEncoding() [7/7]

◆ utf8ValidTo() [1/2]

◆ utf8ValidTo() [2/2]

◆ valueOf() [1/13]

◆ valueOf() [2/13]

◆ valueOf() [3/13]

◆ valueOf() [4/13]

◆ valueOf() [5/13]

◆ valueOf() [6/13]

◆ valueOf() [7/13]

◆ valueOf() [8/13]

◆ valueOf() [9/13]

◆ valueOf() [10/13]

◆ valueOf() [11/13]

◆ valueOf() [12/13]

◆ valueOf() [13/13]

◆ xmlEncodeComment()

◆ xmlEncodeSpecialChars()

◆ xmlValueTag()

Variable Documentation

◆ base64Spare

◆ base64Table

◆ maxSafeFactor

◆ minSafeFactor