Strings and Chars

The string classes describe terminal text before it is rendered. They let you represent a single display character with color and character attributes, build styled text fragments, measure Unicode-aware width, and split or wrap text without interacting with a buffer.

This page focuses on working with Char, CharStyle, and String as data types. For rendering text blocks into rectangles with Text, see Text Rendering.

Usage

Working with Char

Char represents a single terminal display cell together with its foreground color, background color, and optional character attributes such as bold or underline.

Constructing Characters

Use a Unicode code point when you construct a regular character. This is the most explicit form when you already know the exact character.

const auto checkMark = Char{U'✓'};
const auto whiteOnBlue = Char{U'a', fg::White, bg::Blue};

For combined characters, construct Char from UTF-8 or UTF-32 text:

const auto combinedFromUtf8 = Char{"e\xCC\x81"};
const auto combinedFromUtf32 = Char{U"e\u0301"};

To append a combining mark programmatically, use withCombining():

const auto acute = Char{U"e"}.withCombining(char32_t{0x0301});

displayWidth() follows terminal cell width, so wide and combining characters behave correctly during layout:

const auto wide = Char{U'界'};
const auto combined = Char{"e\xCC\x81"};

const auto wideCells = wide.displayWidth();          // 2
const auto combinedCells = combined.displayWidth();  // 1

Testing and Comparing Characters

To compare only the character value and ignore color, compare against a Unicode code point:

if (character == U'?') {
    // ...
}

Use isOneOf() for small sets of accepted characters:

if (character.isOneOf(U'Y', U'y', U'J', U'j')) {
    // ...
}

For screen-level comparisons, renderedEquals() is often more useful than operator== because it treats inherited colors like terminal defaults:

const auto inherited = Char{U'X', fg::Inherited, bg::Inherited};
const auto defaults = Char{U'X', fg::Default, bg::Default};

const auto sameOnScreen = inherited.renderedEquals(defaults);

Recoloring Characters

To adjust the colors of an existing Char, choose the method that matches your intent:

const auto base = Char{U'X', fg::Green, bg::Blue};

const auto overlay = base.withColorOverlay(Color{fg::BrightWhite, bg::Inherited});
const auto replaced = base.withColorReplaced(Color{fg::White, bg::Black});
const auto basedOnTheme = base.withBaseColor(Color{fg::Inherited, bg::BrightBlack});

With withColorOverlay(), any Inherited component keeps the existing color, while Default resets that component to the terminal default.

Working with Character Attributes

Use CharAttributes when you want a character or string fragment to explicitly enable, disable, or inherit ANSI text attributes.

auto emphasis = CharAttributes{};
emphasis.setBold(true);
emphasis.setUnderline(true);

const auto heading = Char{U'H', fg::BrightWhite, emphasis};
const auto plain = heading.withAttributes(CharAttributes::reset());

Unspecified attributes inherit from the surrounding writer or string context, while specified bits overwrite that base state.

Working with Character Styles

Use CharStyle when you want to bundle color and character attributes into one reusable value.

auto emphasis = CharAttributes{};
emphasis.setBold(true);

const auto headingStyle = CharStyle{Color{fg::BrightWhite, bg::Blue}, emphasis};
auto heading = Char{U'H', headingStyle};

heading.setStyle(heading.style().withOverlay(CharStyle{Color{fg::Inherited, bg::Black}}));

withOverlay() keeps inherited color components and unspecified attributes from the existing style, while withBase() resolves a style against an underlying base theme.

Building Strings

String stores a sequence of Char values. It is the right type for status bars, prompts, labels, and any text where characters may use different colors.

Building Colored Text Fragments

Prefer append(...) when building mixed-style strings. It keeps colors, attributes, and text in a single readable sequence.

auto footer = String{};
footer.append(
    bg::BrightBlack,
    fg::BrightYellow,
    "[Q]",
    fg::BrightWhite,
    " quit");

auto highlighted = CharAttributes{};
highlighted.setBold(true);
highlighted.setUnderline(true);

footer.append(
    "  ",
    highlighted,
    "Save",
    CharAttributes::reset(),
    fg::BrightBlack,
    " shortcut");

append(...) accepts colors, CharStyle, Char values, CharAttributes, plain text, and other String instances. Colors and attributes remain active for subsequent elements within the same call.

You can also construct a String directly from UTF-8 or UTF-32 text:

const auto utf8Text = String{"Gruezi"};
const auto utf32Text = String{U"Gru\u0308ezi"};

Control codes are filtered out automatically, except for tab and newline, which are preserved for layout and splitting.

Searching, Slicing, and Measuring

Use size() to count stored characters and displayWidth() to measure terminal cell width. These differ for full-width and combining characters.

const auto text = String{"A界e\xCC\x81"};

const auto characterCount = text.size();         // 3 terminal characters
const auto terminalWidth = text.displayWidth();  // 4 cells

For content-aware processing, the following helpers are commonly useful:

const auto warningCount = String{"!?!!"}.count(U'!');
const auto nextQuestion = String{"abc?def"}.indexOf(U'?');
const auto middle = String{"AB界D"}.substr(1, 2);

count(Char) and indexOf(Char) compare both character and color. The char32_t overloads ignore color and match only the character.

Splitting, Wrapping, and Lines

splitWords() separates text at spaces, tabs, carriage returns, and newlines. splitLines() keeps empty lines and splits only at newline characters.

const auto words = String{"alpha  beta\ngamma"}.splitWords();
const auto lines = String{"first\n\nthird"}.splitLines();

When you want string-level wrapping without creating a Text object, use wrapIntoLines():

const auto wrapped = String{"alpha beta\ngamma"}.wrapIntoLines(6);
const auto wrappedWithSpacing = String{"alpha beta\ngamma"}.wrapIntoLines(
    6,
    ParagraphSpacing::DoubleLine);

const auto lineCount = String{"AA\nBB"}.terminalLines(2);

This is useful for preprocessing text, estimating layout, or building buffers line by line.

StringLines is the line-based companion type returned by splitLines() and wrapIntoLines(). You can also rebuild a string from line data:

const auto text = String::fromLines({"one", "two"}, Color{fg::BrightWhite, bg::Blue});

If you want to render these lines directly into a buffer, see Buffer::fromLines() and Text Rendering.

Interface

class Char

Represents a character string with combined terminal style information.

Used by the UI code to render colored text blocks on the console.

Public Functions

constexpr Char() noexcept = default: Construct an empty block character using inherited colors.

inline explicit constexpr Char(const char32_t codePoint) noexcept

Construct a block character from a single Unicode code point using inherited colors.

Parameters:: codePoint – The base Unicode code point.

explicit Char(std::string_view charStr)

Construct a block character with inherited colors.

Parameters:: charStr – The UTF-8 encoded text to display.
Throws:: std::invalid_argument – If the text is not valid UTF-8, contains U+0000, or uses more than three code points.

explicit Char(std::u32string_view charStr)

Construct a block character with inherited colors.

Parameters:: charStr – The UTF-32 encoded text to display.
Throws:: std::invalid_argument – If the text contains U+0000 or uses more than three code points.

inline constexpr Char(const char32_t codePoint, const CharStyle style) noexcept

Construct a block character from a single Unicode code point with explicit style.

Parameters:

codePoint – The base Unicode code point.
style – The style for the character.

inline constexpr Char(const char32_t codePoint, const Color color, const CharAttributes attributes = {}) noexcept

Construct a block character from a single Unicode code point with explicit color and attributes.

Parameters:

codePoint – The base Unicode code point.
color – The color for the character.
attributes – The character attributes.

inline explicit Char(std::string_view charStr, CharStyle style)

Construct a block character with explicit text and style.

Parameters:

charStr – The UTF-8 encoded text to display.
style – The style for the character.

inline explicit Char(const std::string_view charStr, const Color color, const CharAttributes attributes = {})

Construct a block character with explicit text, color, and attributes.

Parameters:

charStr – The UTF-8 encoded text to display.
color – The color for the character.
attributes – The character attributes.

inline explicit Char(std::u32string_view charStr, CharStyle style)

Construct a block character with explicit text and style.

Parameters:

charStr – The UTF-32 encoded text to display.
style – The style for the character.

inline explicit Char(const std::u32string_view charStr, const Color color, const CharAttributes attributes = {})

Construct a block character with explicit text, color, and attributes.

Parameters:

charStr – The UTF-32 encoded text to display.
color – The color for the character.
attributes – The character attributes.

template<typename ...tColorArgs> inline constexpr Char(const char32_t codePoint, tColorArgs... color) noexcept

Construct a block character from a single Unicode code point and a color.

Parameters:

codePoint – The base Unicode code point.
color – The color for the character.

template<typename ...tColorArgs> inline explicit Char(const std::string_view charStr, tColorArgs... color)

Construct a block character with explicit text and colors.

Parameters:

charStr – The UTF-8 encoded text to display.
color – The color for the character.

template<typename ...tColorArgs> inline explicit Char(const std::u32string_view charStr, tColorArgs... color)

Construct a block character with explicit text and colors.

Parameters:

charStr – The UTF-32 encoded text to display.
color – The color for the character.

inline bool operator==(const Char &other) const noexcept: Compare two terminal characters for equality.

inline bool operator!=(const Char &other) const noexcept: Compare two terminal characters for inequality.

bool operator==(char32_t other) const noexcept: Compare just a single-code point character, without the color.

bool operator!=(char32_t other) const noexcept: Compare just a single-code point character, without the color.

std::string charStr() const

Get the character string as UTF-8 text.

Returns:: A UTF-8 encoded copy of the stored character sequence.

inline constexpr char32_t mainCodePoint() const noexcept

Get the leading Unicode code point.

Returns:: The base code point, or 0 if this character is empty.

inline constexpr const impl::CombinedChar::Storage &codePoints() const noexcept

Get the stored Unicode code points.

Unused entries are set to 0.

inline constexpr std::size_t codePointCount() const noexcept: Get the number of stored Unicode code points.

inline Color color() const noexcept: Get the character color.

inline CharAttributes attributes() const noexcept: Get the character attributes.

inline const CharStyle &style() const noexcept: Get the combined character style.

int displayWidth() const noexcept: Get the display width on a terminal in cells.

std::size_t byteCount() const noexcept: Get the number of UTF-8 bytes needed to encode this character.

void appendTo(std::string &buffer) const noexcept

Append the UTF-8 representation to an existing buffer.

Parameters:: buffer – The destination buffer.

inline void setStyle(const CharStyle style) noexcept

Replace the full style of this character.

Parameters:: style – The new style.

Char withCombining(char32_t codePoint) const

Create a character with an additional combining code point appended.

Parameters:: codePoint – The combining code point to append.
Throws:: std::invalid_argument – If codePoint is a control code, is not zero-width, or if this character already stores three code points.
Returns:: A copy of this character with the combining code point appended.

Char withColorOverlay(Color color) const

Create a character with the given colors applied as an overlay.

Parameters:: color – The color override to apply.
Returns:: A copy of this character with the adjusted colors. If the applied colors contain Inherited, the existing component from this character is kept unchanged.

Char withOverlay(Color color, CharAttributes attributes) const noexcept

Create a character with style applied on top of the stored style.

Inherited color components keep the current color component, and unspecified attributes keep the current attribute state.

Parameters:

color – The color override to apply.
attributes – The attribute override to apply.

Returns:

A copy of this character with the overlaid style.

Char withColorReplaced(Color color) const noexcept

Create a character with the given color replacing the stored color.

Parameters:: color – The replacement color.
Returns:: A copy of this character with exactly color.

Char withAttributes(CharAttributes attributes) const noexcept

Create a character with the given attributes replacing the stored attributes.

Parameters:: attributes – The replacement attributes.
Returns:: A copy of this character with exactly attributes.

Char withBaseColor(Color color) const noexcept

Create a character with a base color underneath the stored color.

Parameters:: color – The base color.
Returns:: A copy of this character where this character color overlays color.

Char withBase(Color color, CharAttributes attributes) const noexcept

Create a character with style used as the base underneath the stored style.

The stored color and stored attributes overwrite the base style.

Parameters:

color – The base color.
attributes – The base attributes.

Returns:

A copy of this character resolved against the base style.

Char withBase(const Char &base) const noexcept

Create a character with another character used as the style base.

Only the style is used from base; the stored Unicode character is preserved.

Parameters:: base – The character providing the base color and attributes.
Returns:: A copy of this character resolved against base.

inline constexpr bool isEmpty() const noexcept: Test if this character is empty (has no code-point).

bool isSpacing() const noexcept

Test if this character is spacing.

Tests for space, tab, newline, and CR.

bool isControl() const noexcept: Test if this character is a control character.

bool isOneOf(std::u32string_view characters) const noexcept

Test if this character is one of the given characters.

Tests only the character, not the color. Only tests one code-point characters.

bool isOneOf(std::initializer_list<char32_t> characters) const noexcept: This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

template<typename ...tCharacters> inline bool isOneOf(tCharacters... characters) const noexcept: This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

bool renderedEquals(const Char &other, bool colorEnabled = true, bool attributeEnabled = true) const noexcept

Compare how two characters would appear on screen.

Code points must match exactly. When colorEnabled is true, inherited color components are treated as the terminal default color before comparing. When attributeEnabled is true, inherited attributes are treated as disabled before comparing.

Parameters:

other – The character to compare with.
colorEnabled – true to include colors in the comparison.
attributeEnabled – true to include character attributes in the comparison.

Returns:

true if both characters render identically.

inline constexpr std::size_t hash() const noexcept: Get a hash for this character and its color.

Public Static Functions

static const Char &space() noexcept: A space with inherited colors.

class CharAttributes

A set of optional ANSI character attributes.

Each attribute stores two states: whether it is explicitly specified and whether it is enabled. Unspecified attributes inherit the state from the surrounding writer or character below.

Public Functions

constexpr CharAttributes() noexcept = default: Create attributes with no explicitly specified flags.

inline constexpr CharAttributes(const Flag flag) noexcept

Create attributes with one enabled flag.

Parameters:: flag – The flag to enable and specify.

bool operator==(const CharAttributes&) const noexcept = default: Compare two attribute sets for equality.

bool operator!=(const CharAttributes&) const noexcept = default: Compare two attribute sets for inequality.

inline constexpr uint8_t enabledMask() const noexcept

Get the enabled bit mask.

Only specified bits are relevant.

inline constexpr uint8_t specifiedMask() const noexcept: Get the specified bit mask.

inline constexpr uint8_t mask() const noexcept: Get the mask of attributes that are both specified and enabled.

inline constexpr bool isSpecified(const Flag flag) const noexcept

Test whether a flag is explicitly specified.

Parameters:: flag – The flag to test.
Returns:: true if the flag is explicitly specified.

inline constexpr bool isEnabled(const Flag flag) const noexcept

Test whether a flag is specified and enabled.

Parameters:: flag – The flag to test.
Returns:: true if the flag is specified and enabled.

inline constexpr CharAttributes resolvedWith(const CharAttributes base) const noexcept

Apply these attributes on top of a base attribute set.

Only explicitly specified attributes overwrite the base state.

Parameters:: base – The base attributes.
Returns:: The resolved attribute set.

inline constexpr CharAttributes withFlag(const Flag flag, const bool enabled) const noexcept

Create a copy with one flag explicitly enabled or disabled.

Parameters:

flag – The flag to change.
enabled – true to enable the flag, false to disable it.

Returns:

The updated attribute set.

inline constexpr std::size_t hash() const noexcept: Get a stable hash for the attribute set.

inline constexpr bool isBoldSpecified() const noexcept: Test if the bold attribute is specified.

inline constexpr bool isBold() const noexcept: Test if the bold attribute is enabled.

inline constexpr bool isDimSpecified() const noexcept: Test if the dim attribute is specified.

inline constexpr bool isDim() const noexcept: Test if the dim attribute is enabled.

inline constexpr bool isItalicSpecified() const noexcept: Test if the italic attribute is specified.

inline constexpr bool isItalic() const noexcept: Test if the italic attribute is enabled.

inline constexpr bool isUnderlineSpecified() const noexcept: Test if the underline attribute is specified.

inline constexpr bool isUnderline() const noexcept: Test if the underline attribute is enabled.

inline constexpr bool isBlinkSpecified() const noexcept: Test if the blink attribute is specified.

inline constexpr bool isBlink() const noexcept: Test if the blink attribute is enabled.

inline constexpr bool isReverseSpecified() const noexcept: Test if the reverse attribute is specified.

inline constexpr bool isReverse() const noexcept: Test if the reverse attribute is enabled.

inline constexpr bool isHiddenSpecified() const noexcept: Test if the hidden attribute is specified.

inline constexpr bool isHidden() const noexcept: Test if the hidden attribute is enabled.

inline constexpr bool isStrikethroughSpecified() const noexcept: Test if the strikethrough attribute is specified.

inline constexpr bool isStrikethrough() const noexcept: Test if the strikethrough attribute is enabled.

inline constexpr void setBold(const bool enabled) noexcept

Set or clear the bold attribute explicitly.

Parameters:: enabled – true to enable the attribute, false to disable it.

inline constexpr void setBoldInherited() noexcept: Make the bold attribute inherit from the base state.

inline constexpr void setDim(const bool enabled) noexcept

Set or clear the dim attribute explicitly.

Parameters:: enabled – true to enable the attribute, false to disable it.

inline constexpr void setDimInherited() noexcept: Make the dim attribute inherit from the base state.

inline constexpr void setItalic(const bool enabled) noexcept

Set or clear the italic attribute explicitly.

Parameters:: enabled – true to enable the attribute, false to disable it.

inline constexpr void setItalicInherited() noexcept: Make the italic attribute inherit from the base state.

inline constexpr void setUnderline(const bool enabled) noexcept

Set or clear the underline attribute explicitly.

Parameters:: enabled – true to enable the attribute, false to disable it.

inline constexpr void setUnderlineInherited() noexcept: Make the underline attribute inherit from the base state.

inline constexpr void setBlink(const bool enabled) noexcept

Set or clear the blink attribute explicitly.

Parameters:: enabled – true to enable the attribute, false to disable it.

inline constexpr void setBlinkInherited() noexcept: Make the blink attribute inherit from the base state.

inline constexpr void setReverse(const bool enabled) noexcept

Set or clear the reverse attribute explicitly.

Parameters:: enabled – true to enable the attribute, false to disable it.

inline constexpr void setReverseInherited() noexcept: Make the reverse attribute inherit from the base state.

inline constexpr void setHidden(const bool enabled) noexcept

Set or clear the hidden attribute explicitly.

Parameters:: enabled – true to enable the attribute, false to disable it.

inline constexpr void setHiddenInherited() noexcept: Make the hidden attribute inherit from the base state.

inline constexpr void setStrikethrough(const bool enabled) noexcept

Set or clear the strikethrough attribute explicitly.

Parameters:: enabled – true to enable the attribute, false to disable it.

inline constexpr void setStrikethroughInherited() noexcept: Make the strikethrough attribute inherit from the base state.

Public Static Functions

static inline constexpr CharAttributes fromMasks(uint8_t enabledMask, uint8_t specifiedMask) noexcept

Create attributes from an enabled/specified mask pair.

Parameters:

enabledMask – The enabled bits.
specifiedMask – The specified bits.

Returns:

The new attribute set.

static inline constexpr CharAttributes fromMask(const uint8_t mask) noexcept

Create a fully specified attribute mask from enabled bits.

Parameters:: mask – The enabled bits.
Returns:: The fully specified attribute set.

static inline constexpr CharAttributes reset() noexcept

Create a fully specified attribute set with all flags disabled.

Returns:: The reset attribute set.

static inline constexpr CharAttributes all() noexcept

Create a fully specified attribute set with all flags enabled.

Returns:: The fully enabled attribute set.

Public Static Attributes

static constexpr auto Bold = Flag{0x01U}: Bold text.

static constexpr auto Dim = Flag{0x02U}: Dim text.

static constexpr auto Italic = Flag{0x04U}: Italic text.

static constexpr auto Underline = Flag{0x08U}: Underlined text.

static constexpr auto Blink = Flag{0x10U}: Blinking text.

static constexpr auto Reverse = Flag{0x20U}: Reverse foreground/background display.

static constexpr auto Hidden = Flag{0x40U}: Hidden text.

static constexpr auto Strikethrough = Flag{0x80U}: Strikethrough text.

struct Flag

A single character attribute flag.

Public Members

uint8_t value: The bit mask value for the flag.

class CharStyle

A combined terminal text style with color and character attributes.

Public Functions

constexpr CharStyle() noexcept = default: Create a style with inherited color and attributes.

inline constexpr CharStyle(const Color color, const CharAttributes attributes = {}) noexcept

Create a style from color and attributes.

Parameters:

color – The color for the style.
attributes – The character attributes for the style.

inline constexpr CharStyle(const CharAttributes attributes) noexcept

Create a style from character attributes and inherited color.

Parameters:: attributes – The character attributes for the style.

bool operator==(const CharStyle&) const noexcept = default: Compare two character styles for equality.

bool operator!=(const CharStyle&) const noexcept = default: Compare two character styles for inequality.

inline Color color() const noexcept: Get the color part of the style.

inline void setColor(const Color color) noexcept

Set the color part of the style.

Parameters:: color – The new color.

inline Foreground fg() const noexcept: Get the foreground color.

inline void setFg(const Foreground foreground) noexcept

Set the foreground color.

Parameters:: foreground – The new foreground color.

inline Background bg() const noexcept: Get the background color.

inline void setBg(const Background background) noexcept

Set the background color.

Parameters:: background – The new background color.

inline CharAttributes attributes() const noexcept: Get the character attributes.

inline void setAttributes(const CharAttributes attributes) noexcept

Set the character attributes.

Parameters:: attributes – The new character attributes.

inline CharStyle withOverlay(const CharStyle overlay) const noexcept

Create a new style by overlaying another style onto this one.

Inherited color components keep the existing color, and unspecified attributes keep the existing attributes.

Parameters:: overlay – The overlay style.
Returns:: The combined style.

inline CharStyle withBase(const CharStyle base) const noexcept

Create a new style by placing a base style underneath this one.

The current style overwrites inherited or unspecified parts from the base style.

Parameters:: base – The base style.
Returns:: The resolved style.

inline constexpr std::size_t hash() const noexcept: Get a stable hash for the character style.

class String

A terminal string represented as a sequence of Char values.

Public Types

using Storage = std::vector<Char>: Storage container for the characters.

using iterator = Storage::iterator: Mutable forward iterator.

using const_iterator = Storage::const_iterator: Immutable forward iterator.

using reverse_iterator = Storage::reverse_iterator: Mutable reverse iterator.

using const_reverse_iterator = Storage::const_reverse_iterator: Immutable reverse iterator.

using size_type = Storage::size_type: Unsigned size type.

using difference_type = Storage::difference_type: Signed distance type.

using value_type = Storage::value_type: Stored value type.

using reference = Storage::reference: Mutable element reference.

using const_reference = Storage::const_reference: Immutable element reference.

using pointer = Storage::pointer: Mutable element pointer.

using const_pointer = Storage::const_pointer: Immutable element pointer.

Public Functions

String() = default: Create an empty terminal string.

explicit String(std::string_view str, Color color = {})

Create a terminal string from UTF-8 text.

Parameters:

str – The UTF-8 text to split into terminal characters.
color – The color to use for the characters. Control codes are ignored except for tab and newline.

Throws:

std::invalid_argument – If the text is not valid UTF-8 or contains an unsupported character sequence.

explicit String(std::string_view str, CharStyle style)

Create a terminal string from UTF-8 text.

Parameters:

str – The UTF-8 text to split into terminal characters.
style – The style to use for the characters. Control codes are ignored except for tab and newline.

Throws:

std::invalid_argument – If the text is not valid UTF-8 or contains an unsupported character sequence.

explicit String(std::u32string_view str, Color color = {})

Create a terminal string from UTF-32 text.

Parameters:

str – The UTF-32 text to split into terminal characters.
color – The color to use for the characters. Control codes are ignored except for tab and newline.

Throws:

std::invalid_argument – If the text contains an unsupported character sequence.

explicit String(std::u32string_view str, CharStyle style)

Create a terminal string from UTF-32 text.

Parameters:

str – The UTF-32 text to split into terminal characters.
style – The style to use for the characters. Control codes are ignored except for tab and newline.

Throws:

std::invalid_argument – If the text contains an unsupported character sequence.

explicit String(std::size_t count, Char character) noexcept

Create a terminal string repeating the same Char.

Parameters:

count – The repetition count. Limited to 10’000’000.
character – The character to repeat.

inline Char operator[](const std::size_t index) const noexcept

Access one character without bounds checking.

Parameters:: index – The character index.
Returns:: A copy of the character at index.

inline Char &operator[](const std::size_t index) noexcept

Access one character without bounds checking.

Parameters:: index – The character index.
Returns:: A mutable reference to the character at index.

inline String &operator+=(const Char &character) noexcept

Append one character to this string.

Parameters:: character – The character to append.
Returns:: Reference to this string.

inline String &operator+=(const String &other) noexcept

Append another terminal string to this string.

Parameters:: other – The string to append.
Returns:: Reference to this string.

inline String operator+(const Char &character) const noexcept

Create a new string with one appended character.

Parameters:: character – The character to append.
Returns:: The concatenated string.

inline String operator+(const String &other) const noexcept

Create a new string with another appended string.

Parameters:: other – The string to append.
Returns:: The concatenated string.

inline std::size_t size() const noexcept: Get the number of stored characters.

int displayWidth() const noexcept

Get the width of the string in terminal cells.

Returns:: The sum of all character display widths.

inline Char at(const std::size_t index) const

Access one character with bounds checking.

Parameters:: index – The character index.
Returns:: A copy of the character at index.

inline bool empty() const noexcept: Test if this string is empty.

inline auto begin() noexcept: Get an iterator to the first character.

inline auto end() noexcept: Get an iterator past the last character.

inline auto begin() const noexcept: Get a const iterator to the first character.

inline auto end() const noexcept: Get a const iterator past the last character.

inline auto cbegin() const noexcept: Get a const iterator to the first character.

inline auto cend() const noexcept: Get a const iterator past the last character.

inline auto rbegin() noexcept: Get a reverse iterator to the last character.

inline auto rend() noexcept: Get a reverse iterator past the first character.

inline auto rbegin() const noexcept: Get a const reverse iterator to the last character.

inline auto rend() const noexcept: Get a const reverse iterator past the first character.

inline auto crbegin() const noexcept: Get a const reverse iterator to the last character.

inline auto crend() const noexcept: Get a const reverse iterator past the first character.

std::size_t count(Char character) const noexcept

Count the number of characters with a given color.

Parameters:: character – The character to count.
Returns:: The number of characters in this string.

std::size_t count(char32_t character) const noexcept

Count the number of characters matching any color.

Parameters:: character – The character to count (1 code-point).
Returns:: The number of characters in this string.

std::size_t indexOf(Char character, std::size_t startIndex = 0) const noexcept

Get the index of the next character with a given color.

If startIndex is out of bounds, returns npos. If no character is found, returns npos.

Parameters:

character – The character to search for. Compares both, character and color!
startIndex – The start index to search from. Defaults to 0.

Returns:

The index of the next character or npos if not found.

std::size_t indexOf(char32_t character, std::size_t startIndex = 0) const noexcept

Get the index of the next character matching any color.

If startIndex is out of bounds, returns npos. If no character is found, returns npos.

Parameters:

character – The character to search for. Only compares the character (1 code-point).
startIndex – The start index to search from. Defaults to 0.

Returns:

The index of the next character or npos if not found.

String substr(std::size_t startIndex, std::size_t length = npos) const noexcept

Get a substring.

If startIndex is out of bounds, returns an empty string. If length exceeds the string length, returns the remaining characters.

Parameters:

startIndex – The start index of the substring.
length – The number of characters after the start index.

Returns:

The substring or an empty string if startIndex is out of bounds.

bool containsControlCharacters() const noexcept

Test if this string contains control characters.

As most control codes are filtered on construction, this mainly tests for NL and TAB.

inline void reserve(const std::size_t size) noexcept

Reserve storage for at least the given number of characters.

Parameters:: size – The requested capacity.

inline void clear() noexcept: Remove all characters from this string.

template<PrintableArg... Args> inline void append(Args... args) noexcept

Append elements to this string.

This works similar to Terminal::print(). If you add a color, this color is “active” for all following characters in the same call. If you add character attributes, these attributes are active for all following characters in the same call. Appended Char and String values with inherited color components or inherited attributes resolve against the currently active state. Just adding a color does not change the string.

Parameters:: args – The arguments to append.

std::vector<String> splitWords() const noexcept

Split the string into words at space, tab, carriage return, or newline characters.

Returns:: A sequence of words.

std::vector<String> wrapIntoLines(int width, ParagraphSpacing paragraphSpacing = ParagraphSpacing::SingleLine) const noexcept

Wrap this string into lines that have a maximum display width.

Paragraph breaks from newline characters are preserved using the selected paragraph spacing.

Parameters:

width – The maximum terminal width in cells. Must be greater than zero.
paragraphSpacing – The spacing to use between newline-separated paragraphs.

Returns:

A sequence of lines.

int terminalLines(int width) const noexcept

Count how many terminal lines this string occupies for a given terminal width.

Newline characters start a new terminal line and printable characters wrap at the given width. The result is undefined for abstract terminal widths smaller than 10 cells.

Parameters:: width – The available terminal width in cells. Must be greater than zero.
Returns:: The number of occupied terminal lines.

std::vector<String> splitLines() const noexcept

Splits this string into individual lines.

The string is split at the NL character that is not included in the result. Empty lines are preserved. A NL at the end of the string does not generate an additional empty line.

Returns:: A sequence of lines.

Public Static Functions

static String fromLines(std::initializer_list<std::string_view> lines, Color color = {}, CharAttributes attributes = {}) noexcept

Create a new string from a list of lines.

All lines are joined using a new-line character.

Parameters:

lines – The lines for the string.
color – The base color to use for each character.
attributes – The base attributes to use for each character.

Returns:

The new string.

static String fromLines(std::initializer_list<std::string_view> lines, CharStyle style) noexcept: This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

static auto fromLines(std::initializer_list<std::u32string_view> lines, Color color = {}, CharAttributes attributes = {}) noexcept -> String : This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

static String fromLines(std::initializer_list<std::u32string_view> lines, CharStyle style) noexcept: This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Public Static Attributes

static constexpr std::size_t npos = std::numeric_limits<std::size_t>::max(): No valid position.

using erbsland::cterm::StringLines = std::vector<String>: A sequence of wrapped terminal text lines.