deduction guides for std::basic_string

 

C++

Compiler support

Freestanding and hosted

Language

Standard library

Standard library headers

Named requirements

Feature test macros (C++20)

Language support library

Concepts library (C++20)

Metaprogramming library (C++11)

Diagnostics library

General utilities library

Strings library

Containers library

Iterators library

Ranges library (C++20)

Algorithms library

Numerics library

Localizations library

Input/output library

Filesystem library (C++17)

Regular expressions library (C++11)

Concurrency support library (C++11)

Execution support library (C++26)

Technical specifications

Symbols index

External libraries

 

Strings library

Null-terminated strings

Byte strings

Multibyte strings

Wide strings

Classes

basic_string

basic_string_view (C++17)

char_traits

 

std::basic_string

Member functions basic_string::basic_string basic_string::~basic_string basic_string::operator= basic_string::assign basic_string::assign_range (C++23) basic_string::get_allocator Element access basic_string::at basic_string::operator[] basic_string::front (DR*) basic_string::back (DR*) basic_string::data basic_string::c_str basic_string::operator  basic_string_view (C++17) Iterators basic_string::beginbasic_string::cbegin (C++11) basic_string::endbasic_string::cend (C++11) basic_string::rbeginbasic_string::crbegin (C++11) basic_string::rendbasic_string::crend (C++11) Capacity basic_string::empty basic_string::sizebasic_string::length basic_string::max_size basic_string::reserve basic_string::capacity basic_string::shrink_to_fit (DR*) Modifiers basic_string::clear basic_string::insert basic_string::insert_range (C++23) basic_string::erase basic_string::push_back basic_string::pop_back (DR*) basic_string::append basic_string::append_range (C++23) basic_string::operator+= basic_string::replace basic_string::replace_with_range (C++23) basic_string::copy basic_string::resize basic_string::resize_and_overwrite (C++23)   basic_string::swap

Search basic_string::find basic_string::rfind basic_string::find_first_of basic_string::find_first_not_of basic_string::find_last_of basic_string::find_last_not_of Operations basic_string::compare basic_string::starts_with (C++20) basic_string::ends_with (C++20) basic_string::contains (C++23) basic_string::substr Constants basic_string::npos Non-member functions operator+ swap(std::basic_string) erase(std::basic_string)erase_if(std::basic_string) (C++20)(C++20) I/O operator<<operator>> getline Comparison operator==operator!=operator<operator>operator<=operator>=operator<=> (until C++20)(until C++20)(until C++20)(until C++20)(until C++20)(C++20) Numeric conversions stoistolstoll (C++11)(C++11)(C++11) stoulstoull (C++11)(C++11) stofstodstold (C++11)(C++11)(C++11) to_string (C++11) to_wstring (C++11) Literals operator""s (C++14) Helper classes hash<std::basic_string> (C++11) Deduction guides (C++17)

 

Defined in header <string>
template< class InputIt, class Alloc = std::allocator<                              typename std::iterator_traits<InputIt>::value_type> > basic_string( InputIt, InputIt, Alloc = Alloc() )     -> basic_string<typename std::iterator_traits<InputIt>::value_type,                     std::char_traits<                         typename std::iterator_traits<InputIt>::value_type>, Alloc>;	(1)	(since C++17)
template< class CharT,           class Traits,           class Alloc = std::allocator<CharT> > explicit basic_string( std::basic_string_view<CharT, Traits>, const Alloc& = Alloc() )     -> basic_string<CharT, Traits, Alloc>;	(2)	(since C++17)
template< class CharT,           class Traits,           class Alloc = std::allocator<CharT>> > basic_string( std::basic_string_view<CharT, Traits>,               typename /* see below */::size_type,               typename /* see below */::size_type,               const Alloc& = Alloc() )     -> basic_string<CharT, Traits, Alloc>;	(3)	(since C++17)
template< ranges::input_range R,           class Alloc = std::allocator<ranges::range_value_t<R>> > basic_string( std::from_range_t, R&&, Alloc = Alloc() )     -> basic_string<ranges::range_value_t<R>,                        std::char_traits<ranges::range_value_t<R>>, Alloc>;	(4)	(since C++23)

1) This deduction guide is provided for std::basic_string to allow deduction from an iterator range. This overload participates in overload resolution only if InputIt satisfies LegacyInputIterator and Alloc satisfies Allocator.

2,3) These deduction guides are provided for std::basic_string to allow deduction from a std::basic_string_view. The size_type parameter type in (3) refers to the size_type member type of the type deduced by the deduction guide. These overloads participate in overload resolution only if Alloc satisfies Allocator.

4) This deduction guide is provided for std::basic_string to allow deduction from a std::from_range_t tag and an input_range.

Note: the extent to which the library determines that a type does not satisfy LegacyInputIterator is unspecified, except that as a minimum integral types do not qualify as input iterators. Likewise, the extent to which it determines that a type does not satisfy Allocator is unspecified, except that as a minimum the member type Alloc::value_type must exist and the expression std::declval<Alloc&>().allocate(std::size_t{}) must be well-formed when treated as an unevaluated operand.

Notes

Guides (2,3) are needed because the std::basic_string constructors for std::basic_string_views are made templates to avoid causing ambiguities in existing code, and those templates do not support class template argument deduction.

Notes

Feature-test macro	Value	Std	Feature
__cpp_lib_containers_ranges	202202L	(C++23)	Ranges-aware construction and insertion; overload (4)

Example

Run this code

#include <cassert>
#include <string>
#include <vector>
 
int main()
{
    std::vector<char> v = {'a', 'b', 'c'};
    std::basic_string s1(v.begin(), v.end()); // uses deduction guide (1)
    assert(s1 == "abc");
 
#if __cpp_lib_containers_ranges >= 202202L
    std::vector<wchar_t> v4{0x43, 43, 053, 0x32, 0x33};
    std::basic_string s4(std::from_range, v4); // uses deduction guide (4)
    assert(s4 == L"C++23");
#endif
}

Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

DR	Applied to	Behavior as published	Correct behavior
LWG 3075	C++17	deduction from basic_string_view was unsupported (exacerbated by LWG issue 2946)	deduction guides added