[#bsl-basic_string-0f3]
= xref:bsl.adoc[bsl]::xref:bsl/basic_string-0faf.adoc[basic_string]<char32_t>
:relfileprefix: ../
:mrdocs:

== Synopsis

Declared in `<bslstl_string.h>`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
template<>
class xref:bsl/basic_string-0faf.adoc[basic_string]<char32_t>;
----

== Type Aliases

[cols="1,4"]
|===
| Name| Description
| xref:bsl/basic_string-0f3/allocator_type.adoc[`allocator_type`] 
| Alias for the (template parameter) `ALLOCATOR` type.
| xref:bsl/basic_string-0f3/const_iterator.adoc[`const_iterator`] 
| Alias for a constant iterator over the characters of this string.
| xref:bsl/basic_string-0f3/const_pointer.adoc[`const_pointer`] 
| Alias for a constant pointer to the character type.
| xref:bsl/basic_string-0f3/const_reference.adoc[`const_reference`] 
| Alias for a non‐modifiable reference to the character type.
| xref:bsl/basic_string-0f3/const_reverse_iterator.adoc[`const_reverse_iterator`] 
| These types satisfy the `ReversibleSequence` requirements.
| xref:bsl/basic_string-0f3/difference_type.adoc[`difference_type`] 
| This `typedef` is an alias to `AllocatorTraits::difference_type`.
| xref:bsl/basic_string-0f3/iterator.adoc[`iterator`] 
| Alias for an iterator over the characters of this string.
| xref:bsl/basic_string-0f3/pointer.adoc[`pointer`] 
| Alias for a pointer to the character type.
| xref:bsl/basic_string-0f3/reference.adoc[`reference`] 
| Alias for a modifiable reference to the character type.
| xref:bsl/basic_string-0f3/reverse_iterator.adoc[`reverse_iterator`] 
| Alias for a reverse iterator over the characters of this string.
| xref:bsl/basic_string-0f3/size_type.adoc[`size_type`] 
| Alias for the size type of this string.
| xref:bsl/basic_string-0f3/traits_type.adoc[`traits_type`] 
| Alias for the (template parameter) `CHAR_TRAITS` type.
| xref:bsl/basic_string-0f3/value_type.adoc[`value_type`] 
| Alias for the character type stored in this string.
|===


== Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:bsl/basic_string-0f3/2constructor-0d.adoc[`basic_string`]         [.small]#[constructor]#
| Constructors
| xref:bsl/basic_string-0f3/2destructor.adoc[`~basic_string`] [.small]#[destructor]#
| Destroy this string object.
| xref:bsl/basic_string-0f3/operator_assign-09.adoc[`operator=`] 
| Assignment operators
| xref:bsl/basic_string-0f3/append-03.adoc[`append`] 
| `append` overloads
| xref:bsl/basic_string-0f3/append_range.adoc[`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`.
| xref:bsl/basic_string-0f3/assign-06.adoc[`assign`] 
| `assign` overloads
| xref:bsl/basic_string-0f3/assign_range.adoc[`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`.
| xref:bsl/basic_string-0f3/at-0f.adoc[`at`] 
| `at` overloads
| xref:bsl/basic_string-0f3/back-0d.adoc[`back`] 
| `back` overloads
| xref:bsl/basic_string-0f3/begin-064.adoc[`begin`] 
| `begin` overloads
| xref:bsl/basic_string-0f3/c_str.adoc[`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.
| xref:bsl/basic_string-0f3/capacity.adoc[`capacity`] 
| Return the capacity of this string, i.e., the maximum length for which resizing is guaranteed not to trigger a reallocation.
| xref:bsl/basic_string-0f3/cbegin.adoc[`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).
| xref:bsl/basic_string-0f3/cend.adoc[`cend`] 
| Return the past‐the‐end iterator for this string.
| xref:bsl/basic_string-0f3/clear.adoc[`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`.
| xref:bsl/basic_string-0f3/compare-04.adoc[`compare`] 
| `compare` overloads
| xref:bsl/basic_string-0f3/contains-00.adoc[`contains`] 
| `contains` overloads
| xref:bsl/basic_string-0f3/copy.adoc[`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.
| xref:bsl/basic_string-0f3/crbegin.adoc[`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).
| xref:bsl/basic_string-0f3/crend.adoc[`crend`] 
| Return the past‐the‐end reverse iterator for this string.
| xref:bsl/basic_string-0f3/data-0b.adoc[`data`] 
| `data` overloads
| xref:bsl/basic_string-0f3/empty.adoc[`empty`] 
| Return `true` if this string has length 0, and `false` otherwise.
| xref:bsl/basic_string-0f3/end-07.adoc[`end`] 
| `end` overloads
| xref:bsl/basic_string-0f3/ends_with-07.adoc[`ends_with`] 
| `ends_with` overloads
| xref:bsl/basic_string-0f3/erase-0b.adoc[`erase`] 
| `erase` overloads
| xref:bsl/basic_string-0f3/find-00.adoc[`find`] 
| `find` overloads
| xref:bsl/basic_string-0f3/find_first_not_of-0e.adoc[`find_first_not_of`] 
| `find_first_not_of` overloads
| xref:bsl/basic_string-0f3/find_first_of-00.adoc[`find_first_of`] 
| `find_first_of` overloads
| xref:bsl/basic_string-0f3/find_last_not_of-0d.adoc[`find_last_not_of`] 
| `find_last_not_of` overloads
| xref:bsl/basic_string-0f3/find_last_of-09.adoc[`find_last_of`] 
| `find_last_of` overloads
| xref:bsl/basic_string-0f3/front-0f.adoc[`front`] 
| `front` overloads
| xref:bsl/basic_string-0f3/get_allocator.adoc[`get_allocator`] 
| Return the allocator used by this string to supply memory.
| xref:bsl/basic_string-0f3/insert-00e.adoc[`insert`] 
| `insert` overloads
| xref:bsl/basic_string-0f3/insert_range.adoc[`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`>
| xref:bsl/basic_string-0f3/length.adoc[`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.
| xref:bsl/basic_string-0f3/max_size.adoc[`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.
| xref:bsl/basic_string-0f3/operator_plus_eq-06.adoc[`operator+=`] 
| Addition assignment operators
| xref:bsl/basic_string-0f3/operator_subs-01.adoc[`operator[]`] 
| Subscript operators
| xref:bsl/basic_string-0f3/pop_back.adoc[`pop_back`] 
| Erase the last character from this string. The behavior is undefined if this string is empty.
| xref:bsl/basic_string-0f3/push_back.adoc[`push_back`] 
| Append the specified `character` to this string.
| xref:bsl/basic_string-0f3/rbegin-08.adoc[`rbegin`] 
| `rbegin` overloads
| xref:bsl/basic_string-0f3/rend-0c.adoc[`rend`] 
| `rend` overloads
| xref:bsl/basic_string-0f3/replace-0f.adoc[`replace`] 
| `replace` overloads
| xref:bsl/basic_string-0f3/replace_with_range.adoc[`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`.
| xref:bsl/basic_string-0f3/reserve.adoc[`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.
| xref:bsl/basic_string-0f3/resize-0b.adoc[`resize`] 
| `resize` overloads
| xref:bsl/basic_string-0f3/resize_and_overwrite.adoc[`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`.
| xref:bsl/basic_string-0f3/rfind-06.adoc[`rfind`] 
| `rfind` overloads
| xref:bsl/basic_string-0f3/shrink_to_fit.adoc[`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.
| xref:bsl/basic_string-0f3/size.adoc[`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.
| xref:bsl/basic_string-0f3/starts_with-02.adoc[`starts_with`] 
| `starts_with` overloads
| xref:bsl/basic_string-0f3/substr-06.adoc[`substr`] 
| `substr` overloads
| xref:bsl/basic_string-0f3/swap.adoc[`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.
| xref:bsl/basic_string-0f3/2conversion-0c.adoc[`operator BloombergLP::bslmf::NestedTraitDeclaration<basic_string<char32_t>, IsBitwiseMoveable, BloombergLP::bslmf::IsBitwiseMoveable<bsl::allocator<char32_t>>::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.
| xref:bsl/basic_string-0f3/2conversion-01.adoc[`operator basic_string_view<char32_t, char_traits<char32_t>>`] 
| 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).
| xref:bsl/basic_string-0f3/2conversion-0d.adoc[`operator std::basic_string<char32_t, char_traits<char32_t>, 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

[cols="1,4"]
|===
| Name| Description
| xref:bsl/basic_string-0f3/npos.adoc[`npos`] 
| Value used to denote "not‐a‐position", guaranteed to be outside the range `[0 .. max_size()]`.
|===


== Friends

[cols="1,4"]
|===
| Name| Description
| `xref:bsl/String_ClearProctor.adoc[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).
| `xref:bsl/to_string-08.adoc[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.
| `xref:bsl/to_string-07.adoc[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.
| `xref:bsl/to_string-0c8.adoc[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.
| `xref:bsl/to_string-03.adoc[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.
| `xref:bsl/to_string-09.adoc[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.
| `xref:bsl/to_string-0c7.adoc[bsl::to_string]`
| `to_string` functions are made friends to allow access to the internal short string buffer.
|===


[.small]#Created with https://www.mrdocs.com[MrDocs]#