Utilities

## Classes

class | regina::GenericBitManipulator< T, size >
| A generic class for bitwise analysis and manipulation of native data types. More...
class | regina::BitManipulator< T, size >
| An optimised class for bitwise analysis and manipulation of native data types. More...
struct | regina::boost::remove_pointer< T >
| A template class used to remove the indirection from a pointer type. More...
class | regina::boost::reference_wrapper< T >
| A wrapper allowing references to be passed through generic functions. More...
class | regina::boost::noncopyable
| A base class that guarantees that derived classes cannot be copied. 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::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::NBitmask
| A bitmask that can store arbitrarily many true-or-false bits. More...
class | regina::NBitmask1< T >
| A small but extremely fast bitmask class that can store up to 8 * sizeof(T) true-or-false bits. More...
class | regina::NBitmask2< 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::NTriBool
| A three-way extension of the boolean type. More...
class | regina::NTriBool_Illegal_Integer_Conversion
| An exception thrown when an illegal integer conversion is attempted with NTriBool. More...
class | regina::NBoolSet
| A set of booleans. More...
class | regina::NListOnCall< T >
| Offers a hard-coded list of expensive objects that should only be created if they are required. More...
class | regina::NMarkedElement
| A base class for elements of NMarkedVector. More...
class | regina::NMarkedVector< T >
| A vector of objects with fast, space-efficient reverse lookup of array indices. More...
class | regina::StoreValue< T >
| An NProperty storage policy indicating that the property should be held by value. More...
class | regina::StoreConstPtr< T >
| An NProperty storage policy indicating that the property should be held by constant pointer. More...
class | regina::StoreManagedPtr< T >
| An NProperty 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::NPropertyBase
| A base class that provides routines shared by all properties, regardless of their individual NProperty template parameters. More...
class | regina::NProperty< T, Storage >
| Stores a calculable property of an object. More...
class | regina::NQitmask1< 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::NQitmask2< 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::NMutex
| A mutual exclusion device (mutex) used to ensure that different threads do not interfere when working with the same data. More...
class | regina::NThread
| Provides very basic thread handling. More...
class | regina::NTrieSet< T >
| A trie-like data structure for storing and retriving sets. More...
class | regina::NTritmask1< 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::NTritmask2< 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::LessDeref< T, Comp >
| An adaptable binary function used to compare the objects to which pointers are pointing. More...
struct | regina::stl::select1st< Pair >
| An adaptable unary function used to select the first element of a pair. More...
struct | regina::stl::select2nd< Pair >
| An adaptable unary function used to select the second element of a pair. More...
class | regina::stl::unary_compose< Operation1, Operation2 >
| An adaptable unary function used to compose two unary functions. 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...
class | regina::ZBuffer
| A common base class for compression/decompression stream buffers. More...
class | regina::CompressionBuffer
| An output stream buffer that compresses data as it is written. More...
class | regina::DecompressionBuffer
| An input stream buffer that decompresses data as it is read. More...
class | regina::CompressionStream
| An output stream that compresses data as it is written. More...
class | regina::DecompressionStream
| An input stream that decompresses data as it is read. More...

## Typedefs

typedef NBitmask1< unsigned char > | regina::NBitmaskLen8
| A convenience typedef that gives a small and extremely fast bitmask class capable of holding at least 8 true-or-false bits. More...
typedef NBitmask1< unsigned int > | regina::NBitmaskLen16
| 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::NBitmaskLen32
| 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::NBitmaskLen64
| A convenience typedef that gives a small and extremely fast bitmask class capable of holding at least 64 true-or-false bits. More...
typedef NQitmask1< unsigned char > | regina::NQitmaskLen8
| A convenience typedef that gives a small and extremely fast qitmask class capable of holding at least 8 true-or-false bits. More...
typedef NQitmask1< unsigned int > | regina::NQitmaskLen16
| 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::NQitmaskLen32
| 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::NQitmaskLen64
| A convenience typedef that gives a small and extremely fast qitmask class capable of holding at least 64 true-or-false bits. More...
typedef pthread_t | regina::NThreadID
| The type used for a thread identifier. More...
typedef NTritmask1< unsigned char > | regina::NTritmaskLen8
| A convenience typedef that gives a small and extremely fast tritmask class capable of holding at least 8 true-or-false bits. More...
typedef NTritmask1< unsigned int > | regina::NTritmaskLen16
| 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::NTritmaskLen32
| 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::NTritmaskLen64
| A convenience typedef that gives a small and extremely fast tritmask class capable of holding at least 64 true-or-false bits. More...

## Functions

REGINA_API size_t | regina::base64Length (size_t bytes)
| Returns the number of base64 characters required to encode the given number of bytes. More...
REGINA_API bool | regina::isBase64 (char ch)
| Determines whether the given character is a base64 printable character as used by the base64 routines in Regina. More...
REGINA_API 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...
REGINA_API 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...
REGINA_API 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...
REGINA_API 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...
template<class T >
reference_wrapper< T > const | regina::boost::ref (T &t)
| Returns a wrapper for the given reference. More...
template<class T >
reference_wrapper< T const > const | regina::boost::cref (T const &t)
| Returns a wrapper for the given const reference. More...
template<class T >
T | regina::boost::prior (T it)
| Returns the iterator prior to the given iterator. More...
template<class T >
T | regina::boost::next (T it)
| Returns the iterator following the given iterator. More...
static const char * | regina::i18n::Locale::codeset ()
| Returns the character encoding used in the current locale. More...
| regina::i18n::IConvStreamBuffer::IConvStreamBuffer ()
| Creates a new stream buffer. More...
| regina::i18n::IConvStreamBuffer::~IConvStreamBuffer ()
| Destroys this stream buffer. More...
IConvStreamBuffer * | regina::i18n::IConvStreamBuffer::open (std::ostream &dest, const char *srcCode, const char *destCode)
| Opens a new stream buffer that wraps around the given output stream. More...
IConvStreamBuffer * | regina::i18n::IConvStreamBuffer::close () throw ()
| Closes this stream buffer. More...
int_type | regina::i18n::IConvStreamBuffer::overflow (int_type c)
| Sends buffered data to the destination output stream, converting between character sets en route. More...
int_type | regina::i18n::IConvStreamBuffer::underflow ()
| Simply returns EOF (since this is not an input stream). More...
int | regina::i18n::IConvStreamBuffer::sync ()
| Flushes all output buffers. More...
| regina::i18n::IConvStream::IConvStream (std::ostream &dest, const char *srcCode, const char *destCode)
| Creates a new IConvStream; see the class notes for details. More...
REGINA_API std::ostream & | regina::operator<< (std::ostream &out, const NBitmask &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 NBitmask1< 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 NBitmask2< T, U > &mask)
| Writes the given bitmask to the given output stream as a sequence of zeroes and ones. More...
REGINA_API std::ostream & | regina::operator<< (std::ostream &out, const NTriBool &set)
| Writes the given three-way boolean to the given output stream. More...
REGINA_API std::ostream & | regina::operator<< (std::ostream &out, const NBoolSet &set)
| Writes the given boolean set to the given output stream. More...
template<typename T >
std::ostream & | regina::operator<< (std::ostream &out, const NQitmask1< 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 NQitmask2< 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 NTritmask1< 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 NTritmask2< T, U > &mask)
| Writes the given tritmask to the given output stream as a sequence of digits (0, 1 and/or 2). 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::auto_ptr< T > &cloneMe)
| A simple routine for cloning an object if and only if it exists. More...
template<class Operation1 , class Operation2 >
unary_compose< Operation1, Operation2 > | regina::stl::compose1 (const Operation1 &func1, const Operation2 &func2)
| Returns an adaptable unary function that is the composition of the two given functions. More...
REGINA_API char * | regina::duplicate (const std::string &str)
| Creates a new C string that is a duplicate of the given C++ string. More...
REGINA_API bool | regina::startsWith (const std::string &str, const std::string &prefix)
| Determines whether the given C++ string begins with the given prefix. More...
REGINA_API std::string | regina::stripWhitespace (const std::string &str)
| Strips all whitespace from the beginning and end of the given C++ string. More...
REGINA_API 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...
REGINA_API 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...
REGINA_API 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...
REGINA_API 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...
template<bool supportInfinity>
REGINA_API bool | regina::valueOf (const std::string &str, NIntegerBase< supportInfinity > &dest)
| Converts the entire given string to an arbitrary precision integer and reports whether this conversion was successful. More...
REGINA_API 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...
REGINA_API 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...
REGINA_API bool | regina::valueOf (const std::string &str, NTriBool &dest)
| Converts the entire given string to a three-way boolean (true, false or unknown) and reports whether this conversion was successful. More...
REGINA_API bool | regina::valueOf (const std::string &str, NBoolSet &dest)
| Converts the entire given string to a set of booleans and reports whether this conversion was successful. More...
template<class OutputIterator >
REGINA_API unsigned | regina::basicTokenise (OutputIterator results, const std::string &str)
| Decomposes the given string into tokens. More...
REGINA_API std::string | regina::stringToToken (const char *str)
| Returns a token derived from the given string. More...
REGINA_API std::string | regina::stringToToken (const std::string &str)
| Returns a token derived from the given string. More...
REGINA_API std::string | regina::xml::xmlEncodeSpecialChars (const std::string &original)
| Returns the given string with special characters converted to XML entities. More...
REGINA_API 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

## Typedef Documentation

typedef NBitmask1<unsigned int> regina::NBitmaskLen16

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

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

Python:
  Not present.

typedef InternalBitmaskLen32 ::Type regina::NBitmaskLen32

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

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

Python:
  Not present.

typedef InternalBitmaskLen64 ::Type regina::NBitmaskLen64

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 NBitmask1 or the template class NBitmask2.

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

Python:
  Not present.

typedef NBitmask1<unsigned char> regina::NBitmaskLen8

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

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

Python:
  Not present.

typedef NQitmask1<unsigned int> regina::NQitmaskLen16

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

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

Python:
  Not present.

typedef InternalQitmaskLen32 ::Type regina::NQitmaskLen32

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

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

Python:
  Not present.

typedef InternalQitmaskLen64 ::Type regina::NQitmaskLen64

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 NQitmask1 or the template class NQitmask2.

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

Python:
  Not present.

typedef NQitmask1<unsigned char> regina::NQitmaskLen8

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

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

Python:
  Not present.

typedef pthread_t regina::NThreadID

The type used for a thread identifier.

typedef NTritmask1<unsigned int> regina::NTritmaskLen16

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

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

Python:
  Not present.

typedef InternalTritmaskLen32 ::Type regina::NTritmaskLen32

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

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

Python:
  Not present.

typedef InternalTritmaskLen64 ::Type regina::NTritmaskLen64

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 NTritmask1 or the template class NTritmask2.

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

Python:
  Not present.

typedef NTritmask1<unsigned char> regina::NTritmaskLen8

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

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

Python:
  Not present.

## Function Documentation

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

Test:
  Included in the test suite.

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.

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

Test:
  Included in the test suite.

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.

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

Test:
  Included in the test suite.

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.

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

Test:
  Included in the test suite.

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.

REGINA_API 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

  bytes | the number of raw input bytes.

Returns
  the corresponding number of base64 printable output characters.

template<class OutputIterator >

REGINA_API 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

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

Returns
  the number of tokens found.

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

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

template<typename T >

T* regina::clonePtr | ( | const std::auto_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::auto_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

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

IConvStreamBuffer* regina::i18n::IConvStreamBuffer::close | ( |  | ) |
throw | ( |
| ) |  |

Closes this stream buffer.

Returns
  this stream buffer on success, or 0 on error.

static const char* regina::i18n::Locale::codeset | ( |  | ) |

static

Returns the character encoding used in the current locale.

This is a plain string, such as "UTF-8" or "ISO-8859-1".

Returns
  the character encoding for the current locale.

template<class Operation1 , class Operation2 >

unary_compose<Operation1, Operation2> regina::stl::compose1 | ( | const Operation1 & | func1,
|  | const Operation2 & | func2
| ) |  |

inline

Returns an adaptable unary function that is the composition of the two given functions.

This class is for use with the Standard Template Library.

The composition of functions `func1` and `func2` is the function `comp` for which `comp(x) == func1(func2(x))`.

Precondition
  Both arguments are themselves adaptable unary functions.
  Type `Operation1::argument_type` is the same as (or can be constructed from) type `Operation2::result_type`.

Python:
  Not present.

Parameters

  func1 | the first function to use in the composition.
  func2 | the second function to use in the composition.

Returns
  the composition of the two given functions.

Author
  This routine was taken and modified from the Standard Template Library (`http://www.stlport.org/`).

template<class T >

reference_wrapper<T const> const regina::boost::cref | ( | T const & | t | ) |

inline

Returns a wrapper for the given const reference.

See reference_wrapper for further details.

Python:
  Not present.

Parameters

  t | the reference to wrap.

Returns
  the corresponding wrapper.

Author
  This routine was taken and modified from the Boost C++ libraries (`http://www.boost.org/`).

REGINA_API 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

  str | the C++ string to duplicate.

Returns
  the new duplicate C string.

regina::i18n::IConvStream::IConvStream | ( | std::ostream & | dest,
|  | const char * | srcCode,
|  | const char * | destCode
| ) |  |

inline

Creates a new IConvStream; see the class notes for details.

If the given encodings are invalid, this stream will still forward data to the given output stream but no conversion will take place.

See the iconv documentation for information on what encodings are supported. For the GNU C library implementation, valid encodings can be found by running `iconv –list`.

Precondition
  The destination output stream is already open.

Parameters

  dest | the destination output stream.
  srcCode | the character encoding for data that is to be written into this IConvStream.
  destCode | the character encoding for the translated data that will subsequently be written to the destination output stream.

regina::i18n::IConvStreamBuffer::IConvStreamBuffer | ( |  | ) |

inline

Creates a new stream buffer.

REGINA_API 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

  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.

template<class T >

T regina::boost::next | ( | T | it | ) |

inline

Returns the iterator following the given iterator.

This function avoids having to explicitly create a temporary to increment.

Only the increment operator `++it` needs to be defined.

Python:
  Not present.

Parameters

  it | the iterator to examine.

Returns
  the iterator following the given iterator.

Author
  This routine was taken and modified from the Boost C++ libraries (`http://www.boost.org/`).

IConvStreamBuffer* regina::i18n::IConvStreamBuffer::open | ( | std::ostream & | dest,
|  | const char * | srcCode,
|  | const char * | destCode
| ) |  |

Opens a new stream buffer that wraps around the given output stream.

If this stream buffer is already open, it will be closed and then reopened with the given parameters.

Any data that is sent to this stream buffer will be translated from srcCode to destCode and passed on to the given output stream.

If the given encodings are invalid, this stream will still forward data to the given output stream but no conversion will take place.

See the iconv documentation for information on what encodings are supported. For the GNU C library implementation, valid encodings can be found by running `iconv –list`.

Precondition
  The destination output stream is already open.

Parameters

  dest | the destination output stream.
  srcCode | the character encoding for data that is to be written into this stream buffer.
  destCode | the character encoding for the translated data that will subsequently be written to the destination output stream.

Returns
  this stream buffer on success, or 0 on error.

template<typename T >

std::ostream& regina::operator<< | ( | std::ostream & | out,
|  | const NQitmask1< 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

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

Returns
  a reference to the given output stream.

template<typename T >

std::ostream& regina::operator<< | ( | std::ostream & | out,
|  | const NTritmask1< 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

  out | the output stream to which to write.
  mask | the tritmask to write.

Returns
  a reference to the given output stream.

REGINA_API std::ostream& regina::operator<< | ( | std::ostream & | out,
|  | const NTriBool & | set
| ) |  |

Writes the given three-way boolean to the given output stream.

The value will be written in the form `true`, `false` or `unknown`.

Parameters

  out | the output stream to which to write.
  set | the three-way boolean to write.

Returns
  a reference to out.

std::ostream & regina::operator<< | ( | std::ostream & | out,
|  | const NBitmask & | 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

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

Returns
  a reference to the given output stream.

template<typename T , typename U >

std::ostream& regina::operator<< | ( | std::ostream & | out,
|  | const NQitmask2< 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

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

Returns
  a reference to the given output stream.

template<typename T , typename U >

std::ostream& regina::operator<< | ( | std::ostream & | out,
|  | const NTritmask2< 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

  out | the output stream to which to write.
  mask | the tritmask to write.

Returns
  a reference to the given output stream.

REGINA_API std::ostream& regina::operator<< | ( | std::ostream & | out,
|  | const NBoolSet & | 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.

template<typename T >

std::ostream& regina::operator<< | ( | std::ostream & | out,
|  | const NBitmask1< 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

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

Returns
  a reference to the given output stream.

template<typename T , typename U >

std::ostream& regina::operator<< | ( | std::ostream & | out,
|  | const NBitmask2< 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

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

Returns
  a reference to the given output stream.

int_type regina::i18n::IConvStreamBuffer::overflow | ( | int_type | c | ) |

Sends buffered data to the destination output stream, converting between character sets en route.

The buffer will be flushed as far as possible, and any invalid characters will be replaced with one or more question marks. If the buffer ends in an incomplete multibyte character, this incomplete character will be held back (since it presumably needs to be combined with later input).

Parameters

  c | an extra character to send that did not fit in the internal buffer, or EOF if we simply wish to flush the buffer.

Returns
  0 on success, or EOF on error.

template<class T >

T regina::boost::prior | ( | T | it | ) |

inline

Returns the iterator prior to the given iterator.

This function avoids having to explicitly create a temporary to decrement.

Only the decrement operator `–it` needs to be defined.

Python:
  Not present.

Parameters

  it | the iterator to examine.

Returns
  the iterator prior to the given iterator.

Author
  This routine was taken and modified from the Boost C++ libraries (`http://www.boost.org/`).

template<class T >

reference_wrapper<T> const regina::boost::ref | ( | T & | t | ) |

inline

Returns a wrapper for the given reference.

See reference_wrapper for further details.

Python:
  Not present.

Parameters

  t | the reference to wrap.

Returns
  the corresponding wrapper.

Author
  This routine was taken and modified from the Boost C++ libraries (`http://www.boost.org/`).

REGINA_API 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

  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.

REGINA_API 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

  str | the string on which to base the token.

Returns
  the corresponding token.

REGINA_API 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

  str | the string on which to base the token.

Returns
  the corresponding token.

REGINA_API 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

  str | the string to be stripped.

Returns
  the resulting stripped string.

int regina::i18n::IConvStreamBuffer::sync | ( |  | ) |

Flushes all output buffers.

The buffers for both this stream and the destination output stream will be flushed.

Returns
  0 on success, or -1 on error.

IConvStreamBuffer::int_type regina::i18n::IConvStreamBuffer::underflow | ( |  | ) |

inline

Simply returns EOF (since this is not an input stream).

Returns
  EOF.

REGINA_API 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

  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.

REGINA_API 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

  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.

REGINA_API 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

  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.

REGINA_API 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

  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.

template<bool supportInfinity>

REGINA_API bool regina::valueOf | ( | const std::string & | str,
|  | NIntegerBase< 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

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

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

REGINA_API 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

  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.

REGINA_API 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` or `F` (either upper- or lower-case), the string will be successfully converted to `true` or `false` respectively. Otherwise the conversion will be unsuccessful and argument dest will be set to `false`.

Python:
  Not present.

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.

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

Converts the entire given string to a three-way boolean (true, false or unknown) and reports whether this conversion was successful.

If the given string begins with `T`, `F` or `U` (either upper- or lower-case), the string will be successfully converted to true, false or unknown respectively. If the string is one of `1`, `-1` or `0`, the string will likewise be converted to true, false or unknown respectively. Otherwise the conversion will be unsuccessful and argument dest will be set to unknown.

Python:
  Not present.

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.

REGINA_API bool regina::valueOf | ( | const std::string & | str,
|  | NBoolSet & | 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 NBoolSet::sNone and `false` will be returned.

Python:
  Not present.

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.

REGINA_API 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

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

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

REGINA_API 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

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

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

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.

regina::i18n::IConvStreamBuffer::~IConvStreamBuffer | ( |  | ) |

inline

Destroys this stream buffer.

This stream buffer will be closed, but the destination output stream will not be.

Copyright © 1999-2013, 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@debian.org).