char-positions 0.1.0

Iterate chars and their positions, i.e. line, column, and byte ranges
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126

# char-positions

<!-- cargo-rdme start -->

Similar to the standard library's [`.char_indicies()`], but instead of only
producing the start byte position. This library implements [`.char_positions()`],
which can produce any combination of line, column, start byte, and end byte position.

As an example use
<code>text.[char_positions]::&lt;[LineCol]&gt;()</code>
to get the line and column of each [`char`].
Use [`LineColByteRange`] to additionally get the byte range,
or just [`Line`] to simply get the line number.

### Example

```rust
use char_positions::{CharPositionsExt, LineCol};

let text = "Hello šŸ‘‹\nWorld šŸŒ\nšŸ¦€šŸ¦€";

for (LineCol(line, col), c) in text.char_positions() {
    println!("[Ln {line}, Col {col}] {c:?}");
}
```

Which will output:

```text
[Ln 1, Col 1] 'H'
[Ln 1, Col 2] 'e'
[Ln 1, Col 3] 'l'
[Ln 1, Col 4] 'l'
[Ln 1, Col 5] 'o'
[Ln 1, Col 6] ' '
[Ln 1, Col 7] 'šŸ‘‹'
[Ln 1, Col 8] '\n'
[Ln 2, Col 1] 'W'
[Ln 2, Col 2] 'o'
[Ln 2, Col 3] 'r'
[Ln 2, Col 4] 'l'
[Ln 2, Col 5] 'd'
[Ln 2, Col 6] ' '
[Ln 2, Col 7] 'šŸŒ'
[Ln 2, Col 8] '\n'
[Ln 3, Col 1] 'šŸ¦€'
[Ln 3, Col 2] 'šŸ¦€'
```

### Supported

| `.char_positions::<T>()` | Produces |
|:---|---|
| [`usize`] | Start byte index (same as [`.char_indicies()`]) |
| [`std::ops::Range<usize>`] | Start byte and end byte index, i.e. `&text[range]` is the `char` |
| [`LineColByteRange`] | Line number, column number, and byte range |
| [`LineCol`] | Line number and column number |
| [`Line`] | Line number |
| [`Col`] | Column number |
| [`ByteRange`] | Same as using [`std::ops::Range<usize>`] |
| [`ByteStart`] | Start byte index (same as [`.char_indicies()`]) |
| [`ByteEnd`] | End byte index |
| _Tuples are also supported, e.g._ | |
| <code>([Line],)</code> | _Produces the tuple_ |
| <code>([Line], [Col])</code> | _Produces the tuple_ |
| <code>([Line], [Col], [ByteStart], [ByteEnd])</code> | _Produces the tuple_ |
| _etc._ | |

### Example - `LineColByteRange`

```rust
use char_positions::{CharPositionsExt, LineColByteRange};

let text = "Hello šŸ‘‹\nWorld šŸŒ\nšŸ¦€šŸ¦€";

let mut iter = text
    .char_positions::<LineColByteRange>()
    .map(|(LineColByteRange(line, col, range), c)| (line, col, range, c));

assert_eq!(iter.next(), Some((1, 1, 0..1, 'H')));
assert_eq!(iter.next(), Some((1, 2, 1..2, 'e')));
assert_eq!(iter.next(), Some((1, 3, 2..3, 'l')));
assert_eq!(iter.next(), Some((1, 4, 3..4, 'l')));
assert_eq!(iter.next(), Some((1, 5, 4..5, 'o')));
assert_eq!(iter.next(), Some((1, 6, 5..6, ' ')));
assert_eq!(iter.next(), Some((1, 7, 6..10, 'šŸ‘‹')));
assert_eq!(iter.next(), Some((1, 8, 10..11, '\n')));
assert_eq!(iter.next(), Some((2, 1, 11..12, 'W')));
assert_eq!(iter.next(), Some((2, 2, 12..13, 'o')));
assert_eq!(iter.next(), Some((2, 3, 13..14, 'r')));
assert_eq!(iter.next(), Some((2, 4, 14..15, 'l')));
assert_eq!(iter.next(), Some((2, 5, 15..16, 'd')));
assert_eq!(iter.next(), Some((2, 6, 16..17, ' ')));
assert_eq!(iter.next(), Some((2, 7, 17..21, 'šŸŒ')));
assert_eq!(iter.next(), Some((2, 8, 21..22, '\n')));
assert_eq!(iter.next(), Some((3, 1, 22..26, 'šŸ¦€')));
assert_eq!(iter.next(), Some((3, 2, 26..30, 'šŸ¦€')));
assert_eq!(iter.next(), None);
```


[`.char_positions()`]: https://docs.rs/char-positions/*/char_positions/trait.CharPositionsExt.html#tymethod.char_positions
[char_positions]: https://docs.rs/char-positions/*/char_positions/trait.CharPositionsExt.html#tymethod.char_positions

[`LineColByteRange`]: https://docs.rs/char-positions/*/char_positions/struct.LineColByteRange.html
[`LineCol`]: https://docs.rs/char-positions/*/char_positions/struct.LineCol.html
[`Line`]: https://docs.rs/char-positions/*/char_positions/struct.Line.html
[`Col`]: https://docs.rs/char-positions/*/char_positions/struct.Line.html
[`ByteRange`]: https://docs.rs/char-positions/*/char_positions/struct.ByteRange.html
[`ByteStart`]: https://docs.rs/char-positions/*/char_positions/struct.ByteStart.html
[`ByteEnd`]: https://docs.rs/char-positions/*/char_positions/struct.ByteEnd.html

[LineColByteRange]: https://docs.rs/char-positions/*/char_positions/struct.LineColByteRange.html
[LineCol]: https://docs.rs/char-positions/*/char_positions/struct.LineCol.html
[Line]: https://docs.rs/char-positions/*/char_positions/struct.Line.html
[Col]: https://docs.rs/char-positions/*/char_positions/struct.Col.html
[ByteStart]: https://docs.rs/char-positions/*/char_positions/struct.ByteStart.html
[ByteEnd]: https://docs.rs/char-positions/*/char_positions/struct.ByteEnd.html

[`.char_indicies()`]: https://doc.rust-lang.org/std/primitive.str.html#method.char_indices

[`char`]: https://doc.rust-lang.org/std/primitive.char.html
[`usize`]: https://doc.rust-lang.org/std/primitive.usize.html
[`std::ops::Range<usize>`]: https://doc.rust-lang.org/std/ops/struct.Range.html

<!-- cargo-rdme end -->