regina::TightEncodable< T > Struct Template Reference

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

#include <utilities/tightencoding.h>

Inheritance diagram for regina::TightEncodable< T >:

Public Member Functions
std::string	tightEncoding () const
	Returns the tight encoding of this object.
size_t	hash () const
	Hashes this object to a non-negative integer, allowing it to be used for keys in hash tables.

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

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 three functions, which work with simpler (non-stream) data types, and which are documented in full below:

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

A class T that supports tight encodings does not need to derive from TightEncodable. However, if it does not then it should implement all five 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 and a simple arithmetic hash).

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(), tightDecoding() and hash() will be provided directly through the various subclasses.

Member Function Documentation

hash()

template<class T>

size_t regina::TightEncodable< T >::hash ( ) const

inline

Hashes this object to a non-negative integer, allowing it to be used for keys in hash tables.

This hash function makes use of Regina's tight encodings. In particular, any two objects with the same tight encoding will have equal hashes. This implementation (and therefore the specific hash value for each object) is subject to change in future versions of Regina.

Python

For Python users, this function uses the standard Python name hash(). This allows objects of this type to be used as keys in Python dictionaries and sets.

Returns

The integer hash of this object.

tightDecoding()

template<class T>

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