libgrapheme

unicode string library
git clone git://git.suckless.org/libgrapheme
Log | Files | Refs | README | LICENSE

README (1903B)


      1 libgrapheme
      2 ===========
      3 
      4 The libgrapheme library provides functions to properly handle Unicode
      5 strings according to the Unicode specification. Unicode strings are made
      6 up of user-perceived characters (so-called "grapheme clusters") that are
      7 made up of one or more Unicode codepoints, which in turn are encoded in
      8 one or more bytes in an encoding like UTF-8.
      9 
     10 There is a widespread misconception that it was enough to simply
     11 determine codepoints in a string and treat them as user-perceived
     12 characters to be Unicode compliant. While this may work in some cases,
     13 this assumption quickly breaks, especially for non-Western languages and
     14 decomposed Unicode strings where user-perceived characters are usually
     15 represented using multiple codepoints.
     16 
     17 Despite the complicated multilevel structure of Unicode strings,
     18 libgrapheme provides methods to work with them at the byte-level (i.e.
     19 UTF-8 ‘char’ arrays) while also providing codepoint-level methods.
     20 
     21 See libgrapheme(7) to get started and try out the self-contained examples
     22 given on the manual pages for each function.
     23 
     24 Requirements
     25 ------------
     26 A C99-compiler and POSIX make.
     27 
     28 Installation
     29 ------------
     30 Edit config.mk to match your local setup (usually not necessary, the
     31 default prefix is /usr/local).
     32 
     33 Afterwards enter the following command to build and install libgrapheme
     34 (if necessary as root):
     35 
     36 	make install
     37 
     38 Conformance
     39 -----------
     40 The libgrapheme library is compliant with the Unicode 14.0.0
     41 specification (September 2021).
     42 
     43 To ensure conformance, libgrapheme includes hundreds of tests including
     44 all provided with the standard-provided test-data that is parsed
     45 automatically. The tests can be run with
     46 
     47 	make test
     48 
     49 to check standard conformance.
     50 
     51 Usage
     52 -----
     53 Include the header grapheme.h in your code and link against libgrapheme
     54 with "-lgrapheme" either statically ("-static") or dynamically.
     55 
     56 Author
     57 ------
     58 Laslo Hunhold <dev@frign.de>