regina::Output< T, supportsUtf8 > Struct Template Reference
Engine Structure

A common base class for objects that write human-readable text output. More...

`#include <output.h>`

Inheritance diagram for regina::Output< T, supportsUtf8 >:

## Public Member Functions

std::string | str () const
| Returns a short text representation of this object. More...
std::string | utf8 () const
| Returns a short text representation of this object using unicode characters. More...
std::string | detail () const
| Returns a detailed text representation of this object. More...

## Detailed Description

### template<class T, bool supportsUtf8 = false>
struct regina::Output< T, supportsUtf8 >

A common base class for objects that write human-readable text output.

This class ensures that text output routines have consistent names and behaviours across Regina's entire API.

Three types of output are supported:

- short output, which fits on a single line and uses plain ASCII characters wherever possible;
- utf8 output, which is like short output but supports the much richer unicode character set; and
- detailed output, which may be arbitrarily long.

Any class that provides text output should ultimately inherit from this base class. Your derived class must provide two functions:

- `writeTextShort(std::ostream& out, bool utf8 = false)`, which writes either the short output or the utf8 output to the given output stream, according to whether utf8 is `false` or `true` respectively;
- `writeTextLong(std::ostream& out)`, which writes the detailed output to the given output stream.

The boolean utf8 argument to writeTextShort() must be optional. Moreover, if your class does not benefit from unicode characters (i.e., the short and utf8 outputs are identical), then you may omit the utf8 argument entirely; in this case, you must set the template argument supportsUtf8 as `false`. Both writeTextShort() and writeTextLong() may take additional arguments, as long as they are optional.

The documentation for str(), utf8() and detail() gives guidelines as to how the various types of output should be formatted.

In return, this class will provide the functions str(), utf8() and detail(), which return the short, utf8 and detailed outputs respectively in std::string format. It will also provide a global operator << that allows you to write objects of type T to an arbitrary output stream.

If your class is simple and has no need for detailed output then it may derive from ShortOutput instead, which provides a default implementation for writeTextLong().

Template Parameters

  T | the class that provides the implementations of writeTextShort() and writeTextLong(). Typically this will be your own class (i.e., your class C derives from Output<C>). However, this may be deeper in the class hierarchy.

  supportsUtf8

  `true` if the class T can make use of the richer unicode character set, or `false` if the short and utf8 outputs are identical. If this is `false` then T::writeTextShort() will only ever be called in the form `writeTextShort(std::ostream&)`, and you may for simplicity omit the second boolean utf8 argument. This Output base class will still provide a utf8() function, but it will return the same output as short().

Note
  Every object of this class that is ever instantiated must be derived from the class T. In other words, end users can construct objects of type T (which derives from Output<T>), but they cannot construct objects of the parent class Output<T> itself.

Python:
  Not present, but the output routines str(), utf8() and detail() will be provided directly through the various subclasses.

## Member Function Documentation

## detail()

template<class T, bool supportsUtf8 = false>

std::string regina::Output< T, supportsUtf8 >::detail | ( |  | ) | const

Returns a detailed text representation of this object.

This text may span many lines, and should provide the user with all the information they could want. It should be human-readable, should not contain extremely long lines (which cause problems for users reading the output in a terminal), and should end with a final newline. There are no restrictions on the underlying character set.

Returns
  a detailed text representation of this object.

## str()

template<class T, bool supportsUtf8 = false>

std::string regina::Output< T, supportsUtf8 >::str | ( |  | ) | const

Returns a short text representation of this object.

This text should be human-readable, should fit on a single line, and should not end with a newline. Where possible, it should use plain ASCII characters.

Python:
  In addition to str(), this is also used as the Python "stringification" function `__str__()`.

Returns
  a short text representation of this object.

## utf8()

template<class T, bool supportsUtf8 = false>

std::string regina::Output< T, supportsUtf8 >::utf8 | ( |  | ) | const

Returns a short text representation of this object using unicode characters.

Like str(), this text should be human-readable, should fit on a single line, and should not end with a newline. In addition, it may use unicode characters to make the output more pleasant to read. This string will be encoded in UTF-8.

Returns
  a short text representation of this object.

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

- output.h

Copyright © 1999-2016, 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).