The insert function is used to insert an element into the set, and it returns a pair of an iterator to the inserted element (or the element that prevented the insertion) and a boolean value indicating whether the insertion took place. (It is exception for std::set, generally insert() returns iterator).

std::pair<std::set<int>::iterator, bool> result = mySet.insert(6);
if (result.second) {
    std::cout << "Insertion successful. Inserted element: " << *(result.first) << std::endl;
} else {
    std::cout << "Element already exists: " << *(result.first) << std::endl;
}

On the other hand, multiset::insert() function returns an iterator pointing to the inserted element in the multiset container.

Return Values of insert() across Different Containers:

-by Bard

1. Vector:

• Overloads:
  • iterator insert(iterator pos, const value_type& value):
    • Returns an iterator pointing to the newly inserted element.
    • If insertion fails (e.g., due to memory allocation issues), throws an out_of_range exception.
  • iterator insert(iterator pos, initializer_list<value_type> il):
    • Returns an iterator pointing past the last inserted element.
    • Follows the same insertion rules as the single-element overload.
  • iterator insert(iterator pos, size_type n, const value_type& value):
    • Returns an iterator pointing past the last inserted element.
    • Inserts n copies of value at pos.
    • Throws length_error if n exceeds the container's maximum size.
  • template<class InputIt> iterator insert(iterator pos, InputIt first, InputIt last):
    • Returns an iterator pointing past the last inserted element.
    • Inserts elements in the range [first, last) at pos.
    • Uses the container's move assignment or copy assignment as appropriate.

2. Set (Unique Elements):

• Overloads:
  • iterator insert(const value_type& value):
    • Returns a pair: (iterator, bool).
      • iterator points to the inserted element if successful, or to an existing equivalent element.
      • bool is true if insertion was successful (new element added), false otherwise.
    • If insertion fails due to memory allocation issues or violation of uniqueness, throws an out_of_range exception.
  • iterator insert(initializer_list<value_type> il):
    • Returns an iterator pointing past the last inserted element.
    • Inserts elements in the range il, considering their unique properties.
  • iterator insert(iterator hint, const value_type& value):
    • Similar to the single-element overload, with a hint suggesting a potential insertion position.
    • May improve performance in certain cases.

3. Multiset (Allowing Duplicates):

• Overloads:
  • iterator insert(const value_type& value):
    • Returns an iterator pointing to the inserted element.
    • If insertion fails due to memory allocation issues, throws an out_of_range exception.
  • iterator insert(initializer_list<value_type> il):
    • Returns an iterator pointing past the last inserted element.
    • Inserts elements in the range il.
  • iterator insert(iterator pos, const value_type& value):
    • Returns an iterator pointing to the newly inserted element.
    • Similar to the single-element overload, but inserts at pos.
  • template<class InputIt> iterator insert(iterator pos, InputIt first, InputIt last):
    • Returns an iterator pointing past the last inserted element.
    • Inserts elements in the range [first, last) at pos.

4. List (Doubly Linked List):

• Overloads:
  • iterator insert(iterator pos, const value_type& value):
    • Returns an iterator pointing to the newly inserted element.
    • Inserts value before pos.
    • If insertion fails (e.g., due to memory allocation issues), throws an out_of_range exception.
  • iterator insert(iterator pos, initializer_list<value_type> il):
    • Returns an iterator pointing past the last inserted element.
    • Inserts elements in the range il before pos.

5. Map (Unique Keys):

• Overloads:
  • pair<iterator, bool> insert(const key_type& key, const mapped_type& value):
    • Returns a pair: (iterator, bool).
      • iterator points to the inserted element if successful, or to an existing equivalent element.
      • bool is true if insertion was successful (new key-value pair added), false otherwise.
    • If insertion fails due to memory allocation issues or violation of uniqueness (duplicate key), throws an out_of_range exception.
  • iterator insert(initializer_list<pair<key_type, mapped_type>> il):
    • Returns an iterator pointing past the last inserted element.
    • Inserts key-value pairs from il, considering their unique keys.
  • iterator insert(iterator hint, const key_type& key, const mapped_type& value):
    • Similar to the single-element overload, with a hint suggesting a potential insertion position.
    • May improve performance in certain cases.

6. Multimap (Duplicates Keys Allowed):

• Overloads:
  • iterator insert(const key_type& key, const mapped_type& value):
    • Returns an iterator pointing to the newly inserted element.
    • If insertion fails due to memory allocation issues, throws an out_of_range exception.
  • iterator insert(initializer_list<pair<key_type, mapped_type>> il):
    • Returns an iterator pointing past the last inserted element.
    • Inserts key-value pairs from il.
  • iterator insert(iterator pos, const key_type& key, const mapped_type& value):
    • Returns an iterator pointing to the newly inserted element.
    • Similar to the single-element overload, but inserts at pos (which may already have the same key).

Inserting Multiple Elements with insert()