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

STL‐compliant string conforming to the `bslma::Allocator` model.

== Synopsis

Declared in `<bslstl_string.h>`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
template<
    class CHAR_TYPE,
    class CHAR_TRAITS = char_traits<CHAR_TYPE>,
    class ALLOCATOR = xref:bsl/allocator-0df.adoc[allocator<CHAR_TYPE>]>
class basic_string;
----

== Type Aliases

[cols="1,4"]
|===
| Name| Description
| xref:bsl/basic_string-0faf/allocator_type.adoc[`allocator_type`] 
| Alias for the (template parameter) `ALLOCATOR` type.
| xref:bsl/basic_string-0faf/const_iterator.adoc[`const_iterator`] 
| Alias for a constant iterator over the characters of this string.
| xref:bsl/basic_string-0faf/const_pointer.adoc[`const_pointer`] 
| Alias for a constant pointer to the character type.
| xref:bsl/basic_string-0faf/const_reference.adoc[`const_reference`] 
| Alias for a non‐modifiable reference to the character type.
| xref:bsl/basic_string-0faf/const_reverse_iterator.adoc[`const_reverse_iterator`] 
| These types satisfy the `ReversibleSequence` requirements.
| xref:bsl/basic_string-0faf/difference_type.adoc[`difference_type`] 
| This `typedef` is an alias to `AllocatorTraits::difference_type`.
| xref:bsl/basic_string-0faf/iterator.adoc[`iterator`] 
| Alias for an iterator over the characters of this string.
| xref:bsl/basic_string-0faf/pointer.adoc[`pointer`] 
| Alias for a pointer to the character type.
| xref:bsl/basic_string-0faf/reference.adoc[`reference`] 
| Alias for a modifiable reference to the character type.
| xref:bsl/basic_string-0faf/reverse_iterator.adoc[`reverse_iterator`] 
| Alias for a reverse iterator over the characters of this string.
| xref:bsl/basic_string-0faf/size_type.adoc[`size_type`] 
| Alias for the size type of this string.
| xref:bsl/basic_string-0faf/traits_type.adoc[`traits_type`] 
| Alias for the (template parameter) `CHAR_TRAITS` type.
| xref:bsl/basic_string-0faf/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-0faf/2constructor-0ec.adoc[`basic_string`]         [.small]#[constructor]#
| Constructors
| xref:bsl/basic_string-0faf/2destructor.adoc[`~basic_string`] [.small]#[destructor]#
| Destroy this string object.
| xref:bsl/basic_string-0faf/operator_assign-00.adoc[`operator=`] 
| Assignment operators
| xref:bsl/basic_string-0faf/append-0b.adoc[`append`] 
| `append` overloads
| xref:bsl/basic_string-0faf/append_range.adoc[`append_range`] 
| Append characters from a range to this string.
| xref:bsl/basic_string-0faf/assign-0ce.adoc[`assign`] 
| `assign` overloads
| xref:bsl/basic_string-0faf/assign_range.adoc[`assign_range`] 
| Assign characters from a range to this string.
| 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.
| xref:bsl/basic_string-0faf/begin-0f.adoc[`begin`] 
| `begin` overloads
| xref:bsl/basic_string-0faf/c_str.adoc[`c_str`] 
| Return a pointer to the null‐terminated character buffer.
| xref:bsl/basic_string-0faf/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-0faf/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-0faf/cend.adoc[`cend`] 
| Return the past‐the‐end iterator for this string.
| xref:bsl/basic_string-0faf/clear.adoc[`clear`] 
| Reset this string to an empty value.
| xref:bsl/basic_string-0faf/compare-0f.adoc[`compare`] 
| Lexicographically compare this string with another sequence.
| 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.
| xref:bsl/basic_string-0faf/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-0faf/crend.adoc[`crend`] 
| Return the past‐the‐end reverse iterator for this string.
| xref:bsl/basic_string-0faf/data-00.adoc[`data`] 
| Return a pointer to the character buffer of this string.
| xref:bsl/basic_string-0faf/empty.adoc[`empty`] 
| Return `true` if this string has length 0, and `false` otherwise.
| xref:bsl/basic_string-0faf/end-04.adoc[`end`] 
| `end` overloads
| xref:bsl/basic_string-0faf/ends_with-05.adoc[`ends_with`] 
| Return whether this string ends with the specified sequence.
| 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_first_not_of`] 
| `find_first_not_of` overloads
| xref:bsl/basic_string-0faf/find_first_of-0c.adoc[`find_first_of`] 
| `find_first_of` overloads
| xref:bsl/basic_string-0faf/find_last_not_of-0a0.adoc[`find_last_not_of`] 
| `find_last_not_of` overloads
| xref:bsl/basic_string-0faf/find_last_of-032.adoc[`find_last_of`] 
| `find_last_of` overloads
| xref:bsl/basic_string-0faf/front-0b.adoc[`front`] 
| `front` overloads
| xref:bsl/basic_string-0faf/get_allocator.adoc[`get_allocator`] 
| Return the allocator used by this string to supply memory.
| xref:bsl/basic_string-0faf/insert-030.adoc[`insert`] 
| `insert` overloads
| xref:bsl/basic_string-0faf/insert_range.adoc[`insert_range`] 
| Insert characters from a range into this string.
| xref:bsl/basic_string-0faf/length.adoc[`length`] 
| Return the length of this string.
| xref:bsl/basic_string-0faf/max_size.adoc[`max_size`] 
| Return the maximum possible length of this string.
| xref:bsl/basic_string-0faf/operator_plus_eq-044.adoc[`operator+=`] 
| Addition assignment operators
| xref:bsl/basic_string-0faf/operator_subs-0fc.adoc[`operator[]`] 
| Return a reference to the character at the specified position.
| xref:bsl/basic_string-0faf/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-0faf/push_back.adoc[`push_back`] 
| Append the specified `character` to this string.
| 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_with_range`] 
| Replace a substring with characters from a range.
| xref:bsl/basic_string-0faf/reserve.adoc[`reserve`] 
| Request that the capacity be at least the specified value.
| xref:bsl/basic_string-0faf/resize-01.adoc[`resize`] 
| Change the length of this string.
| xref:bsl/basic_string-0faf/resize_and_overwrite.adoc[`resize_and_overwrite`] 
| Resize this string and overwrite its contents.
| xref:bsl/basic_string-0faf/rfind-0c.adoc[`rfind`] 
| `rfind` overloads
| xref:bsl/basic_string-0faf/shrink_to_fit.adoc[`shrink_to_fit`] 
| Request removal of unused capacity.
| xref:bsl/basic_string-0faf/size.adoc[`size`] 
| Return the length of this string.
| xref:bsl/basic_string-0faf/starts_with-03.adoc[`starts_with`] 
| `starts_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.
| xref:bsl/basic_string-0faf/2conversion-00.adoc[`operator BloombergLP::bslmf::NestedTraitDeclaration<basic_string, IsBitwiseMoveable, BloombergLP::bslmf::IsBitwiseMoveable<ALLOCATOR>::value>`] 
| Declare that `basic_string` is bitwise‐movable when `ALLOCATOR` is.
| xref:bsl/basic_string-0faf/2conversion-0f.adoc[`operator basic_string_view<CHAR_TYPE, CHAR_TRAITS>`] 
| Convert this string to a matching `basic_string_view`.
| xref:bsl/basic_string-0faf/2conversion-04.adoc[`operator std::basic_string<CHAR_TYPE, CHAR_TRAITS, ALLOC2>`] 
| Convert this string to a platform `basic_string`.
|===


== Static Data Members

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


== Deduction Guides

[cols="1,4"]
|===
| Name| Description
| xref:bsl/basic_string-01.adoc[`basic_string<CHAR_TYPE>`] 
| Deduce template arguments for `basic_string` from constructor arguments.
| xref:bsl/basic_string-0c4.adoc[`basic_string<CHAR_TYPE>`] 
| Deduce template arguments for `basic_string` from constructor arguments.
| xref:bsl/basic_string-02.adoc[`basic_string<CHAR_TYPE>`] 
| Deduce template arguments for `basic_string` from constructor arguments.
| xref:bsl/basic_string-06.adoc[`basic_string<CHAR_TYPE>`] 
| Deduce template arguments for `basic_string` from constructor arguments.
| xref:bsl/basic_string-00.adoc[`basic_string<CHAR_TYPE>`] 
| Deduce template arguments for `basic_string` from constructor arguments.
| xref:bsl/basic_string-0fa9.adoc[`basic_string<CHAR_TYPE, CHAR_TRAITS>`] 
| Deduce template arguments for `basic_string` from constructor arguments.
| xref:bsl/basic_string-0c7.adoc[`basic_string<CHAR_TYPE, CHAR_TRAITS, ALLOCATOR>`] 
| Deduce template arguments for `basic_string` from constructor arguments.
| xref:bsl/basic_string-074.adoc[`basic_string<CHAR_TYPE, CHAR_TRAITS, ALLOCATOR>`] 
| Deduce template arguments for `basic_string` from constructor arguments.
| xref:bsl/basic_string-09.adoc[`basic_string<CHAR_TYPE, CHAR_TRAITS, ALLOCATOR>`] 
| Deduce template arguments for `basic_string` from constructor arguments.
| xref:bsl/basic_string-07a.adoc[`basic_string<CHAR_TYPE, char_traits<CHAR_TYPE>, ALLOCATOR>`] 
| Deduce template arguments for `basic_string` from constructor arguments.
|===


== Friends

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

== Non-Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:bsl/erase-07.adoc[`erase`]
| Erase all occurrences of a character from a string.
| xref:bsl/erase_if-0e.adoc[`erase_if`]
| Erase all characters matching a predicate from a string.
| xref:bsl/hashBasicString-0d.adoc[`hashBasicString`]
| Return a hash value for the specified string.
| xref:bsl/operator_plus-014.adoc[`operator+`]
| Same as the primary `operator+` with a C‐string `lhs`.
| xref:bsl/operator_plus-01b.adoc[`operator+`]
| Same as the primary `operator+` with a C‐string `rhs`.
| xref:bsl/operator_plus-02.adoc[`operator+`]
| Same as the primary `operator+` with a single `CHAR_TYPE` `rhs` and rvalue `lhs`.
| xref:bsl/operator_plus-03.adoc[`operator+`]
| Same as the primary `operator+` with an rvalue `lhs` C‐string.
| xref:bsl/operator_plus-04.adoc[`operator+`]
| Same as the primary `operator+` overload with an rvalue `lhs`.
| xref:bsl/operator_plus-062.adoc[`operator+`]
| Same as the primary `operator+` with a string‐view‐like `lhs` and string `rhs`.
| xref:bsl/operator_plus-064.adoc[`operator+`]
| Same as the primary `operator+` with a C‐string `rhs` and rvalue `lhs`.
| xref:bsl/operator_plus-06c.adoc[`operator+`]
| Return the concatenation of the specified operands.
| xref:bsl/operator_plus-06e.adoc[`operator+`]
| Return the concatenation of `lhs` and `rhs`.
| xref:bsl/operator_plus-07.adoc[`operator+`]
| Same as the primary `operator+` with an rvalue `lhs` and C‐string `rhs`.
| xref:bsl/operator_plus-08.adoc[`operator+`]
| Same as the primary `operator+` for mixed `std`/`bsl` strings with an rvalue `rhs`.
| xref:bsl/operator_plus-09.adoc[`operator+`]
| Same as the primary `operator+` overload with an rvalue `lhs` and lvalue `rhs`.
| xref:bsl/operator_plus-0a.adoc[`operator+`]
| Same as the primary `operator+` for mixed `bsl`/`std` strings.
| xref:bsl/operator_plus-0b.adoc[`operator+`]
| Same as the primary `operator+` with a single `CHAR_TYPE` `lhs` and rvalue `rhs`.
| xref:bsl/operator_plus-0c9.adoc[`operator+`]
| Same as the primary `operator+` with C‐string operands.
| xref:bsl/operator_plus-0cd.adoc[`operator+`]
| Same as the primary `operator+` overload with an rvalue `lhs`.
| xref:bsl/operator_plus-0d8.adoc[`operator+`]
| Same as the primary `operator+` with a C‐string `lhs` and rvalue `rhs`.
| xref:bsl/operator_plus-0dd.adoc[`operator+`]
| Same as the primary `operator+` for mixed `bsl`/`std` strings.
| xref:bsl/operator_plus-0e1.adoc[`operator+`]
| Same as the primary `operator+` with a C‐string `rhs` and rvalue `lhs`.
| xref:bsl/operator_plus-0e3.adoc[`operator+`]
| Same as the primary `operator+` for mixed `std`/`bsl` strings.
| xref:bsl/operator_3way-041c.adoc[`operator<=>`]
| Perform a lexicographic three‐way comparison of two strings.
| xref:bsl/operator_3way-07c1.adoc[`operator<=>`]
| Perform a lexicographic three‐way comparison of two strings.
| xref:bsl/operator_3way-0d7.adoc[`operator<=>`]
| Perform a lexicographic three‐way comparison of two strings.
| xref:bsl/operator_eq-02e.adoc[`operator==`]
| Return whether two strings have the same value.
| xref:bsl/operator_eq-052.adoc[`operator==`]
| Same as the two‐argument `operator==` for `basic_string`.
| xref:bsl/operator_eq-0c0.adoc[`operator==`]
| Same as the two‐argument `operator==` for mixed `bsl`/`std` strings.
| xref:bsl/quoted-03.adoc[`quoted`]
| Return a streamable object that quotes the specified `value`.
| xref:bsl/quoted-0c.adoc[`quoted`]
| Return a streamable object that quotes the specified `value`.
| xref:bsl/swap-0eb7.adoc[`swap`]
| Exchange the contents of two strings.
| xref:BloombergLP/bslstl/operator_plus-00.adoc[`::BloombergLP::bslstl::operator+`]
| Return the concatenation of the specified `lhs` string ref and the specified `rhs` `std::basic_string` value.
| xref:BloombergLP/bslstl/operator_plus-02.adoc[`::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.
| xref:BloombergLP/bslstl/operator_plus-03.adoc[`::BloombergLP::bslstl::operator+`]
| Return the concatenation of the specified C string and string ref.
| xref:BloombergLP/bslstl/operator_plus-05.adoc[`::BloombergLP::bslstl::operator+`]
| Return the concatenation of the specified `lhs` string ref and the specified `rhs` `bsl::basic_string` value.
| xref:BloombergLP/bslstl/operator_plus-072.adoc[`::BloombergLP::bslstl::operator+`]
| Return the concatenation of the specified `lhs` string ref and the specified `rhs` `bsl::basic_string` value.
| xref:BloombergLP/bslstl/operator_plus-076.adoc[`::BloombergLP::bslstl::operator+`]
| Return the concatenation of the specified string ref and C string.
| xref:BloombergLP/bslstl/operator_plus-0f7.adoc[`::BloombergLP::bslstl::operator+`]
| Return the concatenation of the specified `lhs` `std::basic_string` and the specified `rhs` string ref.
|===


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