---

yaml
---
r: 67266
b: refs/heads/master
c: af5a17b
h: refs/heads/master
v: v3

Author: thestinger

[refs]

@@ -1,5 +1,5 @@
 ---
-refs/heads/master: 8c0227251299982eaab1c8ebebc76bd856efd38f
+refs/heads/master: af5a17b7d0788438bb6b39cccfc96a0b13e00250
 refs/heads/snap-stage1: e33de59e47c5076a89eadeb38f4934f58a3618a6
 refs/heads/snap-stage3: 18e3db7392d2d0697b7e27d6d986139960144d85
 refs/heads/try: 7b78b52e602bb3ea8174f9b2006bff3315f03ef9

trunk/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`
+~~~