std::list::assign(3)

💖 std::list::assign 💖

okay bestie, welcome to the std::list::assign(3) page from the C++ Standard Libary — manual name folded in right here at the top so we can get straight into the group chat 💅✨

💖 NAME 💖

std::list::assign — std::list::assign. That's it, that's the name, no cap. It's literally the assign member of std::list 🫶

✨ Synopsis ✨

void assign( size_type count, const T& value ); (1)
template< class InputIt >                       (2)
void assign( InputIt first, InputIt last );
void assign( std::initializer_list<T> ilist );  (3) (since C++11)

Replaces the contents of the container. Periodt. The way that this just wholesale swaps out what's inside is giving main character energy 🎀

• (1) — replaces the contents with count copies of the value value.
• (2) — replaces the contents with copies of those in the range [first, last). ⚠️ The behavior is undefined if either argument is an iterator into *this.
  • until C++11: this overload has the same effect as overload (1) if InputIt is an integral type.
  • since C++11: this overload participates in overload resolution only if InputIt satisfies LegacyInputIterator.
• (3) — replaces the contents with the elements from the initializer list ilist.

⚠️ All iterators, pointers and references to the elements of the container are invalidated. Like, do not hold onto them, bestie 😭

🌸 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 — initializer list to copy the values from.

🦋 Complexity 🦋

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

🎀 Example 🎀

The following code uses assign to add several characters to a std::list<char>:

// Run this code

#include <list>
#include <iostream>
#include <string>

int main()
{
    std::list<char> characters;

    auto print_list = [&]()
    {
        for (char c : characters)
            std::cout << c << ' ';
        std::cout << '\n';
    };

    characters.assign(5, 'a');
    print_list();

    const std::string extra(6, 'b');
    characters.assign(extra.begin(), extra.end());
    print_list();

    characters.assign({'C', '+', '+', '1', '1'});
    print_list();
}

Output:

a a a a a
b b b b b b
C + + 1 1

🩹 Defect reports 🩹

The following behavior-changing defect reports were applied retroactively to previously published C++ standards:

• LWG 320, applied to C++98: behavior as published was that the replacement operation was defined as erasing all existing elements followed by inserting the given elements; correct behavior is removed the definition.

👑 See also 👑

• constructor — constructs the list (public member function).

okay that's the whole page, bestie 🫶 — source: http://cppreference.com, version/date: 2024.06.10, and the manual name is std::list::assign(3). slay 💖