bsl::basic_string

Synopsis

Declared in <bslstl_string.h>

template<
    class CHAR_TYPE,
    class CHAR_TRAITS = char_traits<CHAR_TYPE>,
    class ALLOCATOR = allocator<CHAR_TYPE>>
class basic_string;

Description

1. any method that would result in a string of length larger than the size returned by max_size throws std::length_error, and 2. any method that attempts to access a position outside the valid range of a string throws std::out_of_range.

Circumstances where a method throws bsl::length_error (1) are clear and not repeated in the individual function-level documentations below.

More generally, this class supports an almost complete set of in-core value semantic operations, including copy construction, assignment, equality comparison (but excluding ostream printing since this component is below STL). A precise operational definition of when two objects have the same value can be found in the description of operator== for the class. This class is exception neutral with full guarantee of rollback: if an exception is thrown during the invocation of a method on a pre-existing object, the object is left unchanged. In no event is memory leaked.

Note that aliasing (e.g., using all or part of an object as both source and destination) is supported in all cases in the public interface of basic_string. However, the private interface (...Raw methods) should be assumed to be not alias-safe unless specifically noted otherwise.

Type Aliases

Name	Description
`allocator_type`	Alias for the (template parameter) `ALLOCATOR` type.
`const_iterator`	Alias for a constant iterator over the characters of this string.
`const_pointer`	Alias for a constant pointer to the character type.
`const_reference`	Alias for a non-modifiable reference to the character type.
`const_reverse_iterator`	These types satisfy the `ReversibleSequence` requirements.
`difference_type`	This `typedef` is an alias to `AllocatorTraits::difference_type`.
`iterator`	Alias for an iterator over the characters of this string.
`pointer`	Alias for a pointer to the character type.
`reference`	Alias for a modifiable reference to the character type.
`reverse_iterator`	Alias for a reverse iterator over the characters of this string.
`size_type`	Alias for the size type of this string.
`traits_type`	Alias for the (template parameter) `CHAR_TRAITS` type.
`value_type`	Alias for the character type stored in this string.

Member Functions

Name	Description
`basic_string` [constructor]	Constructors
`~basic_string` [destructor]	Destroy this string object.
`operator=`	Assignment operators
`append`	`append` overloads
`append_range`	Append to this string the characters from the specified `range`. Return a reference providing modifiable access to this string. Note that `range` must meet the requirements of an input range and the values from `range` must have a type matching or convertible to (template parameter) `CHAR_TYPE`.
`assign`	`assign` overloads
`assign_range`	Assign to this string the characters from the specified `range`. Return a reference providing modifiable access to this string. Note that `range` must meet the requirements of an input range and the values from `range` must have a type matching or convertible to (template parameter) `CHAR_TYPE`.
`at`	`at` overloads
`back`	`back` overloads
`begin`	`begin` overloads
`c_str`	Return an address providing non-modifiable access to the null-terminated buffer of `length() + 1` characters whose contents are identical to the value of this string. Note that any call to the string destructor or any of its manipulators invalidates the returned pointer.
`capacity`	Return the capacity of this string, i.e., the maximum length for which resizing is guaranteed not to trigger a reallocation.
`cbegin`	Return an iterator providing non-modifiable access to the first character of this string (or the past-the-end iterator if this string is empty).
`cend`	Return the past-the-end iterator for this string.
`clear`	Reset this string to an empty value. Note that the capacity may change (or not if `BASIC_STRING_DEALLOCATE_IN_CLEAR` is `false`). Note that the Standard doesn't allow to reduce capacity on `clear`.
`compare`	`compare` overloads
`contains`	`contains` overloads
`copy`	Copy from this string, starting from the optionally specified `position`, the specified `numChars` or `length() - position` characters, whichever is smaller, into the specified `characterString` buffer, and return the number of characters copied. If `position` is not specified, 0 is used. Throw `out_of_range` if `position > length()`. The behavior is undefined unless `characterString` is at least `numChars` long. Note that the output `characterString` is not null-terminated.
`crbegin`	Return a reverse iterator providing non-modifiable access to the last character of this string (or the past-the-end reverse iterator if this string is empty).
`crend`	Return the past-the-end reverse iterator for this string.
`data`	`data` overloads
`empty`	Return `true` if this string has length 0, and `false` otherwise.
`end`	`end` overloads
`ends_with`	`ends_with` overloads
`erase`	`erase` overloads
`find`	`find` overloads
`find_first_not_of`	`find_first_not_of` overloads
`find_first_of`	`find_first_of` overloads
`find_last_not_of`	`find_last_not_of` overloads
`find_last_of`	`find_last_of` overloads
`front`	`front` overloads
`get_allocator`	Return the allocator used by this string to supply memory.
`insert`	`insert` overloads
`insert_range`	Insert at the specified `position` in this string the characters from the specified `range` and return an iterator providing non-modifiable access to the first inserted character, or a non-`const` copy of `position` if `true == bsl::ranges.empty()`. The behavior is undefined unless `position` is an iterator in the range `[begin() .. end()]` (both endpoints included). Note that `range` must meet the requirements of an input range and the values from `range` must have a type matching or convertible to (template parameter) `CHAR_TYPE`>
`length`	Return the length of this string. Note that this number may differ from `CHAR_TRAITS::length(c_str())` in case the string contains null characters. Also note that a null-terminating character added by the `c_str` method is not counted in this length.
`max_size`	Return the maximal possible length of this string. Note that requests to create a string longer than this number of characters are guaranteed to raise a `length_error` exception.
`operator+=`	Addition assignment operators
`operator[]`	Subscript operators
`pop_back`	Erase the last character from this string. The behavior is undefined if this string is empty.
`push_back`	Append the specified `character` to this string.
`rbegin`	`rbegin` overloads
`rend`	`rend` overloads
`replace`	`replace` overloads
`replace_with_range`	Replace the substring in the range starting at the specified `first` position and ending right before the specified `last` position with the characters from the specified `range`. Return a reference providing modifiable access to this string. The behavior is undefined unless `first` and `last` are both within the range `[cbegin() .. cend()]`. Note that `range` must meet the requirements of an input range and the values from `range` must have a type matching or convertible to template parameter) `CHAR_TYPE`.
`reserve`	Change the capacity of this string to the specified `newCapacity`. Note that the capacity of a string is the maximum length it can accommodate without reallocation. The actual storage allocated may be higher.
`resize`	`resize` overloads
`resize_and_overwrite`	Change the length of this string to the specified `newLength`, erasing characters at the end if `newLength < length()` or appending the appropriate number of characters at the end if `length() < newLength`. Subsequently, invoke the specified `operation` passing the address of the null-terminated buffer and the adjusted length of this string as parameters. Finally, change the length of this string to the value returned by the `operation`. Throw `length_error` if `newLength > max_size()`. The behavior is undefined unless the value returned by the `operation` is less than or equal to `newLength`.
`rfind`	`rfind` overloads
`shrink_to_fit`	Request the removal of unused capacity by causing reallocation. Note that this method has no effect if the capacity is equal to the size. Also note that if (and only if) reallocation occurs, all iterators, including the past the end iterator, and all references to the elements are invalidated.
`size`	Return the length of this string. Note that this number may differ from `CHAR_TRAITS::length(c_str())` in case the string contains null characters. Also note that a null-terminating character added by the `c_str` method is not counted in this length.
`starts_with`	`starts_with` overloads
`substr`	`substr` overloads
`swap`	Exchange the value of this object with that of the specified `other` object; also exchange the allocator of this object with that of `other` if the (template parameter) type `ALLOCATOR` has the `propagate_on_container_swap` trait, and do not modify either allocator otherwise. This method provides the no-throw exception-safety guarantee. This operation has `O[1]` complexity if either this object was created with the same allocator as `other` or `ALLOCATOR` has the `propagate_on_container_swap` trait; otherwise, it has `O[n + m]` complexity, where `n` and `m` are the lengths of this object and `other`, respectively. Note that this method`s support for swapping objects created with different allocators when `ALLOCATOR` does not have the `propagate_on_container_swap` trait is a departure from the C++ Standard.
`operator BloombergLP::bslmf::NestedTraitDeclaration<basic_string, IsBitwiseMoveable, BloombergLP::bslmf::IsBitwiseMoveable<ALLOCATOR>::value>`	`CHAR_TYPE` is required to be a POD as per the Standard, which makes `CHAR_TYPE` bitwise-movable, so `basic_string` is bitwise-movable as long as the (template parameter) type `ALLOCATOR` is also bitwise-movable.
`operator basic_string_view<CHAR_TYPE, CHAR_TRAITS>`	Convert this object to a `string_view` type instantiated with the same character type and traits type. The return view will contain the same sequence of characters as this object. Note that this conversion operator can be invoked implicitly (e.g., during argument passing).
`operator std::basic_string<CHAR_TYPE, CHAR_TRAITS, ALLOC2>`	Convert this object to a string type native to the compiler's library, instantiated with the same character type and traits type, but not necessarily the same allocator type. The return string will contain the same sequence of characters as `orig` and will have a default-constructed allocator. Note that this conversion operator can be invoked implicitly (e.g., during argument passing).

Static Data Members

Name	Description
`npos`	Value used to denote "not-a-position", guaranteed to be outside the range `[0 .. max_size()]`.

Specializations

Name
`basic_string<char>`
`basic_string<char16_t>`
`basic_string<char32_t>`
`basic_string<char8_t>`
`basic_string<wchar_t>`

Deduction Guides

Name	Description
`basic_string<CHAR_TYPE>`	Deduce the template parameter `CHAR_TYPE` from the `value_type` of the `initializer_list` passed to the constructor of `basic_string`. This deduction guide does not participate unless the specified `ALLOC` is convertible to `bsl::allocator<CHAR_TYPE>`.
`basic_string<CHAR_TYPE>`	Deduce the template parameter `CHAR_TYPE` from the parameters passed to the constructor of `basic_string`. This deduction guide does not participate unless the specified `ALLOC` is convertible to `bsl::allocator<CHAR_TYPE>`.
`basic_string<CHAR_TYPE>`	Deduce the template parameter `CHAR_TYPE` from the `value_type` of the iterators passed to passed to the constructor of `basic_string`. This deduction guide does not participate unless the specified `ALLOC` is convertible to `bsl::allocator<CHAR_TYPE>`.
`basic_string<CHAR_TYPE>`	Deduce the template parameter `CHAR_TYPE` from the parameters passed to the constructor of `basic_string`. This deduction guide does not participate unless the specified `ALLOC` is convertible to `bsl::allocator<CHAR_TYPE>`.
`basic_string<CHAR_TYPE>`	Deduce the template parameter `CHAR_TYPE` from the parameters passed to the constructor of `basic_string`. This deduction guide does not participate unless the specified `ALLOC` is convertible to `bsl::allocator<CHAR_TYPE>`.
`basic_string<CHAR_TYPE, CHAR_TRAITS>`	Deduce the template parameters `CHAR_TYPE` and `TRAITS` from the corresponding template parameters of the `bsl::basic_string_view` passed to the constructor of `basic_string`. This deduction guide does not participate unless the specified `ALLOC` is convertible to `bsl::allocator<CHAR_TYPE>`.
`basic_string<CHAR_TYPE, CHAR_TRAITS, ALLOCATOR>`	Deduce the template parameters `CHAR_TYPE` and `TRAITS` from the corresponding template parameters of the `bsl::basic_string_view` passed to the constructor of `basic_string`. Deduce the template parameter `ALLOCATOR` from the optional argument passed to the constructor. This deduction guide does not participate unless the specified `ALLOCATOR` meets the requirements of a standard allocator.
`basic_string<CHAR_TYPE, CHAR_TRAITS, ALLOCATOR>`	Deduce the template parameters `CHAR_TYPE`, `TRAITS`, and `ALLOCATOR` from the corresponding template parameters of the `bsl::basic_string` passed to the constructor of `basic_string`. This deduction guide does not participate unless the specified `ALLOC` is convertible to `ALLOCATOR`.
`basic_string<CHAR_TYPE, CHAR_TRAITS, ALLOCATOR>`	Deduce the template parameters `CHAR_TYPE`, `TRAITS`, and `ALLOCATOR` from the corresponding template parameters of the `bsl::basic_string` passed to the constructor of `basic_string`. This deduction guide does not participate unless the specified `ALLOC` is convertible to `ALLOCATOR`.
`basic_string<CHAR_TYPE, char_traits<CHAR_TYPE>, ALLOCATOR>`	Deduce the template parameter `CHAR_TYPE` from the `value_type` of the iterators passed to passed to the constructor of `basic_string`. Deduce the template parameter `ALLOCATOR` from the optional argument passed to the constructor. This deduction guide does not participate unless the specified `ALLOCATOR` meets the requirements of a standard allocator.

Friends

Name	Description
`bsl::String_ClearProctor`	This component private `class` implements a proctor that sets the length of a string to zero, and, if `release` is not called, will restore that string upon it's destruction. The intended usage is to implement `assign` methods in terms of `append` (by clearing the string before appending to it), while maintaining the strong exceptions guarantee. Note that after constructing this proctor for a string `s`, the invariant `s[s.length()]== CHAR_TYPE()` is violated for non-empty `s`. This invariant will be restored by either a successful `append` or by the proctor's destructor if an exception is thrown. Note that the template parameter was renamed from STRING_TYPE to FULL_STRING_TYPE due to a name clash with a define elsewhere in the code base (see DRQS 112049582).
`bsl::to_string`	Constructs a string with contents equal to the specified `value`. The contents of the string will be the same as what `std::sprintf(buf, "%llu", value)` would produce with a sufficiently large buffer.
`bsl::to_string`	Constructs a string with contents equal to the specified `value`. The contents of the string will be the same as what `std::sprintf(buf, "%lu", value)` would produce with a sufficiently large buffer.
`bsl::to_string`	Constructs a string with contents equal to the specified `value`. The contents of the string will be the same as what `std::sprintf(buf, "%u", value)` would produce with a sufficiently large buffer.
`bsl::to_string`	Constructs a string with contents equal to the specified `value`. The contents of the string will be the same as what `std::sprintf(buf, "%lld", value)` would produce with a sufficiently large buffer.
`bsl::to_string`	Constructs a string with contents equal to the specified `value`. The contents of the string will be the same as what `std::sprintf(buf, "%ld", value)` would produce with a sufficiently large buffer.
`bsl::to_string`	`to_string` functions are made friends to allow access to the internal short string buffer.

Non-Member Functions

Name	Description
`erase`	Erase (in-place) all the elements from the specified `str` that compare equal to the specified `c`, and return the number of erased elements.
`erase_if`	Erase (in-place) all the elements from the specified `str` where the specified `pred` returns `true`, and return the number of erased elements.
`hashBasicString`	Return a hash value for the specified `str`.
`operator+`	Same as the primary `operator+` with a C-string `lhs`.
`operator+`	Same as the primary `operator+` with a C-string `rhs`.
`operator+`	Same as the primary `operator+` with a single `CHAR_TYPE` `rhs` and rvalue `lhs`.
`operator+`	Same as the primary `operator+` with an rvalue `lhs` C-string.
`operator+`	Same as the primary `operator+` overload with an rvalue `lhs`.
`operator+`	Same as the primary `operator+` with a string-view-like `lhs` and string `rhs`.
`operator+`	Same as the primary `operator+` with a C-string `rhs` and rvalue `lhs`.
`operator+`	Return the concatenation of strings constructed from the specified `lhs` and `rhs` arguments, i.e., `basic_string(lhs).append(rhs)`. The allocator of the returned string is determined per the rules in P1165 (https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p1165r1.html). Note that overloads that accept rvalue references are implemented for C++11 and later only.
`operator+`	Same as the primary `operator+` with a C-string `rhs`.
`operator+`	Same as the primary `operator+` with an rvalue `lhs` and C-string `rhs`.
`operator+`	Same as the primary `operator+` for mixed `std`/`bsl` strings with an rvalue `rhs`.
`operator+`	Same as the primary `operator+` overload with an rvalue `lhs` and lvalue `rhs`.
`operator+`	Same as the primary `operator+` for mixed `bsl`/`std` strings.
`operator+`	Same as the primary `operator+` with a single `CHAR_TYPE` `lhs` and rvalue `rhs`.
`operator+`	Same as the primary `operator+` with C-string operands.
`operator+`	Same as the primary `operator+` overload with an rvalue `lhs`.
`operator+`	Same as the primary `operator+` with a C-string `lhs` and rvalue `rhs`.
`operator+`	Same as the primary `operator+` for mixed `bsl`/`std` strings.
`operator+`	Same as the primary `operator+` with a C-string `rhs` and rvalue `lhs`.
`operator+`	Same as the primary `operator+` for mixed `std`/`bsl` strings.
`operator<=>`	Perform a lexicographic three-way comparison of the specified `lhs` and the specified `rhs` strings by using `CHAR_TRAITS::eq` on each character; return the result of that comparison.
`operator<=>`	Perform a lexicographic three-way comparison of the specified `lhs` and the specified `rhs` strings by using `CHAR_TRAITS::eq` on each character; return the result of that comparison.
`operator<=>`	Perform a lexicographic three-way comparison of the specified `lhs` string and the specified `rhs` C-string by using `CHAR_TRAITS::eq` on each character; return the result of that comparison.
`operator==`	Return `true` if the specified `lhs` string has the same value as the specified `rhs` string, and `false` otherwise. Two strings have the same value if they have the same length, and the characters at each respective position have the same value according to `CHAR_TRAITS::eq`.
`operator==`	Same as the two-argument `operator==` for `basic_string`.
`operator==`	Same as the two-argument `operator==` for mixed `bsl`/`std` strings.
`quoted`	Return an object, containing quoted version of the specified `value` obtained using the optionally specified `delim` and `escape` characters, and that can be inserted to output stream. Return an object, containing quoted version of the specified `value` obtained using the optionally specified `delim` and `escape` characters, and that can be inserted to output stream.
`quoted`	Return an object, containing quoted version of the specified `value` obtained using the optionally specified `delim` and `escape` characters, and that can be inserted to output (or extracted from input) stream. Return an object, containing quoted version of the specified `value` obtained using the optionally specified `delim` and `escape` characters, and that can be inserted to output (or extracted from input) stream.
`swap`	Exchange the value of the specified `a` object with that of the specified `b` object; also exchange the allocator of `a` with that of `b` if the (template parameter) type `ALLOCATOR` has the `propagate_on_container_swap` trait, and do not modify either allocator otherwise. This function provides the no-throw exception-safety guarantee. This operation has `O[1]` complexity if either `a` was created with the same allocator as `b` or `ALLOCATOR` has the `propagate_on_container_swap` trait; otherwise, it has `O[n + m]` complexity, where `n` and `m` are the lengths of `a` and `b`, respectively. Note that this function`s support for swapping objects created with different allocators when `ALLOCATOR` does not have the `propagate_on_container_swap` trait is a departure from the C++ Standard.
`::BloombergLP::bslstl::operator+`	Return the concatenation of the specified `lhs` string ref and the specified `rhs` `std::basic_string` value.
`::BloombergLP::bslstl::operator+`	Return a `bsl::string` having the value of the concatenation of the strings referred to by the specified `lhs` and `rhs` values.
`::BloombergLP::bslstl::operator+`	Return the concatenation of the specified C string and string ref.
`::BloombergLP::bslstl::operator+`	Return the concatenation of the specified `lhs` string ref and the specified `rhs` `bsl::basic_string` value.
`::BloombergLP::bslstl::operator+`	Return the concatenation of the specified `lhs` string ref and the specified `rhs` `bsl::basic_string` value.
`::BloombergLP::bslstl::operator+`	Return the concatenation of the specified string ref and C string.
`::BloombergLP::bslstl::operator+`	Return the concatenation of the specified `lhs` `std::basic_string` and the specified `rhs` string ref.