libgrapheme.sh (6346B)
1 cat << EOF 2 .Dd ${MAN_DATE} 3 .Dt LIBGRAPHEME 7 4 .Os suckless.org 5 .Sh NAME 6 .Nm libgrapheme 7 .Nd unicode string library 8 .Sh SYNOPSIS 9 .In grapheme.h 10 .Sh DESCRIPTION 11 The 12 .Nm 13 library provides functions to properly handle Unicode strings according 14 to the Unicode specification in regard to character, word, sentence and 15 line segmentation and case detection and conversion. 16 .Pp 17 Unicode strings are made up of user-perceived characters (so-called 18 .Dq grapheme clusters , 19 see 20 .Sx MOTIVATION ) 21 that are composed of one or more Unicode codepoints, which in turn 22 are encoded in one or more bytes in an encoding like UTF-8. 23 .Pp 24 There is a widespread misconception that it was enough to simply 25 determine codepoints in a string and treat them as user-perceived 26 characters to be Unicode compliant. 27 While this may work in some cases, this assumption quickly breaks, 28 especially for non-Western languages and decomposed Unicode strings 29 where user-perceived characters are usually represented using multiple 30 codepoints. 31 .Pp 32 Despite this complicated multilevel structure of Unicode strings, 33 .Nm 34 provides methods to work with them at the byte-level (i.e. UTF-8 35 .Sq char 36 arrays) while also offering codepoint-level methods. 37 Additionally, it is a 38 .Dq freestanding 39 library (see ISO/IEC 9899:1999 section 4.6) and thus does not depend on 40 a standard library. This makes it easy to use in bare metal environments. 41 .Pp 42 Every documented function's manual page provides a self-contained 43 example illustrating the possible usage. 44 .Sh SEE ALSO 45 .Xr grapheme_decode_utf8 3 , 46 .Xr grapheme_encode_utf8 3 , 47 .Xr grapheme_is_character_break 3 , 48 .Xr grapheme_is_lowercase 3 , 49 .Xr grapheme_is_lowercase_utf8 3 , 50 .Xr grapheme_is_titlecase 3 , 51 .Xr grapheme_is_titlecase_utf8 3 , 52 .Xr grapheme_is_uppercase 3 , 53 .Xr grapheme_is_uppercase_utf8 3 , 54 .Xr grapheme_next_character_break 3 , 55 .Xr grapheme_next_character_break_utf8 3 , 56 .Xr grapheme_next_line_break 3 , 57 .Xr grapheme_next_line_break_utf8 3 , 58 .Xr grapheme_next_sentence_break 3 , 59 .Xr grapheme_next_sentence_break_utf8 3 , 60 .Xr grapheme_next_word_break 3 , 61 .Xr grapheme_next_word_break_utf8 3 , 62 .Xr grapheme_to_lowercase 3 , 63 .Xr grapheme_to_lowercase_utf8 3 , 64 .Xr grapheme_to_titlecase 3 , 65 .Xr grapheme_to_titlecase_utf8 3 66 .Xr grapheme_to_uppercase 3 , 67 .Xr grapheme_to_uppercase_utf8 3 , 68 .Sh STANDARDS 69 .Nm 70 is compliant with the Unicode ${UNICODE_VERSION} specification. 71 .Sh MOTIVATION 72 The idea behind every character encoding scheme like ASCII or Unicode 73 is to express abstract characters (which can be thought of as shapes 74 making up a written language). ASCII for instance, which comprises the 75 range 0 to 127, assigns the number 65 (0x41) to the abstract character 76 .Sq A . 77 This number is called a 78 .Dq codepoint , 79 and all codepoints of an encoding make up its so-called 80 .Dq code space . 81 .Pp 82 Unicode's code space is much larger, ranging from 0 to 0x10FFFF, but its 83 first 128 codepoints are identical to ASCII's. The additional code 84 points are needed as Unicode's goal is to express all writing systems 85 of the world. 86 To give an example, the abstract character 87 .Sq \[u00C4] 88 is not expressable in ASCII, given no ASCII codepoint has been assigned 89 to it. 90 It can be expressed in Unicode, though, with the codepoint 196 (0xC4). 91 .Pp 92 One may assume that this process is straightfoward, but as more and 93 more codepoints were assigned to abstract characters, the Unicode 94 Consortium (that defines the Unicode standard) was facing a problem: 95 Many (mostly non-European) languages have such a large amount of 96 abstract characters that it would exhaust the available Unicode code 97 space if one tried to assign a codepoint to each abstract character. 98 The solution to that problem is best introduced with an example: Consider 99 the abstract character 100 .Sq \[u01DE] , 101 which is 102 .Sq A 103 with an umlaut and a macron added to it. 104 In this sense, one can consider 105 .Sq \[u01DE] 106 as a two-fold modification (namely 107 .Dq add umlaut 108 and 109 .Dq add macron ) 110 of the 111 .Dq base character 112 .Sq A . 113 .Pp 114 The Unicode Consortium adapted this idea by assigning codepoints to 115 modifications. 116 For example, the codepoint 0x308 represents adding an umlaut and 0x304 117 represents adding a macron, and thus, the codepoint sequence 118 .Dq 0x41 0x308 0x304 , 119 namely the base character 120 .Sq A 121 followed by the umlaut and macron modifiers, represents the abstract 122 character 123 .Sq \[u01DE] . 124 As a side-note, the single codepoint 0x1DE was also assigned to 125 .Sq \[u01DE] , 126 which is a good example for the fact that there can be multiple 127 representations of a single abstract character in Unicode. 128 .Pp 129 Expressing a single abstract character with multiple codepoints solved 130 the code space exhaustion-problem, and the concept has been greatly 131 expanded since its first introduction (emojis, joiners, etc.). A sequence 132 (which can also have the length 1) of codepoints that belong together 133 this way and represents an abstract character is called a 134 .Dq grapheme cluster . 135 .Pp 136 In many applications it is necessary to count the number of 137 user-perceived characters, i.e. grapheme clusters, in a string. 138 A good example for this is a terminal text editor, which needs to 139 properly align characters on a grid. 140 This is pretty simple with ASCII-strings, where you just count the number 141 of bytes (as each byte is a codepoint and each codepoint is a grapheme 142 cluster). 143 With Unicode-strings, it is a common mistake to simply adapt the 144 ASCII-approach and count the number of code points. 145 This is wrong, as, for example, the sequence 146 .Dq 0x41 0x308 0x304 , 147 while made up of 3 codepoints, is a single grapheme cluster and 148 represents the user-perceived character 149 .Sq \[u01DE] . 150 .Pp 151 The proper way to segment a string into user-perceived characters 152 is to segment it into its grapheme clusters by applying the Unicode 153 grapheme cluster breaking algorithm (UAX #29). 154 It is based on a complex ruleset and lookup-tables and determines if a 155 grapheme cluster ends or is continued between two codepoints. 156 Libraries like ICU and libunistring, which also offer this functionality, 157 are often bloated, not correct, difficult to use or not reasonably 158 statically linkable. 159 .Pp 160 Analogously, the standard provides algorithms to separate strings by 161 words, sentences and lines, convert cases and compare strings. 162 The motivation behind 163 .Nm 164 is to make unicode handling suck less and abide by the UNIX philosophy. 165 .Sh AUTHORS 166 .An Laslo Hunhold Aq Mt dev@frign.de 167 EOF