Gromacs
2024.4
|
#include <gromacs/onlinehelp/helpformat.h>
Formats rows of a table for text output.
This utility class formats tabular data, mainly for console output. Each row in the table can take multiple lines, and automatic text wrapping is supported. If text overflows the allocated width, the remaining columns on that line become shifted. To avoid this, it is possible to start the output for different columns from different lines (it is the caller's responsibility to check that overflows are avoided or are acceptable).
Column definitions are first set with addColumn(). To format a row, first call clear(). Then call addColumnLine() to add text to each column (can be called multiple times on a single column to add multiple lines), and possibly setColumnFirstLineOffset() to adjust the line from which the column output should start. Finally, call formatRow() to obtain the formatted row.
A header (column titles and a horizontal line) is printed before the first line.
Typical usage:
Methods in this class may throw std::bad_alloc if out of memory. Other exceptions are not thrown.
Classes | |
class | Impl |
Private implementation class for TextTableFormatter. More... | |
Public Member Functions | |
TextTableFormatter () | |
Constructs an empty formatter. | |
void | addColumn (const char *title, int width, bool bWrap) |
Adds a column to the table. More... | |
void | setFirstColumnIndent (int indent) |
Sets amount on indentation before the first column. More... | |
void | setFoldLastColumnToNextLine (int indent) |
Enables folding the last column to separate lines if it overflows. More... | |
bool | didOutput () const |
Whether formatRow() has been successfully called. More... | |
void | clear () |
Removes all text from all columns and resets the line offsets. More... | |
void | addColumnLine (int index, const std::string &text) |
Adds text to be printed in a column. More... | |
void | addColumnHelpTextBlock (int index, const HelpWriterContext &context, const std::string &text) |
Adds text containing help markup to be printed in a column. More... | |
void | setColumnFirstLineOffset (int index, int firstLine) |
Sets the first line to which text is printed for a column. More... | |
std::string | formatRow () |
Formats the lines for the current row. More... | |
void gmx::TextTableFormatter::addColumn | ( | const char * | title, |
int | width, | ||
bool | bWrap | ||
) |
Adds a column to the table.
[in] | title | Title string for the column (used for header). |
[in] | width | Width of the column (must be > 0). |
[in] | bWrap | Whether text that exceeds width is automatically wrapped. |
The length of title
must not exceed width
.
void gmx::TextTableFormatter::addColumnHelpTextBlock | ( | int | index, |
const HelpWriterContext & | context, | ||
const std::string & | text | ||
) |
Adds text containing help markup to be printed in a column.
[in] | index | Zero-based column index. |
[in] | context | Context to use for markup processing. |
[in] | text | Text to add. |
Works as addColumnLine(), except that it uses HelpWriterContext::substituteMarkupAndWrapToVector() to process markup in the input text instead of just wrapping it as plain text.
void gmx::TextTableFormatter::addColumnLine | ( | int | index, |
const std::string & | text | ||
) |
Adds text to be printed in a column.
[in] | index | Zero-based column index. |
[in] | text | Text to add. |
Can be called multiple times. Additional calls append text
as additional lines. Any calls with text
empty have no effect. To add an empty line, use "\n" as text
.
If text
contains newlines, the text is automatically splitted to multiple lines. The same happens if automatic wrapping is on for the column and the text contains lines that are longer than what fits the column.
void gmx::TextTableFormatter::clear | ( | ) |
Removes all text from all columns and resets the line offsets.
Removes all text added using addColumnLine() and resets line offsets set with setColumnFirstLineOffset() to zero. Should be called before starting to add data for a row.
Does not throw.
bool gmx::TextTableFormatter::didOutput | ( | ) | const |
Whether formatRow() has been successfully called.
This method can be used to determine after-the-fact whether anything was written in the table.
Does not throw.
std::string gmx::TextTableFormatter::formatRow | ( | ) |
Formats the lines for the current row.
Formats the data as set after the previous clear()/formatRow() using addColumnLine() and setColumnFirstLineOffset().
If this is the first line to be formatted, a header is also added to the beginning of the returned string if any column has a title.
The return value always terminates with a newline.
Calls clear() on successful return.
void gmx::TextTableFormatter::setColumnFirstLineOffset | ( | int | index, |
int | firstLine | ||
) |
Sets the first line to which text is printed for a column.
[in] | index | Zero-based column index. |
[in] | firstLine | Zero-based line index from which to start the output. |
Can be called if there is no text for column index
. Does not affect the output in this case.
Does not throw.
void gmx::TextTableFormatter::setFirstColumnIndent | ( | int | indent | ) |
Sets amount on indentation before the first column.
[in] | indent | Number of spaces to use for indenting. |
Does not throw.
void gmx::TextTableFormatter::setFoldLastColumnToNextLine | ( | int | indent | ) |
Enables folding the last column to separate lines if it overflows.
[in] | indent | Number of spaces to use for indenting the lines. |
If called with indent >= 0
, the last column for each row is treated specially: if it contains more lines than the other columns, and if the text would fit more compactly as separate lines after the row, then the whole last column is written after the row with the given indent
. The column text then spans the whole space reserved for the table, making long text fit into a smaller amount of vertical space. If not called, the last column is not treates specially.
Does not throw.