#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:

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

gmx::TextLineWrapper wrapper;
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...

TextLineWrapperSettings &	settings ()
	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] settings Wrapping 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]	input	String to wrap.
[in]	lineStart	Index 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:

gmx::TextLineWrapper wrapper;
// <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]	input	String to wrap.
[in]	lineStart	Index 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:

gmx::TextLineWrapper wrapper;
// <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]	input	Input string.
[in]	lineStart	Index of first character of the line to format.
[in]	lineEnd	Index of first character of the next line.

Returns: The line with leading and/or trailing whitespace removed and indentation applied.

Exceptions

std::bad_alloc if 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] input String to wrap.

Returns: input with added newlines such that maximum line length is not exceeded.

Exceptions

std::bad_alloc if 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] input String to wrap.

Returns: input split into lines such that maximum line length is not exceeded.

Exceptions

std::bad_alloc if 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:

src/gromacs/utility/stringutil.h
src/gromacs/utility/stringutil.cpp

Description

Public Member Functions

Constructor & Destructor Documentation

Member Function Documentation