diff --git a/content/cpp/concepts/unordered-set/terms/emplace-hint/emplace-hint.md b/content/cpp/concepts/unordered-set/terms/emplace-hint/emplace-hint.md new file mode 100644 index 00000000000..d585f2ed17e --- /dev/null +++ b/content/cpp/concepts/unordered-set/terms/emplace-hint/emplace-hint.md @@ -0,0 +1,125 @@ +--- +Title: 'emplace_hint()' +Description: 'Inserts a new element into an `unordered_set` using a position hint, constructing the element in place.' +Subjects: + - 'Code Foundations' + - 'Computer Science' +Tags: + - 'Containers' + - 'Methods' + - 'Sets' + - 'STL' +CatalogContent: + - 'learn-c-plus-plus' + - 'paths/computer-science' +--- + +The **`emplace_hint()`** method inserts a new element into an `unordered_set` by constructing it directly in the container, using a provided iterator as a hint. In `unordered_set`, the hint does not affect performance or insertion position, but it is included for interface consistency with ordered containers like `set`. + +## Syntax + +```pseudo +unordered_set.emplace_hint(position, value) +``` + +`unordered_set` is the container into which the element is inserted. + +**Parameters:** + +- `position`: An iterator hint indicating where the insertion might occur (ignored by `unordered_set`). +- `value`: The value to be inserted, constructed in place. + +**Return value:** + +Returns an iterator pointing to the inserted element, or to the existing element if the value already exists in the set. + +## Example 1: Basic insertion using `emplace_hint()` + +This example shows inserting an element into an `unordered_set` using a hint iterator: + +```cpp +#include +#include + +int main() { + std::unordered_set numbers = {1, 2, 3}; + + auto hint = numbers.begin(); + auto it = numbers.emplace_hint(hint, 4); + + std::cout << "Inserted element: " << *it << std::endl; + return 0; +} +``` + +The output of this code is: + +```shell +Inserted element: 4 +``` + +## Example 2: Attempting to insert a duplicate element + +This example demonstrates that `emplace_hint()` does not insert duplicate values: + +```cpp +#include +#include + +int main() { + std::unordered_set values = {10, 20, 30}; + + auto it = values.emplace_hint(values.begin(), 20); + + std::cout << "Element at iterator: " << *it << std::endl; + std::cout << "Set size: " << values.size() << std::endl; + + return 0; +} +``` + +The output of this code is: + +```shell +Element at iterator: 20 +Set size: 3 +``` + +## Codebyte Example: Using `emplace_hint()` with a custom type + +This example uses `emplace_hint()` to construct a custom object directly inside the set: + +```codebyte/cpp +#include +#include +#include + +struct User { + std::string name; + + bool operator==(const User& other) const { + return name == other.name; + } +}; + +struct UserHash { + size_t operator()(const User& u) const { + return std::hash()(u.name); + } +}; + +int main() { + std::unordered_set users; + + users.emplace_hint(users.begin(), User{"Alice"}); + users.emplace_hint(users.begin(), User{"Bob"}); + + for (const auto& user : users) { + std::cout << user.name << std::endl; + } + + return 0; +} +``` + +> **Note:** Unlike `set::emplace_hint()`, the hint provided to `unordered_set::emplace_hint()` does not influence insertion efficiency or placement, since elements are stored based on hash values rather than order.