[#bsl-basic_string-0e]
= xref:bsl.adoc[bsl]::xref:bsl/basic_string-0faf.adoc[basic&lowbar;string]&lt;wchar&lowbar;t&gt;
:relfileprefix: ../
:mrdocs:

== Synopsis

Declared in `&lt;bslstl&lowbar;string&period;h&gt;`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
template&lt;&gt;
class xref:bsl/basic_string-0faf.adoc[basic&lowbar;string]&lt;wchar&lowbar;t&gt;;
----

== Type Aliases

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


== Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:bsl/basic_string-0e/2constructor-0c.adoc[`basic&lowbar;string`]         [.small]#[constructor]#
| Constructors
| xref:bsl/basic_string-0e/2destructor.adoc[`&#126;basic&lowbar;string`] [.small]#[destructor]#
| Destroy this string object&period;
| xref:bsl/basic_string-0e/operator_assign-0a0.adoc[`operator&equals;`] 
| Assignment operators
| xref:bsl/basic_string-0e/append-07.adoc[`append`] 
| `append` overloads
| xref:bsl/basic_string-0e/append_range.adoc[`append&lowbar;range`] 
| Append to this string the characters from the specified `range`&period; Return a reference providing modifiable access to this string&period; 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&lowbar;TYPE`&period;
| xref:bsl/basic_string-0e/assign-001.adoc[`assign`] 
| `assign` overloads
| xref:bsl/basic_string-0e/assign_range.adoc[`assign&lowbar;range`] 
| Assign to this string the characters from the specified `range`&period; Return a reference providing modifiable access to this string&period; 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&lowbar;TYPE`&period;
| xref:bsl/basic_string-0e/at-07.adoc[`at`] 
| `at` overloads
| xref:bsl/basic_string-0e/back-04.adoc[`back`] 
| `back` overloads
| xref:bsl/basic_string-0e/begin-06.adoc[`begin`] 
| `begin` overloads
| xref:bsl/basic_string-0e/c_str.adoc[`c&lowbar;str`] 
| Return an address providing non&hyphen;modifiable access to the null&hyphen;terminated buffer of `length() &plus; 1` characters whose contents are identical to the value of this string&period; Note that any call to the string destructor or any of its manipulators invalidates the returned pointer&period;
| xref:bsl/basic_string-0e/capacity.adoc[`capacity`] 
| Return the capacity of this string, i&period;e&period;, the maximum length for which resizing is guaranteed not to trigger a reallocation&period;
| xref:bsl/basic_string-0e/cbegin.adoc[`cbegin`] 
| Return an iterator providing non&hyphen;modifiable access to the first character of this string (or the past&hyphen;the&hyphen;end iterator if this string is empty)&period;
| xref:bsl/basic_string-0e/cend.adoc[`cend`] 
| Return the past&hyphen;the&hyphen;end iterator for this string&period;
| xref:bsl/basic_string-0e/clear.adoc[`clear`] 
| Reset this string to an empty value&period; Note that the capacity may change (or not if `BASIC&lowbar;STRING&lowbar;DEALLOCATE&lowbar;IN&lowbar;CLEAR` is `false`)&period; Note that the Standard doesn&apos;t allow to reduce capacity on `clear`&period;
| xref:bsl/basic_string-0e/compare-0f0.adoc[`compare`] 
| `compare` overloads
| xref:bsl/basic_string-0e/contains-0e.adoc[`contains`] 
| `contains` overloads
| xref:bsl/basic_string-0e/copy.adoc[`copy`] 
| Copy from this string, starting from the optionally specified `position`, the specified `numChars` or `length() &hyphen; position` characters, whichever is smaller, into the specified `characterString` buffer, and return the number of characters copied&period; If `position` is not specified, 0 is used&period; Throw `out&lowbar;of&lowbar;range` if `position &gt; length()`&period; The behavior is undefined unless `characterString` is at least `numChars` long&period; Note that the output `characterString` is _not_ null&hyphen;terminated&period;
| xref:bsl/basic_string-0e/crbegin.adoc[`crbegin`] 
| Return a reverse iterator providing non&hyphen;modifiable access to the last character of this string (or the past&hyphen;the&hyphen;end reverse iterator if this string is empty)&period;
| xref:bsl/basic_string-0e/crend.adoc[`crend`] 
| Return the past&hyphen;the&hyphen;end reverse iterator for this string&period;
| xref:bsl/basic_string-0e/data-09.adoc[`data`] 
| `data` overloads
| xref:bsl/basic_string-0e/empty.adoc[`empty`] 
| Return `true` if this string has length 0, and `false` otherwise&period;
| xref:bsl/basic_string-0e/end-0e.adoc[`end`] 
| `end` overloads
| xref:bsl/basic_string-0e/ends_with-09.adoc[`ends&lowbar;with`] 
| `ends&lowbar;with` overloads
| xref:bsl/basic_string-0e/erase-0b.adoc[`erase`] 
| `erase` overloads
| xref:bsl/basic_string-0e/find-08.adoc[`find`] 
| `find` overloads
| xref:bsl/basic_string-0e/find_first_not_of-02.adoc[`find&lowbar;first&lowbar;not&lowbar;of`] 
| `find&lowbar;first&lowbar;not&lowbar;of` overloads
| xref:bsl/basic_string-0e/find_first_of-0dc.adoc[`find&lowbar;first&lowbar;of`] 
| `find&lowbar;first&lowbar;of` overloads
| xref:bsl/basic_string-0e/find_last_not_of-0b9.adoc[`find&lowbar;last&lowbar;not&lowbar;of`] 
| `find&lowbar;last&lowbar;not&lowbar;of` overloads
| xref:bsl/basic_string-0e/find_last_of-09.adoc[`find&lowbar;last&lowbar;of`] 
| `find&lowbar;last&lowbar;of` overloads
| xref:bsl/basic_string-0e/front-00.adoc[`front`] 
| `front` overloads
| xref:bsl/basic_string-0e/get_allocator.adoc[`get&lowbar;allocator`] 
| Return the allocator used by this string to supply memory&period;
| xref:bsl/basic_string-0e/insert-0b.adoc[`insert`] 
| `insert` overloads
| xref:bsl/basic_string-0e/insert_range.adoc[`insert&lowbar;range`] 
| Insert at the specified `position` in this string the characters from the specified `range` and return an iterator providing non&hyphen;modifiable access to the first inserted character, or a non&hyphen;`const` copy of `position` if `true &equals;&equals; bsl&colon;&colon;ranges&period;empty()`&period; The behavior is undefined unless `position` is an iterator in the range `&lsqb;begin() &period;&period; end()&rsqb;` (both endpoints included)&period; 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&lowbar;TYPE`&gt;
| xref:bsl/basic_string-0e/length.adoc[`length`] 
| Return the length of this string&period; Note that this number may differ from `CHAR&lowbar;TRAITS&colon;&colon;length(c&lowbar;str())` in case the string contains null characters&period; Also note that a null&hyphen;terminating character added by the `c&lowbar;str` method is _not_ counted in this length&period;
| xref:bsl/basic_string-0e/max_size.adoc[`max&lowbar;size`] 
| Return the maximal possible length of this string&period; Note that requests to create a string longer than this number of characters are guaranteed to raise a `length&lowbar;error` exception&period;
| xref:bsl/basic_string-0e/operator_plus_eq-05.adoc[`operator&plus;&equals;`] 
| Addition assignment operators
| xref:bsl/basic_string-0e/operator_subs-0f.adoc[`operator&lsqb;&rsqb;`] 
| Subscript operators
| xref:bsl/basic_string-0e/pop_back.adoc[`pop&lowbar;back`] 
| Erase the last character from this string&period; The behavior is undefined if this string is empty&period;
| xref:bsl/basic_string-0e/push_back.adoc[`push&lowbar;back`] 
| Append the specified `character` to this string&period;
| xref:bsl/basic_string-0e/rbegin-0c.adoc[`rbegin`] 
| `rbegin` overloads
| xref:bsl/basic_string-0e/rend-01.adoc[`rend`] 
| `rend` overloads
| xref:bsl/basic_string-0e/replace-0bd.adoc[`replace`] 
| `replace` overloads
| xref:bsl/basic_string-0e/replace_with_range.adoc[`replace&lowbar;with&lowbar;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`&period; Return a reference providing modifiable access to this string&period; The behavior is undefined unless `first` and `last` are both within the range `&lsqb;cbegin() &period;&period; cend()&rsqb;`&period; 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&lowbar;TYPE`&period;
| xref:bsl/basic_string-0e/reserve.adoc[`reserve`] 
| Change the capacity of this string to the specified `newCapacity`&period; Note that the capacity of a string is the maximum length it can accommodate without reallocation&period; The actual storage allocated may be higher&period;
| xref:bsl/basic_string-0e/resize-0c.adoc[`resize`] 
| `resize` overloads
| xref:bsl/basic_string-0e/resize_and_overwrite.adoc[`resize&lowbar;and&lowbar;overwrite`] 
| Change the length of this string to the specified `newLength`, erasing characters at the end if `newLength &lt; length()` or appending the appropriate number of characters at the end if `length() &lt; newLength`&period; Subsequently, invoke the specified `operation` passing the address of the null&hyphen;terminated buffer and the adjusted length of this string as parameters&period; Finally, change the length of this string to the value returned by the `operation`&period; Throw `length&lowbar;error` if `newLength &gt; max&lowbar;size()`&period; The behavior is undefined unless the value returned by the `operation` is less than or equal to `newLength`&period;
| xref:bsl/basic_string-0e/rfind-0f.adoc[`rfind`] 
| `rfind` overloads
| xref:bsl/basic_string-0e/shrink_to_fit.adoc[`shrink&lowbar;to&lowbar;fit`] 
| Request the removal of unused capacity by causing reallocation&period; Note that this method has no effect if the capacity is equal to the size&period; 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&period;
| xref:bsl/basic_string-0e/size.adoc[`size`] 
| Return the length of this string&period; Note that this number may differ from `CHAR&lowbar;TRAITS&colon;&colon;length(c&lowbar;str())` in case the string contains null characters&period; Also note that a null&hyphen;terminating character added by the `c&lowbar;str` method is _not_ counted in this length&period;
| xref:bsl/basic_string-0e/starts_with-06.adoc[`starts&lowbar;with`] 
| `starts&lowbar;with` overloads
| xref:bsl/basic_string-0e/substr-0e.adoc[`substr`] 
| `substr` overloads
| xref:bsl/basic_string-0e/swap.adoc[`swap`] 
| Exchange the value of this object with that of the specified `other` object&semi; also exchange the allocator of this object with that of `other` if the (template parameter) type `ALLOCATOR` has the `propagate&lowbar;on&lowbar;container&lowbar;swap` trait, and do not modify either allocator otherwise&period; This method provides the no&hyphen;throw exception&hyphen;safety guarantee&period; This operation has `O&lsqb;1&rsqb;` complexity if either this object was created with the same allocator as `other` or `ALLOCATOR` has the `propagate&lowbar;on&lowbar;container&lowbar;swap` trait&semi; otherwise, it has `O&lsqb;n &plus; m&rsqb;` complexity, where `n` and `m` are the lengths of this object and `other`, respectively&period; Note that this method&grave;s support for swapping objects created with different allocators when `ALLOCATOR` does not have the `propagate&lowbar;on&lowbar;container&lowbar;swap` trait is a departure from the C&plus;&plus; Standard&period;
| xref:bsl/basic_string-0e/2conversion-0a.adoc[`operator BloombergLP::bslmf::NestedTraitDeclaration&lt;basic&lowbar;string&lt;wchar&lowbar;t&gt;, IsBitwiseMoveable, BloombergLP&colon;&colon;bslmf&colon;&colon;IsBitwiseMoveable&lt;bsl&colon;&colon;allocator&lt;wchar&lowbar;t&gt;&gt;&colon;&colon;value&gt;`] 
| `CHAR&lowbar;TYPE` is required to be a POD as per the Standard, which makes `CHAR&lowbar;TYPE` bitwise&hyphen;movable, so `basic&lowbar;string` is bitwise&hyphen;movable as long as the (template parameter) type `ALLOCATOR` is also bitwise&hyphen;movable&period;
| xref:bsl/basic_string-0e/2conversion-0f.adoc[`operator basic&lowbar;string&lowbar;view&lt;wchar&lowbar;t, char&lowbar;traits&lt;wchar&lowbar;t&gt;&gt;`] 
| Convert this object to a `string&lowbar;view` type instantiated with the same character type and traits type&period; The return view will contain the same sequence of characters as this object&period; Note that this conversion operator can be invoked implicitly (e&period;g&period;, during argument passing)&period;
| xref:bsl/basic_string-0e/2conversion-09.adoc[`operator std::basic&lowbar;string&lt;wchar&lowbar;t, char&lowbar;traits&lt;wchar&lowbar;t&gt;, ALLOC2&gt;`] 
| Convert this object to a string type native to the compiler&apos;s library, instantiated with the same character type and traits type, but not necessarily the same allocator type&period; The return string will contain the same sequence of characters as `orig` and will have a default&hyphen;constructed allocator&period; Note that this conversion operator can be invoked implicitly (e&period;g&period;, during argument passing)&period;
|===


== Static Data Members

[cols="1,4"]
|===
| Name| Description
| xref:bsl/basic_string-0e/npos.adoc[`npos`] 
| Value used to denote &quot;not&hyphen;a&hyphen;position&quot;, guaranteed to be outside the range `&lsqb;0 &period;&period; max&lowbar;size()&rsqb;`&period;
|===


== Friends

[cols="1,4"]
|===
| Name| Description
| `xref:bsl/String_ClearProctor.adoc[bsl::String&lowbar;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&apos;s destruction&period; 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&period; Note that after constructing this proctor for a string `s`, the invariant `s&lsqb;s&period;length()&rsqb;&equals;&equals; CHAR&lowbar;TYPE()` is violated for non&hyphen;empty `s`&period; This invariant will be restored by either a successful `append` or by the proctor&apos;s destructor if an exception is thrown&period; Note that the template parameter was renamed from STRING&lowbar;TYPE to FULL&lowbar;STRING&lowbar;TYPE due to a name clash with a define elsewhere in the code base (see DRQS 112049582)&period;
| `xref:bsl/to_string-08.adoc[bsl::to&lowbar;string]`
| Constructs a string with contents equal to the specified `value`&period; The contents of the string will be the same as what `std&colon;&colon;sprintf(buf, &quot;%llu&quot;, value)` would produce with a sufficiently large buffer&period;
| `xref:bsl/to_string-07.adoc[bsl::to&lowbar;string]`
| Constructs a string with contents equal to the specified `value`&period; The contents of the string will be the same as what `std&colon;&colon;sprintf(buf, &quot;%lu&quot;, value)` would produce with a sufficiently large buffer&period;
| `xref:bsl/to_string-0c8.adoc[bsl::to&lowbar;string]`
| Constructs a string with contents equal to the specified `value`&period; The contents of the string will be the same as what `std&colon;&colon;sprintf(buf, &quot;%u&quot;, value)` would produce with a sufficiently large buffer&period;
| `xref:bsl/to_string-03.adoc[bsl::to&lowbar;string]`
| Constructs a string with contents equal to the specified `value`&period; The contents of the string will be the same as what `std&colon;&colon;sprintf(buf, &quot;%lld&quot;, value)` would produce with a sufficiently large buffer&period;
| `xref:bsl/to_string-09.adoc[bsl::to&lowbar;string]`
| Constructs a string with contents equal to the specified `value`&period; The contents of the string will be the same as what `std&colon;&colon;sprintf(buf, &quot;%ld&quot;, value)` would produce with a sufficiently large buffer&period;
| `xref:bsl/to_string-0c7.adoc[bsl::to&lowbar;string]`
| `to&lowbar;string` functions are made friends to allow access to the internal short string buffer&period;
|===


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