# README

`unicode-data` provides Haskell APIs to efficiently access the Unicode
character database. [Performance](#performance) is the primary goal in the
design of this package.

The Haskell data structures are generated programmatically from the
[Unicode character database](https://www.unicode.org/ucd/) (UCD) files.
The latest Unicode version supported by this library is
[`15.0.0`](https://www.unicode.org/versions/Unicode15.0.0/).

Please see the
[Haddock documentation](https://hackage.haskell.org/package/unicode-data)
for reference documentation.

## Performance

`unicode-data` is up to _5 times faster_ than `base`.

The following benchmark compares the time taken in milliseconds to process all
the Unicode code points for `base-4.16` (GHC 9.2.1) and this package (v0.3).
Machine: 8 × AMD Ryzen 5 2500U on Linux.

```
All
  Unicode.Char.Case.Compat
    isLower
      base:           OK (1.53s)
         24 ms ± 3.8 ms
      unicode-data:   OK (2.25s)
        4.4 ms ±  88 μs, 0.19x
    isUpper
      base:           OK (1.50s)
         24 ms ± 450 μs
      unicode-data:   OK (2.37s)
        4.7 ms ± 200 μs, 0.19x
    toLower
      base:           OK (1.40s)
         22 ms ± 1.8 ms
      unicode-data:   OK (1.89s)
        7.2 ms ± 297 μs, 0.32x
    toTitle
      base:           OK (1.25s)
         20 ms ± 2.0 ms
      unicode-data:   OK (1.65s)
        6.4 ms ± 509 μs, 0.32x
    toUpper
      base:           OK (1.26s)
         20 ms ± 2.5 ms
      unicode-data:   OK (1.72s)
        6.8 ms ± 335 μs, 0.34x
  Unicode.Char.General
    generalCategory
      base:           OK (2.02s)
        134 ms ± 1.6 ms
      unicode-data:   OK (1.75s)
        116 ms ± 1.6 ms, 0.87x
    isAlphaNum
      base:           OK (1.53s)
         24 ms ± 1.7 ms
      unicode-data:   OK (2.16s)
        4.2 ms ±  29 μs, 0.18x
    isControl
      base:           OK (1.47s)
         23 ms ± 2.6 ms
      unicode-data:   OK (2.23s)
        4.4 ms ±  22 μs, 0.19x
    isMark
      base:           OK (1.47s)
         23 ms ± 624 μs
      unicode-data:   OK (2.28s)
        4.5 ms ±  48 μs, 0.19x
    isPrint
      base:           OK (1.53s)
         25 ms ± 2.4 ms
      unicode-data:   OK (2.27s)
        4.4 ms ±  50 μs, 0.18x
    isPunctuation
      base:           OK (1.51s)
         24 ms ± 459 μs
      unicode-data:   OK (2.24s)
        4.4 ms ±  25 μs, 0.18x
    isSeparator
      base:           OK (1.52s)
         24 ms ± 407 μs
      unicode-data:   OK (2.43s)
        4.8 ms ±  94 μs, 0.20x
    isSymbol
      base:           OK (1.49s)
         24 ms ± 863 μs
      unicode-data:   OK (1.34s)
        5.2 ms ±  92 μs, 0.22x
  Unicode.Char.General.Compat
    isAlpha
      base:           OK (1.46s)
         23 ms ± 322 μs
      unicode-data:   OK (2.14s)
        4.1 ms ±  36 μs, 0.18x
    isLetter
      base:           OK (1.44s)
         22 ms ± 640 μs
      unicode-data:   OK (2.17s)
        4.3 ms ±  58 μs, 0.19x
    isSpace
      base:           OK (1.44s)
         11 ms ± 1.2 ms
      unicode-data:   OK (1.36s)
        5.3 ms ± 243 μs, 0.49x
  Unicode.Char.Numeric
    isNumber
      base:           OK (1.52s)
         24 ms ± 368 μs
      unicode-data:   OK (2.41s)
        4.7 ms ±  41 μs, 0.19x
```

## Unicode database version update

To update the Unicode version please update the version number in
`ucd.sh`.

To download the Unicode database, run `ucd.sh download` from the top
level directory of the repo to fetch the database in `./ucd`.

```
$ ./ucd.sh download
```

To generate the Haskell data structure files from the downloaded database
files, run `ucd.sh generate` from the top level directory of the repo.

```
$ ./ucd.sh generate
```

## Running property doctests

Temporarily add `QuickCheck` to build depends of library.

```
$ cabal build
$ cabal-docspec --check-properties --property-variables c
```

## Licensing

`unicode-data` is an [open source](https://github.com/composewell/unicode-data)
project available under a liberal [Apache-2.0 license](LICENSE).

## Contributing

As an open project we welcome contributions.