Regina Calculation Engine
Classes | Macros | Typedefs | Functions
Miscellaneous Utilities

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::BitManipulatorBySize< T, size >
 Contains implementation details for BitManipulator where we optimise according to the size of the underlying data type. More...
 
class  regina::BitManipulator< T >
 
An optimised class for bitwise analysis and manipulation of native data types. 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::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. 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...
 
class  regina::ListOnCall< T >
 
Offers a hard-coded list of expensive objects that should only be created if they are required. 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...
 
struct  regina::FuncNew< T >
 
An adaptable generator used to create objects using default constructors. More...
 
struct  regina::FuncNewCopyPtr< T >
 
An adaptable unary function used to create objects using copy constructors. More...
 
struct  regina::FuncNewCopyRef< T >
 
An adaptable unary function used to create objects using copy constructors. More...
 
struct  regina::FuncNewClonePtr< T >
 
An adaptable unary function used to create objects using the clone() method. More...
 
struct  regina::FuncDelete< T >
 
An adaptable unary function used to deallocate objects. More...
 
class  regina::StoreValue< T >
 
A Property storage policy indicating that the property should be held by value. More...
 
class  regina::StoreConstPtr< T >
 
A Property storage policy indicating that the property should be held by constant pointer. More...
 
class  regina::StoreManagedPtr< T >
 
A Property storage policy indicating that the property should be held by pointer and that the property wrapper will also take responsibility for memory management. More...
 
class  regina::Property< T, Storage >
 
Stores a calculable property of an object. More...
 
class  regina::LessDeref< T, Comp >
 
An adaptable binary function used to compare the objects to which pointers are pointing. 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...
 
struct  regina::Returns< ReturnType_ >
 
A convenience base class for a non-void function object, which does nothing beyond provide a ReturnType typedef. More...
 
class  regina::HasReturnType< T >
 Internal to ReturnsTraits. More...
 
struct  regina::ReturnsTraitsImplementation< T, hasReturnType >
 Provides the implementation of ReturnsTraits. More...
 
struct  regina::ReturnsTraits< T >
 Helper class to assist with compile-time analysis of Regina's function objects. More...
 
struct  regina::NewFunction< Base >
 
A function object that creates a new object subclassed from Base, where the particular subclass is chosen according to the template argument to operator(). More...
 
class  regina::SafePointeeBase< T >
 A base class for objects of type T to be referenceable by a SafePtr. More...
 
class  regina::SafePtr< T >
 A reference counted smart pointer that supports alternate models of ownership. More...
 
class  regina::LightweightSequence< T >
 
A lightweight class for storing a random-access sequence of objects. More...
 
class  regina::TrieSet< T >
 
A trie-like data structure for storing and retriving sets. More...
 
class  regina::Tritmask1< T >
 
A small but extremely fast "ternary bitmask" class that can store up to 8 * sizeof(T) "trits", each equal to 0, 1 or 2. More...
 
class  regina::Tritmask2< T, U >
 
A small but extremely fast "ternary bitmask" class that can store up to 8 * sizeof(T) + 8 * sizeof(U) "trits", each equal to 0, 1 or 2. More...
 
class  regina::xml::XMLPropertyDict
 
Represents a map from property names to property values. More...
 
class  regina::xml::XMLParserCallback
 
Provides the callbacks for an XMLParser. More...
 
class  regina::xml::XMLParser
 
Used to parse an entire XML file. More...
 

Macros

#define INT128_AVAILABLE
 Defined if and only if native 128-bit arithmetic is available on this platform. More...
 

Typedefs

typedef Bitmask1< unsigned char > regina::BitmaskLen8
 
A convenience typedef that gives a small and extremely fast bitmask class capable of holding at least 8 true-or-false bits. More...
 
typedef Bitmask1< unsigned int > regina::BitmaskLen16
 
A convenience typedef that gives a small and extremely fast bitmask class capable of holding at least 16 true-or-false bits. More...
 
typedef InternalBitmaskLen32 ::Type regina::BitmaskLen32
 
A convenience typedef that gives a small and extremely fast bitmask class capable of holding at least 32 true-or-false bits. More...
 
typedef InternalBitmaskLen64 ::Type regina::BitmaskLen64
 
A convenience typedef that gives a small and extremely fast bitmask class capable of holding at least 64 true-or-false bits. More...
 
typedef BoolSet regina::NBoolSet
 Deprecated typedef for backward compatibility. More...
 
typedef Qitmask1< unsigned char > regina::QitmaskLen8
 
A convenience typedef that gives a small and extremely fast qitmask class capable of holding at least 8 true-or-false bits. More...
 
typedef Qitmask1< unsigned int > regina::QitmaskLen16
 
A convenience typedef that gives a small and extremely fast qitmask class capable of holding at least 16 true-or-false bits. More...
 
typedef InternalQitmaskLen32 ::Type regina::QitmaskLen32
 
A convenience typedef that gives a small and extremely fast qitmask class capable of holding at least 32 true-or-false bits. More...
 
typedef InternalQitmaskLen64 ::Type regina::QitmaskLen64
 
A convenience typedef that gives a small and extremely fast qitmask class capable of holding at least 64 true-or-false bits. More...
 
typedef Tritmask1< unsigned char > regina::TritmaskLen8
 
A convenience typedef that gives a small and extremely fast tritmask class capable of holding at least 8 true-or-false bits. More...
 
typedef Tritmask1< unsigned int > regina::TritmaskLen16
 
A convenience typedef that gives a small and extremely fast tritmask class capable of holding at least 16 true-or-false bits. More...
 
typedef InternalTritmaskLen32 ::Type regina::TritmaskLen32
 
A convenience typedef that gives a small and extremely fast tritmask class capable of holding at least 32 true-or-false bits. More...
 
typedef InternalTritmaskLen64 ::Type regina::TritmaskLen64
 
A convenience typedef that gives a small and extremely fast tritmask 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...
 
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, const 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...
 
void regina::writeResUsage (std::ostream &out)
 
Writes time and memory usage for the current process to the given output stream. More...
 
template<typename T >
T * regina::clonePtr (T *cloneMe)
 
A simple routine for cloning an object if and only if it exists. More...
 
template<typename T >
T * regina::clonePtr (const std::unique_ptr< T > &cloneMe)
 
A simple routine for cloning an object if and only if it exists. 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...
 
char * regina::duplicate (const std::string &str)
 
Creates a new C string that is a duplicate of the given C++ string. 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)
 
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...
 
template<class OutputIterator >
unsigned regina::basicTokenise (OutputIterator results, const std::string &str)
 
Decomposes the given string into tokens. More...
 
std::string regina::stringToToken (const char *str)
 Returns a token derived from the given string. More...
 
std::string regina::stringToToken (const 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...
 
template<typename T >
std::ostream & regina::operator<< (std::ostream &out, const Tritmask1< T > &mask)
 
Writes the given tritmask to the given output stream as a sequence of digits (0, 1 and/or 2). More...
 
template<typename T , typename U >
std::ostream & regina::operator<< (std::ostream &out, const Tritmask2< T, U > &mask)
 
Writes the given tritmask to the given output stream as a sequence of digits (0, 1 and/or 2). More...
 
std::string regina::xml::xmlString (xmlChar *str, bool free=true)
 Converts the given string from libxml into a C++ string, optionally deallocating the original libxml string. 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...
 

Detailed Description

Miscellaneous helper classes and functions.

Macro Definition Documentation

◆ INT128_AVAILABLE

#define INT128_AVAILABLE

Defined if and only if native 128-bit arithmetic is available on this platform.

If this macro is defined, then you can access native signed and unsigned 128-bit integers through the types IntOfSize<16>::type and IntOfSize<16>::utype respectively.

If this macro is not defined, then the types IntOfSize<16>::type and IntOfSize<16>::utype will both be void.

Typedef Documentation

◆ BitmaskLen16

typedef Bitmask1<unsigned int> regina::BitmaskLen16


A convenience typedef 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.

Python
Not present.

◆ BitmaskLen32

typedef InternalBitmaskLen32 ::Type regina::BitmaskLen32


A convenience typedef 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.

Python
Not present.

◆ BitmaskLen64

typedef InternalBitmaskLen64 ::Type regina::BitmaskLen64


A convenience typedef 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.

Python
Not present.

◆ BitmaskLen8

typedef Bitmask1<unsigned char> regina::BitmaskLen8


A convenience typedef 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.

Python
Not present.

◆ NBoolSet

Deprecated typedef for backward compatibility.

This typedef will be removed in a future release of Regina.

Deprecated:
The class NBoolSet has now been renamed to BoolSet.

◆ QitmaskLen16

typedef Qitmask1<unsigned int> regina::QitmaskLen16


A convenience typedef 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.

Python
Not present.

◆ QitmaskLen32

typedef InternalQitmaskLen32 ::Type regina::QitmaskLen32


A convenience typedef 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.

Python
Not present.

◆ QitmaskLen64

typedef InternalQitmaskLen64 ::Type regina::QitmaskLen64


A convenience typedef 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.

Python
Not present.

◆ QitmaskLen8

typedef Qitmask1<unsigned char> regina::QitmaskLen8


A convenience typedef 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.

Python
Not present.

◆ TritmaskLen16

typedef Tritmask1<unsigned int> regina::TritmaskLen16


A convenience typedef that gives a small and extremely fast tritmask class capable of holding at least 16 true-or-false bits.

This tritmask class is guaranteed to be an instantiation of the template class Tritmask1.

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

Python
Not present.

◆ TritmaskLen32

typedef InternalTritmaskLen32 ::Type regina::TritmaskLen32


A convenience typedef that gives a small and extremely fast tritmask class capable of holding at least 32 true-or-false bits.

This tritmask class is guaranteed to be an instantiation of the template class Tritmask1.

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

Python
Not present.

◆ TritmaskLen64

typedef InternalTritmaskLen64 ::Type regina::TritmaskLen64


A convenience typedef that gives a small and extremely fast tritmask class capable of holding at least 64 true-or-false bits.

This tritmask class is guaranteed to be an instantiation of either the template class Tritmask1 or the template class Tritmask2.

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

Python
Not present.

◆ TritmaskLen8

typedef Tritmask1<unsigned char> regina::TritmaskLen8


A convenience typedef that gives a small and extremely fast tritmask class capable of holding at least 8 true-or-false bits.

This tritmask class is guaranteed to be an instantiation of the template class Tritmask1.

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

Python
Not present.

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 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
Not present.
Parameters
inthe input sequence of base64 characters; this does not need to be terminated in any special way.
inlenthe length of the input sequence.
outthe output buffer into which the resulting raw bytes will be written.
outlenmust 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.

◆ 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 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
Not present.
Parameters
inthe input sequence of base64 characters; this does not need to be terminated in any special way.
inlenthe length of the input sequence.
outthe address of a pointer which will be set to the output array of raw bytes (or which will be set to null on failure).
outlenthe 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.

◆ base64Encode() [1/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
Not present.
Parameters
inthe sequence of input bytes; this does not need to be terminated in any special way.
inlenthe length of the input sequence.
outthe output buffer into which the resulting base64 characters will be written.
outlenthe 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.

◆ base64Encode() [2/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
Not present.
Parameters
inthe sequence of input bytes; this does not need to be terminated in any special way.
inlenthe length of the input sequence.
outthe 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.

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

Python
Not present.
Parameters
bytesthe number of raw input bytes.
Returns
the corresponding number of base64 printable output characters.

◆ basicTokenise()

template<class OutputIterator >
unsigned regina::basicTokenise ( OutputIterator  results,
const std::string &  str 
)


Decomposes the given string into tokens.

This is an extremely simple tokeniser; tokens are defined to be separated by whitespace.

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.
Python
Not present.
Parameters
resultsthe output iterator to which the resulting tokens will be written; this must accept objects of type const std::string&.
strthe string to decompose.
Returns
the number of tokens found.

◆ bitsRequired()

template<typename IntType >
constexpr int regina::bitsRequired ( IntType  n)


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
nany integer.
Returns
the number of bits required to store 0,...,n-1.
Template Parameters
IntTypeany integer type, such as int, long, and so on.

◆ clonePtr() [1/2]

template<typename T >
T* regina::clonePtr ( T *  cloneMe)
inline


A simple routine for cloning an object if and only if it exists.

If the given pointer is non-null, this routine returns a new clone of the object, created using the copy constructor for type T. Otherwise this routine simply returns a null pointer.

The caller of this routine is responsible for deleting the new clone when it is no longer required.

This routine can be useful when implementing copy constructors for classes that only initialise internal data members on demand.

Python
Not present.
Parameters
cloneMea pointer to the object to clone; this may be null.
Returns
a newly allocated copy of the given object, or the null pointer if cloneMe is null.

◆ clonePtr() [2/2]

template<typename T >
T* regina::clonePtr ( const std::unique_ptr< T > &  cloneMe)
inline


A simple routine for cloning an object if and only if it exists.

If the given pointer is non-null, this routine returns a new clone of the object, created using the copy constructor for type T. Otherwise this routine simply returns a null pointer.

Note that, even though this routine takes a std::unique_ptr, it returns a raw pointer. The caller of this routine is responsible for deleting the new clone when it is no longer required.

This routine can be useful when implementing copy constructors for classes that only initialise internal data members on demand.

Python
Not present.
Parameters
cloneMea pointer to the object to clone; this may be null.
Returns
a newly allocated copy of the given object, or the null pointer if cloneMe is null.

◆ duplicate()

char* regina::duplicate ( const std::string &  str)


Creates a new C string that is a duplicate of the given C++ string.

The deallocation of the new C string is the responsibility of the caller of this routine.

Python
Not present.
Parameters
strthe C++ string to duplicate.
Returns
the new duplicate C string.

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

Python
Not present.
Parameters
chany 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)


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
nany integer.
Returns
the smallest integer power of two that is ≥ n.
Template Parameters
IntTypeany integer type, such as int, long, and so on.

◆ operator<<() [1/9]

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

Python
Not present.
Parameters
outthe output stream to which to write.
maskthe qitmask to write.
Returns
a reference to the given output stream.

◆ operator<<() [2/9]

template<typename T >
std::ostream& regina::operator<< ( std::ostream &  out,
const Tritmask1< T > &  mask 
)


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

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

Python
Not present.
Parameters
outthe output stream to which to write.
maskthe tritmask to write.
Returns
a reference to the given output stream.

◆ operator<<() [3/9]

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

Python
Not present.
Parameters
outthe output stream to which to write.
maskthe qitmask to write.
Returns
a reference to the given output stream.

◆ operator<<() [4/9]

std::ostream& regina::operator<< ( std::ostream &  out,
const 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
outthe output stream to which to write.
setthe boolean set to write.
Returns
a reference to out.

◆ operator<<() [5/9]

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
outthe output stream to which to write.
sthe sequence to write.
Returns
a reference to the given output stream.

◆ operator<<() [6/9]

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

Python
Not present.
Parameters
outthe output stream to which to write.
maskthe bitmask to write.
Returns
a reference to the given output stream.

◆ operator<<() [7/9]

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

Python
Not present.
Parameters
outthe output stream to which to write.
maskthe bitmask to write.
Returns
a reference to the given output stream.

◆ operator<<() [8/9]

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


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

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

Python
Not present.
Parameters
outthe output stream to which to write.
maskthe tritmask to write.
Returns
a reference to the given output stream.

◆ operator<<() [9/9]

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

Python
Not present.
Parameters
outthe output stream to which to write.
maskthe bitmask to write.
Returns
a reference to the given output stream.

◆ startsWith()

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


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

Python
Not present.
Parameters
strthe full C++ string to examine.
prefixthe prefix whose presence we are testing for.
Returns
true if and only if str begins with prefix.

◆ stringToToken() [1/2]

std::string regina::stringToToken ( const char *  str)

Returns a token derived from the given string.

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

Parameters
strthe string on which to base the token.
Returns
the corresponding token.

◆ stringToToken() [2/2]

std::string regina::stringToToken ( const 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
strthe 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.
Python
Not present.
Parameters
strthe string to be stripped.
Returns
the resulting stripped string.

◆ subscript()

template<typename T >
std::string regina::subscript ( 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 ( 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.

◆ utf8ValidTo() [1/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.

◆ utf8ValidTo() [2/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.

◆ valueOf() [1/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
Not present.
Parameters
strthe string to convert.
destthe variable in which to store the resulting 8-bit integer.
Returns
true if the conversion was completely successful or false otherwise.

◆ valueOf() [2/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
Not present.
Parameters
strthe string to convert.
destthe variable in which to store the resulting unsigned 8-bit integer.
Returns
true if the conversion was completely successful or false otherwise.

◆ valueOf() [3/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
Not present.
Parameters
strthe string to convert.
destthe variable in which to store the resulting short integer.
Returns
true if the conversion was completely successful or false otherwise.

◆ valueOf() [4/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
Not present.
Parameters
strthe string to convert.
destthe variable in which to store the resulting unsigned short integer.
Returns
true if the conversion was completely successful or false otherwise.

◆ valueOf() [5/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
Not present.
Parameters
strthe string to convert.
destthe variable in which to store the resulting integer.
Returns
true if the conversion was completely successful or false otherwise.

◆ valueOf() [6/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
Not present.
Parameters
strthe string to convert.
destthe variable in which to store the resulting unsigned 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
Not present.
Parameters
strthe string to convert.
destthe 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,
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.
Parameters
strthe string to convert.
destthe variable in which to store the resulting unsigned long integer.
Returns
true if the conversion was completely successful or false otherwise.

◆ valueOf() [9/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
Not present.
Parameters
strthe string to convert.
destthe variable in which to store the resulting long long integer.
Returns
true if the conversion was completely successful or false otherwise.

◆ valueOf() [10/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
Not present.
Parameters
strthe string to convert.
destthe variable in which to store the resulting unsigned long long integer.
Returns
true if the conversion was completely successful or false otherwise.

◆ valueOf() [11/14]

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


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.

Python
Not present.
Parameters
strthe string to convert.
destthe variable in which to store the resulting arbitrary precision integer.
Returns
true if the conversion was completely successful or false otherwise.

◆ valueOf() [12/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
Not present.
Parameters
strthe string to convert.
destthe variable in which to store the resulting real number.
Returns
true if the conversion was completely successful or false otherwise.

◆ valueOf() [13/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
Not present.
Parameters
strthe string to convert.
destthe variable in which to store the resulting boolean.
Returns
true if the conversion was completely successful or false otherwise.

◆ valueOf() [14/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 strings , T-, -F or TF. If the conversion is unsuccessful, argument dest will be set to BoolSet::sNone and false will be returned.

Python
Not present.
Parameters
strthe string to convert.
destthe variable in which to store the resulting set of booleans.
Returns
true if the conversion was successful or false otherwise.

◆ writeResUsage()

void regina::writeResUsage ( std::ostream &  out)


Writes time and memory usage for the current process to the given output stream.

Information is gathered from the /proc filesystem, which means that this routine will only write meaningful information under a Linux system where /proc is mounted.

Specifically, this routine reads information on the running process from /proc/self/stat, and writes a short string to the given output stream of the form:

utime=..., stime=..., vsize=...

The three ellipses in the example above will be replaced with integers, representing:

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

The output will not contain a newline, and the given output stream will not be flushed.

If /proc/self/stat cannot be read, this routine will write a short message to that effect to the given output stream (which means that this utility is safe to call under non-Linux operating systems, although it will of course be useless in such scenarios).

If /proc/self/stat can be read but contains unexpected information, the behaviour of this routine is undefined.

Python
This routine does not take any arguments; instead the stream out is assumed to be standard output.
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 write a note to this effect to the given output stream. If you encounter this problem, you should be able to fix it by renaming your executable to something shorter.
Parameters
outthe output stream to which usage information will be written.

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

Python
Not present.
Parameters
commentthe 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 \&lt; b".

Python
Not present.
Parameters
originalthe string to convert; this string will not be changed.
Returns
the converted string with special characters replaced by XML entities.

◆ xmlString()

std::string regina::xml::xmlString ( xmlChar *  str,
bool  free = true 
)
inline

Converts the given string from libxml into a C++ string, optionally deallocating the original libxml string.

The given libxml string str may be null, in which case the resulting C++ string will be the empty string.

Parameters
strthe string to convert.
freetrue if the original libxml string str should be deallocated, or false if it should be preserved.
Returns
the given string as a C++ string.

◆ 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
tagNamethe name of the XML tag to create.
valuethe value to assign to the value property of the tag.
Returns
the corresponding XML tag.

Copyright © 1999-2021, The Regina development team
This software is released under the GNU General Public License, with some additional permissions; see the source code for details.
For further information, or to submit a bug or other problem, please contact Ben Burton (bab@maths.uq.edu.au).