omni::string¶
Defined in omni/String.h
-
class
omni
::
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
= std::char_traits<char>¶ 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
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.
Public Functions
-
string
() noexcept¶ Default constructor.
Constructs empty string.
-
string
(size_type n, value_type c)¶ Constructs the string with
n
copies of characterc
.- 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())
ofstr
.- 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 thanstr.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)
ofstr
.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 thanstr.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 bys
.s
can contain null characters. The length of the string isn
. 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
isnullptr
.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, ifs
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
isnullptr
.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 initalize 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 byva_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)
ofstr
.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 thanstr.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::cpp17::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::cpp17::string_view &sv, size_type pos, size_type n)¶ Constructs the string with a substring
[pos, pos + n)
ofsv
.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 thansv.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>>
explicitstring
(const T &t)¶ Implicitly converts
t
to typestd::string_view
and initializes this string with the contents of thatstd::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 typestd::string_view
and initializes this string with a substring[pos, pos + n)
of thatstring_view
.If
n == npos
, or if the requested substring lasts past the end of thestring_view
, the resulting substring is[pos, sv.size())
. This overload participates in overload resolution only ifstd::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 thansv.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
isnullptr
.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::cpp17::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 typestd::string_view
and replaces the contents of this string with the contents of thatstd::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 &
assign
(size_type n, value_type c)¶ Replaces the contents with
n
copies of characterc
.- 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)
ofstr
.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 bys
.s
can contain null characters. The length of the string isn
. 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
isnullptr
.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
isnullptr
.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)
ofstr
.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::cpp17::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::cpp17::string_view &sv, size_type pos, size_type n = npos)¶ Replaces the string with a substring
[pos, pos + n)
ofsv
.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 typestd::string_view
and replaces the contents of this string with a substring[pos, pos + n)
of thatstring_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 thansv.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 typestd::string_view
and replaces the contents of this string with a substring[pos, pos + n)
of thatstring_view
.If
n == npos
, or if the requested substring lasts past the end of thestring_view
, the resulting substring is[pos, sv.size())
. This overload participates in overload resolution only ifstd::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 thansv.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 withva_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::cpp17::string_view
() const noexcept¶ Returns a
carb::cpp17::string_view
constructed as if bycarb::cpp17::string_view(data(), size())
.- Returns
A
carb::cpp17::string_view
representing the string.
-
constexpr
operator std::string_view
() const noexcept¶ Returns a
std::string_view
constructed as if bystd::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 thannew_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 characterc
at positionpos
.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 positionpos
.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
isnullptr
.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 bys
at positionpos
.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
isnullptr
.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 positionpos
.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 positionpos1
.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() orpos2
is greater thanstr.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 byp
.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 characterc
before the character pointed to byp
.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
>
iteratorinsert
(const_iterator p, InputIterator first, InputIterator last)¶ Inserts characters from the range
[first, last)
before the character pointed to byp
.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 byp
.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 positionpos
.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 positionpos1
.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() orpos2
is greater thanstr.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::cpp17::string_view &sv)¶ Inserts the string_view
sv
at positionpos
.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::cpp17::string_view &sv, size_type pos2, size_type n = npos)¶ Inserts the substring
sv.substr(pos2, n)
at positionpos1
.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() orpos2
is greater thansv.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 typestd::string_view
and inserts thatstring_view
at positionpos
.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 typestd::string_view
and inserts inserts the substringsv.substr(pos2, n)
at positionpos1
.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() orpos2
is greater thansv.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 thepos
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 thepos
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 byva_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 byp
.- 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 byp
.- 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 byva_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 atpos
.If
n
isnpos
orpos + 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()], orfirst > 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 characterc
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 thanstr.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 strings
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
isnullptr
.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
isnullptr
.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 thanstr.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::cpp17::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::cpp17::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 thanstr.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 typestd::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 typestd::string_view
and appends the substringsv.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 thanstr.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 byva_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
isnullptr
.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::cpp17::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 typestd::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 equivilant, 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 substringsubstr(pos1, n1)
.- See
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 equivilant, 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 substringsubstr(pos1, n1)
.- See
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() orpos2
is greater thanstr.size()
.- Returns
A negative value if
*this
appears before the other string in lexicographical order, zero if*this
and the other string compare equivilant, 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
compare() for details on how the comparison is performed.
- Parameters
s – String to compare to.
- Throws
std::invalid_argument – if
s
isnullptr
.- Returns
A negative value if
*this
appears before the other string in lexicographical order, zero if*this
and the other string compare equivilant, 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 substringsubstr(pos1, n1)
.- See
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
isnullptr
.
- Returns
A negative value if
*this
appears before the other string in lexicographical order, zero if*this
and the other string compare equivilant, 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 strings
to the substringsubstr(pos1, n1)
.- See
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
isnullptr
.
- Returns
A negative value if
*this
appears before the other string in lexicographical order, zero if*this
and the other string compare equivilant, or a positive value if*this
appears after the other string in lexicographical order.
-
constexpr int
compare
(const std::string &str) const noexcept¶ Compares
str
to this string.- See
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 equivilant, or a positive value if*this
appears after the other string in lexicographical order.
-
constexpr int
compare
(size_type pos1, size_type n1, const std::string &str) const¶ Compares
str
to the substringsubstr(pos1, n1)
.- See
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 equivilant, or a positive value if*this
appears after the other string in lexicographical order.
-
constexpr 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 substringsubstr(pos1, n1)
.- See
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() orpos2
is greater thanstr.size()
.- Returns
A negative value if
*this
appears before the other string in lexicographical order, zero if*this
and the other string compare equivilant, or a positive value if*this
appears after the other string in lexicographical order.
-
constexpr int
compare
(const carb::cpp17::string_view &sv) const noexcept¶ Compares
sv
to this string.- See
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 equivilant, 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::cpp17::string_view &sv) const¶ Compares
sv
to the substringsubstr(pos1, n1)
.- See
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 equivilant, 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::cpp17::string_view &sv, size_type pos2, size_type n2 = npos) const¶ Compares
sv.substr(pos2, n2)
to the substringsubstr(pos1, n1)
.- See
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() orpos2
is greater thansv.size()
.- Returns
A negative value if
*this
appears before the other string in lexicographical order, zero if*this
and the other string compare equivilant, or a positive value if*this
appears after the other string in lexicographical order.
-
template<typename
T
, typename = detail::is_sv_convertible<T>>
constexpr intcompare
(const T &t) const noexcept¶ Implicitly converts
t
to typestd::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
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 equivilant, or a positive value if*this
appears after the other string in lexicographical order.
-
template<typename
T
, typename = detail::is_sv_convertible<T>>
constexpr intcompare
(size_type pos1, size_type n1, const T &t) const¶ Implicitly converts
t
to typestd::string_view
and compares it to the substringsubstr(pos1, n1)
.This overload participates in overload resolution only if
std::is_convertible_v<const T&, std::string_view>
is true.- See
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 equivilant, or a positive value if*this
appears after the other string in lexicographical order.
-
template<typename
T
, typename = detail::is_sv_convertible<T>>
constexpr intcompare
(size_type pos1, size_type n1, const T &t, size_type pos2, size_type n2 = npos) const¶ Implicitly converts
t
to typestd::string_view
and comparessv.substr(pos2, n2)
to the substringsubstr(pos1, n1)
.This overload participates in overload resolution only if
std::is_convertible_v<const T&, std::string_view>
is true.- See
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() orpos2
is greater thansv.size()
.- Returns
A negative value if
*this
appears before the other string in lexicographical order, zero if*this
and the other string compare equivilant, 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
isnullptr
.- Returns
true if the string starts with
s
, false otherwise.
-
constexpr bool
starts_with
(carb::cpp17::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
isnullptr
.- Returns
true if the string ends with
s
, false otherwise.
-
constexpr bool
ends_with
(carb::cpp17::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
isnullptr
.- Returns
true if the string contains
s
, false otherwise.
-
constexpr bool
contains
(carb::cpp17::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)
withstr
.If
n == npos
, orpos + 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 substringstr.substr(pos2, n2)
.If
n == npos
, orpos + 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() orpos2
is greater thanstr.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 replacment characters.
- Throws
std::out_of_range – if the range
[i1,i2)
is invalid (not in the range [begin(), end()], ori1 > 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)
withn2
characters from strings
.The character sequence can contain null characters. If
n == npos
, orpos + 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
isnullptr
.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 strings
.If
n == npos
, orpos + 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
isnullptr
.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)
withn2
copies of characterc
.If
n == npos
, orpos + 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)
withstr
.If
n == npos
, orpos + 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 substringstr.substr(pos2, n2)
.If
n == npos
, orpos + 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() orpos2
is greater thanstr.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::cpp17::string_view &sv)¶ Replaces the portion of this string
[pos, pos + n1)
withsv
.If
n == npos
, orpos + 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::cpp17::string_view &sv, size_type pos2, size_type n2 = npos)¶ Replaces the portion of this string
[pos, pos + n1)
with the substringsv.substr(pos2, n2)
.If
n == npos
, orpos + 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() orpos2
is greater thansv.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 typestd::string_view
and replaces the portion of this string[pos, pos + n1)
withsv
.If
n == npos
, orpos + n
is greater than size(), the substring to the end of the string is replaced. This overload participates in overload resolution only ifstd::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 typestd::string_view
and replaces the portion of this string[pos, pos + n1)
with the substringsv.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 ifstd::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() orpos2
is greater thansv.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)
withstr
.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()], ori1 > 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)
withn
characters from strings
.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()], ori1 > i2
.std::invalid_argument – if
s
isnullptr
.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 strings
.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()], ori1 > i2
.std::invalid_argument – if
s
isnullptr
.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)
withn
copies of characterc
.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()], ori1 > 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 inilist
.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()], ori1 > 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)
withstr
.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()], ori1 > 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::cpp17::string_view &sv)¶ Replaces the portion of this string
[i1, i2)
withsv
.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()], ori1 > 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 typestd::string_view
and replaces the portion of this string[i1, i2)
withsv
.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()], ori1 > 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 aprintf
style formatted string.If
n == npos
, orpos + 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
isnullptr
.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 avprintf
style formatted string.If
n == npos
, orpos + 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 withva_start
. Arguments must not overlap with*this
.
- Throws
std::out_of_range – if
pos
is greater than size().std::invalid_argument – if
s
isnullptr
.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 aprintf
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
isnullptr
.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 aprintf
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 withva_start
. Arguments must not overlap with*this
.
- Throws
std::out_of_range – if
pos
is greater thansize()
.std::invalid_argument – if
s
isnullptr
.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
, orpos + 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 destinations
.If
n == npos
, orpos + 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
isnullptr
.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 characterc
are appended. Ifn
is smaller than size(), the string is shrunk to sizen
.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 ofNUL
are appended. Ifn
is smaller than size(), the string is shrunk to sizen
.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 ofs
.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
isnullptr
.- 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
isnullptr
.- Returns
Position of the first character of the matching substring, or
npos
if no such substring exists.
-
constexpr 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::cpp17::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_typefind
(const T &t, size_type pos = 0) const noexcept¶ Implicitly converts
t
to typestd::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 ifstd::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
. Ifpos == npos
orpos >= 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 ofs
.The string may contain nulls.The search begins at
pos
. Ifpos == npos
orpos >= 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
isnullptr
.- 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
. Ifpos == npos
orpos >= size()
, the whole string is searched.- Parameters
s – String to find.
pos – Position to begin the search.
- Throws
std::invalid_argument – if
s
isnullptr
.- 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
. Ifpos == npos
orpos >= 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.
-
constexpr 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
. Ifpos == npos
orpos >= 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::cpp17::string_view &sv, size_type pos = npos) const noexcept¶ Finds the last substring of this string that matches
sv
.The search begins at
pos
. Ifpos == npos
orpos >= 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_typerfind
(const T &t, size_type pos = npos) const noexcept¶ Implicitly converts
t
to typestd::string_view
and finds the last substring of this string that matches it.The search begins at
pos
. Ifpos == npos
orpos >= size()
, the whole string is searched. This overload participates in overload resolution only ifstd::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 strings
.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
isnullptr
- 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
isnullptr
.- 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.
-
constexpr 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::cpp17::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_typefind_first_of
(const T &t, size_type pos = 0) const noexcept¶ Implicitly converts
t
to typestd::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 ifstd::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
. Ifpos == npos
orpos >= 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 strings
.The search begins at
pos
. Ifpos == npos
orpos >= 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
isnullptr
.- 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
. Ifpos == npos
orpos >= 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
isnullptr
.- 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
. Ifpos == npos
orpos >= 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.
-
constexpr 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
. Ifpos == npos
orpos >= 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::cpp17::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
. Ifpos == npos
orpos >= 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_typefind_last_of
(const T &t, size_type pos = npos) const noexcept¶ Implicitly converts
t
to typestd::string_view
and finds the last character equal to one of the characters in that string view.The search begins at
pos
. Ifpos == npos
orpos >= size()
, the whole string is searched. The search begins atpos
. This overload participates in overload resolution only ifstd::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 strings
.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
isnullptr
.- 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
isnullptr
.- 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.
-
constexpr 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::cpp17::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_typefind_first_not_of
(const T &t, size_type pos = 0) const noexcept¶ Implicitly converts
t
to typestd::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 ifstd::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
. Ifpos == npos
orpos >= 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 strings
.The search begins at
pos
. Ifpos == npos
orpos >= 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
isnullptr
.- 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
. Ifpos == npos
orpos >= 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
isnullptr
.- Returns
Position of the lastst 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
. Ifpos == npos
orpos >= 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.
-
constexpr 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
. Ifpos == npos
orpos >= 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::cpp17::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
. Ifpos == npos
orpos >= 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_typefind_last_not_of
(const T &t, size_type pos = npos) const noexcept¶ Implicitly converts
t
to typestd::string_view
and finds the last character not equal to one of the characters in that string view.The search begins at
pos
. Ifpos == npos
orpos >= size()
, the whole string is searched. This overload participates in overload resolution only ifstd::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 Members
-
allocated_data
m_allocated_data
¶
-
value_type
m_local_data
[kSMALL_STRING_SIZE
]¶ Local buffer for small string optimization.
When the string is small enough to fit in the local buffer, the last byte is the size remaining in the buffer. This has the advantage of when the local buffer is full, the size remaining will be 0, which acts as the NUL terminator for the local string. When the string is larger than the buffer, the last byte will be m_sentinel_value, indicated the string is allocated.
-
using