Merge pull request #594 from mdinger/functionality

Rewrite and expand the closure section

Author: steveklabnik

examples/fn/unused/input.md renamed to examples/attribute/unused/input.md

@@ -0,0 +1,18 @@
+// `F` must implement `Fn` for a closure which takes no
+// inputs and returns nothing. Exactly what is required
+// for `print`.
+fn apply<F>(f: F) where
+    F: Fn() {
+
+    f()
+}
+
+fn main() {
+    let x = 7;
+
+    // Capture `x` into an anonymous type and implement
+    // `Fn` for it. Store it in `print`.
+    let print = || println!("{}", x);
+
+    apply(print);
+}

examples/fn/unused/unused.rs renamed to examples/attribute/unused/unused.rs

@@ -0,0 +1,34 @@
+Closures succinctly capture variables from enclosing scopes. Does this have
+any consequences? It surely does. Observe how using a closure in a function
+requires generics, which is necessary because of how they are defined:
+
+```rust
+// `F` must be generic.
+fn apply<F>(f: F) where
+    F: FnOnce() {
+    f()
+}
+```
+
+When a closure is defined, the compiler implicitly creates a new
+anonymous structure to store the captured variables inside, meanwhile
+implementing the functionality via one of the `traits`: `Fn`, `FnMut`, or
+`FnOnce` for this unknown type. This type is assigned to the variable which
+is stored until calling.
+
+Since this new type is of unknown type, any usage in a function will require
+generics. However, an unbounded type parameter (`<T>`) would still be ambiguous
+and not be allowed. Thus, bounding by one of the `traits`: `Fn`, `FnMut`, or
+`FnOnce` (which it implements) is sufficient to specify it's type.
+
+{anonymity.play}
+
+### See also:
+
+[A thorough analysis][thorough_analysis], [`Fn`][fn], [`FnMut`][fn_mut],
+and [`FnOnce`][fn_once]
+
+[fn]: http://doc.rust-lang.org/std/ops/trait.Fn.html
+[fn_mut]: http://doc.rust-lang.org/std/ops/trait.FnMut.html
+[fn_once]: http://doc.rust-lang.org/std/ops/trait.FnOnce.html
+[thorough_analysis]: http://huonw.github.io/blog/2015/05/finding-closure-in-rust/

examples/fn/closures/anonymity/anonymity.rs

@@ -0,0 +1,52 @@
+fn main() {
+    let color = "green";
+
+    // A closure to print `color` which immediately borrows (`&`)
+    // `color` and stores the borrow and closure in the `print`
+    // variable. It will remain borrowed until `print` goes out of
+    // scope. `println!` only requires `by reference` so it doesn't
+    // impose anything more restrictive.
+    let print = || println!("`color`: {}", color);
+
+    // Call the closure using the borrow.
+    print();
+    print();
+
+    let mut count = 0;
+
+    // A closure to increment `count` could take either `&mut count`
+    // or `count` but `&mut count` is less restrictive so it takes
+    // that. Immediately borrows `count`.
+    //
+    // A `mut` is required on `inc` because a `&mut` is stored inside.
+    // Thus, calling the closure mutates the closure which requires
+    // a `mut`.
+    let mut inc = || {
+        count += 1;
+        println!("`count`: {}", count);
+    };
+
+    // Call the closure.
+    inc();
+    inc();
+
+    //let reborrow = &mut count;
+    // ^ TODO: try uncommenting this line.
+    
+    // A non-copy type.
+    let movable = Box::new(3);
+
+    // `drop` requires `T` so this must take by value. A copy type
+    // would copy into the closure leaving the original untouched.
+    // A non-copy must move and so `movable` immediately moves into
+    // the closure.
+    let consume = || {
+        println!("`movable`: {:?}", movable);
+        drop(movable);
+    };
+
+    // `eat` consumes the variable so this can only be called once.
+    consume();
+    //consume();
+    // ^ TODO: Try uncommenting this line.
+}

examples/fn/closures/anonymity/input.md

@@ -0,0 +1,20 @@
+Closures are inherently flexible and will do what the functionality requires
+to make the closure work without annotation. This allows capturing to
+flexibly adapt to the use case, sometimes moving and sometimes borrowing.
+Closures can capture variables:
+
+* by reference: `&T`
+* by mutable reference: `&mut T`
+* by value: `T`
+
+They preferentially capture variables by reference and only go lower when
+required.
+
+{capture.play}
+
+### See also:
+
+[`Box`][box] and [`std::mem::drop`][drop]
+
+[box]: /std/box.html
+[drop]: http://doc.rust-lang.org/std/mem/fn.drop.html

examples/fn/closures/capture/capture.rs

@@ -0,0 +1 @@
+A brief analysis of a few different `std` library closure examples.

examples/fn/closures/capture/input.md

@@ -0,0 +1,26 @@
+`Iterator::any` is a function which when passed an iterator, will return
+`true` if any element satisfies the predicate. Otherwise `false`. It's
+signature:
+
+```rust
+pub trait Iterator {
+    // The type being iterated over.
+    type Item;
+
+    // `any` takes `&mut self` meaning the caller may be borrowed
+    // and modified, but not consumed.
+    fn any<F>(&mut self, f: F) -> bool where
+        // `FnMut` meaning any captured variable may at most be
+        // modified, not consumed. `Self::Item` states it takes
+        // arguments to the closure by value.
+        F: FnMut(Self::Item) -> bool {}
+}
+```
+
+{iter_any.play}
+
+### See also:
+
+[`Iterator::any`][any]
+
+[any]: http://doc.rust-lang.org/std/iter/trait.Iterator.html#method.any

examples/fn/closures/closure_analysis/input.md

@@ -0,0 +1,17 @@
+fn main() {
+    let vec1 = vec![1, 2, 3];
+    let vec2 = vec![4, 5, 6];
+
+    // `iter` yields `&i32`. Destructure to `i32`.
+    println!("2 in vec1: {}", vec1.iter()     .any(|&x| x == 2));
+    // `into_iter` yields `i32`. No destructuring required.
+    println!("2 in vec2: {}", vec2.into_iter().any(| x| x == 2));
+
+    let array1 = [1, 2, 3];
+    let array2 = [4, 5, 6];
+
+    // `iter()` is normal. `into_iter()` for arrays unusually
+    // yields `&i32`. These would not normally both be `&`.
+    println!("2 in array1: {}", array1.iter()     .any(|&x| x == 2));
+    println!("2 in array2: {}", array2.into_iter().any(|&x| x == 2));
+}

examples/fn/closures/closure_analysis/iter_any/input.md

@@ -0,0 +1,26 @@
+`Iterator::find` is a function which when passed an iterator, will return
+the first element which satisfies the predicate as an `Option`. It's
+signature:
+
+```rust
+pub trait Iterator {
+    // The type being iterated over.
+    type Item;
+
+    // `any` takes `&mut self` meaning the caller may be borrowed
+    // and modified, but not consumed.
+    fn find<P>(&mut self, predicate: P) -> Option<Self::Item> where
+        // `FnMut` meaning any captured variable may at most be
+        // modified, not consumed. `&Self::Item` states it takes
+        // arguments to the closure by reference.
+        P: FnMut(&Self::Item) -> bool {}
+}
+```
+
+{iter_find.play}
+
+### See also:
+
+[`Iterator::find`][find]
+
+[find]: http://doc.rust-lang.org/std/iter/trait.Iterator.html#method.find