std::string constructors

std::basic_string class can be constructed in many different ways. Use the button in the top-right corner to navigate with arrows for convenience.

note

std::basic_string is a class template, with following type parameters, that are used within constructors:

pub	CharT	character type
pub	Traits	traits class specifying the operations on the character type
pub	Allocator	Allocator type used to allocate internal storage

Default constructor

C++20

Simplified

// 1)
basic_string()
    : basic_string( Allocator() )
{
}

// 2)
explicit basic_string( Allocator const& alloc );

• constructor 1) is noexcept if constructor of the Allocator is noexcept as well
• constructor 2) is noexcept, because Allocator was constructed before
• both constructors are constexpr

Detailed

// 1)
constexpr basic_string() noexcept(noexcept( Allocator() ))
    : basic_string( Allocator() )
{
}

// 2)
explicit constexpr basic_string( Allocator const& alloc ) noexcept;

C++17

Simplified

// 1)
basic_string()
    : basic_string( Allocator() )
{
}

// 2)
explicit basic_string( Allocator const& alloc );

• constructor 1) is noexcept if constructor of the Allocator is noexcept as well
• constructor 2) is noexcept, because Allocator was constructed before

Detailed

// 1)
basic_string() noexcept(noexcept( Allocator() ))
    : basic_string( Allocator() )
{
}

// 2)
explicit basic_string( Allocator const& alloc ) noexcept;

until C++17

basic_string();

explicit basic_string( Allocator const& alloc );

Default constructor. Constructs empty string (zero size and unspecified capacity). If no allocator is supplied, allocator is obtained from a default-constructed instance.

Example

#include <iostream>
#include <string>
#include <cassert>

int main() {
	// Default constructed string:
	std::string s;

	// This assertion has to pass:
	assert(s.empty() && (s.length() == 0) && (s.size() == 0));

	// Capacity is unspecified:
    std::cout << "s.capacity(): " << s.capacity() << '\n';
}

Result

s.capacity(): 15

Repeat character constructor

C++20

constexpr basic_string(
		size_type			count,
		CharT				ch,
		Allocator const& 	alloc = Allocator()
	);

until C++20

basic_string(
		size_type			count,
		CharT				ch,
		Allocator const& 	alloc = Allocator()
	);

Constructs the string with count copies of character ch.

Deduction guide (since C++17)

This constructor is not used for class template argument deduction if the Allocator type that would be deduced does not qualify as an allocator.

Example

#include <iostream>
#include <string>
#include <iomanip> // for std::quoted

int main() {
	std::string s(4, '=');

	std::cout << std::quoted(s) << '\n';
}

Result (console)

"===="

Copy substring constructor (unbound)

C++20

constexpr basic_string(
		basic_string const&		other,
		size_type				pos,
		Allocator const&		alloc = Allocator()
	);

until C++20

basic_string(
		basic_string const&		other,
		size_type				pos,
		Allocator const&		alloc = Allocator()
	);

Constructs the string with a substring [pos, other.size()) of other.
Other words, copies the other string starting from element at pos index.

Example

#include <iostream>
#include <string>

int main() {

	// |01234567....|
	// |-------+++++|
	// "Hello, World"
	std::string hw = "Hello, World";
	std::string s(hw, 7);

	std::cout << s << '\n';
}

Result (console)

World

Copy substring constructor (bound)

C++20

constexpr basic_string(
		basic_string const&	other,
		size_type			pos,
		size_type			count,
		Allocator const&	alloc = Allocator()
	);

until C++20

basic_string(
		basic_string const&	other,
		size_type			pos,
		size_type			count,
		Allocator const&	alloc = Allocator()
	);

Constructs the string with a substring [pos, pos+count) of other. If count == npos, or if the requested substring lasts past the end of the string, the resulting substring is [pos, other.size()).

Example

#include <iostream>
#include <string>

int main() {
	
	// |012345......|
	// |--++++------|
	// "Hello, World"
	std::string hw = "Hello, World";
	std::string s(hw, 2, 4);

	std::cout << s << '\n';
}

Result (console)

llo,

Copy character range constructor (unbound)

C++20

constexpr basic_string(
		CharT const*		s,
		Allocator const&	alloc = Allocator()
	);

until C++20

basic_string(
		CharT const*		s,
		Allocator const&	alloc = Allocator()
	);

Constructs the string with the contents initialized with a copy of the null-terminated character string pointed to by s. The length of the string is determined by the first null character. The behavior is undefined if [s, s + Traits::length(s)) is not a valid range (for example, if s is a null pointer).

Deduction guide since C++17

This constructor is not used for class template argument deduction if the Allocator type that would be deduced does not qualify as an allocator. (since C++17)

Example

#include <iostream>
#include <string>

int main() {
	std::string s("Hello, World!");

	std::cout << s << '\n';
}

Result (console)

Hello, World!

Copy character range constructor (bound)

C++20

constexpr basic_string(
		CharT const*		s,
		size_type			count,
		Allocator const&	alloc = Allocator()
	);

until C++20

basic_string(
		CharT const*		s,
		size_type			count,
		Allocator const&	alloc = Allocator()
	);

Constructs the string with the first count characters of character string pointed to by s. s can contain null characters. The length of the string is count. The behavior is undefined if [s, s + count) is not a valid range.

Example

#include <iostream>
#include <string>

int main() {
	
	// |01234.......|
	// |+++++-------|
	// "Hello, World"
	std::string s("Hello, World", 5);

	std::cout << s << '\n';
}

Result (console)

Hello

Copy from iterator-range constructor

C++20

template <typename InputIt>
constexpr basic_string(
		InputIt				first,
		InputIt				last,
		Allocator const&	alloc = Allocator()
	);

until C++20

template <typename InputIt>
basic_string(
		InputIt				first,
		InputIt				last,
		Allocator const&	alloc = Allocator()
	);

Constructs the string with the contents of the range [first, last).

Details

C++11

Only if InputIt is an integral type, equivalent to overload (2), as if by
basic_string(static_cast<size_type>(first), static_cast<value_type>(last), alloc)

until C++11

This constructor only participates in overload resolution if InputIt satisfies LegacyInputIterator.

Example

#include <iostream>
#include <string>
#include <array>

int main() {
	std::array<char, 6> chars{ "Hello" };

	std::string s(chars.begin(), chars.end());

	std::cout << s << '\n';
}

Result (console)

Hello

Copy constructor

C++20

// 1)
constexpr basic_string( std::basic_string const& other );

// 2)
constexpr basic_string(
		std::basic_string const&	other,
		Allocator const&			alloc
	);

since C++11

// 1)
basic_string( std::basic_string const& other );

// 2)
basic_string(
		std::basic_string const&	other,
		Allocator const&			alloc
	);

Constructs the string with a copy of the contents of other.

You can optionally specify a custom allocator (2).

Example

#include <iostream>
#include <string>

int main() {
	std::string hw = "Hello, World";
	// Uses copy constructor, not assignment operator
	std::string s = hw;

	std::cout << s << '\n';
}

Result (console)

Hello World

Move constructor

C++20

// 1)
constexpr basic_string( std::basic_string && other ) noexcept;

// 2)
constexpr basic_string(
		std::basic_string &&	other,
		Allocator const&		alloc
	);

since C++11

// 1)
basic_string( std::basic_string && other ) noexcept;

// 2)
basic_string(
		std::basic_string &&	other,
		Allocator const&		alloc
	);

Constructs the string with the contents of other using move semantics. other is left in valid, but unspecified state.

You can optionally specify a custom allocator (2).

Example

#include <iostream>
#include <string>

int main() {
	std::string hw = "Hello, World";
	// Uses move constructor, not assignment operator
	std::string s = std::move(hw);
	// hw has unspecified state right now

	std::cout << s << '\n';
}

Result (console)

Hello, World

Initializer-list constructor

C++20

constexpr basic_string(
		std::initializer_list<CharT>	ilist,
		Allocator const& 				alloc = Allocator()
	);

since C++11

basic_string(
		std::initializer_list<CharT>	ilist,
		Allocator const& 				alloc = Allocator()
	);

Constructs the string with the contents of the initializer list ilist.

Example

#include <iostream>
#include <string>

int main() {
	std::string s = { "Hello" };
	// Same as:
	// std::string s = { 'H', 'e', 'l', 'l', 'o', '\0' };

	std::cout << s << '\n';
	std::cout << s.size() << '\n';
}

Result (console)

Hello
5

Copy from string_view-like type constructor (unbound)

C++20

template <typename T>
explicit  constexpr basic_string(
		T const&			t,
		Allocator const&	alloc = Allocator()
	);

since C++17

template <typename T>
explicit basic_string(
		T const&			t,
		Allocator const&	alloc = Allocator()
	);

Constructs the string from contents copied from object t of a string_view-like type T.

How does it work

Implicitly converts t to a string view sv as if by

std::basic_string_view<CharT, Traits> sv = t;

then initializes the string with the contents of sv, as if by

basic_string(sv.data(), sv.size(), alloc)

Overload resolution

This overload participates in overload resolution only if

std::is_convertible_v< const T&, std::basic_string_view<CharT, Traits> >

is true and

std::is_convertible_v<const T&, const CharT*>

is false.

Copy from string_view-like type constructor (bound)

C++20

template <typename T>
explicit  constexpr basic_string(
		T const&			t,
		size_type			pos,
		size_type			n,
		Allocator const&	alloc = Allocator()
	);

since C++17

template <typename T>
explicit basic_string(
		T const&			t,
		size_type			pos,
		size_type			n,
		Allocator const&	alloc = Allocator()
	);

Constructs the string from subrange [pos, pos + n) of contents copied from object t of a string_view-like type T.

How does it work

Implicitly converts t to a string view sv as if by

std::basic_string_view<CharT, Traits> sv = t;

then initializes the string with the subrange [pos, pos + n) of sv as if by

basic_string(sv.data(), sv.size(), alloc)

Overload resolution

This overload participates in overload resolution only if

std::is_convertible_v< const T&, std::basic_string_view<CharT, Traits> >

is true.

Deleted std::nullptr_t constructor

since C++23

constexpr basic_string( std::nullptr_t ) = delete;

basic_string cannot be constructed from nullptr.