hare

commit b34d12b29f0a96d34f9415bf5dc78eb21231d8b1
parent be7920c2e0b21ce944b759feccf6037c2f4b7e1a
Author: Drew DeVault <sir@cmpwn.com>
Date:   Sun, 13 Feb 2022 17:58:55 +0100

strings::iter: improve docs

We'll want to slim down this interface later so that the state is just a
slice.

Signed-off-by: Drew DeVault <sir@cmpwn.com>

Diffstat:
M
strings/iter.ha
 | 
22
+++++++++++++++++++---

1 file changed, 19 insertions(+), 3 deletions(-)
diff --git a/strings/iter.ha b/strings/iter.ha
@@ -1,6 +1,5 @@
 use encoding::utf8;
 
-// An iterator which yields each rune from a string.
 export type iterator = struct {
 	dec:  utf8::decoder,
 	push: (rune | void),
@@ -8,7 +7,19 @@ export type iterator = struct {
 	prev: *fn(_: *utf8::decoder) (rune | void | utf8::more | utf8::invalid),
 };
 
-// Initializes a string iterator, starting at the beginning of the string.
+// Initializes a string iterator, starting at the beginning of the string. You
+// may copy the iterator to save its state.
+//
+//	let iter = strings::iter("hi!");
+//	iter::next(&iter);	// 'h'
+//	iter::next(&iter);	// 'i'
+//
+//	// Copying the iterator copies its state:
+//	let dup = iter;
+//	iter::next(&iter);	// '!'
+//	iter::next(&iter);	// void
+//	iter::next(&dup);	// '!'
+//	iter::next(&dup);	// void
 export fn iter(src: str) iterator = iterator {
 	dec = utf8::decode(src),
 	push = void,
@@ -16,8 +27,11 @@ export fn iter(src: str) iterator = iterator {
 	prev = &utf8::prev,
 };
 
-// Initializes a string iterator, starting at the end of the string.
+// Initializes a string iterator, starting at the end of the string and moving
+// backwards with each call to [[next]].
 export fn riter(src: str) iterator = {
+	// TODO: Add rnext et al to avoid blowing up the stack footprint with
+	// next/prev pointers
 	let ret = iterator {
 		dec = utf8::decode(src),
 		push = void,
@@ -71,6 +85,8 @@ export fn prev(iter: *iterator) (rune | void) = {
 // This does not modify the underlying string, and as such, subsequent calls to
 // functions like [[prev]] or [[iter_str]] will behave as if push were never called.
 export fn push(iter: *iterator, r: rune) void = {
+	// TODO: This should probably be removed, and the push field removed
+	// from the struct.
 	assert(iter.push is void);
 	iter.push = r;
 };