Public API#

Last Updated on 2023-04-20

The header <textwrap/textwrap.h>` declares the classes asap::wrap::TextWrapper and asap::wrap::TextWrapperBuilder which form the core of the text wrapper module public API.

TextWrapper#

class TextWrapper#

The core class for the text wrapper module.

TextWrapper offers a simple interface to wrap text to a specific width while supporting multiple configuration options for how white space is handled and when exactly line/word breaking happen.

Construction of instances of TextWrapper can only be done via its associated TextWrapperBuilder, which maintains coherent configuration values and offers an easy to use fluent interface to set them.

Example

  const auto *passage =
      "  Pride and Prejudice:\n    It is a truth universally   "
      "acknowledged, that a single man in possession of a "
      "good fortune, must be in want "
      "of a wife.   ";

  constexpr size_t column_width = 28;
  const TextWrapper wrapper = asap::wrap::MakeWrapper()
                                  .Width(column_width)
                                  .TrimLines()
                                  .CollapseWhiteSpace()
                                  .IndentWith()
                                  .Initially("")
                                  .Then("...");

  std::cout << "|" << wrapper.Fill(passage).value_or("error") << "|"
            << std::endl;

  // Pride and Prejudice:
  //    It is a truth universally
  //    acknowledged, that a single
  //    man in possession of a good
  //    fortune, must be in want of
  //    a wife.

See also

TextWrapperBuilder for a detailed description of the different configuration options.

Public Functions

ASAP_TEXTWRAP_API auto Wrap(const std::string &str) const -> std::optional<std::vector<std::string>>#

Wraps text so every line is at most the TextWrapper’s width characters long.

The wrapping algorithm is an improved algorithm that favors balanced lines vs. greedy filling of lines. A cost is associated with each line, using the extra spaces at the end of the line not filed with words. The goal of the algorithm is to minimize the overall cost.

Parameters:

str – a single or multi-paragraph string, where each paragraph is separated from the next one by one or more empty lines.

Returns:

a list of output lines, without final newlines. Paragraphs are separated by a single empty line.

ASAP_TEXTWRAP_API auto Fill(const std::string &str) const -> std::optional<std::string>#

Wraps text so every line is at most the TextWrapper’s width characters long and returns a single string containing the result.

Fill() is effectively equivalent to joining the result of Wrap() using \n;

Parameters:

str – a single or multi-paragraph string, where each paragraph is separated from the next one by one or more empty lines.

Returns:

a single string containing the result.

Friends

friend ASAP_TEXTWRAP_API auto operator<<(std::ostream &out, const TextWrapper &wrapper) -> std::ostream&#

Overloaded output stream operator for pretty printing TextWrapper configuration parameters. values.

Parameters:

  • out – output stream to which formatted data will be inserted.

  • wrapper – the TExtWrapper to write to the stream.

Returns:

out

TextWrapperBuilder#

class TextWrapperBuilder#

A fluent interface builder for TextWrapper.

This builder simplifies the creation and configuration of TextWrapper instances through a fluent API.

Example

  const auto *passage =
      "  Pride and Prejudice:\n    It is a truth universally   "
      "acknowledged, that a single man in possession of a "
      "good fortune, must be in want "
      "of a wife.   ";

  constexpr size_t column_width = 28;
  const TextWrapper wrapper = asap::wrap::MakeWrapper()
                                  .Width(column_width)
                                  .TrimLines()
                                  .CollapseWhiteSpace()
                                  .IndentWith()
                                  .Initially("")
                                  .Then("...");

  std::cout << "|" << wrapper.Fill(passage).value_or("error") << "|"
            << std::endl;

  // Pride and Prejudice:
  //    It is a truth universally
  //    acknowledged, that a single
  //    man in possession of a good
  //    fortune, must be in want of
  //    a wife.

Public Functions

inline operator TextWrapper() const#

converts a TextWrapperBuilder instance to a TextWrapper instance at the end of the building.

Returns:

an instance of TExtWrapper.

ASAP_TEXTWRAP_API auto Width(size_t width) -> TextWrapperBuilder&#

The maximum length of wrapped lines.

(default: 80) As long as there are no individual words in the input text longer than width, TextWrapper guarantees that no output line will be longer than width characters.

ASAP_TEXTWRAP_API auto IndentWith() -> TextWrapperBuilder&#

Setup indentation prefixes.

Starts the fluent API for setting the optional indentation prefixes for the first line and the subsequent lines.

See also

Initially

See also

Then

ASAP_TEXTWRAP_API auto Initially(std::string initial_indent) -> TextWrapperBuilder&#

String that will be prepended to the first line of wrapped output.

(default: ‘’) Counts towards the length of the first line. The empty string is not indented.

See also

IndentWith

See also

Then

ASAP_TEXTWRAP_API auto Then(std::string indent) -> TextWrapperBuilder&#

String that will be prepended to all lines of wrapped output except the first.

(default: ‘’) Counts towards the length of the first line. The empty string is not indented.

See also

IndentWith

See also

Initially

ASAP_TEXTWRAP_API auto ExpandTabs(std::string tab) -> TextWrapperBuilder&#

All tab characters in text are expanded using the tab string.

(default: “\t”) This is the first transformation that happens before replacing / collapsing white spaces and before wrapping.

ASAP_TEXTWRAP_API auto CollapseWhiteSpace() -> TextWrapperBuilder&#

Replace contiguous series of white spaces with a single space.

(default: false)

Note

White space collapsing is done after tab expansion, therefore unless tab expansion is done with non white space characters, it is superseded.

ASAP_TEXTWRAP_API auto TrimLines() -> TextWrapperBuilder&#

Whitespace at the beginning and ending of every line (after wrapping but before indenting) is dropped.

(default: false)

ASAP_TEXTWRAP_API auto BreakOnHyphens() -> TextWrapperBuilder&#

Compound words will be broken into separate chunks right after hyphens, as it is customary in English.

(default: false)