Ch9.12.1: String Operations Reference

Overview

This appendix documents all string-specific operations. Return here when you need a particular feature.

1. npos

::fast_io::containers::npos is defined as ::std::numeric_limits<::std::size_t>::max(). It serves two purposes:

“Not found” — returned by all find* operations when the search fails.
“Through end” — default count parameter for subview(), substr(), meaning “to the end of the string”.


#include <fast_io_dsal/string.h>
#include <fast_io.h>
using ::fast_io::containers::npos;

int main() {
    ::fast_io::string s{"Hello, World!"};

    // npos as "not found"
    auto pos = s.find_character('z');
    if (pos == npos) {
        ::fast_io::io::println("'z' not found");
    }

    // npos as "to end"
    auto view = s.subview(7zu); // default count = npos → "World!"
}

2. Search / Find Operations

All search operations return size_type. They return npos when the target is not found.

Operation	Description	Example
`find_character(ch, pos=0)`	Find first occurrence of character `ch` starting at `pos`.	`s.find_character('o')` → 4
`find_not_character(ch, pos=0)`	Find first character that is not `ch`.	`s.find_not_character('H')` → 1
`rfind_character(ch, pos=npos)`	Find last occurrence of `ch`, searching backward from `pos`.	`s.rfind_character('l')` → 10
`rfind_not_character(ch, pos=npos)`	Find last character that is not `ch`.	`s.rfind_not_character('!')` → 11
`find(view, pos=0)`	Find first occurrence of substring `view`.	`s.find("World")` → 7
`rfind(view, pos=0)`	Find last occurrence of substring `view`.	`s.rfind("l")` → 10
`find_first_of(view, pos)`	Find first character that matches any character in `view`.	`s.find_first_of("aeiou")` → 1 ('e')
`find_first_not_of(view, pos)`	Find first character that does not match any in `view`.	`s.find_first_not_of("Helo")` → 5 (',')
`find_last_of(view, pos)`	Find last character matching any in `view`.	`s.find_last_of("aeiou")` → 8 ('o')
`find_last_not_of(view, pos)`	Find last character not matching any in `view`.	`s.find_last_not_of(" !")` → 11 ('d')
`contains_character(ch)`	Returns `true` if `ch` exists in the string.	`s.contains_character('W')` → true
`contains(view)`	Returns `true` if substring `view` exists.	`s.contains("World")` → true

3. Substring / Subview Operations

subview* returns a non-owning view (string_view); substr* returns an owning copy (string).

Operation	Returns	Description
`subview(pos, count=npos)`	`string_view`	View of `count` characters starting at `pos`.
`subview_front(count)`	`string_view`	View of the first `count` characters.
`subview_back(count)`	`cstring_view`	View of the last `count` characters (null-terminated).
`substr(idx, count=npos)`	`string`	Copy of `count` characters starting at `idx`.
`substr_front(count)`	`string`	Copy of the first `count` characters.
`substr_back(count)`	`string`	Copy of the last `count` characters.

All subview* and substr* methods have _unchecked variants that skip bounds checking.

4. starts_with / ends_with

Operation	Description	Example
`starts_with(view)`	Returns `true` if string begins with `view`.	`s.starts_with("Hello")` → true
`starts_with_character(ch)`	Returns `true` if first character is `ch`.	`s.starts_with_character('H')` → true
`ends_with(view)`	Returns `true` if string ends with `view`.	`s.ends_with("!")` → true
`ends_with_character(ch)`	Returns `true` if last character is `ch`.	`s.ends_with_character('!')` → true

5. Trim Operations

Trim operations remove leading and/or trailing characters. The _c_space variants trim C whitespace (space, tab, newline, etc.).

Operation	Modifies?	Description
`trim_c_space()`	Yes (returns `string&`)	Remove leading and trailing whitespace in-place.
`trim_prefix_c_space()`	Yes	Remove leading whitespace only.
`trim_suffix_c_space()`	Yes	Remove trailing whitespace only.
`trim_subview_c_space()`	No (returns `string_view`)	Return a view with whitespace removed (does not modify the string).
`trim_prefix_subview_c_space()`	No	Return a view with leading whitespace removed.
`trim_suffix_subview_c_space()`	No	Return a view with trailing whitespace removed.

There are also generic trim(), trim_prefix(), trim_suffix() overloads that accept a character category trait for custom character sets.

6. Replace / Insert / Erase

Operation	Description
`replace_index(first, last, view)`	Replace range `[first, last)` with `view`.
`insert_index(idx, view)`	Insert `view` at index `idx`.
`erase_index(idx)`	Erase character at index `idx`.
`erase_index(first, last)`	Erase range `[first, last)`.
`remove_suffix(n)`	Remove the last `n` characters.
`assign(view)`	Replace entire contents with `view`.
`assign_characters(n, ch)`	Replace contents with `n` copies of `ch`.
`append(view)`	Append `view` to the end.

7. Comparison

Strings and string views support == and <=> (C++20 three-way comparison). Comparison is lexicographic.


::fast_io::string a{"abc"};
::fast_io::string b{"abd"};

bool eq = (a == b);          // false
auto cmp = (a <=> b);       // std::strong_ordering::less

8. c_str()

c_str() returns a null-terminated const char* for interfacing with C APIs. Since fast_io::string is always null-terminated, this is a Θ(1) pointer return.

9. resize_and_overwrite()

C++23-style method: resize the string to a given size, then call a user callback with a pointer to the raw buffer. Useful for filling the string from a C API or custom logic without an extra copy.