README.md

# string_width

[![Package Version](https://img.shields.io/hexpm/v/string_width)](https://hex.pm/packages/string_width)
[![Hex Docs](https://img.shields.io/badge/hex-docs-ffaff3)](https://hexdocs.pm/string_width/)

```sh
gleam add string_width@1
```
```gleam
import string_width

pub fn main() {
  string_width.dimensions("hello,\n안녕하세요", [])
  // --> #(2, 10)

  string_width.line("👩‍👩‍👦‍👦", [string_width.HandleGraphemeClusters])
  // --> 2
}
```

A small package estimates the required number of cells when printing a string on the terminal. It supports all Gleam targets.

### Limitations

- Many terminals don't support grapheme clusters properly, so by default, the
  values returned by this library try to match the behaviour of libc instead
  of modern text rendering pipelines.

- The width of many characters is context-dependent and may vary based on the
  current locale, selected font, operating system, or surrounding context;
  The numbers reported by the functions in this library may not be fully accurate.

  If you encounter a mismatch that is consistent across multiple environments,
  feel free to open an issue or ping me on Discord!

- The behaviour when encountering variant selectors does not match other similar libraries.


### Sources

This library is heavily based on musl libc `wcwidth` implementation, the ansi-regex npm package, and uses many of the test cases of the string-width npm package.


- **UAX #11 East Asian Width:** [https://www.unicode.org/reports/tr11/](https://www.unicode.org/reports/tr11/)
- **Grapheme Clusters in Terminals:** [https://mitchellh.com/writing/grapheme-clusters-in-terminals](https://mitchellh.com/writing/grapheme-clusters-in-terminals)
- **get-east-asian-width:** [https://github.com/sindresorhus/get-east-asian-width](https://github.com/sindresorhus/get-east-asian-width)
- **string-width:** [https://github.com/sindresorhus/string-width](https://github.com/sindresorhus/string-width)
- **ansi-regex:** [https://github.com/chalk/ansi-regex](https://github.com/chalk/ansi-regex)
- **musl-libc wcwidth:** [https://git.musl-libc.org/cgit/musl/tree/src/ctype/wcwidth.c](https://git.musl-libc.org/cgit/musl/tree/src/ctype/wcwidth.c)
- **glibc wcwidth:** [https://sourceware.org/git/?p=glibc.git;a=blob;f=wcsmbs/wcwidth.h;hb=HEAD](https://sourceware.org/git/?p=glibc.git;a=blob;f=wcsmbs/wcwidth.h;hb=HEAD)