![Build and test](https://github.com/bobhy/print-positions/actions/workflows/ci.yml/badge.svg)
# Crate print_positions
Iterators which return the slice of characters making up a "print position", rather
than the individual characters of a source string.
* [Documentation](https://docs.rs/print-positions)
* [crates.io](https://crates.io/crates/print-positions)
* [Release notes](https://github.com/bobhy/print-positions/blob/main/CHANGELOG.md)
The [print_positions](https://docs.rs/print-positions/latest/print_positions/fn.print_positions.html)
and [print_position_indices](https://docs.rs/print-positions/latest/print_positions/fn.print_position_indices.html) functions
provide iterators which return "print positions".
A print position is a generalization of a
[UAX#29 extended grapheme cluster](http://www.unicode.org/reports/tr29/#Grapheme_Cluster_Boundaries).
Like the grapheme, it occupies one "character" when rendered on the screen.
However, it may also contain [ANSI escape codes](https://en.wikipedia.org/wiki/ANSI_escape_code#Description)
which affect color or intensity rendering as well.
## Example:
```rust
use print_positions::print_positions;
let content = ["\u{1b}[30;42m", "\u{0065}", "\u{0308}", "\u{1b}[0m"].join("");
let print_positions:Vec<_> = print_positions(&content).collect();
assert_eq!(content.len(), 15); assert_eq!(print_positions.len(), 1); ```
## Rationale:
When laying out a fixed-width screen application, it is useful to know how many visible
columns a piece of content will consume. But the number of bytes or characters in
the content is generally larger, inflated by UTF8 encoding, Unicode combining characters
and zero-width joiners and, for ANSI compatible devices and applications, by control codes and escape
sequences which specify text color and emphasis.
The print_position iterators account for these factors
and simplify the arithmetic: the number of columns the content will consume on the screen is
the number of print position slices returned by the iterator.
## Known Issues:
* No accounting for cursor motion
ANSI control characters and sequences are *all* assumed to consume no space on the screen.
This is arguably a bug
in the case of backspace, tab, newline, CUP, CUU, CUD and several more. PRs or simple suggestions for improvement are welcome!