Merge branch 'master' of github.com:rust-lang/rfcs

Author: nikomatsakis

text/1640-duration-checked-sub.md

@@ -0,0 +1,102 @@
+- Feature Name: `duration_checked`
+- Start Date: 2016-06-04
+- RFC PR: [rust-lang/rfcs#1640](https://github.com/rust-lang/rfcs/pull/1640)
+- Rust Issue: [rust-lang/rust#35774](https://github.com/rust-lang/rust/issues/35774)
+
+# Summary
+[summary]: #summary
+
+This RFC adds the `checked_*` methods already known from primitives like
+`usize` to `Duration`.
+
+# Motivation
+[motivation]: #motivation
+
+Generally this helps when subtracting `Duration`s which can be the case quite
+often.
+
+One abstract example would be executing a specific piece of code repeatedly
+after a constant amount of time.
+
+Specific examples would be a network service or a rendering process emitting a
+constant amount of frames per second.
+
+Example code would be as follows:
+
+```rust
+
+// This function is called repeatedly
+fn render() {
+    // 10ms delay results in 100 frames per second
+    let wait_time = Duration::from_millis(10);
+
+    // `Instant` for elapsed time
+    let start = Instant::now();
+
+    // execute code here
+    render_and_output_frame();
+
+    // there are no negative `Duration`s so this does nothing if the elapsed
+    // time is longer than the defined `wait_time`
+    start.elapsed().checked_sub(wait_time).and_then(std::thread::sleep);
+}
+```
+
+Of course it is also suitable to not introduce `panic!()`s when adding
+`Duration`s.
+
+# Detailed design
+[design]: #detailed-design
+
+The detailed design would be exactly as the current `sub()` method, just
+returning an `Option<Duration>` and passing possible `None` values from the
+underlying primitive types:
+
+```rust
+impl Duration {
+    fn checked_sub(self, rhs: Duration) -> Option<Duration> {
+        if let Some(mut secs) = self.secs.checked_sub(rhs.secs) {
+            let nanos = if self.nanos >= rhs.nanos {
+                self.nanos - rhs.nanos
+            } else {
+                if let Some(secs) = secs.checked_sub(1) {
+                    self.nanos + NANOS_PER_SEC - rhs.nanos
+                }
+                else {
+                    return None;
+                }
+            };
+            debug_assert!(nanos < NANOS_PER_SEC);
+            Some(Duration { secs: secs, nanos: nanos })
+        }
+        else {
+            None
+        }
+    }
+}
+```
+
+The same accounts for all other added methods, namely:
+
+- `checked_add()`
+- `checked_sub()`
+- `checked_mul()`
+- `checked_div()`
+
+# Drawbacks
+[drawbacks]: #drawbacks
+
+`None`.
+
+# Alternatives
+[alternatives]: #alternatives
+
+The alternatives are simply not doing this and forcing the programmer to code
+the check on their behalf.
+This is not what you want.
+
+# Unresolved questions
+[unresolved]: #unresolved-questions
+
+`None`.
+

text/1679-panic-safe-slicing.md

@@ -0,0 +1,122 @@
+- Feature Name: `panic_safe_slicing`
+- Start Date: 2015-10-16
+- RFC PR: [rust-lang/rfcs#1679](https://github.com/rust-lang/rfcs/pull/1679)
+- Rust Issue: [rust-lang/rfcs#35729](https://github.com/rust-lang/rust/issues/35729)
+
+# Summary
+
+Add "panic-safe" or "total" alternatives to the existing panicking indexing syntax.
+
+# Motivation
+
+`SliceExt::get` and `SliceExt::get_mut` can be thought as non-panicking versions of the simple
+indexing syntax, `a[idx]`, and `SliceExt::get_unchecked` and `SliceExt::get_unchecked_mut` can
+be thought of as unsafe versions with bounds checks elided. However, there is no such equivalent for
+`a[start..end]`, `a[start..]`, or `a[..end]`. This RFC proposes such methods to fill the gap.
+
+# Detailed design
+
+The `get`, `get_mut`, `get_unchecked`, and `get_unchecked_mut` will be made generic over `usize`
+as well as ranges of `usize` like slice's `Index` implementation currently is. This will allow e.g.
+`a.get(start..end)` which will behave analagously to `a[start..end]`.
+
+Because methods cannot be overloaded in an ad-hoc manner in the same way that traits may be
+implemented, we introduce a `SliceIndex` trait which is implemented by types which can index into a
+slice:
+```rust
+pub trait SliceIndex<T> {
+    type Output: ?Sized;
+
+    fn get(self, slice: &[T]) -> Option<&Self::Output>;
+    fn get_mut(self, slice: &mut [T]) -> Option<&mut Self::Output>;
+    unsafe fn get_unchecked(self, slice: &[T]) -> &Self::Output;
+    unsafe fn get_mut_unchecked(self, slice: &[T]) -> &mut Self::Output;
+    fn index(self, slice: &[T]) -> &Self::Output;
+    fn index_mut(self, slice: &mut [T]) -> &mut Self::Output;
+}
+
+impl<T> SliceIndex<T> for usize {
+    type Output = T;
+    // ...
+}
+
+impl<T, R> SliceIndex<T> for R
+    where R: RangeArgument<usize>
+{
+    type Output = [T];
+    // ...
+}
+```
+
+And then alter the `Index`, `IndexMut`, `get`, `get_mut`, `get_unchecked`, and `get_mut_unchecked`
+implementations to be generic over `SliceIndex`:
+```rust
+impl<T> [T] {
+    pub fn get<I>(&self, idx: I) -> Option<I::Output>
+        where I: SliceIndex<T>
+    {
+        idx.get(self)
+    }
+
+    pub fn get_mut<I>(&mut self, idx: I) -> Option<I::Output>
+        where I: SliceIndex<T>
+    {
+        idx.get_mut(self)
+    }
+
+    pub unsafe fn get_unchecked<I>(&self, idx: I) -> I::Output
+        where I: SliceIndex<T>
+    {
+        idx.get_unchecked(self)
+    }
+
+    pub unsafe fn get_mut_unchecked<I>(&mut self, idx: I) -> I::Output
+        where I: SliceIndex<T>
+    {
+        idx.get_mut_unchecked(self)
+    }
+}
+
+impl<T, I> Index<I> for [T]
+    where I: SliceIndex<T>
+{
+    type Output = I::Output;
+
+    fn index(&self, idx: I) -> &I::Output {
+        idx.index(self)
+    }
+}
+
+impl<T, I> IndexMut<I> for [T]
+    where I: SliceIndex<T>
+{
+    fn index_mut(&self, idx: I) -> &mut I::Output {
+        idx.index_mut(self)
+    }
+}
+```
+
+# Drawbacks
+
+- The `SliceIndex` trait is unfortunate - it's tuned for exactly the set of methods it's used by.
+  It only exists because inherent methods cannot be overloaded the same way that trait
+  implementations can be. It would most likely remain unstable indefinitely.
+- Documentation may suffer. Rustdoc output currently explicitly shows each of the ways you can
+  index a slice, while there will simply be a single generic implementation with this change. This
+  may not be that bad, though. The doc block currently seems to provided the most valuable
+  information to newcomers rather than the trait bound, and that will still be present with this
+  change.
+
+# Alternatives
+
+- Stay as is.
+- A previous version of this RFC introduced new `get_slice` etc methods rather than overloading
+  `get` etc. This avoids the utility trait but is somewhat less ergonomic.
+- Instead of one trait amalgamating all of the required methods, we could have one trait per
+  method. This would open a more reasonable door to stabilizing those traits, but adds quite a lot
+  more surface area. Replacing an unstable `SliceIndex` trait with a collection would be
+  backwards compatible.
+
+# Unresolved questions
+
+None