1 files changed, 81 insertions, 0 deletions
diff --git a/src/doc/rust-by-example/src/fn/closures/closure_examples/iter_find.md b/src/doc/rust-by-example/src/fn/closures/closure_examples/iter_find.md
new file mode 100644
index 000000000..0a79f7c9d
--- /dev/null
+++ b/src/doc/rust-by-example/src/fn/closures/closure_examples/iter_find.md
@@ -0,0 +1,81 @@
+# Searching through iterators
+
+`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 {
+    // The type being iterated over.
+    type Item;
+
+    // `find` 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;
+}
+```
+
+```rust,editable
+fn main() {
+    let vec1 = vec![1, 2, 3];
+    let vec2 = vec![4, 5, 6];
+
+    // `iter()` for vecs yields `&i32`.
+    let mut iter = vec1.iter();
+    // `into_iter()` for vecs yields `i32`.
+    let mut into_iter = vec2.into_iter();
+
+    // `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));
+    // `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];
+    let array2 = [4, 5, 6];
+
+    // `iter()` for arrays yields `&i32`
+    println!("Find 2 in array1: {:?}", array1.iter()     .find(|&&x| x == 2));
+    // `into_iter()` for arrays yields `i32`
+    println!("Find 2 in array2: {:?}", array2.into_iter().find(|&x| x == 2));
+}
+```
+
+`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];
+
+    // `iter()` for vecs yields `&i32` and `position()` does not take a reference, so
+    // we have to destructure `&i32` to `i32`
+    let index_of_first_even_number = vec.iter().position(|&x| x % 2 == 0);
+    assert_eq!(index_of_first_even_number, Some(5));
+    
+    // `into_iter()` for vecs yields `i32` and `position()` does not take a reference, so
+    // we do not have to destructure    
+    let index_of_first_negative_number = vec.into_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