---

yaml
---
r: 64685
b: refs/heads/snap-stage3
c: af5a17b
h: refs/heads/master
i:
  64683: a4ca4a3
v: v3

Author: thestinger

[refs]

@@ -1,7 +1,7 @@
 ---
 refs/heads/master: 2d28d645422c1617be58c8ca7ad9a457264ca850
 refs/heads/snap-stage1: e33de59e47c5076a89eadeb38f4934f58a3618a6
-refs/heads/snap-stage3: 8c0227251299982eaab1c8ebebc76bd856efd38f
+refs/heads/snap-stage3: af5a17b7d0788438bb6b39cccfc96a0b13e00250
 refs/heads/try: 7b78b52e602bb3ea8174f9b2006bff3315f03ef9
 refs/tags/release-0.1: 1f5c5126e96c79d22cb7862f75304136e204f105
 refs/heads/ndm: f3868061cd7988080c30d6d5bf352a5a5fe2460b

branches/snap-stage3/doc/tutorial-container.md

@@ -322,3 +322,31 @@ for it.invert().advance |x| {
     printfln!("%?", x);
 }
 ~~~
+
+## Random-access iterators
+
+The `RandomAccessIterator` trait represents an iterator offering random access
+to the whole range. The `indexable` method retrieves the number of elements
+accessible with the `idx` method.
+
+The `chain_` adaptor is an implementation of `RandomAccessIterator` if the
+underlying iterators are.
+
+~~~
+let xs = [1, 2, 3, 4, 5];
+let ys = ~[7, 9, 11];
+let mut it = xs.iter().chain_(ys.iter());
+printfln!("%?", it.idx(0)); // prints `Some(&1)`
+printfln!("%?", it.idx(5)); // prints `Some(&7)`
+printfln!("%?", it.idx(7)); // prints `Some(&11)`
+printfln!("%?", it.idx(8)); // prints `None`
+
+// yield two elements from the beginning, and one from the end
+it.next();
+it.next();
+it.next_back();
+
+printfln!("%?", it.idx(0)); // prints `Some(&3)`
+printfln!("%?", it.idx(4)); // prints `Some(&9)`
+printfln!("%?", it.idx(6)); // prints `None`
+~~~