Namespaces
Variants
Views
Actions

Difference between revisions of "Template:cpp/container/assign"

From cppreference.com
m (Text replace - "mark c++11 feature" to "mark since c++11")
(Added LWG issue #2209 DR.)
 
(32 intermediate revisions by 14 users not shown)
Line 1: Line 1:
−
{{cpp/container/{{{1|}}}/title | assign}}
+
{{#vardefine:cont|{{{1|inplace_vector}}}}}<!--
−
{{cpp/container/{{{1|}}}/sidebar}}
+
-->{{cpp/container/{{#var:cont}}/title|assign}}
−
{{ddcl list begin}}
+
{{cpp/container/{{#var:cont}}/navbar}}
−
{{ddcl list item | num=1 | notes={{cpp/container/mark since c++11 | {{{1|}}}}} | 1=
+
{{dcl begin}}
 +
{{#switch:{{#var:cont}}
 +
|vector=
 +
{{dcla|num=1|constexpr=c++20|
 
void assign( size_type count, const T& value );
 
void assign( size_type count, const T& value );
 
}}
 
}}
−
{{ddcl list item | num=2 | notes={{cpp/container/mark since c++11 | {{{1|}}}}} | 1=
+
{{dcla|num=2|constexpr=c++20|
−
template< class InputIterator >
+
template< class InputIt >
−
void assign( InputIterator first, InputIterator last );
+
void assign( InputIt first, InputIt last );
 
}}
 
}}
−
{{ddcl list end}}
+
{{dcla|num=3|since=c++11|constexpr=c++20|
 +
void assign( std::initializer_list<T> ilist );
 +
}}
 +
|inplace_vector=
 +
{{dcl|num=1|since={{cpp/std|{{#var:cont}}}}|
 +
constexpr void assign( size_type count, const T& value );
 +
}}
 +
{{dcl|num=2|since={{cpp/std|{{#var:cont}}}}|
 +
template< class InputIt >
 +
constexpr void assign( InputIt first, InputIt last );
 +
}}
 +
{{dcl|num=3|since={{cpp/std|{{#var:cont}}}}|
 +
constexpr void assign( std::initializer_list<T> ilist );
 +
}}
 +
|
 +
{{dcl|num=1|since={{cpp/std|{{#var:cont}}}}|
 +
void assign( size_type count, const T& value );
 +
}}
 +
{{dcl|num=2|since={{cpp/std|{{#var:cont}}}}|
 +
template< class InputIt >
 +
void assign( InputIt first, InputIt last );
 +
}}
 +
{{dcl|num=3|since=c++11|
 +
void assign( std::initializer_list<T> ilist );
 +
}}
 +
}}
 +
{{dcl end}}
  
 
Replaces the contents of the container.
 
Replaces the contents of the container.
  
−
1) replaces the contents with {{tt|count}} copies of value {{tt|value}}
+
@1@ Replaces the contents with {{c|count}} copies of value {{c|value}}.
  
−
2) replaces the contents with copies of those in the range {{tt|[first, last)}}
+
@2@ Replaces the contents with copies of those in the range {{range|first|last}}.
 +
@@ If either argument is an iterator into {{c|*this}}, the behavior is undefined.
 +
{{#switch:{{#var:cont}}
 +
|inplace_vector=
 +
{{cpp/enable if|{{tt|InputIt}} satisfies {{named req|InputIterator}}}}.
 +
|
 +
{{rrev multi|until1=c++11
 +
|rev1=This overload has the same effect as overload {{v|1}} if {{tt|InputIt}} is an integral type.
 +
|rev2={{cpp/enable if|{{tt|InputIt}} satisfies {{named req|InputIterator}}}}.
 +
}}
 +
}}
 +
@3@ Replaces the contents with the elements from {{c|ilist}}.
 +
 
 +
{{cpp/container/note iterator invalidation|{{#var:cont}}|assign}}
  
 
===Parameters===
 
===Parameters===
−
{{param list begin}}
+
{{par begin}}
−
{{param list item | count | the new size of the container}}
+
{{par|count|the new size of the container}}
−
{{param list item | value | the value to initialize elements of the container with}}
+
{{par|value|the value to initialize elements of the container with}}
−
{{param list item | first, last | the range to copy the elements from}}
+
{{par|first, last|the range to copy the elements from}}
−
{{param list end}}  
+
{{par|ilist|{{lc|std::initializer_list}} to copy the values from}}
 +
{{par end}}
  
 
===Complexity===
 
===Complexity===
 +
@1@ Linear in {{c|count}}.
  
−
1) linear in {{tt|count}}
+
@2@ Linear in distance between {{c|first}} and {{c|last}}.
  
−
2) linear in distance between {{tt|first}} and {{tt|last}}
+
@3@ Linear in {{c|ilist.size()}}.
 +
<!---->
 +
{{#switch:{{#var:cont}}
 +
|inplace_vector=
 +
===Exceptions===
 +
@1@ {{lc|std::bad_alloc}}, if {{c|1=count > capacity()}}.
  
 +
@2@ {{lc|std::bad_alloc}}, if {{c|1=std::ranges::distance(first, last) > capacity()}}.
 +
 +
@3@ {{lc|std::bad_alloc}}, if {{c|1=ilist.size() > capacity()}}.
 +
 +
@1-3@ Any exception thrown by initialization of inserted elements.
 +
}}
 +
<!---->
 
===Example===
 
===Example===
−
{{example cpp
+
{{#switch:{{#var:cont}}
−
| code=
+
|inplace_vector=
−
| output=
+
{{example
 +
|The following code uses {{tt|assign}} to add several characters to a {{c/core|std::{{#var:cont}}<char, 5>}}:
 +
|code=
 +
#include <inplace_vector>
 +
#include <iterator>
 +
#include <new>
 +
#include <print>
 +
 
 +
int main()
 +
{
 +
    std::inplace_vector<char, 5> chars;
 +
   
 +
    chars.assign(4, 'a'); // overload (1)
 +
    std::println("{}", chars);
 +
   
 +
    const char extra[3]{'a', 'b', 'c'};
 +
    chars.assign(std::cbegin(extra), std::cend(extra)); // overload (2)
 +
    std::println("{}", chars);
 +
   
 +
    chars.assign({'C', '+', '+', '2', '6'}); // overload (3)
 +
    std::println("{}", chars);
 +
   
 +
    try
 +
    {
 +
        chars.assign(8, 'x'); // throws: count > chars.capacity()
 +
    }
 +
    catch(const std::bad_alloc&) { std::println("std::bad_alloc #1"); }
 +
   
 +
    try
 +
    {
 +
        const char bad[8]{'?'}; // ranges::distance(bad) > chars.capacity()
 +
        chars.assign(std::cbegin(bad), std::cend(bad)); // throws
 +
    }
 +
    catch(const std::bad_alloc&) { std::println("std::bad_alloc #2"); }
 +
   
 +
    try
 +
    {
 +
        const auto l = {'1', '2', '3', '4', '5', '6'};
 +
        chars.assign(l); // throws: l.size() > chars.capacity()
 +
    }
 +
    catch(const std::bad_alloc&) { std::println("std::bad_alloc #3"); }
 +
}
 +
|output=
 +
['a', 'a', 'a', 'a']
 +
['a', 'b', 'c']
 +
['C', '+', '+', '2', '6']
 +
std::bad_alloc #1
 +
std::bad_alloc #2
 +
std::bad_alloc #3
 
}}
 
}}
 +
|
 +
{{example
 +
|The following code uses {{tt|assign}} to add several characters to a {{c/core|std::{{#var:cont}}<char>}}:
 +
|code=
 +
#include <{{#var:cont}}>
 +
#include <iostream>
 +
#include <string>
  
 +
int main()
 +
{
 +
    std::{{#var:cont}}<char> characters;
 +
   
 +
    auto print_{{#var:cont}} = [&]()
 +
    {
 +
        for (char c : characters)
 +
            std::cout << c << ' ';
 +
        std::cout << '\n';
 +
    };
 +
   
 +
    characters.assign(5, 'a');
 +
    print_{{#var:cont}}();
 +
   
 +
    const std::string extra(6, 'b');
 +
    characters.assign(extra.begin(), extra.end());
 +
    print_{{#var:cont}}();
 +
   
 +
    characters.assign({'C', '+', '+', '1', '1'});
 +
    print_{{#var:cont}}();
 +
}
 +
|output=
 +
a a a a a
 +
b b b b b b
 +
C + + 1 1
 +
}}
 +
}}
 +
<!-- Keep these two comments to avoid extra new lines for inplace_vector -->
 +
{{#ifeq:{{#var:cont}}|inplace_vector||
 +
===Defect reports===
 +
{{dr list begin}}
 +
{{dr list item|wg=lwg|dr={{#ifeq:{{#var:cont}}|list|320|2209}}|std={{#ifeq:{{#var:cont}}
 +
|forward_list|C++11|C++98}}|before=the replacement operation was required to be implemented as<br>erasing all existing elements followed by inserting the given elements|after=removed the<br>requirement}}
 +
{{dr list end}}
 +
}}
 +
<!---->
 
===See also===
 
===See also===
−
 
+
{{dsc begin}}
−
{{dcl list begin}}
+
{{dsc inc|cpp/container/dsc assign_range|{{#var:cont}}}}
−
{{dcl list template | cpp/container/dcl list constructor |{{{1|}}}}}
+
{{dsc inc|cpp/container/dsc operator{{=}}|{{#var:cont}}}}
−
{{dcl list end}}
+
{{dsc end}}

Latest revision as of 22:28, 14 November 2024

 
C++
 
Containers library
 
std::inplace_vector
Member types
Member functions
Non-member functions
 
constexpr void assign( size_type count, const T& value );
 (1) (since C++26)
template< class InputIt >
constexpr void assign( InputIt first, InputIt last );
 (2) (since C++26)
constexpr void assign( std::initializer_list<T> ilist );
 (3) (since C++26)

Replaces the contents of the container.

1) Replaces the contents with count copies of value value.
2) Replaces the contents with copies of those in the range [first, last).
If either argument is an iterator into *this, the behavior is undefined. This overload participates in overload resolution only if InputIt satisfies LegacyInputIterator.
3) Replaces the contents with the elements from ilist.
This section is incomplete

Contents

[edit] Parameters

count - the new size of the container
value - the value to initialize elements of the container with
first, last - the range to copy the elements from
ilist - std::initializer_list to copy the values from

[edit] Complexity

1) Linear in count.
2) Linear in distance between first and last.
3) Linear in ilist.size().

Exceptions

1) std::bad_alloc, if count > capacity().
2) std::bad_alloc, if std::ranges::distance(first, last) > capacity().
3) std::bad_alloc, if ilist.size() > capacity().
1-3) Any exception thrown by initialization of inserted elements.

[edit] Example

The following code uses assign to add several characters to a std::inplace_vector<char, 5>:

Run this code
#include <inplace_vector>
#include <iterator>
#include <new>
#include <print>
 
int main()
{
    std::inplace_vector<char, 5> chars;
 
    chars.assign(4, 'a'); // overload (1)
    std::println("{}", chars);
 
    const char extra[3]{'a', 'b', 'c'};
    chars.assign(std::cbegin(extra), std::cend(extra)); // overload (2)
    std::println("{}", chars);
 
    chars.assign({'C', '+', '+', '2', '6'}); // overload (3)
    std::println("{}", chars);
 
    try
    {
        chars.assign(8, 'x'); // throws: count > chars.capacity()
    }
    catch(const std::bad_alloc&) { std::println("std::bad_alloc #1"); }
 
    try
    {
        const char bad[8]{'?'}; // ranges::distance(bad) > chars.capacity()
        chars.assign(std::cbegin(bad), std::cend(bad)); // throws
    }
    catch(const std::bad_alloc&) { std::println("std::bad_alloc #2"); }
 
    try
    {
        const auto l = {'1', '2', '3', '4', '5', '6'};
        chars.assign(l); // throws: l.size() > chars.capacity()
    }
    catch(const std::bad_alloc&) { std::println("std::bad_alloc #3"); }
}

Output: 

['a', 'a', 'a', 'a']
['a', 'b', 'c']
['C', '+', '+', '2', '6']
std::bad_alloc #1
std::bad_alloc #2
std::bad_alloc #3

[edit] See also

 assigns a range of values to the container
(public member function of std::inplace_vector<T,N>) [edit]
assigns values to the container
(public member function of std::inplace_vector<T,N>) [edit]
Retrieved from "https://en.cppreference.com/mwiki/index.php?title=Template:cpp/container/assign&oldid=177669"