View source for Template:cpp/container/assign range

{{#vardefine:cont|{{{1|inplace_vector}}}}}<!--
-->{{cpp/container/{{#var:cont}}/title|assign_range}}
{{cpp/container/{{#var:cont}}/navbar}}
{{ddcl|since={{#switch:{{#var:cont}}|inplace_vector=c++26|c++23}}|
template< container-compatible-range<T> R >
{{#switch:{{#var:cont}}|inplace_vector|vector=constexpr void|void}} assign_range( R&& rg );
}}

Replaces elements in the container with a copy of each element in {{c|rg}}.

{{cpp/container/note iterator invalidation|{{#var:cont}}|assign_range}}

Each iterator in the range {{c|rg}} is dereferenced exactly once.

The behavior is undefined if {{c|rg}} overlaps with the container.

===Parameters===
{{par begin}}
{{par|rg|an {{lconcept|input_range}} with reference type convertible to the element type of the container}}
{{par hreq}}
{{par req|{{c|std::assignable_from<T&, ranges::range_reference_t<R>>}} must be modeled. Otherwise, the program is ill-formed.}}
{{par req|{{tt|T}} must be {{named req|EmplaceConstructible}} into the container from {{c|*ranges::begin(rg)}}{{#switch:{{#var:cont}}|vector=. If {{tt|R}} models neither {{lconcept|sized_range}} nor {{lconcept|forward_range}}, {{tt|T}} must be also {{named req|MoveInsertable}} into the container}}. Otherwise, the behavior is undefined.}}
{{par end}}

===Return value===
(none)
<!---->
{{#switch:{{#var:cont}}|inplace_vector=
===Exceptions===
* {{lc|bad_alloc}}, if {{c|1=std::ranges::distance(rg) > capacity()}}.
* Any exception thrown by initialization of inserted element.
}}
<!---->
{{#switch:{{#var:cont}}|inplace_vector=|
===Notes===
{{feature test macro|__cpp_lib_containers_ranges|[[cpp/ranges/to#container compatible range|Ranges-aware]] construction and insertion|value=202202L|std=C++23}}
}}
<!---->
===Example===
{{#switch:{{#var:cont}}
|inplace_vector=
{{example
|code=
#include <algorithm>
#include <cassert>
#include <initializer_list>
#include <inplace_vector>
#include <iostream>
#include <new>

int main()
{
    const auto source = {1, 2, 3};
    std::inplace_vector<int, 4> destination{4, 5};
    destination.assign_range(source);
    assert(std::ranges::equal(destination, source));

    try
    {
        const auto bad = {-1, -2, -3, -4, -5};
        destination.assign_range(bad); // throws: bad.size() > destination.capacity()
    }
    catch(const std::bad_alloc& ex)
    {
        std::cout << ex.what() << '\n';
    }
}
|p=true
|output=
std::bad_alloc
}}
|
{{example
|code=
#include <algorithm>
#include <cassert>
#include <{{#var:cont}}>
#include <{{#ifeq:{{#var:cont}}|list|vector|list}}>

int main()
{
    const auto source = std::{{#ifeq:{{#var:cont}}|list|vector|list}}{2, 7, 1};
    auto destination = std::{{#var:cont}}{3, 1, 4};
#ifdef __cpp_lib_containers_ranges
    destination.assign_range(source);
#else
    destination.assign(source.cbegin(), source.cend());
#endif
    assert(std::ranges::equal(source, destination));
}
}}
}}

===See also===
{{dsc begin}}
{{#switch:{{#var:cont}}|forward_list=
{{cpp/container/dsc insert_range_after|{{#var:cont}}}}
|{{cpp/container/dsc insert_range|{{#var:cont}}}}
}}
{{#switch:{{#var:cont}}|deque|forward_list|list=
{{cpp/container/dsc prepend_range|{{#var:cont}}}}
}}
{{#switch:{{#var:cont}}|deque|list|inplace_vector|vector=
{{cpp/container/dsc append_range|{{#var:cont}}}}
}}
{{cpp/container/dsc assign|{{#var:cont}}}}
{{cpp/container/dsc operator{{=}}|{{#var:cont}}}}
{{dsc end}}