omni::string

class string

This class is an ABI safe string implementation.

It is meant to be a drop-in replacement for std::string.

This class is not templated for simplicity and ABI safety .

Note: If exceptions are not enabled, any function that would throw will terminate the program instead.

Note: All functions provide a strong exception guarantee. If they throw an exception for any reason, the function has no effect.

Public Types

using traits_type = detail::char_traits: Char traits type alias.

using value_type = char: Char type alias.

using size_type = std::size_t: Size type alias.

using reference = value_type&: Reference type alias.

using const_reference = const value_type&: Const Reference type alias.

using pointer = value_type*: Pointer type alias.

using const_pointer = const value_type*: Const Pointer type alias.

using difference_type = std::pointer_traits<pointer>::difference_type: Difference type alias.

using iterator = detail::PointerIterator<pointer, string>: Iterator type alias.

using const_iterator = detail::PointerIterator<const_pointer, string>: Const Iterator type alias.

using const_reverse_iterator = std::reverse_iterator<const_iterator>: Const Reverse Iterator type alias.

using reverse_iterator = std::reverse_iterator<iterator>: Reverse Iterator type alias.

Public Functions

string() noexcept

Default constructor.

Constructs empty string.

string(size_type n, value_type c)

Constructs the string with n copies of character c.

Parameters

n – Number of characters to initialize with.
c – The character to initialize with.

Throws

std::length_error – if the string would be larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

string(const string &str, size_type pos)

Constructs the string with a substring [pos, str.size()) of str.

Parameters

str – Another string to use as source to initialize the string with.
pos – Position of the first character to include.

Throws

std::out_of_range – if pos is greater than str.size().
std::length_error – if the string would be larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

string(const string &str, size_type pos, size_type n)

Constructs the string with a substring [pos, pos + n) of str.

If n == npos, or if the requested substring lasts past the end of the string, the resulting substring is [pos, str.size()).

Parameters

str – Another string to use as source to initialize the string with.
pos – Position of the first character to include.
n – Number of characters to include.

Throws

std::out_of_range – if pos is greater than str.size().
std::length_error – if the string would be larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

string(const value_type *s, size_type n)

Constructs the string with the first n characters of character string pointed to by s.

s can contain null characters. The length of the string is n. The behavior is undefined if [s, s + n) is not a valid range.

Parameters

s – Pointer to an array of characters to use as source to initialize the string with.
n – Number of characters to include.

Throws

std::length_error – if the string would be larger than max_size().
std::invalid_argument – if s is nullptr.
Allocation – This function may throw any exception thrown during allocation.

string(const value_type *s)

Constructs the string with the contents initialized with a copy of the null-terminated character string pointed to by s .

The length of the string is determined by the first null character. The behavior is undefined if [s, s + Traits::length(s)) is not a valid range (for example, if s is a null pointer).

Parameters

s – Pointer to an array of characters to use as source to initialize the string with.

Throws

std::length_error – if the string would be larger than max_size().
std::invalid_argument – if s is nullptr.
Allocation – This function may throw any exception thrown during allocation.

template<typename InputIterator> string(InputIterator begin, InputIterator end)

Constructs the string with the contents of the range [first, last).

Parameters

begin – Start of the range to copy characters from.
end – End of the range to copy characters from.

Throws

std::length_error – if the string would be larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

string(const string &str)

Copy constructor.

Constructs the string with a copy of the contents of str.

Parameters

str – Another string to use as source to initialize the string with.

Throws

std::length_error – if the string would be larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

string(string &&str) noexcept

Move constructor.

Constructs the string with the contents of str using move semantics. str is left in valid, but unspecified state.

Parameters

str – Another string to use as source to initialize the string with.

Throws

std::length_error – if the string would be larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

string(std::initializer_list<value_type> ilist)

Constructs the string with the contents of the initializer list ilist.

Parameters

ilist – initializer_list to initialize the string with.

Throws

std::length_error – if the string would be larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

template<class ...Args> string(formatted_t, const char *fmt, Args&&... args)

Constructs the string with the printf style format string and additional parameters.

Parameters

fmt – A printf style format string.
args – Additional arguments to the format string.

Throws

std::length_error – if the string would be larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

string(vformatted_t, const char *fmt, va_list ap)

Constructs the string with the vprintf style format string and additional parameters.

Parameters

fmt – A printf style format string.
ap – A va_list as initialized by va_start.

Throws

std::length_error – if the string would be larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

explicit string(const std::string &str)

Copy constructor.

Constructs the string with a copy of the contents of str.

Parameters

str – Another string to use as source to initialize the string with.

Throws

std::length_error – if the string would be larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

string(const std::string &str, size_type pos, size_type n)

Constructs the string with a substring [pos, pos + n) of str.

If n == npos, or if the requested substring lasts past the end of the string, the resulting substring is [pos, str.size()).

Parameters

str – Another string to use as source to initialize the string with.
pos – Position of the first character to include.
n – Number of characters to include.

Throws

std::out_of_range – if pos is greater than str.size().
std::length_error – if the string would be larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

explicit string(const carb::cpp::string_view &sv)

Copy constructor.

Constructs the string with a copy of the contents of sv.

Parameters

sv – String view to use as source to initialize the string with.

Throws

std::length_error – if the string would be larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

string(const carb::cpp::string_view &sv, size_type pos, size_type n)

Constructs the string with a substring [pos, pos + n) of sv.

If n == npos, or if the requested substring lasts past the end of the string, the resulting substring is [pos, sv.size()).

Parameters

sv – String view to use as source to initialize the string with.
pos – Position of the first character to include.
n – Number of characters to include.

Throws

std::out_of_range – if pos is greater than sv.size().
std::length_error – if the string would be larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

template<typename T, typename = detail::is_sv_convertible<T>> explicit string(const T &t)

Implicitly converts t to type std::string_view and initializes this string with the contents of that std::string_view.

This overload participates in overload resolution only if std::is_convertible_v<const T&, std::string_view> is true.

Parameters

t – Object that can be converted to std::string_view to initialize with.

Throws

std::length_error – if the string would be larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

template<typename T, typename = detail::is_sv_convertible<T>> string(const T &t, size_type pos, size_type n)

Implicitly converts t to type std::string_view and initializes this string with a substring [pos, pos + n) of that string_view.

If n == npos, or if the requested substring lasts past the end of the string_view, the resulting substring is [pos, sv.size()). This overload participates in overload resolution only if std::is_convertible_v<const T&, std::string_view> is true.

Parameters

t – Object that can be converted to std::string_view to initialize with.
pos – Position of the first character to include.
n – Number of characters to include.

Throws

std::out_of_range – if pos is greater than sv.size().
std::length_error – if the string would be larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

string(std::nullptr_t) = delete: Cannot be constructed from nullptr.

~string() noexcept: Destroys the string, deallocating internal storage if used.

string &operator=(const string &str)

Replaces the contents with a copy of str.

If *this and str are the same object, this function has no effect.

Parameters

str – String to be used as the source to initialize the string with.

Throws

std::length_error – if the string would be larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

Returns

*this.

string &operator=(string &&str) noexcept

Replaces the contents with those of str using move semantics.

str is in a valid but unspecified state afterwards.

Parameters

str – String to be used as the source to initialize the string with.

Throws

std::length_error – if the string would be larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

Returns

*this.

string &operator=(const value_type *s)

Replaces the contents with those of null-terminated character string pointed to by s.

Parameters

s – Pointer to a null-terminated character string to use as source to initialize the string with.

Throws

std::length_error – if the string would be larger than max_size().
std::invalid_argument – if s is nullptr.
Allocation – This function may throw any exception thrown during allocation.

Returns

*this.

string &operator=(value_type c)

Replaces the contents with character c.

Parameters

c – Character to use as source to initialize the string with.

Throws

std::length_error – if the string would be larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

Returns

*this.

string &operator=(std::initializer_list<value_type> ilist)

Replaces the contents with those of the initializer list ilist.

Parameters

ilist – initializer list to use as source to initialize the string with.

Throws

std::length_error – if the string would be larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

Returns

*this.

string &operator=(const std::string &str)

Replaces the contents with a copy of str.

Parameters

str – String to be used as the source to initialize the string with.

Throws

std::length_error – if the string would be larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

Returns

*this.

string &operator=(const carb::cpp::string_view &sv)

Replaces the contents with a copy of sv.

Parameters

sv – String view to be used as the source to initialize the string with.

Throws

std::length_error – if the string would be larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

Returns

*this.

template<typename T, typename = detail::is_sv_convertible<T>> string &operator=(const T &t)

Implicitly converts t to type std::string_view and replaces the contents of this string with the contents of that std::string_view.

This overload participates in overload resolution only if std::is_convertible_v<const T&, std::string_view> is true.

Parameters

t – Object that can be converted to std::string_view to initialize with.

Throws

std::length_error – if the string would be larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

string &operator=(std::nullptr_t) = delete: Cannot be assigned from nullptr.

string &assign(size_type n, value_type c)

Replaces the contents with n copies of character c.

Parameters

n – Number of characters to initialize with.
c – Character to use as source to initialize the string with.

Throws

std::length_error – if the string would be larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

Returns

*this.

string &assign(const string &str)

Replaces the contents with a copy of str.

Parameters

str – String to be used as the source to initialize the string with.

Throws

std::length_error – if the string would be larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

Returns

*this.

string &assign(const string &str, size_type pos, size_type n = npos)

Replaces the string with a substring [pos, pos + n) of str.

If n == npos, or if the requested substring lasts past the end of the string, the resulting substring is [pos, str.size()).

Parameters

str – Another string to use as source to initialize the string with.
pos – Position of the first character to include.
n – Number of characters to include.

Throws

std::length_error – if the string would be larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

Returns

*this.

string &assign(string &&str)

Replaces the contents with those of str using move semantics.

str is in a valid but unspecified state afterwards.

Parameters

str – String to be used as the source to initialize the string with.

Throws

std::length_error – if the string would be larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

Returns

*this.

string &assign(const value_type *s, size_type n)

Replace the string with the first n characters of character string pointed to by s.

s can contain null characters. The length of the string is n. The behavior is undefined if [s, s + n) is not a valid range.

Parameters

s – Pointer to an array of characters to use as source to initialize the string with.
n – Number of characters to include.

Throws

std::invalid_argument – if s is nullptr.
std::length_error – if the string would be larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

Returns

*this.

string &assign(const value_type *s)

Replaces the contents with those of null-terminated character string pointed to by s.

Parameters

s – Pointer to a null-terminated character string to use as source to initialize the string with.

Throws

std::invalid_argument – if s is nullptr.
std::length_error – if the string would be larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

Returns

*this.

template<class InputIterator> string &assign(InputIterator first, InputIterator last)

Replace the string with the contents of the range [first, last).

Parameters

first – Start of the range to copy characters from.
last – End of the range to copy characters from.

Throws

std::length_error – if the string would be larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

Returns

*this.

string &assign(std::initializer_list<value_type> ilist)

Replaces the contents with those of the initializer list ilist.

Parameters

ilist – initializer list to use as source to initialize the string with.

Throws

std::length_error – if the string would be larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

Returns

*this.

string &assign(const std::string &str)

Replaces the contents with a copy of str.

Parameters

str – String to be used as the source to initialize the string with.

Throws

std::length_error – if the string would be larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

Returns

*this.

string &assign(const std::string &str, size_type pos, size_type n = npos)

Replaces the string with a substring [pos, pos + n) of str.

If n == npos, or if the requested substring lasts past the end of the string, the resulting substring is [pos, str.size()).

Parameters

str – Another string to use as source to initialize the string with.
pos – Position of the first character to include.
n – Number of characters to include.

Throws

std::length_error – if the string would be larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

Returns

*this.

string &assign(const carb::cpp::string_view &sv)

Replaces the contents with a copy of sv.

Parameters

sv – String view to be used as the source to initialize the string with.

Throws

std::length_error – if the string would be larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

Returns

*this.

string &assign(const carb::cpp::string_view &sv, size_type pos, size_type n = npos)

Replaces the string with a substring [pos, pos + n) of sv.

If n == npos, or if the requested substring lasts past the end of the string, the resulting substring is [pos, sv.size()).

Parameters

sv – String view to use as source to initialize the string with.
pos – Position of the first character to include.
n – Number of characters to include.

Throws

std::length_error – if the string would be larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

Returns

*this.

template<typename T, typename = detail::is_sv_convertible<T>> string &assign(const T &t)

Implicitly converts t to type std::string_view and replaces the contents of this string with a substring [pos, pos + n) of that string_view.

This overload participates in overload resolution only if std::is_convertible_v<const T&, std::string_view> is true.

Parameters

t – Object that can be converted to std::string_view to initialize with.

Throws

std::out_of_range – if pos is greater than sv.size().
std::length_error – if the string would be larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

template<typename T, typename = detail::is_sv_convertible<T>> string &assign(const T &t, size_type pos, size_type n = npos)

Implicitly converts t to type std::string_view and replaces the contents of this string with a substring [pos, pos + n) of that string_view.

If n == npos, or if the requested substring lasts past the end of the string_view, the resulting substring is [pos, sv.size()). This overload participates in overload resolution only if std::is_convertible_v<const T&, std::string_view> is true.

Parameters

t – Object that can be converted to std::string_view to initialize with.
pos – Position of the first character to include.
n – Number of characters to include.

Throws

std::out_of_range – if pos is greater than sv.size().
std::length_error – if the string would be larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

string &assign_printf(const char *fmt, ...)

Replaces the contents with those of the printf style format string and arguments.

Parameters

fmt – printf style format string to initialize the string with. Must not overlap with *this.
... – additional arguments matching fmt. Arguments must not overlap with *this.

Throws

std::length_error – if the string would be larger than max_size().
std::runtime_error – if an overlap is detected or vsnprintf reports error.
Allocation – This function may throw any exception thrown during allocation.

Returns

*this.

string &assign_vprintf(const char *fmt, va_list ap)

Replaces the contents with those of the vprintf style format string and arguments.

Parameters

fmt – vprintf style format string to initialize the string with. Must not overlap with *this.
ap – va_list as initialized with va_start. Arguments must not overlap with *this.

Throws

std::length_error – if the string would be larger than max_size().
std::runtime_error – if an overlap is detected or vsnprintf reports error.
Allocation – This function may throw any exception thrown during allocation.

Returns

*this.

constexpr reference at(size_type pos)

Returns a reference to the character at specified location pos.

Bounds checking is performed.

Parameters: pos – Position of the character to return.
Throws: std::out_of_range – if pos is greater than size().
Returns: Reference to the character at pos.

constexpr const_reference at(size_type pos) const

Returns a reference to the character at specified location pos.

Bounds checking is performed.

Parameters: pos – Position of the character to return.
Throws: std::out_of_range – if pos is greater than size().
Returns: Reference to the character at pos.

constexpr reference operator[](size_type pos)

Returns a reference to the character at specified location pos.

No bounds checking is performed.

Parameters: pos – Position of the character to return.
Returns: Reference to the character at pos.

constexpr const_reference operator[](size_type pos) const

Returns a reference to the character at specified location pos.

No bounds checking is performed.

Parameters: pos – Position of the character to return.
Returns: Reference to the character at pos.

constexpr reference front()

Returns a reference to the first character.

Behavior is undefined if this string is empty.

Returns: Reference to the first character.

constexpr const_reference front() const

Returns a reference to the first character.

Behavior is undefined if this string is empty.

Returns: Reference to the first character.

constexpr reference back()

Returns a reference to the last character.

Behavior is undefined if this string is empty.

Returns: Reference to the last character.

constexpr const_reference back() const

Returns a reference to the last character.

Behavior is undefined if this string is empty.

Returns: Reference to the last character.

constexpr const value_type *data() const noexcept

Returns a pointer to the character array of the string.

The returned array is null-terminated.

Returns: Pointer to the character array of the string.

constexpr value_type *data() noexcept

Returns a pointer to the character array of the string.

The returned array is null-terminated.

Returns: Pointer to the character array of the string.

constexpr const value_type *c_str() const noexcept

Returns a pointer to the character array of the string.

The returned array is null-terminated.

Returns: Pointer to the character array of the string.

constexpr operator carb::cpp::string_view() const noexcept

Returns a carb::cpp::string_view constructed as if by carb::cpp::string_view(data(), size()).

Returns: A carb::cpp::string_view representing the string.

constexpr operator std::string_view() const noexcept

Returns a std::string_view constructed as if by std::string_view(data(), size()).

Returns: A std::string_view representing the string.

constexpr iterator begin() noexcept

Returns an iterator to the first character in the string.

Returns: iterator to the first character in the string.

constexpr const_iterator begin() const noexcept

Returns a constant iterator to the first character in the string.

Returns: iterator to the first character in the string.

constexpr const_iterator cbegin() const noexcept

Returns a constant iterator to the first character in the string.

Returns: iterator to the first character in the string.

constexpr iterator end() noexcept

Returns an iterator to the character following the last character of the string.

Returns: iterator to the character following the last character of the string.

constexpr const_iterator end() const noexcept

Returns a constant iterator to the character following the last character of the string.

Returns: iterator to the character following the last character of the string.

constexpr const_iterator cend() const noexcept

Returns a constant iterator to the character following the last character of the string.

Returns: iterator to the character following the last character of the string.

reverse_iterator rbegin() noexcept

Returns a reverse iterator to the first character in the reversed string.

This character is the last character in the non-reversed string.

Returns: reverse iterator to the first character in the reversed string.

const_reverse_iterator rbegin() const noexcept

Returns a constant reverse iterator to the first character in the reversed string.

This character is the last character in the non-reversed string.

Returns: reverse iterator to the first character in the reversed string.

const_reverse_iterator crbegin() const noexcept

Returns a constant reverse iterator to the first character in the reversed string.

This character is the last character in the non-reversed string.

Returns: reverse iterator to the first character in the reversed string.

reverse_iterator rend() noexcept

Returns a reverse iterator to the character following the last character in the reversed string.

This character corresponds to character before the first character in the non-reversed string.

Returns: reverse iterator to the character following the last character in the reversed string.

const_reverse_iterator rend() const noexcept

Returns a constant reverse iterator to the character following the last character in the reversed string.

This character corresponds to character before the first character in the non-reversed string.

Returns: reverse iterator to the character following the last character in the reversed string.

const_reverse_iterator crend() const noexcept

Returns a constant reverse iterator to the character following the last character in the reversed string.

This character corresponds to character before the first character in the non-reversed string.

Returns: reverse iterator to the character following the last character in the reversed string.

constexpr bool empty() const noexcept

Checks if the string is empty.

Returns: true if the string is empty, false otherwise.

constexpr size_type size() const noexcept

Returns the number of characters in the string.

Returns: the number of characters in the string.

constexpr size_type length() const noexcept

Returns the number of characters in the string.

Returns: the number of characters in the string.

constexpr size_type max_size() const noexcept

Returns the maximum number of characters that can be in the string.

Returns: the maximum number of characters that can be in the string.

void reserve(size_type new_cap)

Attempt to change the capacity of the string.

If new_cap is greater than the current capacity(), the string will allocate a new buffer equal to or larger than new_cap.

If new_cap is less than the current capacity(), the string may shrink the buffer.

If new_cap is less that the current size(), the string will shrink the buffer to fit the current size() as if by calling shrink_to_fit().

If reallocation takes place, all pointers, references, and iterators are invalidated.

Throws

std::length_error – if new_cap is larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

Returns

none.

void reserve()

Reduce the capacity of the string as if by calling shrink_to_fit().

If reallocation takes place, all pointers, references, and iterators are invalidated.

Throws: Allocation – This function may throw any exception thrown during allocation.
Returns: none.

constexpr size_type capacity() const noexcept

Returns the number of characters that can fit in the current storage array.

Returns: the number of characters that can fit in the current storage array.

void shrink_to_fit()

Reduce capacity() to size().

If reallocation takes place, all pointers, references, and iterators are invalidated.

Throws: Allocation – This function may throw any exception thrown during allocation.
Returns: none.

constexpr void clear() noexcept

Clears the contents of the string.

capacity() is not changed by this function.

All pointers, references, and iterators are invalidated.

Returns: none.

string &insert(size_type pos, size_type n, value_type c)

Inserts n copies of character c at position pos.

If reallocation occurs, all pointers, references, and iterators are invalidated.

Parameters

pos – Position to insert characters.
n – Number of characters to insert.
c – Character to insert.

Throws

std::out_of_range – if pos is greater than size().
std::length_error – if n + size() would be larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

Returns

*this.

string &insert(size_type pos, const value_type *s)

Inserts the string pointed to by s at position pos.

If reallocation occurs, all pointers, references, and iterators are invalidated.

Parameters

pos – Position to insert characters.
s – String to insert.

Throws

std::out_of_range – if pos is greater than size().
std::invalid_argument – if s is nullptr.
std::length_error – if Traits::length(s) + size() would be larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

Returns

*this.

string &insert(size_type pos, const value_type *s, size_type n)

Inserts the first n characters of the string pointed to by s at position pos.

The range can contain null characters.

If reallocation occurs, all pointers, references, and iterators are invalidated.

Parameters

pos – Position to insert characters.
s – String to insert.
n – Number of characters to insert.

Throws

std::out_of_range – if pos is greater than size().
std::invalid_argument – if s is nullptr.
std::length_error – if n + size() would be larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

Returns

*this.

string &insert(size_type pos, const string &str)

Inserts the string str at position pos.

If reallocation occurs, all pointers, references, and iterators are invalidated.

Parameters

pos – Position to insert characters.
str – String to insert.

Throws

std::out_of_range – if pos is greater than size().
std::length_error – if str.size() + size() would be larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

Returns

*this.

string &insert(size_type pos1, const string &str, size_type pos2, size_type n = npos)

Inserts the substring str.substr(pos2, n) at position pos1.

If reallocation occurs, all pointers, references, and iterators are invalidated.

Parameters

pos1 – Position to insert characters.
str – String to insert.
pos2 – Position in str to copy characters from.
n – Number of characters to insert.

Throws

std::out_of_range – if pos1 is greater than size() or pos2 is greater than str.size().
std::length_error – if n + size() would be larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

Returns

*this.

iterator insert(const_iterator p, value_type c)

Inserts the character c before the character pointed to by p.

If reallocation occurs, all pointers, references, and iterators are invalidated.

Parameters

p – Iterator to the position the character should be inserted before.
c – Character to insert.

Throws

std::out_of_range – if p is not in the range [begin(), end()].
std::length_error – if 1 + size() would be larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

Returns

Iterator to the inserted character, or p if no character was inserted.

iterator insert(const_iterator p, size_type n, value_type c)

Inserts n copies of the character c before the character pointed to by p.

If reallocation occurs, all pointers, references, and iterators are invalidated.

Parameters

p – Iterator to the position the character should be inserted before.
n – Number of characters to inserts.
c – Character to insert.

Throws

std::out_of_range – if p is not in the range [begin(), end()].
std::length_error – if n + size() would be larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

Returns

Iterator to the first inserted character, or p if no character was inserted.

template<class InputIterator> iterator insert(const_iterator p, InputIterator first, InputIterator last)

Inserts characters from the range [first, last) before the character pointed to by p.

If reallocation occurs, all pointers, references, and iterators are invalidated.

Parameters

p – Iterator to the position the character should be inserted before.
first – Iterator to the first character to insert.
last – Iterator to the first character not to be inserted.

Throws

std::out_of_range – if p is not in the range [begin(), end()].
std::length_error – if std::distance(first, last) + size() would be larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

Returns

Iterator to the first inserted character, or p if no character was inserted.

iterator insert(const_iterator p, std::initializer_list<value_type> ilist)

Inserts the characters in ilist before the character pointed to by p.

If reallocation occurs, all pointers, references, and iterators are invalidated.

Parameters

p – Iterator to the position the character should be inserted before.
ilist – Initializer list of characters to insert.

Throws

std::out_of_range – if p is not in the range [begin(), end()].
std::length_error – if ilist.size() + size() would be larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

Returns

Iterator to the first inserted character, or p if no character was inserted.

string &insert(size_type pos, const std::string &str)

Inserts the string str at position pos.

If reallocation occurs, all pointers, references, and iterators are invalidated.

Parameters

pos – Position to insert characters.
str – String to insert.

Throws

std::out_of_range – if pos is greater than size().
std::length_error – if str.size() + size() would be larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

Returns

*this.

string &insert(size_type pos1, const std::string &str, size_type pos2, size_type n = npos)

Inserts the substring str.substr(pos2, n) at position pos1.

If reallocation occurs, all pointers, references, and iterators are invalidated.

Parameters

pos1 – Position to insert characters.
str – String to insert.
pos2 – Position in str to copy characters from.
n – Number of characters to insert.

Throws

std::out_of_range – if pos1 is greater than size() or pos2 is greater than str.size().
std::length_error – if n + size() would be larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

Returns

*this.

string &insert(size_type pos, const carb::cpp::string_view &sv)

Inserts the string_view sv at position pos.

If reallocation occurs, all pointers, references, and iterators are invalidated.

Parameters

pos – Position to insert characters.
sv – String view to insert.

Throws

std::out_of_range – if pos is greater than size().
std::length_error – if str.size() + size() would be larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

Returns

*this.

string &insert(size_type pos1, const carb::cpp::string_view &sv, size_type pos2, size_type n = npos)

Inserts the substring sv.substr(pos2, n) at position pos1.

If reallocation occurs, all pointers, references, and iterators are invalidated.

Parameters

pos1 – Position to insert characters.
sv – String view to insert.
pos2 – Position in str to copy characters from.
n – Number of characters to insert.

Throws

std::out_of_range – if pos1 is greater than size() or pos2 is greater than sv.size().
std::length_error – if n + size() would be larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

Returns

*this.

template<typename T, typename = detail::is_sv_convertible<T>> string &insert(size_type pos, const T &t)

Implicitly converts t to type std::string_view and inserts that string_view at position pos.

This overload participates in overload resolution only if std::is_convertible_v<const T&, std::string_view> is true.

If reallocation occurs, all pointers, references, and iterators are invalidated.

Parameters

pos – Position to insert characters.
t – Object that can be converted to std::string_view to initialize with.

Throws

std::out_of_range – if pos is greater than size().
std::length_error – if str.size() + size() would be larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

Returns

*this.

template<typename T, typename = detail::is_sv_convertible<T>> string &insert(size_type pos1, const T &t, size_type pos2, size_type n = npos)

Implicitly converts t to type std::string_view and inserts inserts the substring sv.substr(pos2, n) at position pos1.

This overload participates in overload resolution only if std::is_convertible_v<const T&, std::string_view> is true.

If reallocation occurs, all pointers, references, and iterators are invalidated.

Parameters

pos1 – Position to insert characters.
t – Object that can be converted to std::string_view to initialize with.
pos2 – Position in str to copy characters from.
n – Number of characters to insert.

Throws

std::out_of_range – if pos1 is greater than size() or pos2 is greater than sv.size().
std::length_error – if n + size() would be larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

Returns

*this.

string &insert_printf(size_type pos, const char *fmt, ...)

Inserts the printf style format string and arguments before the pos position.

Parameters

pos – Position to insert characters.
fmt – printf style format string to initialize the string with. Must not overlap with *this.
... – additional arguments matching fmt. Arguments must not overlap with *this.

Throws

std::out_of_range – if pos is not in the range [0, size()].
std::length_error – if the resulting string would be larger than max_size().
std::runtime_error – if an overlap is detected or vsnprintf reports error.
Allocation – This function may throw any exception thrown during allocation.

Returns

*this.

string &insert_vprintf(size_type pos, const char *fmt, va_list ap)

Inserts the vprintf style format string and arguments before the pos position.

Parameters

pos – Position to insert characters.
fmt – vprintf style format string to initialize the string with. Must not overlap with *this.
ap – va_list as initialized by va_start. Arguments must not overlap with *this.

Throws

std::out_of_range – if pos is not in the range [0, size()].
std::length_error – if the resulting string would be larger than max_size().
std::runtime_error – if an overlap is detected or vsnprintf reports error.
Allocation – This function may throw any exception thrown during allocation.

Returns

*this.

iterator insert_printf(const_iterator p, const char *fmt, ...)

Inserts the printf style format string and arguments before the character pointed to by p.

Parameters

p – Iterator to the position the string should be inserted before.
fmt – printf style format string to initialize the string with. Must not overlap with *this.
... – additional arguments matching fmt. Arguments must not overlap with *this.

Throws

std::out_of_range – if p is not in the range [begin(), end()].
std::length_error – if the resulting string would be larger than max_size().
std::runtime_error – if an overlap is detected or vsnprintf reports error.
Allocation – This function may throw any exception thrown during allocation.

Returns

Iterator to the first inserted character, or p if nothing was inserted.

iterator insert_vprintf(const_iterator p, const char *fmt, va_list ap)

Inserts the vprintf style format string and arguments before the character pointed to by p.

Parameters

p – Iterator to the position the string should be inserted before.
fmt – vprintf style format string to initialize the string with. Must not overlap with *this.
ap – va_list as initialized by va_start. Arguments must not overlap with *this.

Throws

std::out_of_range – if p is not in the range [begin(), end()].
std::length_error – if the resulting string would be larger than max_size().
std::runtime_error – if an overlap is detected or vsnprintf reports error.
Allocation – This function may throw any exception thrown during allocation.

Returns

Iterator to the first inserted character, or p if nothing was inserted.

constexpr string &erase(size_type pos = 0, size_type n = npos)

Erases n characters from the string starting at pos.

If n is npos or pos + n > size(), characters are erased to the end of the string.

Pointers, references, and iterators may be invalidated.

Parameters

pos – Position to begin erasing.
n – Number of characters to erase.

Throws

std::out_of_range – if pos is greater than size().

Returns

*this.

constexpr iterator erase(const_iterator pos)

Erases the character pointed to by pos.

Pointers, references, and iterators may be invalidated.

Parameters: pos – Position to erase character at.
Returns: iterator pointing to the character immediately following the character erased, or end() if no such character exists.

constexpr iterator erase(const_iterator first, const_iterator last)

Erases characters in the range [first, last).

Pointers, references, and iterators may be invalidated.

Parameters

first – Position to begin erasing at.
last – Position to stop erasing at.

Throws

std::out_of_range – if the range [first, last) is invalid (not in the range [begin(), end()], or first > last.

Returns

iterator pointing to the character last pointed to before the erase, or end() if no such character exists.

void push_back(value_type c)

Appends the character c to the string.

If reallocation occurs, all pointers, references, and iterators are invalidated.

Throws

std::length_error – if the function would result in size() being larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

Returns

none.

constexpr void pop_back()

Removes the last character from the string.

Pointers, references, and iterators may be invalidated.

Throws: std::runtime_error – if the string is empty().
Returns: none.

string &append(size_type n, value_type c)

Appends n copies of character c to the end of the string.

If reallocation occurs, all pointers, references, and iterators are invalidated.

Parameters

n – Number of characters to append.
c – Character to append.

Throws

std::length_error – if the function would result in size() being larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

Returns

*this.

string &append(const string &str)

Appends str to the end of the string.

If reallocation occurs, all pointers, references, and iterators are invalidated.

Parameters

str – The string to append.

Throws

std::length_error – if the function would result in size() being larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

Returns

*this.

string &append(const string &str, size_type pos, size_type n = npos)

Appends the substring str.substr(pos2, n) to the end of the string.

If reallocation occurs, all pointers, references, and iterators are invalidated.

Parameters

str – The string to append.
pos – Position of the first character to append.
n – Number of characters to append.

Throws

std::out_of_range – if pos is greater than str.size().
std::length_error – if the function would result in size() being larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

Returns

*this.

string &append(const value_type *s, size_type n)

Appends n character of the string s to the end of the string.

The range can contain nulls.

If reallocation occurs, all pointers, references, and iterators are invalidated.

Parameters

s – String to append characters from.
n – Number of characters to append.

Throws

std::invalid_argument – if s is nullptr.
std::length_error – if the function would result in size() being larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

Returns

*this.

string &append(const value_type *s)

Appends the null-terminated string s to the end of the string.

Behavior is undefined if s is not a valid string.

If reallocation occurs, all pointers, references, and iterators are invalidated.

Parameters

s – String to append characters from.

Throws

std::invalid_argument – if s is nullptr.
std::length_error – if the function would result in size() being larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

Returns

*this.

template<class InputIterator> string &append(InputIterator first, InputIterator last)

Appends characters in the range [first, last) to the string.

If reallocation occurs, all pointers, references, and iterators are invalidated.

Parameters

first – First character in the range to append.
last – End of the range to append.

Throws

std::length_error – if the function would result in size() being larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

Returns

*this.

string &append(std::initializer_list<value_type> ilist)

Appends characters in ilist to the string.

If reallocation occurs, all pointers, references, and iterators are invalidated.

Parameters

ilist – Initializer list of characters to append.

Throws

std::length_error – if the function would result in size() being larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

Returns

*this.

string &append(const std::string &str)

Appends str to the end of the string.

If reallocation occurs, all pointers, references, and iterators are invalidated.

Parameters

str – The string to append.

Throws

std::length_error – if the function would result in size() being larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

Returns

*this.

string &append(const std::string &str, size_type pos, size_type n = npos)

Appends the substring str.substr(pos2, n) to the end of the string.

If reallocation occurs, all pointers, references, and iterators are invalidated.

Parameters

str – The string to append.
pos – Position of the first character to append.
n – Number of characters to append.

Throws

std::out_of_range – if pos is greater than str.size().
std::length_error – if the function would result in size() being larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

Returns

*this.

string &append(const carb::cpp::string_view &sv)

Appends sv to the end of the string.

If reallocation occurs, all pointers, references, and iterators are invalidated.

Parameters

sv – The string view to append.

Throws

std::length_error – if the function would result in size() being larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

Returns

*this.

string &append(const carb::cpp::string_view &sv, size_type pos, size_type n = npos)

Appends the substring sv.substr(pos2, n) to the end of the string.

If reallocation occurs, all pointers, references, and iterators are invalidated.

Parameters

sv – The string view to append.
pos – Position of the first character to append.
n – Number of characters to append.

Throws

std::out_of_range – if pos is greater than str.size().
std::length_error – if the function would result in size() being larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

Returns

*this.

template<typename T, typename = detail::is_sv_convertible<T>> string &append(const T &t)

Implicitly converts t to type std::string_view and appends it to the end of the string.

This overload participates in overload resolution only if std::is_convertible_v<const T&, std::string_view> is true.

If reallocation occurs, all pointers, references, and iterators are invalidated.

Parameters

t – Object that can be converted to std::string_view to initialize with.

Throws

std::length_error – if the function would result in size() being larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

Returns

*this.

template<typename T, typename = detail::is_sv_convertible<T>> string &append(const T &t, size_type pos, size_type n = npos)

Implicitly converts t to type std::string_view and appends the substring sv.substr(pos2, n) to the end of the string.

This overload participates in overload resolution only if std::is_convertible_v<const T&, std::string_view> is true.

If reallocation occurs, all pointers, references, and iterators are invalidated.

Parameters

t – Object that can be converted to std::string_view to initialize with.
pos – Position of the first character to append.
n – Number of characters to append.

Throws

std::out_of_range – if pos is greater than str.size().
std::length_error – if the function would result in size() being larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

Returns

*this.

string &append_printf(const char *fmt, ...)

Appends the printf style format string and arguments to the string.

Parameters

fmt – printf style format string to initialize the string with. Must not overlap with *this.
... – additional arguments matching fmt. Arguments must not overlap with *this.

Throws

std::length_error – if the resulting string would be larger than max_size().
std::runtime_error – if an overlap is detected or vsnprintf reports error.
Allocation – This function may throw any exception thrown during allocation.

Returns

*this.

string &append_vprintf(const char *fmt, va_list ap)

Appends the printf style format string and arguments to the string.

Parameters

fmt – printf style format string to initialize the string with. Must not overlap with *this.
ap – va_list as initialized by va_start. Arguments must not overlap with *this.

Throws

std::length_error – if the resulting string would be larger than max_size().
std::runtime_error – if an overlap is detected or vsnprintf reports error.
Allocation – This function may throw any exception thrown during allocation.

Returns

*this.

string &operator+=(const string &str)

Appends str to the end of the string.

If reallocation occurs, all pointers, references, and iterators are invalidated.

Parameters

str – The string to append.

Throws

std::length_error – if the function would result in size() being larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

Returns

*this.

string &operator+=(value_type c)

Appends the character c to the end of the string.

If reallocation occurs, all pointers, references, and iterators are invalidated.

Parameters

c – Character to append.

Throws

std::length_error – if the function would result in size() being larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

Returns

*this.

string &operator+=(const value_type *s)

Appends the null-terminated string s to the end of the string.

Behavior is undefined if s is not a valid string.

If reallocation occurs, all pointers, references, and iterators are invalidated.

Parameters

s – String to append characters from.

Throws

std::invalid_argument – if s is nullptr.
std::length_error – if the function would result in size() being larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

Returns

*this.

string &operator+=(std::initializer_list<value_type> ilist)

Appends characters in ilist to the string.

If reallocation occurs, all pointers, references, and iterators are invalidated.

Parameters

ilist – Initializer list of characters to append.

Throws

std::length_error – if the function would result in size() being larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

Returns

*this.

string &operator+=(const std::string &str)

Appends str to the end of the string.

If reallocation occurs, all pointers, references, and iterators are invalidated.

Parameters

str – The string to append.

Throws

std::length_error – if the function would result in size() being larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

Returns

*this.

string &operator+=(const carb::cpp::string_view &sv)

Appends sv to the end of the string.

If reallocation occurs, all pointers, references, and iterators are invalidated.

Parameters

sv – The string view to append.

Throws

std::length_error – if the function would result in size() being larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

Returns

*this.

template<typename T, typename = detail::is_sv_convertible<T>> string &operator+=(const T &t)

Implicitly converts t to type std::string_view and appends it to the end of the string.

This overload participates in overload resolution only if std::is_convertible_v<const T&, std::string_view> is true.

If reallocation occurs, all pointers, references, and iterators are invalidated.

Parameters

t – Object that can be converted to std::string_view to append.

Throws

std::length_error – if the function would result in size() being larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

Returns

*this.

constexpr int compare(const string &str) const noexcept

Compares str to this string.

Comparison is performed as follows:
If Traits::compare(this, str, min(size(), str.size())) < 0, a negative value is returned
If Traits::compare(this, str, min(size(), str.size())) == 0, then:
    If size() < str.size(), a negative value is returned
    If size() = str.size(), zero is returned
    If size() > str.size(), a positive value is returned
If Traits::compare(this, str, min(size(), str.size())) > 0, a positive value is returned

Parameters: str – String to compare to.
Returns: A negative value if *this appears before the other string in lexicographical order, zero if *this and the other string compare equivalent, or a positive value if *this appears after the other string in lexicographical order.

constexpr int compare(size_type pos1, size_type n1, const string &str) const

Compares str to the substring substr(pos1, n1).

See also

compare() for details on how the comparison is performed.

Parameters

pos1 – Position to start this substring.
n1 – Number of characters in this substring.
str – String to compare to.

Throws

std::out_of_range – if pos1 is greater than size().

Returns

A negative value if *this appears before the other string in lexicographical order, zero if *this and the other string compare equivalent, or a positive value if *this appears after the other string in lexicographical order.

constexpr int compare(size_type pos1, size_type n1, const string &str, size_type pos2, size_type n2 = npos) const

Compares str.substr(pos2, n2) to the substring substr(pos1, n1).

See also

compare() for details on how the comparison is performed.

Parameters

pos1 – Position to start this substring.
n1 – Number of characters in this substring.
str – String to compare to.
pos2 – Position to start other substring.
n2 – Number of characters in other substring.

Throws

std::out_of_range – if pos1 is greater than size() or pos2 is greater than str.size().

Returns

A negative value if *this appears before the other string in lexicographical order, zero if *this and the other string compare equivalent, or a positive value if *this appears after the other string in lexicographical order.

constexpr int compare(const value_type *s) const

Compares the null-terminated string s to this string.

See also

compare() for details on how the comparison is performed.

Parameters: s – String to compare to.
Throws: std::invalid_argument – if s is nullptr.
Returns: A negative value if *this appears before the other string in lexicographical order, zero if *this and the other string compare equivalent, or a positive value if *this appears after the other string in lexicographical order.

constexpr int compare(size_type pos1, size_type n1, const value_type *s) const

Compares the null-terminated string s to the substring substr(pos1, n1).

See also

compare() for details on how the comparison is performed.

Parameters

pos1 – Position to start this substring.
n1 – Number of characters in this substring.
s – String to compare to.

Throws

std::out_of_range – if pos1 is greater than size().
std::invalid_argument – if s is nullptr.

Returns

A negative value if *this appears before the other string in lexicographical order, zero if *this and the other string compare equivalent, or a positive value if *this appears after the other string in lexicographical order.

constexpr int compare(size_type pos1, size_type n1, const value_type *s, size_type n2) const

Compares the first n2 characters of string string s to the substring substr(pos1, n1).

See also

compare() for details on how the comparison is performed.

Parameters

pos1 – Position to start this substring.
n1 – Number of characters in this substring.
s – String to compare to.
n2 – Number of characters of s to compare.

Throws

std::out_of_range – if pos1 is greater than size().
std::invalid_argument – if s is nullptr.

Returns

A negative value if *this appears before the other string in lexicographical order, zero if *this and the other string compare equivalent, or a positive value if *this appears after the other string in lexicographical order.

int compare(const std::string &str) const noexcept

Compares str to this string.

See also

compare() for details on how the comparison is performed.

Parameters: str – String to compare to.
Returns: A negative value if *this appears before the other string in lexicographical order, zero if *this and the other string compare equivalent, or a positive value if *this appears after the other string in lexicographical order.

int compare(size_type pos1, size_type n1, const std::string &str) const

Compares str to the substring substr(pos1, n1).

See also

compare() for details on how the comparison is performed.

Parameters

pos1 – Position to start this substring.
n1 – Number of characters in this substring.
str – String to compare to.

Throws

std::out_of_range – if pos1 is greater than size().

Returns

A negative value if *this appears before the other string in lexicographical order, zero if *this and the other string compare equivalent, or a positive value if *this appears after the other string in lexicographical order.

int compare(size_type pos1, size_type n1, const std::string &str, size_type pos2, size_type n2 = npos) const

Compares str.substr(pos2, n2) to the substring substr(pos1, n1).

See also

compare() for details on how the comparison is performed.

Parameters

pos1 – Position to start this substring.
n1 – Number of characters in this substring.
str – String to compare to.
pos2 – Position to start other substring.
n2 – Number of characters in other substring.

Throws

std::out_of_range – if pos1 is greater than size() or pos2 is greater than str.size().

Returns

A negative value if *this appears before the other string in lexicographical order, zero if *this and the other string compare equivalent, or a positive value if *this appears after the other string in lexicographical order.

constexpr int compare(const carb::cpp::string_view &sv) const noexcept

Compares sv to this string.

See also

compare() for details on how the comparison is performed.

Parameters: sv – String view to compare to.
Returns: A negative value if *this appears before the other string in lexicographical order, zero if *this and the other string compare equivalent, or a positive value if *this appears after the other string in lexicographical order.

constexpr int compare(size_type pos1, size_type n1, const carb::cpp::string_view &sv) const

Compares sv to the substring substr(pos1, n1).

See also

compare() for details on how the comparison is performed.

Parameters

pos1 – Position to start this substring.
n1 – Number of characters in this substring.
sv – String view to compare to.

Throws

std::out_of_range – if pos1 is greater than size().

Returns

A negative value if *this appears before the other string in lexicographical order, zero if *this and the other string compare equivalent, or a positive value if *this appears after the other string in lexicographical order.

constexpr int compare(size_type pos1, size_type n1, const carb::cpp::string_view &sv, size_type pos2, size_type n2 = npos) const

Compares sv.substr(pos2, n2) to the substring substr(pos1, n1).

See also

compare() for details on how the comparison is performed.

Parameters

pos1 – Position to start this substring.
n1 – Number of characters in this substring.
sv – String view to compare to.
pos2 – Position to start other substring.
n2 – Number of characters in other substring.

Throws

std::out_of_range – if pos1 is greater than size() or pos2 is greater than sv.size().

Returns

A negative value if *this appears before the other string in lexicographical order, zero if *this and the other string compare equivalent, or a positive value if *this appears after the other string in lexicographical order.

template<typename T, typename = detail::is_sv_convertible<T>> constexpr int compare(const T &t) const noexcept

Implicitly converts t to type std::string_view and compares it to the string.

This overload participates in overload resolution only if std::is_convertible_v<const T&, std::string_view> is true.

See also

compare() for details on how the comparison is performed.

Parameters: t – Object that can be converted to std::string_view to compare to.
Returns: A negative value if *this appears before the other string in lexicographical order, zero if *this and the other string compare equivalent, or a positive value if *this appears after the other string in lexicographical order.

template<typename T, typename = detail::is_sv_convertible<T>> constexpr int compare(size_type pos1, size_type n1, const T &t) const

Implicitly converts t to type std::string_view and compares it to the substring substr(pos1, n1).

This overload participates in overload resolution only if std::is_convertible_v<const T&, std::string_view> is true.

See also

compare() for details on how the comparison is performed.

Parameters

pos1 – Position to start this substring.
n1 – Number of characters in this substring.
t – Object that can be converted to std::string_view to compare to.

Throws

std::out_of_range – if pos1 is greater than size().

Returns

A negative value if *this appears before the other string in lexicographical order, zero if *this and the other string compare equivalent, or a positive value if *this appears after the other string in lexicographical order.

template<typename T, typename = detail::is_sv_convertible<T>> constexpr int compare(size_type pos1, size_type n1, const T &t, size_type pos2, size_type n2 = npos) const

Implicitly converts t to type std::string_view and compares sv.substr(pos2, n2) to the substring substr(pos1, n1).

This overload participates in overload resolution only if std::is_convertible_v<const T&, std::string_view> is true.

See also

compare() for details on how the comparison is performed.

Parameters

pos1 – Position to start this substring.
n1 – Number of characters in this substring.
t – Object that can be converted to std::string_view to compare to.
pos2 – Position to start other substring.
n2 – Number of characters in other substring.

Throws

std::out_of_range – if pos1 is greater than size() or pos2 is greater than sv.size().

Returns

A negative value if *this appears before the other string in lexicographical order, zero if *this and the other string compare equivalent, or a positive value if *this appears after the other string in lexicographical order.

constexpr bool starts_with(value_type c) const noexcept

Checks if the string begins with the character c.

Parameters: c – Character to check.
Returns: true if the string starts with c, false otherwise.

constexpr bool starts_with(const_pointer s) const

Checks if the string begins with the string s.

Parameters: s – String to check.
Throws: std::invalid_argument – if s is nullptr.
Returns: true if the string starts with s, false otherwise.

constexpr bool starts_with(carb::cpp::string_view sv) const noexcept

Checks if the string begins with the string view sv.

Parameters: sv – String view to check.
Returns: true if the string starts with sv, false otherwise.

constexpr bool starts_with(std::string_view sv) const noexcept

Checks if the string begins with the string view sv.

Parameters: sv – String view to check.
Returns: true if the string starts with sv, false otherwise.

constexpr bool ends_with(value_type c) const noexcept

Checks if the string ends with the character c.

Parameters: c – Character to check.
Returns: true if the string ends with c, false otherwise.

constexpr bool ends_with(const_pointer s) const

Checks if the string ends with the string s.

Parameters: s – String to check.
Throws: std::invalid_argument – if s is nullptr.
Returns: true if the string ends with s, false otherwise.

constexpr bool ends_with(carb::cpp::string_view sv) const noexcept

Checks if the string ends with the string view sv.

Parameters: sv – String view to check.
Returns: true if the string ends with sv, false otherwise.

constexpr bool ends_with(std::string_view sv) const noexcept

Checks if the string ends with the string view sv.

Parameters: sv – String view to check.
Returns: true if the string ends with sv, false otherwise.

constexpr bool contains(value_type c) const noexcept

Checks if the string contains the character c.

Parameters: c – Character to check.
Returns: true if the string contains c, false otherwise.

constexpr bool contains(const_pointer s) const

Checks if the string contains the string s.

Parameters: s – String to check.
Throws: std::invalid_argument – if s is nullptr.
Returns: true if the string contains s, false otherwise.

constexpr bool contains(carb::cpp::string_view sv) const noexcept

Checks if the string contains the string view sv.

Parameters: sv – String view to check.
Returns: true if the string contains sv, false otherwise.

constexpr bool contains(std::string_view sv) const noexcept

Checks if the string contains the string view sv.

Parameters: sv – String view to check.
Returns: true if the string contains sv, false otherwise.

string &replace(size_type pos1, size_type n1, const string &str)

Replaces the portion of this string [pos, pos + n1) with str.

If n == npos, or pos + n is greater than size(), the substring to the end of the string is replaced.

All pointers, references, and iterators may be invalidated.

Parameters

pos1 – Position to start replacement.
n1 – Number of characters to replace.
str – String to replace characters with.

Throws

std::out_of_range – if pos1 is greater than size().
std::length_error – if the function would result in size() being larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

Returns

*this.

string &replace(size_type pos1, size_type n1, const string &str, size_type pos2, size_type n2 = npos)

Replaces the portion of this string [pos, pos + n1) with the substring str.substr(pos2, n2).

If n == npos, or pos + n is greater than size(), the substring to the end of the string is replaced.

All pointers, references, and iterators may be invalidated.

Parameters

pos1 – Position to start replacement.
n1 – Number of characters to replace.
str – String to replace characters with.
pos2 – Position of substring to replace characters with.
n2 – Number of characters in the substring to replace with.

Throws

std::out_of_range – if pos1 is greater than size() or pos2 is greater than str.size().
std::length_error – if the function would result in size() being larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

Returns

*this.

template<class InputIterator> string &replace(const_iterator i1, const_iterator i2, InputIterator j1, InputIterator j2)

Replaces the portion of this string [i1, i2) with [j1, j2).

All pointers, references, and iterators may be invalidated.

Parameters

i1 – Position to start replacement.
i2 – Position to stop replacement.
j1 – Start position of replacement characters.
j2 – End position of replacement characters.

Throws

std::out_of_range – if the range [i1,i2) is invalid (not in the range [begin(), end()], or i1 > i2.
std::length_error – if the function would result in size() being larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

Returns

*this.

string &replace(size_type pos, size_type n1, const value_type *s, size_type n2)

Replaces the portion of this string [pos, pos + n1) with n2 characters from string s.

The character sequence can contain null characters. If n == npos, or pos + n is greater than size(), the substring to the end of the string is replaced.

All pointers, references, and iterators may be invalidated.

Parameters

pos – Position to start replacement.
n1 – Number of characters to replace.
s – String to replace characters with.
n2 – The number of replacement characters.

Throws

std::out_of_range – if pos is greater than size().
std::invalid_argument – if s is nullptr.
std::length_error – if the function would result in size() being larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

Returns

*this.

string &replace(size_type pos, size_type n1, const value_type *s)

Replaces the portion of this string [pos, pos + n1) with the null-terminated string s.

If n == npos, or pos + n is greater than size(), the substring to the end of the string is replaced.

All pointers, references, and iterators may be invalidated.

Parameters

pos – Position to start replacement.
n1 – Number of characters to replace.
s – String to replace characters with.

Throws

std::out_of_range – if pos is greater than size().
std::invalid_argument – if s is nullptr.
std::length_error – if the function would result in size() being larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

Returns

*this.

string &replace(size_type pos, size_type n1, size_type n2, value_type c)

Replaces the portion of this string [pos, pos + n1) with n2 copies of character c.

If n == npos, or pos + n is greater than size(), the substring to the end of the string is replaced.

All pointers, references, and iterators may be invalidated.

Parameters

pos – Position to start replacement.
n1 – Number of characters to replace.
n2 – Number of characters to replace with.
c – Character to replace with.

Throws

std::out_of_range – if pos is greater than size().
std::length_error – if the function would result in size() being larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

Returns

*this.

string &replace(size_type pos1, size_type n1, const std::string &str)

Replaces the portion of this string [pos, pos + n1) with str.

If n == npos, or pos + n is greater than size(), the substring to the end of the string is replaced.

All pointers, references, and iterators may be invalidated.

Parameters

pos1 – Position to start replacement.
n1 – Number of characters to replace.
str – String to replace characters with.

Throws

std::out_of_range – if pos1 is greater than size().
std::length_error – if the function would result in size() being larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

Returns

*this.

string &replace(size_type pos1, size_type n1, const std::string &str, size_type pos2, size_type n2 = npos)

Replaces the portion of this string [pos, pos + n1) with the substring str.substr(pos2, n2).

If n == npos, or pos + n is greater than size(), the substring to the end of the string is replaced.

All pointers, references, and iterators may be invalidated.

Parameters

pos1 – Position to start replacement.
n1 – Number of characters to replace.
str – String to replace characters with.
pos2 – Position of substring to replace characters with.
n2 – Number of characters in the substring to replace with.

Throws

std::out_of_range – if pos1 is greater than size() or pos2 is greater than str.size().
std::length_error – if the function would result in size() being larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

Returns

*this.

string &replace(size_type pos1, size_type n1, const carb::cpp::string_view &sv)

Replaces the portion of this string [pos, pos + n1) with sv.

If n == npos, or pos + n is greater than size(), the substring to the end of the string is replaced.

All pointers, references, and iterators may be invalidated.

Parameters

pos1 – Position to start replacement.
n1 – Number of characters to replace.
sv – String view to replace characters with.

Throws

std::out_of_range – if pos1 is greater than size().
std::length_error – if the function would result in size() being larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

Returns

*this.

string &replace(size_type pos1, size_type n1, const carb::cpp::string_view &sv, size_type pos2, size_type n2 = npos)

Replaces the portion of this string [pos, pos + n1) with the substring sv.substr(pos2, n2).

If n == npos, or pos + n is greater than size(), the substring to the end of the string is replaced.

All pointers, references, and iterators may be invalidated.

Parameters

pos1 – Position to start replacement.
n1 – Number of characters to replace.
sv – String view to replace characters with.
pos2 – Position of substring to replace characters with.
n2 – Number of characters in the substring to replace with.

Throws

std::out_of_range – if pos1 is greater than size() or pos2 is greater than sv.size().
std::length_error – if the function would result in size() being larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

Returns

*this.

template<typename T, typename = detail::is_sv_convertible<T>> string &replace(size_type pos1, size_type n1, const T &t)

Implicitly converts t to type std::string_view and replaces the portion of this string [pos, pos + n1) with sv.

If n == npos, or pos + n is greater than size(), the substring to the end of the string is replaced. This overload participates in overload resolution only if std::is_convertible_v<const T&, std::string_view> is true.

All pointers, references, and iterators may be invalidated.

Parameters

pos1 – Position to start replacement.
n1 – Number of characters to replace.
t – Object that can be converted to std::string_view to replace characters with.

Throws

std::out_of_range – if pos1 is greater than size().
std::length_error – if the function would result in size() being larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

Returns

*this.

template<typename T, typename = detail::is_sv_convertible<T>> string &replace(size_type pos1, size_type n1, const T &t, size_type pos2, size_type n2)

Implicitly converts t to type std::string_view and replaces the portion of this string [pos, pos + n1) with the substring sv.substr(pos2, n2).

If n == npos, or `pos + n is greater than size(), the substring to the end of the string is replaced. This overload participates in overload resolution only if std::is_convertible_v<const T&, std::string_view> is true.

All pointers, references, and iterators may be invalidated.

Parameters

pos1 – Position to start replacement.
n1 – Number of characters to replace.
t – Object that can be converted to std::string_view to replace characters with.
pos2 – Position of substring to replace characters with.
n2 – Number of characters in the substring to replace with.

Throws

std::out_of_range – if pos1 is greater than size() or pos2 is greater than sv.size().
std::length_error – if the function would result in size() being larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

Returns

*this.

string &replace(const_iterator i1, const_iterator i2, const string &str)

Replaces the portion of this string [i1, i2) with str.

All pointers, references, and iterators may be invalidated.

Parameters

i1 – Position to start replacement.
i2 – Position to stop replacement.
str – String to replace characters with.

Throws

std::out_of_range – if the range [i1,i2) is invalid (not in the range [begin(), end()], or i1 > i2.
std::length_error – if the function would result in size() being larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

Returns

*this.

string &replace(const_iterator i1, const_iterator i2, const value_type *s, size_type n)

Replaces the portion of this string [i1, i2) with n characters from string s.

The character sequence can contain null characters.

All pointers, references, and iterators may be invalidated.

Parameters

i1 – Position to start replacement.
i2 – Position to stop replacement.
s – String to replace characters with.
n – The number of replacement characters.

Throws

std::out_of_range – if the range [i1,i2) is invalid (not in the range [begin(), end()], or i1 > i2.
std::invalid_argument – if s is nullptr.
std::length_error – if the function would result in size() being larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

Returns

*this.

string &replace(const_iterator i1, const_iterator i2, const value_type *s)

Replaces the portion of this string [i1, i2) with the null-terminated string s.

All pointers, references, and iterators may be invalidated.

Parameters

i1 – Position to start replacement.
i2 – Position to stop replacement.
s – String to replace characters with.

Throws

std::out_of_range – if the range [i1,i2) is invalid (not in the range [begin(), end()], or i1 > i2.
std::invalid_argument – if s is nullptr.
std::length_error – if the function would result in size() being larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

Returns

*this.

string &replace(const_iterator i1, const_iterator i2, size_type n, value_type c)

Replaces the portion of this string [i1, i2) with n copies of character c.

All pointers, references, and iterators may be invalidated.

Parameters

i1 – Position to start replacement.
i2 – Position to stop replacement.
n – Number of characters to replace with.
c – Character to replace with.

Throws

std::out_of_range – if the range [i1,i2) is invalid (not in the range [begin(), end()], or i1 > i2.
std::length_error – if the function would result in size() being larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

Returns

*this.

string &replace(const_iterator i1, const_iterator i2, std::initializer_list<value_type> ilist)

Replaces the portion of this string [i1, i2) with the characters in ilist.

All pointers, references, and iterators may be invalidated.

Parameters

i1 – Position to start replacement.
i2 – Position to stop replacement.
ilist – Initializer list of character to replace with.

Throws

std::out_of_range – if the range [i1,i2) is invalid (not in the range [begin(), end()], or i1 > i2.
std::length_error – if the function would result in size() being larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

Returns

*this.

string &replace(const_iterator i1, const_iterator i2, const std::string &str)

Replaces the portion of this string [i1, i2) with str.

All pointers, references, and iterators may be invalidated.

Parameters

i1 – Position to start replacement.
i2 – Position to stop replacement.
str – String to replace characters with.

Throws

std::out_of_range – if the range [i1,i2) is invalid (not in the range [begin(), end()], or i1 > i2.
std::length_error – if the function would result in size() being larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

Returns

*this.

string &replace(const_iterator i1, const_iterator i2, const carb::cpp::string_view &sv)

Replaces the portion of this string [i1, i2) with sv.

All pointers, references, and iterators may be invalidated.

Parameters

sv – String view to replace characters with.

Throws

std::out_of_range – if the range [i1,i2) is invalid (not in the range [begin(), end()], or i1 > i2.
std::length_error – if the function would result in size() being larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

Returns

*this.

template<typename T, typename = detail::is_sv_convertible<T>> string &replace(const_iterator i1, const_iterator i2, const T &t)

Implicitly converts t to type std::string_view and replaces the portion of this string [i1, i2) with sv.

This overload participates in overload resolution only if std::is_convertible_v<const T&, std::string_view> is true.

All pointers, references, and iterators may be invalidated.

Parameters

t – Object that can be converted to std::string_view to replace characters with.

Throws

std::out_of_range – if the range [i1,i2) is invalid (not in the range [begin(), end()], or i1 > i2.
std::length_error – if the function would result in size() being larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

Returns

*this.

string &replace_format(size_type pos, size_type n1, const value_type *fmt, ...)

Replaces the portion of this string [pos, pos + n1) with a printf style formatted string.

If n == npos, or pos + n is greater than size(), the substring to the end of the string is replaced.

All pointers, references, and iterators may be invalidated.

Parameters

pos – Position to start replacement.
n1 – Number of characters to replace.
fmt – printf style format string to replace characters with. Must not overlap with *this.
... – additional arguments matching fmt. Arguments must not overlap with *this.

Throws

std::out_of_range – if pos is greater than size().
std::invalid_argument – if s is nullptr.
std::length_error – if the function would result in size() being larger than max_size().
std::runtime_error – if an overlap is detected or vsnprintf reports error.
Allocation – This function may throw any exception thrown during allocation.

Returns

*this.

string &replace_vformat(size_type pos, size_type n1, const value_type *fmt, va_list ap)

Replaces the portion of this string [pos, pos + n1) with a vprintf style formatted string.

If n == npos, or pos + n is greater than size(), the substring to the end of the string is replaced.

All pointers, references, and iterators may be invalidated.

Parameters

pos – Position to start replacement.
n1 – Number of characters to replace.
fmt – printf style format string to replace characters with. Must not overlap with *this.
ap – va_list as initialized with va_start. Arguments must not overlap with *this.

Throws

std::out_of_range – if pos is greater than size().
std::invalid_argument – if s is nullptr.
std::length_error – if the function would result in size() being larger than max_size().
std::runtime_error – if an overlap is detected or vsnprintf reports error.
Allocation – This function may throw any exception thrown during allocation.

Returns

*this.

string &replace_format(const_iterator i1, const_iterator i2, const value_type *fmt, ...)

Replaces the portion of this string [i1, i2) with a printf style formatted string.

All pointers, references, and iterators may be invalidated.

Parameters

i1 – Position to start replacement.
i2 – Position to stop replacement.
fmt – printf style format string to replace characters with. Must not overlap with *this.
... – additional arguments matching fmt. Arguments must not overlap with *this.

Throws

std::out_of_range – if pos is greater than size().
std::invalid_argument – if s is nullptr.
std::length_error – if the function would result in size() being larger than max_size().
std::runtime_error – if an overlap is detected or vsnprintf reports error.
Allocation – This function may throw any exception thrown during allocation.

Returns

*this.

string &replace_vformat(const_iterator i1, const_iterator i2, const value_type *fmt, va_list ap)

Replaces the portion of this string [i1, i2) with a printf style formatted string.

All pointers, references, and iterators may be invalidated.

Parameters

i1 – Position to start replacement.
i2 – Position to stop replacement.
fmt – printf style format string to replace characters with. Must not overlap with *this.
ap – va_list as initialized with va_start. Arguments must not overlap with *this.

Throws

std::out_of_range – if pos is greater than size().
std::invalid_argument – if s is nullptr.
std::length_error – if the function would result in size() being larger than max_size().
std::runtime_error – if an overlap is detected or vsnprintf reports error.
Allocation – This function may throw any exception thrown during allocation.

Returns

*this.

string substr(size_type pos = 0, size_type n = npos) const

Returns a substring from [pos, pos + n) of this string.

If n == npos, or pos + n is greater than size(), the substring is to the end of the string.

Parameters

pos – Position to start the substring.
n – Number of characters to include in the substring.

Throws

std::out_of_range – if pos is greater than size().
Allocation – This function may throw any exception thrown during allocation.

Returns

A new string containing the substring.

constexpr size_type copy(value_type *s, size_type n, size_type pos = 0) const

Copies a substring from [pos, pos + n) to the provided destination s.

If n == npos, or pos + n is greater than size(), the substring is to the end of the string. The resulting character sequence is not null terminated.

Parameters

s – Destination to copy characters to.
n – Number of characters to include in the substring.
pos – Position to start the substring.

Throws

std::invalid_argument – if s is nullptr.
std::out_of_range – if pos is greater than size().

Returns

number of characters copied.

void resize(size_type n, value_type c)

Resizes the string to contain n characters.

If n is greater than size(), copies of the character c are appended. If n is smaller than size(), the string is shrunk to size n.

If reallocation occurs, all pointers, references, and iterators are invalidated.

Parameters

n – New size of the string.
c – Character to append when growing the string.

Throws

std::length_error – if the function would result in size() being larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

Returns

none.

void resize(size_type n)

Resizes the string to contain n characters.

If n is greater than size(), copies of NUL are appended. If n is smaller than size(), the string is shrunk to size n.

If reallocation occurs, all pointers, references, and iterators are invalidated.

Parameters

n – New size of the string.

Throws

std::length_error – if the function would result in size() being larger than max_size().
Allocation – This function may throw any exception thrown during allocation.

Returns

none.

void swap(string &str) noexcept

Swaps the contents of this string with str.

All pointers, references, and iterators may be invalidated.

Parameters: str – The string to swap with.
Returns: none.

constexpr size_type find(const string &str, size_type pos = 0) const noexcept

Finds the first substring of this string that matches str.

The search begins at pos.

Parameters

str – String to find.
pos – Position to begin the search.

Returns

Position of the first character of the matching substring, or npos if no such substring exists.

constexpr size_type find(const value_type *s, size_type pos, size_type n) const

Finds the first substring of this string that matches the first n characters of s.

The string may contain nulls.The search begins at pos.

Parameters

s – String to find.
pos – Position to begin the search.
n – Number of characters to search for.

Throws

std::invalid_argument – if s is nullptr.

Returns

Position of the first character of the matching substring, or npos if no such substring exists.

constexpr size_type find(const value_type *s, size_type pos = 0) const

Finds the first substring of this string that matches the null-terminated string s.

The search begins at pos.

Parameters

s – String to find.
pos – Position to begin the search.

Throws

std::invalid_argument – if s is nullptr.

Returns

Position of the first character of the matching substring, or npos if no such substring exists.

size_type find(const std::string &str, size_type pos = 0) const noexcept

Finds the first substring of this string that matches str.

The search begins at pos.

Parameters

str – String to find.
pos – Position to begin the search.

Returns

Position of the first character of the matching substring, or npos if no such substring exists.

constexpr size_type find(const carb::cpp::string_view &sv, size_type pos = 0) const noexcept

Finds the first substring of this string that matches sv.

The search begins at pos.

Parameters

sv – String view to find.
pos – Position to begin the search.

Returns

Position of the first character of the matching substring, or npos if no such substring exists.

template<typename T, typename = detail::is_sv_convertible<T>> constexpr size_type find(const T &t, size_type pos = 0) const noexcept

Implicitly converts t to type std::string_view and finds the first substring of this string that matches it.

The search begins at pos. This overload participates in overload resolution only if std::is_convertible_v<const T&, std::string_view> is true.

Parameters

t – Object that can be converted to std::string_view to find.
pos – Position to begin the search.

Returns

Position of the first character of the matching substring, or npos if no such substring exists.

constexpr size_type find(value_type c, size_type pos = 0) const noexcept

Finds the first substring of this string that matches c.

The search begins at pos.

Parameters

c – Character to find.
pos – Position to begin the search.

Returns

Position of the first character of the matching substring, or npos if no such substring exists.

constexpr size_type rfind(const string &str, size_type pos = npos) const noexcept

Finds the last substring of this string that matches str.

The search begins at pos. If pos == npos or pos >= size(), the whole string is searched.

Parameters

str – String to find.
pos – Position to begin the search.

Returns

Position of the first character of the matching substring, or npos if no such substring exists.

constexpr size_type rfind(const value_type *s, size_type pos, size_type n) const

Finds the last substring of this string that matches the first n characters of s.

The string may contain nulls.The search begins at pos. If pos == npos or pos >= size(), the whole string is searched.

Parameters

s – String to find.
pos – Position to begin the search.
n – Number of characters to search for.

Throws

std::invalid_argument – if s is nullptr.

Returns

Position of the first character of the matching substring, or npos if no such substring exists.

constexpr size_type rfind(const value_type *s, size_type pos = npos) const

Finds the last substring of this string that matches the null-terminated string s.

The search begins at pos. If pos == npos or pos >= size(), the whole string is searched.

Parameters

s – String to find.
pos – Position to begin the search.

Throws

std::invalid_argument – if s is nullptr.

Returns

Position of the first character of the matching substring, or npos if no such substring exists.

constexpr size_type rfind(value_type c, size_type pos = npos) const noexcept

Finds the last substring of this string that matches c.

The search begins at pos. If pos == npos or pos >= size(), the whole string is searched.

Parameters

c – Character to find.
pos – Position to begin the search.

Returns

Position of the first character of the matching substring, or npos if no such substring exists.

size_type rfind(const std::string &str, size_type pos = npos) const noexcept

Finds the last substring of this string that matches str.

The search begins at pos. If pos == npos or pos >= size(), the whole string is searched.

Parameters

str – String to find.
pos – Position to begin the search.

Returns

Position of the first character of the matching substring, or npos if no such substring exists.

constexpr size_type rfind(const carb::cpp::string_view &sv, size_type pos = npos) const noexcept

Finds the last substring of this string that matches sv.

The search begins at pos. If pos == npos or pos >= size(), the whole string is searched.

Parameters

sv – String view to find.
pos – Position to begin the search.

Returns

Position of the first character of the matching substring, or npos if no such substring exists.

template<typename T, typename = detail::is_sv_convertible<T>> constexpr size_type rfind(const T &t, size_type pos = npos) const noexcept

Implicitly converts t to type std::string_view and finds the last substring of this string that matches it.

The search begins at pos. If pos == npos or pos >= size(), the whole string is searched. This overload participates in overload resolution only if std::is_convertible_v<const T&, std::string_view> is true.

Parameters

t – Object that can be converted to std::string_view to find.
pos – Position to begin the search.

Returns

Position of the first character of the matching substring, or npos if no such substring exists.

constexpr size_type find_first_of(const string &str, size_type pos = 0) const noexcept

Finds the first character equal to one of the characters in string str.

The search begins at pos.

Parameters

str – String containing the characters to search for.
pos – Position to begin the search.

Returns

Position of the first found character, or npos if no character is found.

constexpr size_type find_first_of(const value_type *s, size_type pos, size_type n) const

Finds the first character equal to one of the characters in the first n characters of string s.

The search begins at pos.

Parameters

s – String containing the characters to search for.
pos – Position to begin the search.
n – Number of characters in s to search for.

Throws

std::invalid_argument – if s is nullptr

Returns

Position of the first found character, or npos if no character is found.

constexpr size_type find_first_of(const value_type *s, size_type pos = 0) const

Finds the first character equal to one of the characters in null-terminated string s.

The search begins at pos.

Parameters

s – String containing the characters to search for.
pos – Position to begin the search.

Throws

std::invalid_argument – if s is nullptr.

Returns

Position of the first found character, or npos if no character is found.

constexpr size_type find_first_of(value_type c, size_type pos = 0) const noexcept

Finds the first character equal to c.

The search begins at pos.

Parameters

c – Character to search for.
pos – Position to begin the search.

Returns

Position of the first found character, or npos if no character is found.

size_type find_first_of(const std::string &str, size_type pos = 0) const noexcept

Finds the first character equal to one of the characters in string str.

The search begins at pos.

Parameters

str – String containing the characters to search for.
pos – Position to begin the search.

Returns

Position of the first found character, or npos if no character is found.

constexpr size_type find_first_of(const carb::cpp::string_view &sv, size_type pos = 0) const noexcept

Finds the first character equal to one of the characters in string sv.

The search begins at pos.

Parameters

sv – String view containing the characters to search for.
pos – Position to begin the search.

Returns

Position of the first found character, or npos if no character is found.

template<typename T, typename = detail::is_sv_convertible<T>> constexpr size_type find_first_of(const T &t, size_type pos = 0) const noexcept

Implicitly converts t to type std::string_view and finds the first character equal to one of the characters in that string view.

The search begins at pos. This overload participates in overload resolution only if std::is_convertible_v<const T&, std::string_view> is true.

Parameters

t – Object that can be converted to std::string_view containing the characters to search for.
pos – Position to begin the search.

Returns

Position of the first character of the matching substring, or npos if no such substring exists.

constexpr size_type find_last_of(const string &str, size_type pos = npos) const noexcept

Finds the last character equal to one of the characters in string str.

The search begins at pos. If pos == npos or pos >= size(), the whole string is searched.

Parameters

str – String containing the characters to search for.
pos – Position to begin the search.

Returns

Position of the last found character, or npos if no character is found.

constexpr size_type find_last_of(const value_type *s, size_type pos, size_type n) const

Finds the last character equal to one of the characters in the first n characters of string s.

The search begins at pos. If pos == npos or pos >= size(), the whole string is searched.

Parameters

s – String containing the characters to search for.
pos – Position to begin the search.
n – Number of characters in s to search for.

Throws

std::invalid_argument – if s is nullptr.

Returns

Position of the last found character, or npos if no character is found.

constexpr size_type find_last_of(const value_type *s, size_type pos = npos) const

Finds the last character equal to one of the characters in the null-terminated string s.

The search begins at pos. If pos == npos or pos >= size(), the whole string is searched.

Parameters

s – String containing the characters to search for.
pos – Position to begin the search.

Throws

std::invalid_argument – if s is nullptr.

Returns

Position of the last found character, or npos if no character is found.

constexpr size_type find_last_of(value_type c, size_type pos = npos) const noexcept

Finds the last character equal to c.

The search begins at pos. If pos == npos or pos >= size(), the whole string is searched.

Parameters

c – Character to search for.
pos – Position to begin the search.

Returns

Position of the last found character, or npos if no character is found.

size_type find_last_of(const std::string &str, size_type pos = npos) const noexcept

Finds the last character equal to one of the characters in string str.

The search begins at pos. If pos == npos or pos >= size(), the whole string is searched.

Parameters

str – String containing the characters to search for.
pos – Position to begin the search.

Returns

Position of the last found character, or npos if no character is found.

constexpr size_type find_last_of(const carb::cpp::string_view &sv, size_type pos = npos) const noexcept

Finds the last character equal to one of the characters in string view sv.

The search begins at pos. If pos == npos or pos >= size(), the whole string is searched.

Parameters

sv – String view containing the characters to search for.
pos – Position to begin the search.

Returns

Position of the last found character, or npos if no character is found.

template<typename T, typename = detail::is_sv_convertible<T>> constexpr size_type find_last_of(const T &t, size_type pos = npos) const noexcept

Implicitly converts t to type std::string_view and finds the last character equal to one of the characters in that string view.

The search begins at pos. If pos == npos or pos >= size(), the whole string is searched. The search begins at pos. This overload participates in overload resolution only if std::is_convertible_v<const T&, std::string_view> is true.

Parameters

t – Object that can be converted to std::string_view containing the characters to search for.
pos – Position to begin the search.

Returns

Position of the first character of the matching substring, or npos if no such substring exists.

constexpr size_type find_first_not_of(const string &str, size_type pos = 0) const noexcept

Finds the first character not equal to one of the characters in string str.

The search begins at pos.

Parameters

str – String containing the characters to search for.
pos – Position to begin the search.

Returns

Position of the first found character, or npos if no character is found.

constexpr size_type find_first_not_of(const value_type *s, size_type pos, size_type n) const

Finds the first character not equal to one of the characters in the first n characters of string s.

The search begins at pos.

Parameters

s – String containing the characters to search for.
pos – Position to begin the search.
n – Number of characters in s to search for.

Throws

std::invalid_argument – if s is nullptr.

Returns

Position of the first found character, or npos if no character is found.

constexpr size_type find_first_not_of(const value_type *s, size_type pos = 0) const

Finds the first character not equal to one of the characters in null-terminated string s.

The search begins at pos.

Parameters

s – String containing the characters to search for.
pos – Position to begin the search.

Throws

std::invalid_argument – if s is nullptr.

Returns

Position of the first found character, or npos if no character is found.

constexpr size_type find_first_not_of(value_type c, size_type pos = 0) const noexcept

Finds the first character equal to c.

The search begins at pos.

Parameters

c – Character to search for.
pos – Position to begin the search.

Returns

Position of the first found character, or npos if no character is found.

size_type find_first_not_of(const std::string &str, size_type pos = 0) const noexcept

Finds the first character not equal to one of the characters in string str.

The search begins at pos.

Parameters

str – String containing the characters to search for.
pos – Position to begin the search.

Returns

Position of the first found character, or npos if no character is found.

constexpr size_type find_first_not_of(const carb::cpp::string_view &sv, size_type pos = 0) const noexcept

Finds the first character not equal to one of the characters in string view sv.

The search begins at pos.

Parameters

sv – String view containing the characters to search for.
pos – Position to begin the search.

Returns

Position of the first found character, or npos if no character is found.

template<typename T, typename = detail::is_sv_convertible<T>> constexpr size_type find_first_not_of(const T &t, size_type pos = 0) const noexcept

Implicitly converts t to type std::string_view and finds the first character not equal to one of the characters in that string view.

The search begins at pos. This overload participates in overload resolution only if std::is_convertible_v<const T&, std::string_view> is true.

Parameters

t – Object that can be converted to std::string_view containing the characters to search for.
pos – Position to begin the search.

Returns

Position of the first character of the matching substring, or npos if no such substring exists.

constexpr size_type find_last_not_of(const string &str, size_type pos = npos) const noexcept

Finds the last character not equal to one of the characters in string str.

The search begins at pos. If pos == npos or pos >= size(), the whole string is searched.

Parameters

str – String containing the characters to search for.
pos – Position to begin the search.

Returns

Position of the last found character, or npos if no character is found.

constexpr size_type find_last_not_of(const value_type *s, size_type pos, size_type n) const

Finds the last character not equal to one of the characters in the first n characters of string s.

The search begins at pos. If pos == npos or pos >= size(), the whole string is searched.

Parameters

s – String containing the characters to search for.
pos – Position to begin the search.
n – Number of characters in s to search for.

Throws

std::invalid_argument – if s is nullptr.

Returns

Position of the last found character, or npos if no character is found.

constexpr size_type find_last_not_of(const value_type *s, size_type pos = npos) const

Finds the last character not equal to one of the characters in the null-terminated string s.

The search begins at pos. If pos == npos or pos >= size(), the whole string is searched.

Parameters

s – String containing the characters to search for.
pos – Position to begin the search.

Throws

std::invalid_argument – if s is nullptr.

Returns

Position of the last found character, or npos if no character is found.

constexpr size_type find_last_not_of(value_type c, size_type pos = npos) const noexcept

Finds the last character not equal to c.

The search begins at pos. If pos == npos or pos >= size(), the whole string is searched.

Parameters

c – Character to search for.
pos – Position to begin the search.

Returns

Position of the last found character, or npos if no character is found.

size_type find_last_not_of(const std::string &str, size_type pos = npos) const noexcept

Finds the last character not equal to one of the characters in string str.

The search begins at pos. If pos == npos or pos >= size(), the whole string is searched.

Parameters

str – String containing the characters to search for.
pos – Position to begin the search.

Returns

Position of the last found character, or npos if no character is found.

constexpr size_type find_last_not_of(const carb::cpp::string_view &sv, size_type pos = npos) const noexcept

Finds the last character not equal to one of the characters in string view sv.

The search begins at pos. If pos == npos or pos >= size(), the whole string is searched.

Parameters

sv – String view containing the characters to search for.
pos – Position to begin the search.

Returns

Position of the last found character, or npos if no character is found.

template<typename T, typename = detail::is_sv_convertible<T>> constexpr size_type find_last_not_of(const T &t, size_type pos = npos) const noexcept

Implicitly converts t to type std::string_view and finds the last character not equal to one of the characters in that string view.

The search begins at pos. If pos == npos or pos >= size(), the whole string is searched. This overload participates in overload resolution only if std::is_convertible_v<const T&, std::string_view> is true.

Parameters

t – Object that can be converted to std::string_view containing the characters to search for.
pos – Position to begin the search.

Returns

Position of the first character of the matching substring, or npos if no such substring exists.

Public Static Attributes

static constexpr size_type npos = std::numeric_limits<size_type>::max(): Special value normally used to indicate that an operation failed.