Debian Codegraph @

strings/iter.ha

raw
1 // SPDX-License-Identifier: MPL-2.0
2 // (c) Hare authors <https://harelang.org>
3
4 use encoding::utf8;
5
6 export type iterator = struct {
7 dec: utf8::decoder,
8 reverse: bool,
9 };
10
11 // Initializes a string iterator, starting at the beginning of the string. You
12 // may copy the iterator to save its state.
13 //
14 // let iter = strings::iter("hi!");
15 // strings::next(&iter); // 'h'
16 // strings::next(&iter); // 'i'
17 //
18 // // Copying the iterator copies its state:
19 // let dup = iter;
20 // strings::next(&iter); // '!'
21 // strings::next(&iter); // done
22 // strings::next(&dup); // '!'
23 // strings::next(&dup); // done
24 export fn iter(src: str) iterator = iterator {
25 dec = utf8::decode(toutf8(src)),
26 reverse = false,
27 };
28
29 // Initializes a string iterator, starting at the end of the string and moving
30 // backwards with each call to [[next]].
31 export fn riter(src: str) iterator = {
32 let ret = iterator {
33 dec = utf8::decode(toutf8(src)),
34 reverse = true,
35 };
36 ret.dec.offs = len(src);
37 return ret;
38 };
39
40 // Gets the next rune from an iterator, or done if there are none left.
41 //
42 // Be aware that a rune is not the minimum lexographical unit of language in
43 // Unicode strings. If you use these runes to construct a new string,
44 // reordering, editing, or omitting any of the runes without careful discretion
45 // may cause linguistic errors to arise. To avoid this, you may need to use a
46 // third-party Unicode module instead.
47 export fn next(iter: *iterator) (rune | done) = move(!iter.reverse, iter);
48
49 // Gets the previous rune from an iterator, or done when at the start of the
50 // string.
51 export fn prev(iter: *iterator) (rune | done) = move(iter.reverse, iter);
52
53 fn move(forward: bool, iter: *iterator) (rune | done) = {
54 let fun = if (forward) &utf8::next else &utf8::prev;
55 match (fun(&iter.dec)) {
56 case (utf8::more | utf8::invalid) =>
57 abort("Invalid UTF-8 string (this should not happen)");
58 case let r: (rune | done) =>
59 return r;
60 };
61 };
62
63 // Returns a substring from the next rune to the end of the string if initialized
64 // with [[iter]], or the beginning of the string if initialized with [[riter]].
65 export fn iterstr(iter: *iterator) str = {
66 if (iter.reverse) {
67 return fromutf8_unsafe(iter.dec.src[..iter.dec.offs]);
68 } else {
69 return fromutf8_unsafe(iter.dec.src[iter.dec.offs..]);
70 };
71 };
72
73 // Returns a substring from the position of the first iterator to the position of
74 // the second iterator. The iterators must originate from the same string and
75 // the position of the second iterator must not be before the position of the
76 // first one.
77 export fn slice(begin: *iterator, end: *iterator) str = {
78 return fromutf8_unsafe(utf8::slice(begin, end));
79 };
80
81 // Returns the byte-wise position of the iterator. When possible, it's generally
82 // considered more idiomatic to use other functions in this module, such as
83 // [[iterstr]] and [[slice]].
84 export fn position(iter: *iterator) size = iter.dec.offs;
85
86 @test fn iter() void = {
87 let s = iter("こんにちは");
88 assert(prev(&s) is done);
89 const expected1 = ['こ', 'ん'];
90 for (let i = 0z; i < len(expected1); i += 1) {
91 assert(next(&s) as rune == expected1[i]);
92 };
93 assert(iterstr(&s) == "にちは");
94 assert(prev(&s) as rune == 'ん');
95 const expected2 = ['ん', 'に', 'ち', 'は'];
96 for (let i = 0z; i < len(expected2); i += 1) {
97 assert(next(&s) as rune == expected2[i]);
98 };
99 assert(next(&s) is done);
100 assert(next(&s) is done);
101 assert(prev(&s) as rune == 'は');
102
103 s = riter("にちは");
104 const expected3 = ['は', 'ち', 'に'];
105 for (let i = 0z; i < len(expected3); i += 1) {
106 assert(next(&s) as rune == expected3[i]);
107 };
108 assert(next(&s) is done);
109 assert(prev(&s) as rune == 'に');
110 };
111
112 @test fn slice() void = {
113 let s = iter("こんにちは");
114 let t = s;
115 assert(len(slice(&s, &t)) == 0 && len(slice(&t, &s)) == 0);
116 for (let i = 0; i < 2; i += 1) {
117 next(&s);
118 next(&t);
119 };
120 assert(len(slice(&s, &t)) == 0 && len(slice(&t, &s)) == 0);
121 for (let i = 0; i < 3; i += 1) {
122 next(&t);
123 };
124 assert(slice(&s, &t) == "にちは");
125 for (let i = 0; i < 3; i += 1) {
126 next(&s);
127 };
128 assert(len(slice(&s, &t)) == 0 && len(slice(&t, &s)) == 0);
129 };