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

STL&hyphen;compliant string conforming to the `bslma&colon;&colon;Allocator` model&period;

== 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;
----

== 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 characters from a range to this string&period;
| xref:bsl/basic_string-0faf/assign-0ce.adoc[`assign`] 
| `assign` overloads
| xref:bsl/basic_string-0faf/assign_range.adoc[`assign&lowbar;range`] 
| Assign characters from a range to this string&period;
| xref:bsl/basic_string-0faf/at-01.adoc[`at`] 
| `at` overloads
| xref:bsl/basic_string-0faf/back-08.adoc[`back`] 
| Return a reference to the last character of this string&period;
| xref:bsl/basic_string-0faf/begin-0f.adoc[`begin`] 
| `begin` overloads
| xref:bsl/basic_string-0faf/c_str.adoc[`c&lowbar;str`] 
| Return a pointer to the null&hyphen;terminated character buffer&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;
| xref:bsl/basic_string-0faf/compare-0f.adoc[`compare`] 
| Lexicographically compare this string with another sequence&period;
| xref:bsl/basic_string-0faf/contains-01.adoc[`contains`] 
| `contains` overloads
| xref:bsl/basic_string-0faf/copy.adoc[`copy`] 
| Copy characters from this string into a character buffer&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`] 
| Return a pointer to the character buffer of this string&period;
| 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`] 
| Return whether this string ends with the specified sequence&period;
| 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 characters from a range into this string&period;
| xref:bsl/basic_string-0faf/length.adoc[`length`] 
| Return the length of this string&period;
| xref:bsl/basic_string-0faf/max_size.adoc[`max&lowbar;size`] 
| Return the maximum possible length of this string&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;`] 
| Return a reference to the character at the specified position&period;
| 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 a substring with characters from a range&period;
| xref:bsl/basic_string-0faf/reserve.adoc[`reserve`] 
| Request that the capacity be at least the specified value&period;
| xref:bsl/basic_string-0faf/resize-01.adoc[`resize`] 
| Change the length of this string&period;
| xref:bsl/basic_string-0faf/resize_and_overwrite.adoc[`resize&lowbar;and&lowbar;overwrite`] 
| Resize this string and overwrite its contents&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 removal of unused capacity&period;
| xref:bsl/basic_string-0faf/size.adoc[`size`] 
| Return the length of this string&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 contents of two strings&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;`] 
| Declare that `basic&lowbar;string` is bitwise&hyphen;movable when `ALLOCATOR` is&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 string to a matching `basic&lowbar;string&lowbar;view`&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 string to a platform `basic&lowbar;string`&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;
|===


== Deduction Guides

[cols="1,4"]
|===
| Name| Description
| xref:bsl/basic_string-01.adoc[`basic&lowbar;string&lt;CHAR&lowbar;TYPE&gt;`] 
| Deduce template arguments for `basic&lowbar;string` from constructor arguments&period;
| xref:bsl/basic_string-0c4.adoc[`basic&lowbar;string&lt;CHAR&lowbar;TYPE&gt;`] 
| Deduce template arguments for `basic&lowbar;string` from constructor arguments&period;
| xref:bsl/basic_string-02.adoc[`basic&lowbar;string&lt;CHAR&lowbar;TYPE&gt;`] 
| Deduce template arguments for `basic&lowbar;string` from constructor arguments&period;
| xref:bsl/basic_string-06.adoc[`basic&lowbar;string&lt;CHAR&lowbar;TYPE&gt;`] 
| Deduce template arguments for `basic&lowbar;string` from constructor arguments&period;
| xref:bsl/basic_string-00.adoc[`basic&lowbar;string&lt;CHAR&lowbar;TYPE&gt;`] 
| Deduce template arguments for `basic&lowbar;string` from constructor arguments&period;
| xref:bsl/basic_string-0fa9.adoc[`basic&lowbar;string&lt;CHAR&lowbar;TYPE, CHAR&lowbar;TRAITS&gt;`] 
| Deduce template arguments for `basic&lowbar;string` from constructor arguments&period;
| xref:bsl/basic_string-0c7.adoc[`basic&lowbar;string&lt;CHAR&lowbar;TYPE, CHAR&lowbar;TRAITS, ALLOCATOR&gt;`] 
| Deduce template arguments for `basic&lowbar;string` from constructor arguments&period;
| xref:bsl/basic_string-074.adoc[`basic&lowbar;string&lt;CHAR&lowbar;TYPE, CHAR&lowbar;TRAITS, ALLOCATOR&gt;`] 
| Deduce template arguments for `basic&lowbar;string` from constructor arguments&period;
| xref:bsl/basic_string-09.adoc[`basic&lowbar;string&lt;CHAR&lowbar;TYPE, CHAR&lowbar;TRAITS, ALLOCATOR&gt;`] 
| Deduce template arguments for `basic&lowbar;string` from constructor arguments&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 template arguments for `basic&lowbar;string` from constructor arguments&period;
|===


== Friends

[cols="1,4"]
|===
| Name| Description
| `xref:bsl/String_ClearProctor.adoc[bsl::String&lowbar;ClearProctor]`
| Proctor that clears a string and restores it unless released&period;
| `xref:bsl/to_string-08.adoc[bsl::to&lowbar;string]`
| Convert a numeric value to a `string`&period;
| `xref:bsl/to_string-07.adoc[bsl::to&lowbar;string]`
| Convert a numeric value to a `string`&period;
| `xref:bsl/to_string-0c8.adoc[bsl::to&lowbar;string]`
| Convert a numeric value to a `string`&period;
| `xref:bsl/to_string-03.adoc[bsl::to&lowbar;string]`
| Convert a numeric value to a `string`&period;
| `xref:bsl/to_string-09.adoc[bsl::to&lowbar;string]`
| Convert a numeric value to a `string`&period;
| `xref:bsl/to_string-0c7.adoc[bsl::to&lowbar;string]`
| Convert a numeric value to a `string`&period;
|===

== Non-Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:bsl/erase-07.adoc[`erase`]
| Erase all occurrences of a character from a string&period;
| xref:bsl/erase_if-0e.adoc[`erase&lowbar;if`]
| Erase all characters matching a predicate from a string&period;
| xref:bsl/hashBasicString-0d.adoc[`hashBasicString`]
| Return a hash value for the specified string&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 the specified operands&period;
| xref:bsl/operator_plus-06e.adoc[`operator&plus;`]
| Return the concatenation of `lhs` and `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 two strings&period;
| xref:bsl/operator_3way-07c1.adoc[`operator&lt;&equals;&gt;`]
| Perform a lexicographic three&hyphen;way comparison of two strings&period;
| xref:bsl/operator_3way-0d7.adoc[`operator&lt;&equals;&gt;`]
| Perform a lexicographic three&hyphen;way comparison of two strings&period;
| xref:bsl/operator_eq-02e.adoc[`operator&equals;&equals;`]
| Return whether two strings have the same value&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 a streamable object that quotes the specified `value`&period;
| xref:bsl/quoted-0c.adoc[`quoted`]
| Return a streamable object that quotes the specified `value`&period;
| xref:bsl/swap-0eb7.adoc[`swap`]
| Exchange the contents of two strings&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]#
