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

#include <gromacs/utility/stringutil.h>

Description

Wraps lines to a predefined length.

This utility class wraps lines at word breaks to produce lines that are not longer than a predefined length. Explicit newlines ('\n') are preserved. Only space is considered a word separator. If a single word exceeds the maximum line length, it is still printed on a single line. Extra whitespace is stripped from the end of produced lines. Other options on the wrapping, such as the line length or indentation, can be changed using a TextLineWrapperSettings object.

Two interfaces to do the wrapping are provided:

  1. High-level interface using either wrapToString() (produces a single string with embedded newlines) or wrapToVector() (produces a vector of strings with each line as one element). These methods operate on std::string and wrap the entire input string.
  2. Low-level interface using findNextLine() and formatLine(). findNextLine() operates either on a C string or an std::string, and does not do any memory allocation (so it does not throw). It finds the next line to be wrapped, considering the wrapping settings. formatLine() does whitespace operations on the line found by findNextLine() and returns an std::string. These methods allow custom wrapping implementation to either avoid exceptions or to wrap only a part of the input string.

Typical usage:

wrapper.settings().setLineLength(78);
printf("%s\n", wrapper.wrapToString(textToWrap).c_str());

Public Member Functions

 TextLineWrapper ()
 Constructs a new line wrapper with default settings. More...
 
 TextLineWrapper (const TextLineWrapperSettings &settings)
 Constructs a new line wrapper with given settings. More...
 
TextLineWrapperSettingssettings ()
 Provides access to settings of this wrapper. More...
 
bool isTrivial () const
 Returns true if the wrapper would not modify the input string.
 
size_t findNextLine (const char *input, size_t lineStart) const
 Finds the next line to be wrapped. More...
 
size_t findNextLine (const std::string &input, size_t lineStart) const
 Finds the next line to be wrapped. More...
 
std::string formatLine (const std::string &input, size_t lineStart, size_t lineEnd) const
 Formats a single line for output according to wrapping settings. More...
 
std::string wrapToString (const std::string &input) const
 Formats a string, producing a single string with all the lines. More...
 
std::vector< std::string > wrapToVector (const std::string &input) const
 Formats a string, producing a vector with all the lines. More...
 

Constructor & Destructor Documentation

gmx::TextLineWrapper::TextLineWrapper ( )
inline

Constructs a new line wrapper with default settings.

Does not throw.

gmx::TextLineWrapper::TextLineWrapper ( const TextLineWrapperSettings settings)
inlineexplicit

Constructs a new line wrapper with given settings.

Parameters
[in]settingsWrapping settings.

Does not throw.

Member Function Documentation

size_t gmx::TextLineWrapper::findNextLine ( const char *  input,
size_t  lineStart 
) const

Finds the next line to be wrapped.

Parameters
[in]inputString to wrap.
[in]lineStartIndex of first character of the line to find.
Returns
Index of first character of the next line.

If this is the last line, returns the length of input. In determining the length of the returned line, this function considers the maximum line length, leaving space for indentation, and also whitespace stripping behavior. Thus, the line returned may be longer than the maximum line length if it has leading and/or trailing space. When wrapping a line on a space (not on an explicit line break), the returned index is always on a non-whitespace character after the space.

To iterate over lines in a string, use the following code:

// <set desired wrapping settings>
size_t lineStart = 0;
size_t length = input.length();
while (lineStart < length)
{
size_t nextLineStart = wrapper.findNextLine(input, lineStart);
std::string line = wrapper.formatLine(input, lineStart, nextLineStart));
// <do something with the line>
lineStart = nextLineStart;
}
return result;

Does not throw.

size_t gmx::TextLineWrapper::findNextLine ( const std::string &  input,
size_t  lineStart 
) const

Finds the next line to be wrapped.

Parameters
[in]inputString to wrap.
[in]lineStartIndex of first character of the line to find.
Returns
Index of first character of the next line.

If this is the last line, returns the length of input. In determining the length of the returned line, this function considers the maximum line length, leaving space for indentation, and also whitespace stripping behavior. Thus, the line returned may be longer than the maximum line length if it has leading and/or trailing space. When wrapping a line on a space (not on an explicit line break), the returned index is always on a non-whitespace character after the space.

To iterate over lines in a string, use the following code:

// <set desired wrapping settings>
size_t lineStart = 0;
size_t length = input.length();
while (lineStart < length)
{
size_t nextLineStart = wrapper.findNextLine(input, lineStart);
std::string line = wrapper.formatLine(input, lineStart, nextLineStart));
// <do something with the line>
lineStart = nextLineStart;
}
return result;

Does not throw.

std::string gmx::TextLineWrapper::formatLine ( const std::string &  input,
size_t  lineStart,
size_t  lineEnd 
) const

Formats a single line for output according to wrapping settings.

Parameters
[in]inputInput string.
[in]lineStartIndex of first character of the line to format.
[in]lineEndIndex of first character of the next line.
Returns
The line with leading and/or trailing whitespace removed and indentation applied.
Exceptions
std::bad_allocif out of memory.

Intended to be used on the lines found by findNextLine(). When used with the lines returned from findNextLine(), the returned line conforms to the wrapper settings. Trailing whitespace is always stripped (including any newlines, i.e., the return value does not contain a newline).

TextLineWrapperSettings& gmx::TextLineWrapper::settings ( )
inline

Provides access to settings of this wrapper.

Returns
The settings object for this wrapper.

The returned object can be used to modify settings for the wrapper. All subsequent calls to wrapToString() and wrapToVector() use the modified settings.

Does not throw.

std::string gmx::TextLineWrapper::wrapToString ( const std::string &  input) const

Formats a string, producing a single string with all the lines.

Parameters
[in]inputString to wrap.
Returns
input with added newlines such that maximum line length is not exceeded.
Exceptions
std::bad_allocif out of memory.

Newlines in the input are preserved, including terminal newlines. Note that if the input does not contain a terminal newline, the output does not either.

std::vector< std::string > gmx::TextLineWrapper::wrapToVector ( const std::string &  input) const

Formats a string, producing a vector with all the lines.

Parameters
[in]inputString to wrap.
Returns
input split into lines such that maximum line length is not exceeded.
Exceptions
std::bad_allocif out of memory.

The strings in the returned vector do not contain newlines at the end. Note that a single terminal newline does not affect the output: "line\\n" and "line" both produce the same output (but "line\\n\\n" produces two lines, the second of which is empty).


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