[EDSONZ-WASSWA]

Description:
This PR adds Rust Wrappers for C++ std::unordered_map overloads.

Implements issue: #67

Changes

Added Files:

• cpp-overload-test/src/stdcpp/unordered_map.rs - New module with working overloads
• Modified cpp-overload-test/src/lib.rs - Registered the unordered_map module.

Implementation Details

The implementation wraps the following overloaded method names from std::unordered_map<int, int>:

Constructors:

1. Default constructor
2. Constructor with bucket count
3. Constructor from Rust slice
4. Constructor from C++ iterator range
5. Constructor from Rust iterator (with C++23 std::from_range fallback)
6. Copy constructor
7. Move constructor
8. Initializer list constructors (1 and 2 arguments)

Accessors:

1. find(key) - Both const and mutable versions (as associated functions due to macro limitations)
2. max_load_factor() - Getter and setter (as associated functions due to macro limitations)

Modifiers:

1. insert(value) - Insert single key-value pair
2. insert(hint, value) - Insert with position hint
3. insert(slice) - Insert from Rust slice
4. insert(first, last) - Insert from C++ iterator range
5. insert(a, b) - Insert from initializer list
6. erase(pos) - Erase at iterator position (both mut and const iterator)
7. erase(first, last) - Erase range
8. erase(key) - Erase by key

Limitations / Ergonomics

• Iterator does not borrow the map i.e. needed forinsert -with-hint anderase
• insert doesn't overwrite, unlike Rust'sHashMap::insert.
• new(bucket_count) keeps the C++'s default hash or equal given the fact that Rust has no default arguments.
• Initializer-list overloads stop at max two pairs.

Testing

• Comprehensive tests for each overload set verify:

• Correct constructor is called based on arguments

• Bucket count constructor actually allocates buckets

• Copy constructor preserves original

• Move constructor empties original

• Find returns correct iterator or end iterator

• Insert doesn't replace existing keys

• Insert with hint works regardless of hint position

• Erase removes correct elements## Outreachy Application Process

AI Usage:

I have used AI to first understand what the Issue needs me to do exactly. Then Used it to explain more of what is being talked about in this web Page: std::unordered_map.

I studied the forward_list.rs implementation to understand the used patterns, then wrote the unordered_map.rs file implementation from scratch based on that understanding and the explanation obtained from AI.

Tasks

1. Write Rust wrappers for that C++ type, for 3-5 different overloaded method names:
   • Create a new file named after your type in overloading-macros/cpp-overload-test/src/stdcpp/
   • Wrap constructors first, writing tests to make sure the correct constructor is called
   • Explain any potential compatibility issues in a Limitations doc section
   • Explain usability issues in an Ergonomics doc section
   • Check that you have implemented all the overloads for each method name, or documented why you can't
   • Push your changes and wait for a review
2. Add a separate example with some failing overloads
   • [ X] Create a new file named after your type in overloading-macros/cpp-overload-test/unordered_map.rs
   • Wrap accessor/modifier methods
   • Explain how they fail in an Incompatibilities doc section
   • Explain how the overload failures could be resolved in a Workarounds doc section
   • Optional: If there's a C++ feature with no equivalent in Rust, explain that in an Inexpressible Overloads doc section
   • Push your changes and wait for a review
3. Update the overload macro compatibility table Markdown doc
   • If you haven't checked some kinds of overloads, put a ？in those squares
   • Push your changes and wait for a review

Mark items in this checklist as done by clicking the box next to each item.

Needs Review @teor2345

[teor2345]

Thank you, this looks good to me!

Please move on to steps 2 and 3, no need to wait for reviews in between them.

Outreachy applications are due next Monday 9 November, please remember to put your application in before the deadline. You can include any Rust PRs you worked on during that time.

[EDSONZ-WASSWA]

@teor2345 , All has been worked upon. Am now working on my application.

[teor2345]

Thanks, just a few things to tweak here

[EDSONZ-WASSWA]

HELLO @teor2345 , help me with the review and approve the checks

[teor2345]

Looks like the documentation needs to be fixed up

[EDSONZ-WASSWA]

Thanks for the feedback, Suggestions have been worked on @teor2345

[teor2345]

Just some minor fixes needed, then we can merge

[EDSONZ-WASSWA]

hey @teor2345 , all well fixed. Thanks for the review!

[teor2345]

Thank you, this looks reasonably complete.

You are welcome to open another PR if you'd like to add anything else to these files. Adding more is optional. Please also feel free to focus on applying for projects, or feel free to take a break.

Please remember to put in an Outreachy application before by Monday 9 November!

[EDSONZ-WASSWA]

Thanks for the merge @teor2345