From ef75b6ac7b732ea249af79af2a815750f58b0aec Mon Sep 17 00:00:00 2001 From: Nathaniel Theis Date: Fri, 30 Jan 2015 14:44:55 -0800 Subject: [PATCH 1/3] std::iter::once --- text/0000-std-iter-once.md | 47 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 47 insertions(+) create mode 100644 text/0000-std-iter-once.md diff --git a/text/0000-std-iter-once.md b/text/0000-std-iter-once.md new file mode 100644 index 00000000000..958181420d4 --- /dev/null +++ b/text/0000-std-iter-once.md @@ -0,0 +1,47 @@ +- Start Date: (fill me in with today's date, YYYY-MM-DD) 2015-1-30 +- RFC PR: (leave this empty) +- Rust Issue: (leave this empty) + +# Summary + +Add a `once` function to `std::iter` to construct an iterator yielding a given value one time. + +# Motivation + +This is a common task when working with iterators. Currently, this can be done in many ways, most of which are unergonomic, do not work for all types (e.g. requiring Copy/Clone), or both. `once` is simple to implement, simple to use, and simple to understand. + +# Detailed design + +`once` will return a new struct, `std::iter::Once`, implementing Iterator. Internally, `Once` is simply a newtype wrapper around `std::option::IntoIter`. The actual body of `once` is thus trivial: + +```rust +pub struct Once(std::option::IntoIter); + +pub fn once(x: T) -> Once { + Once( + Some(x).into_iter() + ) +} +``` + +The `Once` wrapper struct exists to allow future backwards-compatible changes, and hide the implementation. + +# Drawbacks + +Although a tiny amount of code, it still does come with a testing, maintainance, etc. cost. + +It's already possible to do this via `Some(x).into_iter()`, `std::iter::repeat(x).take(1)` (for `x: Clone`), `vec![x].into_iter()`, various contraptions involving `iterate`... + +The existence of the `Once` struct is not technically necessary. + +# Alternatives + +There are already many, many alternatives to this- `Option::into_iter()`, `iterate`... + +The `Once` struct could be not used, with `std::option::IntoIter` used instead. + +# Unresolved questions + +Naturally, `once` is fairly bikesheddable. `one_time`? `repeat_once`? + +Are versions of `once` that return `&T`/`&mut T` desirable? From b30ad7141d43c7df0bac5ab76b1b5b0d1a735d9f Mon Sep 17 00:00:00 2001 From: Nathaniel Theis Date: Fri, 30 Jan 2015 14:48:46 -0800 Subject: [PATCH 2/3] formatting --- text/0000-std-iter-once.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0000-std-iter-once.md b/text/0000-std-iter-once.md index 958181420d4..5ef066e1086 100644 --- a/text/0000-std-iter-once.md +++ b/text/0000-std-iter-once.md @@ -1,4 +1,4 @@ -- Start Date: (fill me in with today's date, YYYY-MM-DD) 2015-1-30 +- Start Date: 2015-1-30 - RFC PR: (leave this empty) - Rust Issue: (leave this empty) From 5c2aaa0a4c4ef528959ed272c8f07a418df00186 Mon Sep 17 00:00:00 2001 From: Nathaniel Theis Date: Thu, 9 Apr 2015 19:23:21 -0700 Subject: [PATCH 3/3] Update 0000-std-iter-once.md --- text/0000-std-iter-once.md | 18 +++++++++++++++--- 1 file changed, 15 insertions(+), 3 deletions(-) diff --git a/text/0000-std-iter-once.md b/text/0000-std-iter-once.md index 5ef066e1086..0c8993ed608 100644 --- a/text/0000-std-iter-once.md +++ b/text/0000-std-iter-once.md @@ -4,11 +4,11 @@ # Summary -Add a `once` function to `std::iter` to construct an iterator yielding a given value one time. +Add a `once` function to `std::iter` to construct an iterator yielding a given value one time, and an `empty` function to construct an iterator yielding no values. # Motivation -This is a common task when working with iterators. Currently, this can be done in many ways, most of which are unergonomic, do not work for all types (e.g. requiring Copy/Clone), or both. `once` is simple to implement, simple to use, and simple to understand. +This is a common task when working with iterators. Currently, this can be done in many ways, most of which are unergonomic, do not work for all types (e.g. requiring Copy/Clone), or both. `once` and `empty` are simple to implement, simple to use, and simple to understand. # Detailed design @@ -24,7 +24,19 @@ pub fn once(x: T) -> Once { } ``` -The `Once` wrapper struct exists to allow future backwards-compatible changes, and hide the implementation. +`empty` is similar: + +```rust +pub struct Empty(std::option::IntoIter); + +pub fn empty(x: T) -> Empty { + Empty( + None.into_iter() + ) +} +``` + +These wrapper structs exist to allow future backwards-compatible changes, and hide the implementation. # Drawbacks