Reorganize site to make room for documenting the other built-in modules.

doc/site/modules/core/sequence.markdown

@@ -0,0 +1,170 @@
+^title Sequence Class
+
+An abstract base class for any iterable object. Any class that implements the
+core [iterator protocol][] can extend this to get a number of helpful methods.
+
+[iterator protocol]: ../../control-flow.html#the-iterator-protocol
+
+## Methods
+
+### **all**(predicate)
+
+Tests whether all the elements in the sequence pass the `predicate`.
+
+Iterates over the sequence, passing each element to the function `predicate`.
+If it returns something [false](../control-flow.html#truth), stops iterating
+and returns the value. Otherwise, returns `true`.
+
+    :::wren
+    System.print([1, 2, 3].all {|n| n > 2}) //> false
+    System.print([1, 2, 3].all {|n| n < 4}) //> true
+
+### **any**(predicate)
+
+Tests whether any element in the sequence passes the `predicate`.
+
+Iterates over the sequence, passing each element to the function `predicate`.
+If it returns something [true][], stops iterating and
+returns that value. Otherwise, returns `false`.
+
+[true]: ../../control-flow.html#truth
+
+    :::wren
+    System.print([1, 2, 3].any {|n| n < 1}) //> false
+    System.print([1, 2, 3].any {|n| n > 2}) //> true
+
+### **contains**(element)
+
+Returns whether the sequence contains any element equal to the given element.
+
+### **count**
+
+The number of elements in the sequence.
+
+Unless a more efficient override is available, this will iterate over the
+sequence in order to determine how many elements it contains.
+
+### **count**(predicate)
+
+Returns the number of elements in the sequence that pass the `predicate`.
+
+Iterates over the sequence, passing each element to the function `predicate`
+and counting the number of times the returned value evaluates to `true`.
+
+    :::wren
+    System.print([1, 2, 3].count {|n| n > 2}) //> 1
+    System.print([1, 2, 3].count {|n| n < 4}) //> 3
+
+### **each**(function)
+
+Iterates over the sequence, passing each element to the given `function`.
+
+    :::wren
+    ["one", "two", "three"].each {|word| System.print(word) }
+
+### **isEmpty**
+
+Returns whether the sequence contains any elements.
+
+This can be more efficient that `count == 0` because this does not iterate over
+the entire sequence.
+
+### **join**(separator)
+
+Converts every element in the sequence to a string and then joins the results
+together into a single string, each separated by `separator`.
+
+It is a runtime error if `separator` is not a string.
+
+### **join**()
+
+Converts every element in the sequence to a string and then joins the results
+together into a single string.
+
+### **map**(transformation)
+
+Creates a new sequence that applies the `transformation` to each element in the
+original sequence while it is iterated.
+
+    :::wren
+    var doubles = [1, 2, 3].map {|n| n * 2 }
+    for (n in doubles) {
+      System.print(n) //> 2
+                      //> 4
+                      //> 6
+    }
+
+The returned sequence is *lazy*. It only applies the mapping when you iterate
+over the sequence, and it does so by holding a reference to the original
+sequence.
+
+This means you can use `map(_)` for things like infinite sequences or sequences
+that have side effects when you iterate over them. But it also means that
+changes to the original sequence will be reflected in the mapped sequence.
+
+To force eager evaluation, just call `.toList` on the result.
+
+    :::wren
+    var numbers = [1, 2, 3]
+    var doubles = numbers.map {|n| n * 2 }.toList
+    numbers.add(4)
+    System.print(doubles) //> [2, 4, 6]
+
+### **reduce**(function)
+
+Reduces the sequence down to a single value. `function` is a function that
+takes two arguments, the accumulator and sequence item and returns the new
+accumulator value. The accumulator is initialized from the first item in the
+sequence. Then, the function is invoked on each remaining item in the sequence,
+iteratively updating the accumulator.
+
+It is a runtime error to call this on an empty sequence.
+
+### **reduce**(seed, function)
+
+Similar to above, but uses `seed` for the initial value of the accumulator. If
+the sequence is empty, returns `seed`.
+
+### **toList**
+
+Creates a [list][] containing all the elements in the sequence.
+
+[list]: list.html
+
+    :::wren
+    System.print((1..3).toList)  //> [1, 2, 3]
+
+If the sequence is already a list, this creates a copy of it.
+
+### **where**(predicate)
+
+Creates a new sequence containing only the elements from the original sequence
+that pass the `predicate`.
+
+During iteration, each element in the original sequence is passed to the
+function `predicate`. If it returns `false`, the element is skipped.
+
+    :::wren
+    var odds = (1..6).where {|n| n % 2 == 1 }
+    for (n in odds) {
+        System.print(n) //> 1
+                        //> 3
+                        //> 5
+    }
+
+The returned sequence is *lazy*. It only applies the filtering when you iterate
+over the sequence, and it does so by holding a reference to the original
+sequence.
+
+This means you can use `where(_)` for things like infinite sequences or
+sequences that have side effects when you iterate over them. But it also means
+that changes to the original sequence will be reflected in the filtered
+sequence.
+
+To force eager evaluation, just call `.toList` on the result.
+
+    :::wren
+    var numbers = [1, 2, 3, 4, 5, 6]
+    var odds = numbers.where {|n| n % 2 == 1 }.toList
+    numbers.add(7)
+    System.print(odds) //> [1, 3, 5]