regina::TightEncodable< T > Struct Template Reference

A base class that assists with support for tight encodings and corresponding decodings. More...

#include <utilities/tightencoding.h>

Public Member Functions
std::string	tightEncoding () const
	Returns the tight encoding of this object. More...

Static Public Member Functions
static T	tightDecoding (const std::string &enc)
	Reconstructs an object of type T from its given tight encoding. More...

Detailed Description

template<class T>
struct regina::TightEncodable< T >

A base class that assists with support for tight encodings and corresponding decodings.

If a class T supports tight encodings, then it may derive from TightEncodable<T>. If it does, then your derived class must provide the following two functions, which implement tight encodings and decodings via input/output streams:

• void tightEncode(std::ostream&) const, which writes a tight encoding of the object to the given output stream. This is allowed to (but not required to) throw a FailedPrecondition if the object is in an invalid state; if so then the exception should be documented in this member function T::tightEncode().
• static T tightDecode(std::istream&), which reconstructs an object of type T from a tight encoding that is read from the given input stream. This routine must not skip leading whitespace, and must leave the input stream positioned immediately after the encoding (without consuming any trailing whitespace or other characters). This should throw an InvalidInput exception if the input stream does not begin with a valid tight encoding of an object of type T.

In return, this base class will provide the following two functions, both of which work with strings (and which are documented in full below):

• std::string tightEncoding() const; and
• static T tightDecoding(const std::string&).

A class T that supports tight encodings does not need to derive from TightEncodable. However, if it does not then it should implement all four of the above functions itself. Examples of this include the permutation classes (which have optimised implementations due to their very small space requirements), and the arbitrary-precision integer classes (which use the global integer encoding/decoding routines).

Template Parameters

T	the type of object being encoded/decoded; this must derive from TightEncodable<T>.

Note

Every object of this class that is ever instantiated must be derived from the class T. In other words, end users cannot construct objects of the parent class TightEncodable<T>.

Python

Not present, but the routines tightEncoding() and tightDecoding() will be provided directly through the various subclasses.

Member Function Documentation

tightDecoding()

template<class T >

static T regina::TightEncodable< T >::tightDecoding ( const std::string &  enc )

inlinestatic

Reconstructs an object of type T from its given tight encoding.

See the page on tight encodings for details.

The tight encoding should be given as a string. If this string contains leading whitespace or any trailing characters at all (including trailing whitespace), then it will be treated as an invalid encoding (i.e., this routine will throw an exception).

Exceptions

InvalidArgument

The given string is not a tight encoding of an object of type T.

Parameters

enc	the tight encoding for an object of type T.

Returns

the object represented by the given tight encoding.

tightEncoding()

template<class T >

std::string regina::TightEncodable< T >::tightEncoding ( ) const

inline

Returns the tight encoding of this object.

See the page on tight encodings for details.

Exceptions

FailedPrecondition

This may be thrown for some classes T if the object is in an invalid state. If this is possible, then a more detailed explanation of "invalid" can be found in the class documentation for T, under the member function T::tightEncode(). See FacetPairing::tightEncode() for an example of this.

Returns

the resulting encoded string.

---

The documentation for this struct was generated from the following file:

• utilities/tightencoding.h