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

This class template provides an STL&hyphen;compliant `string` that conforms to the `bslma&colon;&colon;Allocator` model&period; For the requirements of a string class, consult the second revision of the ISO&sol;IEC 14882 Programming Language C&plus;&plus; (2003)&period; Note that the (template parameter) `CHAR&lowbar;TYPE` must be _equal_ to `ALLOCATOR&colon;&colon;value&lowbar;type`&period; In addition, this implementation offers strong exception guarantees (see below), with the general rules that&colon;

== Synopsis

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

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
template&lt;
    class CHAR&lowbar;TYPE,
    class CHAR&lowbar;TRAITS = char&lowbar;traits&lt;CHAR&lowbar;TYPE&gt;,
    class ALLOCATOR = xref:bsl/allocator-0df.adoc[allocator&lt;CHAR&lowbar;TYPE&gt;]&gt;
class basic&lowbar;string;
----

== Description

1&period; any method that would result in a string of length larger than the size returned by `max&lowbar;size` throws `std&colon;&colon;length&lowbar;error`, and 2&period; any method that attempts to access a position outside the valid range of a string throws `std&colon;&colon;out&lowbar;of&lowbar;range`&period;

Circumstances where a method throws `bsl&colon;&colon;length&lowbar;error` (1) are clear and not repeated in the individual function&hyphen;level documentations below&period;

More generally, this class supports an almost complete set of _in&hyphen;core_ _value_ _semantic_ operations, including copy construction, assignment, equality comparison (but excluding `ostream` printing since this component is below STL)&period; A precise operational definition of when two objects have the same value can be found in the description of `operator&equals;&equals;` for the class&period; This class is _exception_ _neutral_ with full guarantee of rollback&colon; if an exception is thrown during the invocation of a method on a pre&hyphen;existing object, the object is left unchanged&period; In no event is memory leaked&period;

Note that _aliasing_ (e&period;g&period;, using all or part of an object as both source and destination) is supported in all cases in the public interface of `basic&lowbar;string`&period; However, the private interface (`&period;&period;&period;Raw` methods) should be assumed to be not alias&hyphen;safe unless specifically noted otherwise&period;

== Type Aliases

[cols="1,4"]
|===
| Name| Description
| xref:bsl/basic_string-0faf/allocator_type.adoc[`allocator&lowbar;type`] 
| Alias for the (template parameter) `ALLOCATOR` type&period;
| xref:bsl/basic_string-0faf/const_iterator.adoc[`const&lowbar;iterator`] 
| Alias for a constant iterator over the characters of this string&period;
| xref:bsl/basic_string-0faf/const_pointer.adoc[`const&lowbar;pointer`] 
| Alias for a constant pointer to the character type&period;
| xref:bsl/basic_string-0faf/const_reference.adoc[`const&lowbar;reference`] 
| Alias for a non&hyphen;modifiable reference to the character type&period;
| xref:bsl/basic_string-0faf/const_reverse_iterator.adoc[`const&lowbar;reverse&lowbar;iterator`] 
| These types satisfy the `ReversibleSequence` requirements&period;
| xref:bsl/basic_string-0faf/difference_type.adoc[`difference&lowbar;type`] 
| This `typedef` is an alias to `AllocatorTraits&colon;&colon;difference&lowbar;type`&period;
| xref:bsl/basic_string-0faf/iterator.adoc[`iterator`] 
| Alias for an iterator over the characters of this string&period;
| xref:bsl/basic_string-0faf/pointer.adoc[`pointer`] 
| Alias for a pointer to the character type&period;
| xref:bsl/basic_string-0faf/reference.adoc[`reference`] 
| Alias for a modifiable reference to the character type&period;
| xref:bsl/basic_string-0faf/reverse_iterator.adoc[`reverse&lowbar;iterator`] 
| Alias for a reverse iterator over the characters of this string&period;
| xref:bsl/basic_string-0faf/size_type.adoc[`size&lowbar;type`] 
| Alias for the size type of this string&period;
| xref:bsl/basic_string-0faf/traits_type.adoc[`traits&lowbar;type`] 
| Alias for the (template parameter) `CHAR&lowbar;TRAITS` type&period;
| xref:bsl/basic_string-0faf/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-0faf/2constructor-0ec.adoc[`basic&lowbar;string`]         [.small]#[constructor]#
| Constructors
| xref:bsl/basic_string-0faf/2destructor.adoc[`&#126;basic&lowbar;string`] [.small]#[destructor]#
| Destroy this string object&period;
| xref:bsl/basic_string-0faf/operator_assign-00.adoc[`operator&equals;`] 
| Assignment operators
| xref:bsl/basic_string-0faf/append-0b.adoc[`append`] 
| `append` overloads
| xref:bsl/basic_string-0faf/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-0faf/assign-0ce.adoc[`assign`] 
| `assign` overloads
| xref:bsl/basic_string-0faf/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-0faf/at-01.adoc[`at`] 
| `at` overloads
| xref:bsl/basic_string-0faf/back-08.adoc[`back`] 
| `back` overloads
| xref:bsl/basic_string-0faf/begin-0f.adoc[`begin`] 
| `begin` overloads
| xref:bsl/basic_string-0faf/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-0faf/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-0faf/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-0faf/cend.adoc[`cend`] 
| Return the past&hyphen;the&hyphen;end iterator for this string&period;
| xref:bsl/basic_string-0faf/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-0faf/compare-0f.adoc[`compare`] 
| `compare` overloads
| xref:bsl/basic_string-0faf/contains-01.adoc[`contains`] 
| `contains` overloads
| xref:bsl/basic_string-0faf/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-0faf/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-0faf/crend.adoc[`crend`] 
| Return the past&hyphen;the&hyphen;end reverse iterator for this string&period;
| xref:bsl/basic_string-0faf/data-00.adoc[`data`] 
| `data` overloads
| xref:bsl/basic_string-0faf/empty.adoc[`empty`] 
| Return `true` if this string has length 0, and `false` otherwise&period;
| xref:bsl/basic_string-0faf/end-04.adoc[`end`] 
| `end` overloads
| xref:bsl/basic_string-0faf/ends_with-05.adoc[`ends&lowbar;with`] 
| `ends&lowbar;with` overloads
| xref:bsl/basic_string-0faf/erase-04.adoc[`erase`] 
| `erase` overloads
| xref:bsl/basic_string-0faf/find-0c8.adoc[`find`] 
| `find` overloads
| xref:bsl/basic_string-0faf/find_first_not_of-06.adoc[`find&lowbar;first&lowbar;not&lowbar;of`] 
| `find&lowbar;first&lowbar;not&lowbar;of` overloads
| xref:bsl/basic_string-0faf/find_first_of-0c.adoc[`find&lowbar;first&lowbar;of`] 
| `find&lowbar;first&lowbar;of` overloads
| xref:bsl/basic_string-0faf/find_last_not_of-0a0.adoc[`find&lowbar;last&lowbar;not&lowbar;of`] 
| `find&lowbar;last&lowbar;not&lowbar;of` overloads
| xref:bsl/basic_string-0faf/find_last_of-032.adoc[`find&lowbar;last&lowbar;of`] 
| `find&lowbar;last&lowbar;of` overloads
| xref:bsl/basic_string-0faf/front-0b.adoc[`front`] 
| `front` overloads
| xref:bsl/basic_string-0faf/get_allocator.adoc[`get&lowbar;allocator`] 
| Return the allocator used by this string to supply memory&period;
| xref:bsl/basic_string-0faf/insert-030.adoc[`insert`] 
| `insert` overloads
| xref:bsl/basic_string-0faf/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-0faf/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-0faf/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-0faf/operator_plus_eq-044.adoc[`operator&plus;&equals;`] 
| Addition assignment operators
| xref:bsl/basic_string-0faf/operator_subs-0fc.adoc[`operator&lsqb;&rsqb;`] 
| Subscript operators
| xref:bsl/basic_string-0faf/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-0faf/push_back.adoc[`push&lowbar;back`] 
| Append the specified `character` to this string&period;
| xref:bsl/basic_string-0faf/rbegin-0ef.adoc[`rbegin`] 
| `rbegin` overloads
| xref:bsl/basic_string-0faf/rend-02.adoc[`rend`] 
| `rend` overloads
| xref:bsl/basic_string-0faf/replace-06.adoc[`replace`] 
| `replace` overloads
| xref:bsl/basic_string-0faf/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-0faf/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-0faf/resize-01.adoc[`resize`] 
| `resize` overloads
| xref:bsl/basic_string-0faf/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-0faf/rfind-0c.adoc[`rfind`] 
| `rfind` overloads
| xref:bsl/basic_string-0faf/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-0faf/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-0faf/starts_with-03.adoc[`starts&lowbar;with`] 
| `starts&lowbar;with` overloads
| xref:bsl/basic_string-0faf/substr-0d8.adoc[`substr`] 
| `substr` overloads
| xref:bsl/basic_string-0faf/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-0faf/2conversion-00.adoc[`operator BloombergLP::bslmf::NestedTraitDeclaration&lt;basic&lowbar;string, IsBitwiseMoveable, BloombergLP&colon;&colon;bslmf&colon;&colon;IsBitwiseMoveable&lt;ALLOCATOR&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-0faf/2conversion-0f.adoc[`operator basic&lowbar;string&lowbar;view&lt;CHAR&lowbar;TYPE, CHAR&lowbar;TRAITS&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-0faf/2conversion-04.adoc[`operator std::basic&lowbar;string&lt;CHAR&lowbar;TYPE, CHAR&lowbar;TRAITS, 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-0faf/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;
|===


== Specializations

[cols="1"]
|===
| Name
| xref:bsl/basic_string-0fb.adoc[`basic&lowbar;string&lt;char&gt;`] 
| xref:bsl/basic_string-0ce.adoc[`basic&lowbar;string&lt;char16&lowbar;t&gt;`] 
| xref:bsl/basic_string-0f3.adoc[`basic&lowbar;string&lt;char32&lowbar;t&gt;`] 
| xref:bsl/basic_string-01d.adoc[`basic&lowbar;string&lt;char8&lowbar;t&gt;`] 
| xref:bsl/basic_string-0e.adoc[`basic&lowbar;string&lt;wchar&lowbar;t&gt;`] 
|===


== Deduction Guides

[cols="1,4"]
|===
| Name| Description
| xref:bsl/basic_string-016.adoc[`basic&lowbar;string&lt;CHAR&lowbar;TYPE&gt;`] 
| Deduce the template parameter `CHAR&lowbar;TYPE` from the `value&lowbar;type` of the `initializer&lowbar;list` passed to the constructor of `basic&lowbar;string`&period; This deduction guide does not participate unless the specified `ALLOC` is convertible to `bsl&colon;&colon;allocator&lt;CHAR&lowbar;TYPE&gt;`&period;
| xref:bsl/basic_string-0c4.adoc[`basic&lowbar;string&lt;CHAR&lowbar;TYPE&gt;`] 
| Deduce the template parameter `CHAR&lowbar;TYPE` from the parameters passed to the constructor of `basic&lowbar;string`&period; This deduction guide does not participate unless the specified `ALLOC` is convertible to `bsl&colon;&colon;allocator&lt;CHAR&lowbar;TYPE&gt;`&period;
| xref:bsl/basic_string-02.adoc[`basic&lowbar;string&lt;CHAR&lowbar;TYPE&gt;`] 
| Deduce the template parameter `CHAR&lowbar;TYPE` from the `value&lowbar;type` of the iterators passed to passed to the constructor of `basic&lowbar;string`&period; This deduction guide does not participate unless the specified `ALLOC` is convertible to `bsl&colon;&colon;allocator&lt;CHAR&lowbar;TYPE&gt;`&period;
| xref:bsl/basic_string-06.adoc[`basic&lowbar;string&lt;CHAR&lowbar;TYPE&gt;`] 
| Deduce the template parameter `CHAR&lowbar;TYPE` from the parameters passed to the constructor of `basic&lowbar;string`&period; This deduction guide does not participate unless the specified `ALLOC` is convertible to `bsl&colon;&colon;allocator&lt;CHAR&lowbar;TYPE&gt;`&period;
| xref:bsl/basic_string-00.adoc[`basic&lowbar;string&lt;CHAR&lowbar;TYPE&gt;`] 
| Deduce the template parameter `CHAR&lowbar;TYPE` from the parameters passed to the constructor of `basic&lowbar;string`&period; This deduction guide does not participate unless the specified `ALLOC` is convertible to `bsl&colon;&colon;allocator&lt;CHAR&lowbar;TYPE&gt;`&period;
| xref:bsl/basic_string-0fa9.adoc[`basic&lowbar;string&lt;CHAR&lowbar;TYPE, CHAR&lowbar;TRAITS&gt;`] 
| Deduce the template parameters `CHAR&lowbar;TYPE` and `TRAITS` from the corresponding template parameters of the `bsl&colon;&colon;basic&lowbar;string&lowbar;view` passed to the constructor of `basic&lowbar;string`&period; This deduction guide does not participate unless the specified `ALLOC` is convertible to `bsl&colon;&colon;allocator&lt;CHAR&lowbar;TYPE&gt;`&period;
| xref:bsl/basic_string-0c7.adoc[`basic&lowbar;string&lt;CHAR&lowbar;TYPE, CHAR&lowbar;TRAITS, ALLOCATOR&gt;`] 
| Deduce the template parameters `CHAR&lowbar;TYPE` and `TRAITS` from the corresponding template parameters of the `bsl&colon;&colon;basic&lowbar;string&lowbar;view` passed to the constructor of `basic&lowbar;string`&period; Deduce the template parameter `ALLOCATOR` from the optional argument passed to the constructor&period; This deduction guide does not participate unless the specified `ALLOCATOR` meets the requirements of a standard allocator&period;
| xref:bsl/basic_string-074.adoc[`basic&lowbar;string&lt;CHAR&lowbar;TYPE, CHAR&lowbar;TRAITS, ALLOCATOR&gt;`] 
| Deduce the template parameters `CHAR&lowbar;TYPE`, `TRAITS`, and `ALLOCATOR` from the corresponding template parameters of the `bsl&colon;&colon;basic&lowbar;string` passed to the constructor of `basic&lowbar;string`&period; This deduction guide does not participate unless the specified `ALLOC` is convertible to `ALLOCATOR`&period;
| xref:bsl/basic_string-09.adoc[`basic&lowbar;string&lt;CHAR&lowbar;TYPE, CHAR&lowbar;TRAITS, ALLOCATOR&gt;`] 
| Deduce the template parameters `CHAR&lowbar;TYPE`, `TRAITS`, and `ALLOCATOR` from the corresponding template parameters of the `bsl&colon;&colon;basic&lowbar;string` passed to the constructor of `basic&lowbar;string`&period; This deduction guide does not participate unless the specified `ALLOC` is convertible to `ALLOCATOR`&period;
| xref:bsl/basic_string-07a.adoc[`basic&lowbar;string&lt;CHAR&lowbar;TYPE, char&lowbar;traits&lt;CHAR&lowbar;TYPE&gt;, ALLOCATOR&gt;`] 
| Deduce the template parameter `CHAR&lowbar;TYPE` from the `value&lowbar;type` of the iterators passed to passed to the constructor of `basic&lowbar;string`&period; Deduce the template parameter `ALLOCATOR` from the optional argument passed to the constructor&period; This deduction guide does not participate unless the specified `ALLOCATOR` meets the requirements of a standard allocator&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;
|===

== Non-Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:bsl/erase-07.adoc[`erase`]
| Erase (in&hyphen;place) all the elements from the specified `str` that compare equal to the specified `c`, and return the number of erased elements&period;
| xref:bsl/erase_if-0e.adoc[`erase&lowbar;if`]
| Erase (in&hyphen;place) all the elements from the specified `str` where the specified `pred` returns `true`, and return the number of erased elements&period;
| xref:bsl/hashBasicString-0d.adoc[`hashBasicString`]
| Return a hash value for the specified `str`&period;
| xref:bsl/operator_plus-014.adoc[`operator&plus;`]
| Same as the primary `operator&plus;` with a C&hyphen;string `lhs`&period;
| xref:bsl/operator_plus-01b.adoc[`operator&plus;`]
| Same as the primary `operator&plus;` with a C&hyphen;string `rhs`&period;
| xref:bsl/operator_plus-02.adoc[`operator&plus;`]
| Same as the primary `operator&plus;` with a single `CHAR&lowbar;TYPE` `rhs` and rvalue `lhs`&period;
| xref:bsl/operator_plus-03.adoc[`operator&plus;`]
| Same as the primary `operator&plus;` with an rvalue `lhs` C&hyphen;string&period;
| xref:bsl/operator_plus-04.adoc[`operator&plus;`]
| Same as the primary `operator&plus;` overload with an rvalue `lhs`&period;
| xref:bsl/operator_plus-062.adoc[`operator&plus;`]
| Same as the primary `operator&plus;` with a string&hyphen;view&hyphen;like `lhs` and string `rhs`&period;
| xref:bsl/operator_plus-064.adoc[`operator&plus;`]
| Same as the primary `operator&plus;` with a C&hyphen;string `rhs` and rvalue `lhs`&period;
| xref:bsl/operator_plus-06c.adoc[`operator&plus;`]
| Return the concatenation of strings constructed from the specified `lhs` and `rhs` arguments, i&period;e&period;, `basic&lowbar;string(lhs)&period;append(rhs)`&period; The allocator of the returned string is determined per the rules in P1165 (https&colon;&sol;&sol;www&period;open&hyphen;std&period;org&sol;jtc1&sol;sc22&sol;wg21&sol;docs&sol;papers&sol;2018&sol;p1165r1&period;html)&period; Note that overloads that accept rvalue references are implemented for C&plus;&plus;11 and later only&period;
| xref:bsl/operator_plus-06e.adoc[`operator&plus;`]
| Same as the primary `operator&plus;` with a C&hyphen;string `rhs`&period;
| xref:bsl/operator_plus-07.adoc[`operator&plus;`]
| Same as the primary `operator&plus;` with an rvalue `lhs` and C&hyphen;string `rhs`&period;
| xref:bsl/operator_plus-08.adoc[`operator&plus;`]
| Same as the primary `operator&plus;` for mixed `std`&sol;`bsl` strings with an rvalue `rhs`&period;
| xref:bsl/operator_plus-09.adoc[`operator&plus;`]
| Same as the primary `operator&plus;` overload with an rvalue `lhs` and lvalue `rhs`&period;
| xref:bsl/operator_plus-0a.adoc[`operator&plus;`]
| Same as the primary `operator&plus;` for mixed `bsl`&sol;`std` strings&period;
| xref:bsl/operator_plus-0b.adoc[`operator&plus;`]
| Same as the primary `operator&plus;` with a single `CHAR&lowbar;TYPE` `lhs` and rvalue `rhs`&period;
| xref:bsl/operator_plus-0c9.adoc[`operator&plus;`]
| Same as the primary `operator&plus;` with C&hyphen;string operands&period;
| xref:bsl/operator_plus-0cd.adoc[`operator&plus;`]
| Same as the primary `operator&plus;` overload with an rvalue `lhs`&period;
| xref:bsl/operator_plus-0d8.adoc[`operator&plus;`]
| Same as the primary `operator&plus;` with a C&hyphen;string `lhs` and rvalue `rhs`&period;
| xref:bsl/operator_plus-0dd.adoc[`operator&plus;`]
| Same as the primary `operator&plus;` for mixed `bsl`&sol;`std` strings&period;
| xref:bsl/operator_plus-0e1.adoc[`operator&plus;`]
| Same as the primary `operator&plus;` with a C&hyphen;string `rhs` and rvalue `lhs`&period;
| xref:bsl/operator_plus-0e3.adoc[`operator&plus;`]
| Same as the primary `operator&plus;` for mixed `std`&sol;`bsl` strings&period;
| xref:bsl/operator_3way-041c.adoc[`operator&lt;&equals;&gt;`]
| Perform a lexicographic three&hyphen;way comparison of the specified `lhs` and the specified `rhs` strings by using `CHAR&lowbar;TRAITS&colon;&colon;eq` on each character&semi; return the result of that comparison&period;
| xref:bsl/operator_3way-07c1.adoc[`operator&lt;&equals;&gt;`]
| Perform a lexicographic three&hyphen;way comparison of the specified `lhs` and the specified `rhs` strings by using `CHAR&lowbar;TRAITS&colon;&colon;eq` on each character&semi; return the result of that comparison&period;
| xref:bsl/operator_3way-0d7.adoc[`operator&lt;&equals;&gt;`]
| Perform a lexicographic three&hyphen;way comparison of the specified `lhs` string and the specified `rhs` C&hyphen;string by using `CHAR&lowbar;TRAITS&colon;&colon;eq` on each character&semi; return the result of that comparison&period;
| xref:bsl/operator_eq-02e.adoc[`operator&equals;&equals;`]
| Return `true` if the specified `lhs` string has the same value as the specified `rhs` string, and `false` otherwise&period; 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&lowbar;TRAITS&colon;&colon;eq`&period;
| xref:bsl/operator_eq-052.adoc[`operator&equals;&equals;`]
| Same as the two&hyphen;argument `operator&equals;&equals;` for `basic&lowbar;string`&period;
| xref:bsl/operator_eq-0c0.adoc[`operator&equals;&equals;`]
| Same as the two&hyphen;argument `operator&equals;&equals;` for mixed `bsl`&sol;`std` strings&period;
| xref:bsl/quoted-03.adoc[`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&period; 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&period;
| xref:bsl/quoted-0c.adoc[`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&period; 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&period;
| xref:bsl/swap-0eb7.adoc[`swap`]
| Exchange the value of the specified `a` object with that of the specified `b` object&semi; also exchange the allocator of `a` with that of `b` 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 function provides the no&hyphen;throw exception&hyphen;safety guarantee&period; This operation has `O&lsqb;1&rsqb;` complexity if either `a` was created with the same allocator as `b` 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 `a` and `b`, respectively&period; Note that this function&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:BloombergLP/bslstl/operator_plus-00.adoc[`&colon;&colon;BloombergLP&colon;&colon;bslstl&colon;&colon;operator&plus;`]
| Return the concatenation of the specified `lhs` string ref and the specified `rhs` `std&colon;&colon;basic&lowbar;string` value&period;
| xref:BloombergLP/bslstl/operator_plus-02.adoc[`&colon;&colon;BloombergLP&colon;&colon;bslstl&colon;&colon;operator&plus;`]
| Return a `bsl&colon;&colon;string` having the value of the concatenation of the strings referred to by the specified `lhs` and `rhs` values&period;
| xref:BloombergLP/bslstl/operator_plus-03.adoc[`&colon;&colon;BloombergLP&colon;&colon;bslstl&colon;&colon;operator&plus;`]
| Return the concatenation of the specified C string and string ref&period;
| xref:BloombergLP/bslstl/operator_plus-05.adoc[`&colon;&colon;BloombergLP&colon;&colon;bslstl&colon;&colon;operator&plus;`]
| Return the concatenation of the specified `lhs` string ref and the specified `rhs` `bsl&colon;&colon;basic&lowbar;string` value&period;
| xref:BloombergLP/bslstl/operator_plus-072.adoc[`&colon;&colon;BloombergLP&colon;&colon;bslstl&colon;&colon;operator&plus;`]
| Return the concatenation of the specified `lhs` string ref and the specified `rhs` `bsl&colon;&colon;basic&lowbar;string` value&period;
| xref:BloombergLP/bslstl/operator_plus-076.adoc[`&colon;&colon;BloombergLP&colon;&colon;bslstl&colon;&colon;operator&plus;`]
| Return the concatenation of the specified string ref and C string&period;
| xref:BloombergLP/bslstl/operator_plus-0f7.adoc[`&colon;&colon;BloombergLP&colon;&colon;bslstl&colon;&colon;operator&plus;`]
| Return the concatenation of the specified `lhs` `std&colon;&colon;basic&lowbar;string` and the specified `rhs` string ref&period;
|===


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