View source for cpp/container/inplace vector/try append range

{{cpp/container/inplace_vector/title|try_append_range}}
{{cpp/container/inplace_vector/navbar}}
{{ddcl|since=c++26|
template< container-compatible-range<T> R >
constexpr std::ranges::borrowed_iterator_t<R> try_append_range( R&& rg );
}}

Appends copies of initial elements in {{c|rg}} before {{rlpf|end}}, until all elements are inserted or the internal storage is exhausted (i.e. {{c|1=size() == capacity()}} is {{c|true}}).

All iterators and references remain valid. The {{rlpf|end}} iterator is invalidated.

Each iterator in {{c|rg}} is dereferenced at most once.

===Parameters===
{{par begin}}
{{par|rg|a {{ls|cpp/ranges/to#container compatible range}}, that is, an {{lconcept|input_range}} whose elements are convertible to {{tt|T}}}}
{{par hreq}}
{{par req|{{cpp/precondition|
{{tt|T}} must be {{named req|EmplaceConstructible}} into {{tt|inplace_vector}} from {{c|*ranges::begin(rg)}}.}}}}
{{par end}}

===Return value===
An iterator pointing to the first element of {{c|rg}} that was not inserted into {{c|*this}}, or {{c|ranges::end(rg)}} if no such element exists.

===Complexity===
Linear in the number of elements inserted.

===Exceptions===
Any exception thrown by initialization of inserted element.

{{tt|inplace_vector}} provides the ''basic exception safety guarantee'', i.e., all elements of the container before the call are preserved, and all already inserted elements (before the exception, if any) are also preserved.

===Notes===
{{todo|Explain the purpose of this API.}}

===Example===
{{example
|code=
#include <cassert>
#include <initializer_list>
#include <inplace_vector>

int main()
{
    using I = std::inplace_vector<int, 8>;
    auto nums = I{1, 2, 3};
    const auto rg = {-1, -2, -3};

    auto it = nums.try_append_range(rg);
    assert(nums.size() == 6);
    assert((nums == I{1, 2, 3, -1, -2, -3}));
    assert(it == rg.end());

    it = nums.try_append_range(rg);
    assert(nums.size() == 8);
    assert((nums == I{1, 2, 3, -1, -2, -3, -1, -2}));
    assert(it == rg.begin() + 2);
}
}}

===See also===
{{dsc begin}}
{{dsc inc|cpp/container/dsc append_range|inplace_vector}}
{{dsc inc|cpp/container/dsc push_back|inplace_vector}}
{{dsc inc|cpp/container/dsc try_push_back|inplace_vector}}
{{dsc inc|cpp/container/dsc unchecked_push_back|inplace_vector}}
{{dsc inc|cpp/container/dsc emplace_back|inplace_vector}}
{{dsc inc|cpp/container/dsc try_emplace_back|inplace_vector}}
{{dsc inc|cpp/container/dsc unchecked_emplace_back|inplace_vector}}
{{dsc inc|cpp/container/dsc pop_back|inplace_vector}}
{{dsc inc|cpp/iterator/dsc back_inserter}}
{{dsc end}}

{{langlinks|de|es|fr|it|ja|pt|ru|zh}}