summaryrefslogtreecommitdiff
path: root/doc/api/libstd/iterutil.txt
diff options
context:
space:
mode:
Diffstat (limited to 'doc/api/libstd/iterutil.txt')
-rw-r--r--doc/api/libstd/iterutil.txt100
1 files changed, 100 insertions, 0 deletions
diff --git a/doc/api/libstd/iterutil.txt b/doc/api/libstd/iterutil.txt
new file mode 100644
index 0000000..a023542
--- /dev/null
+++ b/doc/api/libstd/iterutil.txt
@@ -0,0 +1,100 @@
+{
+ title: libstd
+ description: libstd: Summary
+}
+
+
+Iteration Utilities
+----------------
+
+ pkg std =
+ type zipiter(@a, @b)
+ type reverseiter(@a)
+ type enumiter(@a)
+
+ impl iterable zipiter(@a, @b) -> (@a, @b)
+ impl iterable enumiter(@a) -> (size, @a)
+ impl iterable reverseiter(@a) -> @a
+
+ generic byzip : (a : @a[:], b : @b[:] -> zipiter(@a, @b))
+ generic byenum : (a : @a[:] -> enumiter(@a))
+ generic byreverse : (sl : @a[:] -> reverseiter(@a))
+ ;;
+
+Summary
+--------
+
+Iteration over sequence is something that turns up regularly. The iteration
+utilities provided here simplify a number of common instances of iteration
+over collections. They allow for iterating over a zipped sequence,
+enumerating a collection of elements, or going over a collection of elements
+in reverse.
+
+All of these iterators hold a reference to the original data, and require that
+it not be freed until they are finished consuming it. They do not copy the
+slices that they iterate over, and all consume O(1) storage.
+
+Zip Iterators
+-------------
+
+ impl iterable zipiter(@a, @b) -> (@a, @b)
+ generic byzip : (a : @a[:], b : @b[:] -> zipiter(@a, @b))
+
+The zipiter takes two slices, and returns an iterator that will walk over them
+pair by pair. So, for example, if you were to call `std.byzip([1,2,3][:],
+[4,5,6][:])`, you would iterate through the elements `(1,4), (2,5), (3, 6)`.
+
+Zip Iterators
+-------------
+ impl iterable enumiter(@a) -> (size, @a)
+ generic byenum : (a : @a[:] -> enumiter(@a))
+
+The enumiter takes a single sequence, and returns the pair of (index, element)
+tuples. If you were to call `std.byenum(["hello", "there", "friend"][:])`, you
+iterate through the elements `(1, "hello"), (2, "there"), (3, "friend")`.
+
+Reverse Iterators
+-----------------
+
+ impl iterable reverseiter(@a) -> @a
+ generic byreverse : (sl : @a[:] -> reverseiter(@a))
+
+
+The reverse takes a single slice, and returns the same elements back, but in
+the reverse order. Calling `std.byenum(["hello", "there", "friend"][:])`
+would iterate in the sequence `"friend", "there", "hello".
+
+Examples
+--------
+
+This is a simple zip iterator:
+
+```{runmyr zipiter}
+use std
+const main = {
+ for x in std.byzip([1,2,3][:], [4,5,6][:])
+ std.put("{}\n", x)
+ ;;
+}
+```
+
+This is a simple enum iterator:
+
+```{runmyr enumiter}
+use std
+const main = {
+ for x in std.byenum(["hello", "world"][:])
+ std.put("{}\n", x)
+ ;;
+}
+```
+
+```{runmyr reverseiter}
+use std
+const main = {
+ for x in std.byreverse(["hello", "world"][:])
+ std.put("{}\n", x)
+ ;;
+}
+```
+