Gromacs  2024.4
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
List of all members | Classes | Public Member Functions
gmx::TextTableFormatter Class Reference

#include <gromacs/onlinehelp/helpformat.h>

Description

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:

formatter.addColumn("Name", 10, false);
formatter.addColumn("Type", 10, false);
formatter.addColumn("Description", 50, true);
formatter.clear();
formatter.addColumnLine(0, "name");
formatter.addColumnLine(1, "type");
formatter.addColumnLine(2, "Description for name");
printf("%s", formatter.formatRow().c_str());
formatter.clear();
formatter.addColumnLine(0, "averylongname");
formatter.addColumnLine(1, "type");
formatter.setColumnFirstLineOffset(1, 1);
formatter.addColumnLine(2, "Description for name");
printf("%s", formatter.formatRow().c_str());
// format other rows by repeating the above code
*

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

Member Function Documentation

void gmx::TextTableFormatter::addColumn ( const char *  title,
int  width,
bool  bWrap 
)

Adds a column to the table.

Parameters
[in]titleTitle string for the column (used for header).
[in]widthWidth of the column (must be > 0).
[in]bWrapWhether 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.

Parameters
[in]indexZero-based column index.
[in]contextContext to use for markup processing.
[in]textText 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.

Parameters
[in]indexZero-based column index.
[in]textText 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.

Returns
Current row formatted as a single string (contains newlines).

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.

Parameters
[in]indexZero-based column index.
[in]firstLineZero-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.

Parameters
[in]indentNumber 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.

Parameters
[in]indentNumber 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.


The documentation for this class was generated from the following files: