public member function
<string>

std::basic_string::basic_string

default (1)
explicit basic_string (const allocator_type& alloc = allocator_type());
copy (2)
basic_string (const basic_string& str);
substring (3)
basic_string (const basic_string& str, size_type pos, size_type len = npos,
              const allocator_type& alloc = allocator_type());
from c-string (4)
basic_string (const charT* s, const allocator_type& alloc = allocator_type());
from sequence (5)
basic_string (const charT* s, size_type n,
              const allocator_type& alloc = allocator_type());
fill (6)
basic_string (size_type n, charT c,
              const allocator_type& alloc = allocator_type());
range (7)
template <class InputIterator>
  basic_string  (InputIterator first, InputIterator last,
                 const allocator_type& alloc = allocator_type());
default (1)
explicit basic_string (const allocator_type& alloc = allocator_type());
copy (2)
basic_string (const basic_string& str);
basic_string (const basic_string& str, const allocator_type& alloc);
substring (3)
basic_string (const basic_string& str, size_type pos, size_type len = npos,
              const allocator_type& alloc = allocator_type());
from c-string (4)
basic_string (const charT* s, const allocator_type& alloc = allocator_type());
from buffer (5)
basic_string (const charT* s, size_type n,
              const allocator_type& alloc = allocator_type());
fill (6)
basic_string (size_type n, charT c,
              const allocator_type& alloc = allocator_type());
range (7)
template <class InputIterator>
  basic_string  (InputIterator first, InputIterator last,
                 const allocator_type& alloc = allocator_type());
initializer list (8)
basic_string (initializer_list<charT> il,
              const allocator_type& alloc = allocator_type());
move (9)
basic_string (basic_string&& str) noexcept;
basic_string (basic_string&& str, const allocator_type& alloc);
default (1)
basic_string();
explicit basic_string (const allocator_type& alloc);
copy (2)
basic_string (const basic_string& str);
basic_string (const basic_string& str, const allocator_type& alloc);
substring (3)
basic_string (const basic_string& str, size_type pos, size_type len = npos,
              const allocator_type& alloc = allocator_type());
from c-string (4)
basic_string (const charT* s, const allocator_type& alloc = allocator_type());
from buffer (5)
basic_string (const charT* s, size_type n,
              const allocator_type& alloc = allocator_type());
fill (6)
basic_string (size_type n, charT c,
              const allocator_type& alloc = allocator_type());
range (7)
template <class InputIterator>
  basic_string  (InputIterator first, InputIterator last,
                 const allocator_type& alloc = allocator_type());
initializer list (8)
basic_string (initializer_list<charT> il,
              const allocator_type& alloc = allocator_type());
move (9)
basic_string (basic_string&& str) noexcept;
basic_string (basic_string&& str, const allocator_type& alloc);
Construct basic_string object
Constructs a basic_string object, initializing its value depending on the constructor version used:

(1) empty string constructor (default constructor)
Constructs an empty string, with a length of zero characters.
(2) copy constructors
Constructs a copy of str.
(3) substring constructor
Copies the portion of str that begins at the character position pos and spans len characters (or until the end of str, if either str is too short or if len is basic_string::npos).
(4) from c-string
Copies the null-terminated character sequence (C-string) pointed by s.
The length is determined by calling traits_type::length(s).
(5) from buffer
Copies the first n characters from the array of characters pointed by s.
(6) fill constructor
Fills the string with n consecutive copies of character c.
(7) range constructor
Copies the sequence of characters in the range [first,last), in the same order.
(8) initializer list
Copies each of the characters in il, in the same order.
(9) move contructors
Acquires the contents of str.
str is left in an unspecified but valid state.

The basic_string object keeps an internal copy of alloc, which is used to allocate and free storage for the characters it contains throughout its lifetime.
The copy constructor (2) creates an object that keeps and uses a copy of str's allocator.
The basic_string object keeps an internal copy of alloc, which is used to allocate and free storage for the characters it contains.
The copy constructor (2, first signature) creates a container that keeps and uses a copy of the allocator returned by calling the appropriate selected_on_container_copy_construction trait on str's allocator.
The move constructor (9, first signature) acquires str's allocator.
The basic_string object keeps an internal copy of alloc, which is used to allocate and free storage for the characters it contains.
The default constructor (1, first signature) uses a default-constructed allocator.
The copy constructor (2, first signature) creates a container that keeps and uses a copy of the allocator returned by calling the appropriate selected_on_container_copy_construction trait on str's allocator.
The move constructor (9, first signature) acquires str's allocator.

Parameters

alloc
Allocator object.
The container keeps and uses an internal copy of this allocator.
Member type allocator_type is the internal allocator type used by the container, defined in basic_string as an alias of its third template parameter (Alloc).
If allocator_type is an instantiation of the default allocator (which has no state), this is not relevant.
str
Another basic_string object of the same type (with the same class template arguments charT, traits and Alloc), whose value is either copied or acquired.
pos
Position of the first character in str that is copied to the object as a substring.
If this is greater than str's length, it throws out_of_range.
Note: The first character in str is denoted by a value of 0 (not 1).
len
Length of the substring to be copied (if the string is shorter, as many characters as possible are copied).
A value of basic_string::npos indicates all characters until the end of str.
s
Pointer to an array of characters (such as a c-string).
n
Number of characters to copy.
c
Character to fill the string with. Each of the n characters in the string will be initialized to a copy of this value.
first, last
Input iterators to the initial and final positions in a range. The range used is [first,last), which includes all the characters between first and last, including the character pointed by first but not the character pointed by last.
The function template argument InputIterator shall be an input iterator type that points to elements of a type convertible to charT.
If InputIterator is an integral type, the arguments are casted to the proper types so that signature (5) is used instead.
il
An initializer_list object.
These objects are automatically constructed from initializer list declarators.

charT is basic_string's character type (i.e., its first template parameter).
Member type size_type is an unsigned integral type.

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
// string constructor
#include <iostream>
#include <string>

int main ()
{
  std::string s0 ("Initial string");

  // constructors used in the same order as described above:
  std::string s1;
  std::string s2 (s0);
  std::string s3 (s0, 8, 3);
  std::string s4 ("A character sequence", 6);
  std::string s5 ("Another character sequence");
  std::string s6 (10, 'x');
  std::string s7a (10, 42);
  std::string s7b (s0.begin(), s0.begin()+7);

  std::cout << "s1: " << s1 << "\ns2: " << s2 << "\ns3: " << s3;
  std::cout << "\ns4: " << s4 << "\ns5: " << s5 << "\ns6: " << s6;
  std::cout << "\ns7a: " << s7a << "\ns7b: " << s7b << '\n';
  return 0;
}


Output:
s1: 
s2: Initial string
s3: str
s4: A char
s5: Another character sequence
s6: xxxxxxxxxx
s7a: **********
s7b: Initial

Complexity

Unspecified.
Unspecified, but generally linear in the resulting string length (and constant for move constructors).

Iterator validity

The move constructors (9) may invalidate iterators, pointers and references related to str.

Data races

The move constructors (9) modify str.

Exception safety

The move constructor with no allocator argument (9, first) never throws exceptions (no-throw guarantee).
In all other cases, there are no effects in case an exception is thrown (strong guarantee).

If s is a null pointer, if n == npos, or if the range specified by [first,last) is not valid, it causes undefined behavior.

If pos is greater then str's length, an out_of_range exception is thrown.
If n is greater than the array pointed by s, it causes undefined behavior.
If the resulting string length would exceed the max_size, a length_error exception is thrown.
If the type uses the default allocator, a bad_alloc exception is thrown if the function fails when attempting to allocate storage.

See also