public member function
<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.