This class template provides an STL‐compliant string that conforms to the bslma::Allocator model. For the requirements of a string class, consult the second revision of the ISO/IEC 14882 Programming Language C++ (2003). Note that the (template parameter) CHAR_TYPE must be equal to ALLOCATOR::value_type. In addition, this implementation offers strong exception guarantees (see below), with the general rules that:

Synopsis

Declared in <bslstl_string.h>

template<
    class CHAR_TYPE,
    class CHAR_TRAITS = char_traits<CHAR_TYPE>,
    class ALLOCATOR = allocator<CHAR_TYPE>>
class basic_string;

Description

1. any method that would result in a string of length larger than the size returned by max_size throws std::length_error, and 2. any method that attempts to access a position outside the valid range of a string throws std::out_of_range.

Circumstances where a method throws bsl::length_error (1) are clear and not repeated in the individual function‐level documentations below.

More generally, this class supports an almost complete set of in‐core value semantic operations, including copy construction, assignment, equality comparison (but excluding ostream printing since this component is below STL). A precise operational definition of when two objects have the same value can be found in the description of operator== for the class. This class is exception neutral with full guarantee of rollback: if an exception is thrown during the invocation of a method on a pre‐existing object, the object is left unchanged. In no event is memory leaked.

Note that aliasing (e.g., using all or part of an object as both source and destination) is supported in all cases in the public interface of basic_string. However, the private interface (...Raw methods) should be assumed to be not alias‐safe unless specifically noted otherwise.

Type Aliases

Name

Description

allocator_type

Alias for the (template parameter) ALLOCATOR type.

const_iterator

Alias for a constant iterator over the characters of this string.

const_pointer

Alias for a constant pointer to the character type.

const_reference

Alias for a non‐modifiable reference to the character type.

const_reverse_iterator

These types satisfy the ReversibleSequence requirements.

difference_type

This typedef is an alias to AllocatorTraits::difference_type.

iterator

Alias for an iterator over the characters of this string.

pointer

Alias for a pointer to the character type.

reference

Alias for a modifiable reference to the character type.

reverse_iterator

Alias for a reverse iterator over the characters of this string.

size_type

Alias for the size type of this string.

traits_type

Alias for the (template parameter) CHAR_TRAITS type.

value_type

Alias for the character type stored in this string.

Member Functions

Name

Description

basic_string [constructor]

Constructors

~basic_string [destructor]

Destroy this string object.

operator=

Assignment operators

append

append overloads

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.

assign

assign overloads

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.

at

at overloads

back

back overloads

begin

begin overloads

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.

capacity

Return the capacity of this string, i.e., the maximum length for which resizing is guaranteed not to trigger a reallocation.

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).

cend

Return the past‐the‐end iterator for this string.

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.

compare

compare overloads

contains

contains overloads

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.

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).

crend

Return the past‐the‐end reverse iterator for this string.

data

data overloads

empty

Return true if this string has length 0, and false otherwise.

end

end overloads

ends_with

ends_with overloads

erase

erase overloads

find

find overloads

find_first_not_of

find_first_not_of overloads

find_first_of

find_first_of overloads

find_last_not_of

find_last_not_of overloads

find_last_of

find_last_of overloads

front

front overloads

get_allocator

Return the allocator used by this string to supply memory.

insert

insert overloads

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>

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.

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.

operator+=

Addition assignment operators

operator[]

Subscript operators

pop_back

Erase the last character from this string. The behavior is undefined if this string is empty.

push_back

Append the specified character to this string.

rbegin

rbegin overloads

rend

rend overloads

replace

replace overloads

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.

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.

resize

resize overloads

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.

rfind

rfind overloads

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.

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.

starts_with

starts_with overloads

substr

substr overloads

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.

operator BloombergLP::bslmf::NestedTraitDeclaration<basic_string, IsBitwiseMoveable, BloombergLP::bslmf::IsBitwiseMoveable<ALLOCATOR>::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.

operator basic_string_view<CHAR_TYPE, CHAR_TRAITS>

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).

operator std::basic_string<CHAR_TYPE, CHAR_TRAITS, 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

Name

Description

npos

Value used to denote "not‐a‐position", guaranteed to be outside the range [0 .. max_size()].

Specializations

Name

basic_string<char>

basic_string<char16_t>

basic_string<char32_t>

basic_string<char8_t>

basic_string<wchar_t>

Deduction Guides

Name

Description

basic_string<CHAR_TYPE>

Deduce the template parameter CHAR_TYPE from the value_type of the initializer_list passed to the constructor of basic_string. This deduction guide does not participate unless the specified ALLOC is convertible to bsl::allocator<CHAR_TYPE>.

basic_string<CHAR_TYPE>

Deduce the template parameter CHAR_TYPE from the parameters passed to the constructor of basic_string. This deduction guide does not participate unless the specified ALLOC is convertible to bsl::allocator<CHAR_TYPE>.

basic_string<CHAR_TYPE>

Deduce the template parameter CHAR_TYPE from the value_type of the iterators passed to passed to the constructor of basic_string. This deduction guide does not participate unless the specified ALLOC is convertible to bsl::allocator<CHAR_TYPE>.

basic_string<CHAR_TYPE>

Deduce the template parameter CHAR_TYPE from the parameters passed to the constructor of basic_string. This deduction guide does not participate unless the specified ALLOC is convertible to bsl::allocator<CHAR_TYPE>.

basic_string<CHAR_TYPE>

Deduce the template parameter CHAR_TYPE from the parameters passed to the constructor of basic_string. This deduction guide does not participate unless the specified ALLOC is convertible to bsl::allocator<CHAR_TYPE>.

basic_string<CHAR_TYPE, CHAR_TRAITS>

Deduce the template parameters CHAR_TYPE and TRAITS from the corresponding template parameters of the bsl::basic_string_view passed to the constructor of basic_string. This deduction guide does not participate unless the specified ALLOC is convertible to bsl::allocator<CHAR_TYPE>.

basic_string<CHAR_TYPE, CHAR_TRAITS, ALLOCATOR>

Deduce the template parameters CHAR_TYPE and TRAITS from the corresponding template parameters of the bsl::basic_string_view passed to the constructor of basic_string. Deduce the template parameter ALLOCATOR from the optional argument passed to the constructor. This deduction guide does not participate unless the specified ALLOCATOR meets the requirements of a standard allocator.

basic_string<CHAR_TYPE, CHAR_TRAITS, ALLOCATOR>

Deduce the template parameters CHAR_TYPE, TRAITS, and ALLOCATOR from the corresponding template parameters of the bsl::basic_string passed to the constructor of basic_string. This deduction guide does not participate unless the specified ALLOC is convertible to ALLOCATOR.

basic_string<CHAR_TYPE, CHAR_TRAITS, ALLOCATOR>

Deduce the template parameters CHAR_TYPE, TRAITS, and ALLOCATOR from the corresponding template parameters of the bsl::basic_string passed to the constructor of basic_string. This deduction guide does not participate unless the specified ALLOC is convertible to ALLOCATOR.

basic_string<CHAR_TYPE, char_traits<CHAR_TYPE>, ALLOCATOR>

Deduce the template parameter CHAR_TYPE from the value_type of the iterators passed to passed to the constructor of basic_string. Deduce the template parameter ALLOCATOR from the optional argument passed to the constructor. This deduction guide does not participate unless the specified ALLOCATOR meets the requirements of a standard allocator.

Friends

Name

Description

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).

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.

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.

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.

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.

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.

bsl::to_string

to_string functions are made friends to allow access to the internal short string buffer.

Non-Member Functions

Name

Description

erase

Erase (in‐place) all the elements from the specified str that compare equal to the specified c, and return the number of erased elements.

erase_if

Erase (in‐place) all the elements from the specified str where the specified pred returns true, and return the number of erased elements.

hashBasicString

Return a hash value for the specified str.

operator+

Same as the primary operator+ with a C‐string lhs.

operator+

Same as the primary operator+ with a C‐string rhs.

operator+

Same as the primary operator+ with a single CHAR_TYPE rhs and rvalue lhs.

operator+

Same as the primary operator+ with an rvalue lhs C‐string.

operator+

Same as the primary operator+ overload with an rvalue lhs.

operator+

Same as the primary operator+ with a string‐view‐like lhs and string rhs.

operator+

Same as the primary operator+ with a C‐string rhs and rvalue lhs.

operator+

Return the concatenation of strings constructed from the specified lhs and rhs arguments, i.e., basic_string(lhs).append(rhs). The allocator of the returned string is determined per the rules in P1165 (https://www.open‐std.org/jtc1/sc22/wg21/docs/papers/2018/p1165r1.html). Note that overloads that accept rvalue references are implemented for C++11 and later only.

operator+

Same as the primary operator+ with a C‐string rhs.

operator+

Same as the primary operator+ with an rvalue lhs and C‐string rhs.

operator+

Same as the primary operator+ for mixed std/`bsl` strings with an rvalue rhs.

operator+

Same as the primary operator+ overload with an rvalue lhs and lvalue rhs.

operator+

Same as the primary operator+ for mixed bsl/`std` strings.

operator+

Same as the primary operator+ with a single CHAR_TYPE lhs and rvalue rhs.

operator+

Same as the primary operator+ with C‐string operands.

operator+

Same as the primary operator+ overload with an rvalue lhs.

operator+

Same as the primary operator+ with a C‐string lhs and rvalue rhs.

operator+

Same as the primary operator+ for mixed bsl/`std` strings.

operator+

Same as the primary operator+ with a C‐string rhs and rvalue lhs.

operator+

Same as the primary operator+ for mixed std/`bsl` strings.

operator<=>

Perform a lexicographic three‐way comparison of the specified lhs and the specified rhs strings by using CHAR_TRAITS::eq on each character; return the result of that comparison.

operator<=>

Perform a lexicographic three‐way comparison of the specified lhs and the specified rhs strings by using CHAR_TRAITS::eq on each character; return the result of that comparison.

operator<=>

Perform a lexicographic three‐way comparison of the specified lhs string and the specified rhs C‐string by using CHAR_TRAITS::eq on each character; return the result of that comparison.

operator==

Return true if the specified lhs string has the same value as the specified rhs string, and false otherwise. 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_TRAITS::eq.

operator==

Same as the two‐argument operator== for basic_string.

operator==

Same as the two‐argument operator== for mixed bsl/`std` strings.

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. 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.

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. 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.

swap

Exchange the value of the specified a object with that of the specified b object; also exchange the allocator of a with that of b if the (template parameter) type ALLOCATOR has the propagate_on_container_swap trait, and do not modify either allocator otherwise. This function provides the no‐throw exception‐safety guarantee. This operation has O[1] complexity if either a was created with the same allocator as b or ALLOCATOR has the propagate_on_container_swap trait; otherwise, it has O[n + m] complexity, where n and m are the lengths of a and b, respectively. Note that this function`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.

::BloombergLP::bslstl::operator+

Return the concatenation of the specified lhs string ref and the specified rhs std::basic_string value.

::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.

::BloombergLP::bslstl::operator+

Return the concatenation of the specified C string and string ref.

::BloombergLP::bslstl::operator+

Return the concatenation of the specified lhs string ref and the specified rhs bsl::basic_string value.

::BloombergLP::bslstl::operator+

Return the concatenation of the specified lhs string ref and the specified rhs bsl::basic_string value.

::BloombergLP::bslstl::operator+

Return the concatenation of the specified string ref and C string.

::BloombergLP::bslstl::operator+

Return the concatenation of the specified lhs std::basic_string and the specified rhs string ref.

Created with MrDocs