Skip to content

Add unordered_multiset wrapper - #51

Open
Lynndabel wants to merge 3 commits into
rustfoundation:mainfrom
Lynndabel:unordered_multiset
Open

Lynndabel wants to merge 3 commits into
rustfoundation:mainfrom
Lynndabel:unordered_multiset

Conversation

@Lynndabel

@Lynndabel Lynndabel commented Oct 14, 2026 •

Copy link
Copy Markdown

Added a wrapper for std::unordered_multiset with 5 overloads (constructors and insert).

  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
    • Create a new file named after your type in overloading-macros/cpp-overload-test/examples
    • 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.

Focus on Interesting Overloads

Only wrap functions that have overloads. (It is ok to wrap non-overloaded functions just for testing.)

Ignore these overloads:

  • overloaded operators: they are already possible in Rust
  • overloads with an allocator argument, or that only differ by noexcept: not an interesting difference
  • assignment functions, assignment operators, and swap: no equivalent in Rust (which uses memcpy for assignment/swaps)

Only code one example of overloads that:

  • only differ by const/non-const, &/&& (or &/&mut)
  • are iterator methods that only differ by position (before_begin/begin,end)

You can look at stdcpp/forward_list.rs (working overloads) and stdcpp-forward-list.rs (failing overloads) for example code.

Closes #41

@Lynndabel Lynndabel changed the title Unordered multiset Add unordered_multiset wrapper Oct 14, 2026

@teor2345 teor2345 left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Today I updated the PR template to make it clear that all overloads need to be covered, so I updated this PR's description to match it. I also fixed the GitHub checklist formatting.

For this class constructor, there are many overloads, so we can just wrap the ones that are more likely to conflict.

No need to add any more overloaded methods, the constructor and the insert method have enough overloads.

StdUnorderedMultiset::from_slice(items)
}

pub fn new(a: T, b: T) -> StdUnorderedMultiset {

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

To check that an overload set works in Rust, we need to wrap all of the C++ constructor overloads.

There are 14 constructor overloads in C++, excluding overloads that only differ by an allocator argument:
https://en.cppreference.com/cpp/container/unordered_multiset/unordered_multiset

That's a lot of overloads, so you don't have to implement them all. Instead, pick overloads that are very different from each other. For example, you could add one overload starting with these arguments:

  • bucket_count
  • unordered_multiset
  • from_range_t

It would also be interesting to use C++ default arguments to call an overload with just one argument of type:

  • hash
  • key_equal

This would be enough to cover the constructor overload set reasonably well.

Please document the lack of default argument values in Rust as a limitation.

//!
//! - Type annotations are currently required for some overloads where inference should work.
//! - The `as_slice()` call is required to match the slice overload, as arrays don't automatically coerce.
//! - Initializer list overloads require separate functions for each argument count, which is not ergonomic.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please split up this documentation, and move it to the specific types or methods with these problems. That way, when we fix a problem, we are more likely to notice the documentation and update it.

overload! {
impl StdUnorderedMultiset {
/// Insert a single value into the set.
pub fn insert(&mut self, value: T) {

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There's a lot of insert overloads as well, feel free to update this PR in stages, and ask for a review after every stage.

@Lynndabel

Copy link
Copy Markdown
Author

Today I updated the PR template to make it clear that all overloads need to be covered, so I updated this PR's description to match it. I also fixed the GitHub checklist formatting.

For this class constructor, there are many overloads, so we can just wrap the ones that are more likely to conflict.

No need to add any more overloaded methods, the constructor and the insert method have enough overloads.

Ok, I will sync my forked repo and fix all necessary update you mentioned. Thank you for the feedback

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

unordered_multiset

2 participants