From 909bcf5de696e46793960906ca25c8bdf59a7715 Mon Sep 17 00:00:00 2001 From: Richard Zhang Date: Sun, 5 Apr 2015 13:37:33 +0800 Subject: [PATCH 1/4] RFC: Rename `Iterator::size_hint` to `Iterator::len_hint` --- text/0000-iterator-len-hint.md | 54 ++++++++++++++++++++++++++++++++++ 1 file changed, 54 insertions(+) create mode 100644 text/0000-iterator-len-hint.md diff --git a/text/0000-iterator-len-hint.md b/text/0000-iterator-len-hint.md new file mode 100644 index 00000000000..8900e618e38 --- /dev/null +++ b/text/0000-iterator-len-hint.md @@ -0,0 +1,54 @@ +- Feature Name: iterator_len_hint +- Start Date: 2015-04-05 +- RFC PR: (leave this empty) +- Rust Issue: (leave this empty) + +# Summary + +Rename the `size_hint` method of the `Iterator` trait to `len_hint`. + +# Motivation + +Currently, methods returning the numbers of elements in containers are conventionally named `len` in Rust, even for non-linear collections like [`BTreeMap`](http://doc.rust-lang.org/1.0.0-beta/std/collections/btree_map/struct.BTreeMap.html#method.len). But the `Iterator` trait, which represents entities each yielding a sequence of elements, has a `size_hint` method, instead of the more consistent `len_hint`. + +The standard library documentation says about [`size_hint`](http://doc.rust-lang.org/1.0.0-beta/std/iter/trait.Iterator.html#tymethod.size_hint): + +> Returns a lower and upper bound on the remaining *length* of the iterator. + +This method should be renamed. + +# Detailed design + +Rename the `size_hint` method of `std::iter::Iterator` to `len_hint` during the Rust 1.0 beta cycle. + +# Drawbacks + +This is a late breaking change (though only a minor naming correction at that). + +# Alternatives + +#### A. Add `len_hint` as a synonym for `size_hint`, and deprecate `size_hint`. + +A `len_hint` method would be added to the `std::iter::Iterator` trait, which has the following inlined default implementation: + +```rust +fn len_hint(&self) -> (usize, Option) { + self.size_hint() +} +``` + +The `size_hint` method would be marked `deprecated` now. + +In Rust 2.x, `len_hint` would become a required method and `size_hint` would be removed. + +The advantage of this alternative is that it is not a breaking change. + +However, Rust 1.0 final is yet to be released, having something deprecated now but not removed until 2.x is weird. + +#### B. Keep the status quo. + +`size_hint` is not too bad after all, though it is inconsistent, especially when even non-linear collections use methods named `len` instead of `size`. + +# Unresolved questions + +None. From e5dd2c3cff21e2a3b25af67f01b1f1db6bb484cc Mon Sep 17 00:00:00 2001 From: Richard Zhang Date: Tue, 7 Apr 2015 23:01:56 +0800 Subject: [PATCH 2/4] Add discussions about a possible new beta and the timing of the change. --- text/0000-iterator-len-hint.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/text/0000-iterator-len-hint.md b/text/0000-iterator-len-hint.md index 8900e618e38..28660cabcc0 100644 --- a/text/0000-iterator-len-hint.md +++ b/text/0000-iterator-len-hint.md @@ -21,6 +21,20 @@ This method should be renamed. Rename the `size_hint` method of `std::iter::Iterator` to `len_hint` during the Rust 1.0 beta cycle. +A new, inlined, but deprecated `size_hint` method may be added temporarily to ease the transition. That new `size_hint` would be implemented as: + +```rust +fn size_hint(&self) -> (usize, Option) { + self.len_hint() +} +``` + +Depending on the scale of impact of breaking changes planned during the beta cycle, it may or may not be desirable to release a new beta, reflecting the new breaking changes, so that more people can provide feedbacks about the changes before they get set in the stone. + +Ideally, this change should be completed just before a release (either the new beta, if it is decided to be released, or the final, if no new beta gets released). Also, the transition period should be as short as possible. + +The reason is that: If this change happens too early, library authors (that are affected by this change) would have to maintain at least two separate branches of their libraries, one for the old beta, the other for nighties, if they want the widest possible audience. On the other hand, if the change starts and finishes just before a new release, library authors could abandon the old beta immediately and focus on the new release and later nighties. + # Drawbacks This is a late breaking change (though only a minor naming correction at that). From 1bddb7c8ffda129de98b108a194a5c9ab11867cd Mon Sep 17 00:00:00 2001 From: Richard Zhang Date: Fri, 10 Apr 2015 22:14:04 +0800 Subject: [PATCH 3/4] Promote the "deprecate but retain" alternative and propose deprecating `ExactSizeIterator` too. --- text/0000-iterator-len-hint.md | 48 ++++++++++++---------------------- 1 file changed, 16 insertions(+), 32 deletions(-) diff --git a/text/0000-iterator-len-hint.md b/text/0000-iterator-len-hint.md index 28660cabcc0..ba59c8a7f3f 100644 --- a/text/0000-iterator-len-hint.md +++ b/text/0000-iterator-len-hint.md @@ -5,7 +5,7 @@ # Summary -Rename the `size_hint` method of the `Iterator` trait to `len_hint`. +Deprecate `Iterator::size_hint` for `Iterator::len_hint`, and `ExactSizeIterator` for `ExactLengthIterator`, gaining consistency with the standard collections' naming convention. # Motivation @@ -15,53 +15,37 @@ The standard library documentation says about [`size_hint`](http://doc.rust-lang > Returns a lower and upper bound on the remaining *length* of the iterator. -This method should be renamed. +Additionally, there is an [`ExactSizeIterator`](http://doc.rust-lang.org/1.0.0-beta/std/iter/trait.ExactSizeIterator.html) trait that also has an inconsistent name (but the sole method of `ExactSizeIterator` is named `len`, which is consistent). -# Detailed design - -Rename the `size_hint` method of `std::iter::Iterator` to `len_hint` during the Rust 1.0 beta cycle. +So, some names should be changed. However, Rust 1.0 beta has already been released, which means deprecation should be favoured over direct renaming. -A new, inlined, but deprecated `size_hint` method may be added temporarily to ease the transition. That new `size_hint` would be implemented as: - -```rust -fn size_hint(&self) -> (usize, Option) { - self.len_hint() -} -``` +# Detailed design -Depending on the scale of impact of breaking changes planned during the beta cycle, it may or may not be desirable to release a new beta, reflecting the new breaking changes, so that more people can provide feedbacks about the changes before they get set in the stone. +1. Add `core::iter::Iterator::len_hint`, which is an inlined method simply calling `core::iter::Iterator::size_hint`. +2. Add `core::iter::ExactLengthIterator`, which is a re-export of `core::iter::ExactSizeIterator`. +3. Deprecate `core::iter::Iterator::size_hint` and `core::iter::ExactSizeIterator`. +4. Adjust the `std` re-exports accordingly. +5. Deprecate the implementations of `size_hint`. -Ideally, this change should be completed just before a release (either the new beta, if it is decided to be released, or the final, if no new beta gets released). Also, the transition period should be as short as possible. +Later, in Rust 2.x series, remove `size_hint` and `ExactSizeIterator`. -The reason is that: If this change happens too early, library authors (that are affected by this change) would have to maintain at least two separate branches of their libraries, one for the old beta, the other for nighties, if they want the widest possible audience. On the other hand, if the change starts and finishes just before a new release, library authors could abandon the old beta immediately and focus on the new release and later nighties. +This design is fully backwards compatible with Rust 1.0.0-beta. # Drawbacks -This is a late breaking change (though only a minor naming correction at that). +Having deprecated items in the first stable release of Rust is a bit weird. However, this is only a minor drawback. # Alternatives -#### A. Add `len_hint` as a synonym for `size_hint`, and deprecate `size_hint`. - -A `len_hint` method would be added to the `std::iter::Iterator` trait, which has the following inlined default implementation: - -```rust -fn len_hint(&self) -> (usize, Option) { - self.size_hint() -} -``` - -The `size_hint` method would be marked `deprecated` now. - -In Rust 2.x, `len_hint` would become a required method and `size_hint` would be removed. +#### A. Directly rename `size_hint` to `len_hint`, and `ExactSizeIterator` to `ExactLengthIterator` during the 1.0 beta cycle. -The advantage of this alternative is that it is not a breaking change. +This alternative is clearer than the main candidate. -However, Rust 1.0 final is yet to be released, having something deprecated now but not removed until 2.x is weird. +However, this means late breaking changes, which are generally undesirable. If other breaking changes happen during the 1.0 beta cycle, then this alternative can "piggyback" on those changes. #### B. Keep the status quo. -`size_hint` is not too bad after all, though it is inconsistent, especially when even non-linear collections use methods named `len` instead of `size`. +Other than "not introducing deprecations now", the status quo doesn't have any advantage over the main candidate. # Unresolved questions From 4c706a2b0f35b6aa0d26c6fee9ba4329b0f47834 Mon Sep 17 00:00:00 2001 From: Richard Zhang Date: Sat, 11 Apr 2015 00:04:57 +0800 Subject: [PATCH 4/4] Adjust wording. --- text/0000-iterator-len-hint.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/text/0000-iterator-len-hint.md b/text/0000-iterator-len-hint.md index ba59c8a7f3f..e3e5466db72 100644 --- a/text/0000-iterator-len-hint.md +++ b/text/0000-iterator-len-hint.md @@ -21,8 +21,8 @@ So, some names should be changed. However, Rust 1.0 beta has already been releas # Detailed design -1. Add `core::iter::Iterator::len_hint`, which is an inlined method simply calling `core::iter::Iterator::size_hint`. -2. Add `core::iter::ExactLengthIterator`, which is a re-export of `core::iter::ExactSizeIterator`. +1. Add `core::iter::Iterator::len_hint`, a method with an inlined default implementation simply calling `self.size_hint()`. +2. Add `core::iter::ExactLengthIterator`, a re-export of `core::iter::ExactSizeIterator`. 3. Deprecate `core::iter::Iterator::size_hint` and `core::iter::ExactSizeIterator`. 4. Adjust the `std` re-exports accordingly. 5. Deprecate the implementations of `size_hint`.