Fix #1261: document Iterator::position

Author: adamchalmers

src/SUMMARY.md

@@ -69,7 +69,7 @@
         - [As output parameters](fn/closures/output_parameters.md)
         - [Examples in `std`](fn/closures/closure_examples.md)
             - [Iterator::any](fn/closures/closure_examples/iter_any.md)
-            - [Iterator::find](fn/closures/closure_examples/iter_find.md)
+            - [Searching through iterators](fn/closures/closure_examples/iter_find.md)
     - [Higher Order Functions](fn/hof.md)
     - [Diverging functions](fn/diverging.md)
 

src/fn/closures/closure_examples/iter_find.md

@@ -1,8 +1,8 @@
-# Iterator::find
+# Searching through iterators
 
-`Iterator::find` is a function which when passed an iterator, will return
-the first element which satisfies the predicate as an `Option`. Its
-signature:
+`Iterator::find` is a function which iterates over an iterator and searches for the 
+first value which satisfies some condition. If none of the values satisfy the 
+condition, it returns `None`. Its signature:
 
 ```rust,ignore
 pub trait Iterator {
@@ -29,9 +29,11 @@ fn main() {
     // `into_iter()` for vecs yields `i32`.
     let mut into_iter = vec2.into_iter();
 
-    // A reference to what is yielded is `&&i32`. Destructure to `i32`.
+    // `iter()` for vecs yields `&i32`, and we want to reference one of its
+    // items, so we have to destructure `&&i32` to `i32`
     println!("Find 2 in vec1: {:?}", iter     .find(|&&x| x == 2));
-    // A reference to what is yielded is `&i32`. Destructure to `i32`.
+    // `into_iter()` for vecs yields `i32`, and we want to reference one of
+    // its items, so we have to destructure `&i32` to `i32`
     println!("Find 2 in vec2: {:?}", into_iter.find(| &x| x == 2));
 
     let array1 = [1, 2, 3];
@@ -44,8 +46,33 @@ fn main() {
 }
 ```
 
+`Iterator::find` gives you a reference to the item. But if you want the _index_ of the
+item, use `Iterator::position`.
+
+```rust,editable
+fn main() {
+    let vec = vec![1, 9, 3, 3, 13, 2];
+
+    let index_of_first_even_number = vec.iter().position(|x| x % 2 == 0);
+    assert_eq!(index_of_first_even_number, Some(5));
+    
+    
+    let index_of_first_negative_number = vec.iter().position(|x| x < &0);
+    assert_eq!(index_of_first_negative_number, None);
+}
+```
+
 ### See also:
 
 [`std::iter::Iterator::find`][find]
 
+[`std::iter::Iterator::find_map`][find_map]
+
+[`std::iter::Iterator::position`][position]
+
+[`std::iter::Iterator::rposition`][rposition]
+
 [find]: https://doc.rust-lang.org/std/iter/trait.Iterator.html#method.find
+[find_map]: https://doc.rust-lang.org/std/iter/trait.Iterator.html#method.find_map
+[position]: https://doc.rust-lang.org/std/iter/trait.Iterator.html#method.position
+[rposition]: https://doc.rust-lang.org/std/iter/trait.Iterator.html#method.rposition