Skip to content

Document the behaviour of BTreeMap::extend #158069

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Timmmm wants to merge 1 commit into
base: main
Choose a base branch
from
+12 −0
Open

Document the behaviour of BTreeMap::extend #158069

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions library/alloc/src/collections/btree/map.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2556,6 +2556,9 @@ impl<K: Ord, V> FromIterator<(K, V)> for BTreeMap<K, V> {

#[stable(feature = "rust1", since = "1.0.0")]
impl<K: Ord, V, A: Allocator + Clone> Extend<(K, V)> for BTreeMap<K, V, A> {
/// Add all elements from `iter` to this map by calling [`BTreeMap::insert`]

@camsteffen camsteffen Jun 28, 2026 •
edited by rustbot
Loading

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

I would avoid promising that insert is called since that is an implementation detail that could change. It could say:

Inserts each entry into the map. Existing entries with the same key are replaced.

View changes since the review

@Timmmm Timmmm Jun 29, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

It can't change in a way that makes it not semantically equivalent to calling insert. I could say Add all elements from iter to this map, as if insert was called for each element or something... but that seems a bit awkward and pedantic.

I think duplicating the insert documentation is not as good because you lose information. For example with your version you don't get this:

The key is not updated, though; this matters for types that can be == without being identical. See the module-level documentation for more.

/// in a loop. Its return value is ignored. This means duplicate elements
/// will be overwritten.
#[inline]
fn extend<T: IntoIterator<Item = (K, V)>>(&mut self, iter: T) {
iter.into_iter().for_each(move |(k, v)| {
Expand All @@ -2573,6 +2576,9 @@ impl<K: Ord, V, A: Allocator + Clone> Extend<(K, V)> for BTreeMap<K, V, A> {
impl<'a, K: Ord + Copy, V: Copy, A: Allocator + Clone> Extend<(&'a K, &'a V)>
for BTreeMap<K, V, A>
{
/// Add all elements from `iter` to this map by calling [`BTreeMap::insert`]
Comment thread
Timmmm marked this conversation as resolved.
/// in a loop. Its return value is ignored. This means duplicate elements
/// will be overwritten. Keys and values are copied.
fn extend<I: IntoIterator<Item = (&'a K, &'a V)>>(&mut self, iter: I) {
self.extend(iter.into_iter().map(|(&key, &value)| (key, value)));
}
Expand Down
6 changes: 6 additions & 0 deletions library/std/src/collections/hash/map.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3027,6 +3027,9 @@ where
S: BuildHasher,
A: Allocator,
{
/// Add all elements from `iter` to this map by calling [`HashMap::insert`]
/// in a loop. Its return value is ignored. This means duplicate elements
/// will be overwritten.
#[inline]
fn extend<T: IntoIterator<Item = (K, V)>>(&mut self, iter: T) {
self.base.extend(iter)
Expand All @@ -3051,6 +3054,9 @@ where
S: BuildHasher,
A: Allocator,
{
/// Add all elements from `iter` to this map by calling [`HashMap::insert`]
/// in a loop. Its return value is ignored. This means duplicate elements
/// will be overwritten. Keys and values are copied.
#[inline]
fn extend<T: IntoIterator<Item = (&'a K, &'a V)>>(&mut self, iter: T) {
self.base.extend(iter)
Expand Down
Loading