doc/uninorm.texi

   1 @node uninorm.h
   2 @chapter Normalization forms (composition and decomposition) @code{<uninorm.h>}
   3
   4 @cindex normal forms
   5 @cindex normalizing
   6 This include file defines functions for transforming Unicode strings to one
   7 of the four normal forms, known as NFC, NFD, NKFC, NFKD.  These
   8 transformations involve decomposition and --- for NFC and NFKC --- composition
   9 of Unicode characters.
  10
  11 @menu
  12 * Decomposition of characters::
  13 * Composition of characters::
  14 * Normalization of strings::
  15 * Normalizing comparisons::
  16 * Normalization of streams::
  17 @end menu
  18
  19 @node Decomposition of characters
  20 @section Decomposition of Unicode characters
  21
  22 @cindex decomposing
  23 The following enumerated values are the possible types of decomposition of a
  24 Unicode character.
  25
  26 @deftypevr Constant int UC_DECOMP_CANONICAL
  27 Denotes canonical decomposition.
  28 @end deftypevr
  29
  30 @deftypevr Constant int UC_DECOMP_FONT
  31 UCD marker: @code{<font>}.  Denotes a font variant (e.g@. a blackletter form).
  32 @end deftypevr
  33
  34 @deftypevr Constant int UC_DECOMP_NOBREAK
  35 UCD marker: @code{<noBreak>}.
  36 Denotes a no-break version of a space or hyphen.
  37 @end deftypevr
  38
  39 @deftypevr Constant int UC_DECOMP_INITIAL
  40 UCD marker: @code{<initial>}.
  41 Denotes an initial presentation form (Arabic).
  42 @end deftypevr
  43
  44 @deftypevr Constant int UC_DECOMP_MEDIAL
  45 UCD marker: @code{<medial>}.
  46 Denotes a medial presentation form (Arabic).
  47 @end deftypevr
  48
  49 @deftypevr Constant int UC_DECOMP_FINAL
  50 UCD marker: @code{<final>}.
  51 Denotes a final presentation form (Arabic).
  52 @end deftypevr
  53
  54 @deftypevr Constant int UC_DECOMP_ISOLATED
  55 UCD marker: @code{<isolated>}.
  56 Denotes an isolated presentation form (Arabic).
  57 @end deftypevr
  58
  59 @deftypevr Constant int UC_DECOMP_CIRCLE
  60 UCD marker: @code{<circle>}.
  61 Denotes an encircled form.
  62 @end deftypevr
  63
  64 @deftypevr Constant int UC_DECOMP_SUPER
  65 UCD marker: @code{<super>}.
  66 Denotes a superscript form.
  67 @end deftypevr
  68
  69 @deftypevr Constant int UC_DECOMP_SUB
  70 UCD marker: @code{<sub>}.
  71 Denotes a subscript form.
  72 @end deftypevr
  73
  74 @deftypevr Constant int UC_DECOMP_VERTICAL
  75 UCD marker: @code{<vertical>}.
  76 Denotes a vertical layout presentation form.
  77 @end deftypevr
  78
  79 @deftypevr Constant int UC_DECOMP_WIDE
  80 UCD marker: @code{<wide>}.
  81 Denotes a wide (or zenkaku) compatibility character.
  82 @end deftypevr
  83
  84 @deftypevr Constant int UC_DECOMP_NARROW
  85 UCD marker: @code{<narrow>}.
  86 Denotes a narrow (or hankaku) compatibility character.
  87 @end deftypevr
  88
  89 @deftypevr Constant int UC_DECOMP_SMALL
  90 UCD marker: @code{<small>}.
  91 Denotes a small variant form (CNS compatibility).
  92 @end deftypevr
  93
  94 @deftypevr Constant int UC_DECOMP_SQUARE
  95 UCD marker: @code{<square>}.
  96 Denotes a CJK squared font variant.
  97 @end deftypevr
  98
  99 @deftypevr Constant int UC_DECOMP_FRACTION
 100 UCD marker: @code{<fraction>}.
 101 Denotes a vulgar fraction form.
 102 @end deftypevr
 103
 104 @deftypevr Constant int UC_DECOMP_COMPAT
 105 UCD marker: @code{<compat>}.
 106 Denotes an otherwise unspecified compatibility character.
 107 @end deftypevr
 108
 109 The following constant denotes the maximum size of decomposition of a single
 110 Unicode character.
 111
 112 @deftypevr Macro {unsigned int} UC_DECOMPOSITION_MAX_LENGTH
 113 This macro expands to a constant that is the required size of buffer passed to
 114 the @code{uc_decomposition} and @code{uc_canonical_decomposition} functions.
 115 @end deftypevr
 116
 117 The following functions decompose a Unicode character.
 118
 119 @deftypefun int uc_decomposition (ucs4_t@tie{}@var{uc}, int@tie{}*@var{decomp_tag}, ucs4_t@tie{}*@var{decomposition})
 120 Returns the character decomposition mapping of the Unicode character @var{uc}.
 121 @var{decomposition} must point to an array of at least
 122 @code{UC_DECOMPOSITION_MAX_LENGTH} @code{ucs_t} elements.
 123
 124 When a decomposition exists, @code{@var{decomposition}[0..@var{n}-1]} and
 125 @code{*@var{decomp_tag}} are filled and @var{n} is returned.  Otherwise -1 is
 126 returned.
 127 @end deftypefun
 128
 129 @deftypefun int uc_canonical_decomposition (ucs4_t@tie{}@var{uc}, ucs4_t@tie{}*@var{decomposition})
 130 Returns the canonical character decomposition mapping of the Unicode character
 131 @var{uc}.  @var{decomposition} must point to an array of at least
 132 @code{UC_DECOMPOSITION_MAX_LENGTH} @code{ucs_t} elements.
 133
 134 When a decomposition exists, @code{@var{decomposition}[0..@var{n}-1]} is filled
 135 and @var{n} is returned.  Otherwise -1 is returned.
 136
 137 Note: This function returns the (simple) ``canonical decomposition'' of
 138 @var{uc}.  If you want the ``full canonical decomposition'' of @var{uc},
 139 that is, the recursive application of ``canonical decomposition'', use the
 140 function @code{u*_normalize} with argument @code{UNINORM_NFD} instead.
 141 @end deftypefun
 142
 143 @node Composition of characters
 144 @section Composition of Unicode characters
 145
 146 @cindex composing, Unicode characters
 147 @cindex combining, Unicode characters
 148 The following function composes a Unicode character from two Unicode
 149 characters.
 150
 151 @deftypefun ucs4_t uc_composition (ucs4_t@tie{}@var{uc1}, ucs4_t@tie{}@var{uc2})
 152 Attempts to combine the Unicode characters @var{uc1}, @var{uc2}.
 153 @var{uc1} is known to have canonical combining class 0.
 154
 155 Returns the combination of @var{uc1} and @var{uc2}, if it exists.
 156 Returns 0 otherwise.
 157
 158 Not all decompositions can be recombined using this function.  See the Unicode
 159 file @file{CompositionExclusions.txt} for details.
 160 @end deftypefun
 161
 162 @node Normalization of strings
 163 @section Normalization of strings
 164
 165 The Unicode standard defines four normalization forms for Unicode strings.
 166 The following type is used to denote a normalization form.
 167
 168 @deftp Type uninorm_t
 169 An object of type @code{uninorm_t} denotes a Unicode normalization form.
 170 This is a scalar type; its values can be compared with @code{==}.
 171 @end deftp
 172
 173 The following constants denote the four normalization forms.
 174
 175 @deftypevr Macro uninorm_t UNINORM_NFD
 176 Denotes Normalization form D: canonical decomposition.
 177 @end deftypevr
 178
 179 @deftypevr Macro uninorm_t UNINORM_NFC
 180 Normalization form C: canonical decomposition, then canonical composition.
 181 @end deftypevr
 182
 183 @deftypevr Macro uninorm_t UNINORM_NFKD
 184 Normalization form KD: compatibility decomposition.
 185 @end deftypevr
 186
 187 @deftypevr Macro uninorm_t UNINORM_NFKC
 188 Normalization form KC: compatibility decomposition, then canonical composition.
 189 @end deftypevr
 190
 191 The following functions operate on @code{uninorm_t} objects.
 192
 193 @deftypefun bool uninorm_is_compat_decomposing (uninorm_t@tie{}@var{nf})
 194 Tests whether the normalization form @var{nf} does compatibility decomposition.
 195 @end deftypefun
 196
 197 @deftypefun bool uninorm_is_composing (uninorm_t@tie{}@var{nf})
 198 Tests whether the normalization form @var{nf} includes canonical composition.
 199 @end deftypefun
 200
 201 @deftypefun uninorm_t uninorm_decomposing_form (uninorm_t@tie{}@var{nf})
 202 Returns the decomposing variant of the normalization form @var{nf}.
 203 This maps NFC,NFD @arrow{} NFD and NFKC,NFKD @arrow{} NFKD.
 204 @end deftypefun
 205
 206 The following functions apply a Unicode normalization form to a Unicode string.
 207
 208 @deftypefun {uint8_t *} u8_normalize (uninorm_t@tie{}@var{nf}, const@tie{}uint8_t@tie{}*@var{s}, size_t@tie{}@var{n}, uint8_t@tie{}*@var{resultbuf}, size_t@tie{}*@var{lengthp})
 209 @deftypefunx {uint16_t *} u16_normalize (uninorm_t@tie{}@var{nf}, const@tie{}uint16_t@tie{}*@var{s}, size_t@tie{}@var{n}, uint16_t@tie{}*@var{resultbuf}, size_t@tie{}*@var{lengthp})
 210 @deftypefunx {uint32_t *} u32_normalize (uninorm_t@tie{}@var{nf}, const@tie{}uint32_t@tie{}*@var{s}, size_t@tie{}@var{n}, uint32_t@tie{}*@var{resultbuf}, size_t@tie{}*@var{lengthp})
 211 Returns the specified normalization form of a string.
 212
 213 The @var{resultbuf} and @var{lengthp} arguments are as described in
 214 chapter @ref{Conventions}.
 215 @end deftypefun
 216
 217 @node Normalizing comparisons
 218 @section Normalizing comparisons
 219
 220 @cindex comparing, ignoring normalization
 221 The following functions compare Unicode string, ignoring differences in
 222 normalization.
 223
 224 @deftypefun int u8_normcmp (const@tie{}uint8_t@tie{}*@var{s1}, size_t@tie{}@var{n1}, const@tie{}uint8_t@tie{}*@var{s2}, size_t@tie{}@var{n2}, uninorm_t@tie{}@var{nf}, int@tie{}*@var{resultp})
 225 @deftypefunx int u16_normcmp (const@tie{}uint16_t@tie{}*@var{s1}, size_t@tie{}@var{n1}, const@tie{}uint16_t@tie{}*@var{s2}, size_t@tie{}@var{n2}, uninorm_t@tie{}@var{nf}, int@tie{}*@var{resultp})
 226 @deftypefunx int u32_normcmp (const@tie{}uint32_t@tie{}*@var{s1}, size_t@tie{}@var{n1}, const@tie{}uint32_t@tie{}*@var{s2}, size_t@tie{}@var{n2}, uninorm_t@tie{}@var{nf}, int@tie{}*@var{resultp})
 227 Compares @var{s1} and @var{s2}, ignoring differences in normalization.
 228
 229 @var{nf} must be either @code{UNINORM_NFD} or @code{UNINORM_NFKD}.
 230
 231 If successful, sets @code{*@var{resultp}} to -1 if @var{s1} < @var{s2},
 232 0 if @var{s1} = @var{s2}, 1 if @var{s1} > @var{s2}, and returns 0.
 233 Upon failure, returns -1 with @code{errno} set.
 234 @end deftypefun
 235
 236 @cindex comparing, ignoring normalization, with collation rules
 237 @cindex comparing, with collation rules, ignoring normalization
 238 @deftypefun {char *} u8_normxfrm (const@tie{}uint8_t@tie{}*@var{s}, size_t@tie{}@var{n}, uninorm_t@tie{}@var{nf}, char@tie{}*@var{resultbuf}, size_t@tie{}*@var{lengthp})
 239 @deftypefunx {char *} u16_normxfrm (const@tie{}uint16_t@tie{}*@var{s}, size_t@tie{}@var{n}, uninorm_t@tie{}@var{nf}, char@tie{}*@var{resultbuf}, size_t@tie{}*@var{lengthp})
 240 @deftypefunx {char *} u32_normxfrm (const@tie{}uint32_t@tie{}*@var{s}, size_t@tie{}@var{n}, uninorm_t@tie{}@var{nf}, char@tie{}*@var{resultbuf}, size_t@tie{}*@var{lengthp})
 241 Converts the string @var{s} of length @var{n} to a NUL-terminated byte
 242 sequence, in such a way that comparing @code{u8_normxfrm (@var{s1})} and
 243 @code{u8_normxfrm (@var{s2})} with the @code{u8_cmp2} function is equivalent to
 244 comparing @var{s1} and @var{s2} with the @code{u8_normcoll} function.
 245
 246 @var{nf} must be either @code{UNINORM_NFC} or @code{UNINORM_NFKC}.
 247
 248 The @var{resultbuf} and @var{lengthp} arguments are as described in
 249 chapter @ref{Conventions}.
 250 @end deftypefun
 251
 252 @deftypefun int u8_normcoll (const@tie{}uint8_t@tie{}*@var{s1}, size_t@tie{}@var{n1}, const@tie{}uint8_t@tie{}*@var{s2}, size_t@tie{}@var{n2}, uninorm_t@tie{}@var{nf}, int@tie{}*@var{resultp})
 253 @deftypefunx int u16_normcoll (const@tie{}uint16_t@tie{}*@var{s1}, size_t@tie{}@var{n1}, const@tie{}uint16_t@tie{}*@var{s2}, size_t@tie{}@var{n2}, uninorm_t@tie{}@var{nf}, int@tie{}*@var{resultp})
 254 @deftypefunx int u32_normcoll (const@tie{}uint32_t@tie{}*@var{s1}, size_t@tie{}@var{n1}, const@tie{}uint32_t@tie{}*@var{s2}, size_t@tie{}@var{n2}, uninorm_t@tie{}@var{nf}, int@tie{}*@var{resultp})
 255 Compares @var{s1} and @var{s2}, ignoring differences in normalization, using
 256 the collation rules of the current locale.
 257
 258 @var{nf} must be either @code{UNINORM_NFC} or @code{UNINORM_NFKC}.
 259
 260 If successful, sets @code{*@var{resultp}} to -1 if @var{s1} < @var{s2},
 261 0 if @var{s1} = @var{s2}, 1 if @var{s1} > @var{s2}, and returns 0.
 262 Upon failure, returns -1 with @code{errno} set.
 263 @end deftypefun
 264
 265 @node Normalization of streams
 266 @section Normalization of streams of Unicode characters
 267
 268 @cindex stream, normalizing a
 269 A ``stream of Unicode characters'' is essentially a function that accepts an
 270 @code{ucs4_t} argument repeatedly, optionally combined with a function that
 271 ``flushes'' the stream.
 272
 273 @deftp Type {struct uninorm_filter}
 274 This is the data type of a stream of Unicode characters that normalizes its
 275 input according to a given normalization form and passes the normalized
 276 character sequence to the encapsulated stream of Unicode characters.
 277 @end deftp
 278
 279 @deftypefun {struct uninorm_filter *} uninorm_filter_create (uninorm_t@tie{}@var{nf}, int@tie{}(*@var{stream_func})@tie{}(void@tie{}*@var{stream_data}, ucs4_t@tie{}@var{uc}), void@tie{}*@var{stream_data})
 280 Creates and returns a normalization filter for Unicode characters.
 281
 282 The pair (@var{stream_func}, @var{stream_data}) is the encapsulated stream.
 283 @code{@var{stream_func} (@var{stream_data}, @var{uc})} receives the Unicode
 284 character @var{uc} and returns 0 if successful, or -1 with @code{errno} set
 285 upon failure.
 286
 287 Returns the new filter, or NULL with @code{errno} set upon failure.
 288 @end deftypefun
 289
 290 @deftypefun int uninorm_filter_write (struct@tie{}uninorm_filter@tie{}*@var{filter}, ucs4_t@tie{}@var{uc})
 291 Stuffs a Unicode character into a normalizing filter.
 292 Returns 0 if successful, or -1 with @code{errno} set upon failure.
 293 @end deftypefun
 294
 295 @deftypefun int uninorm_filter_flush (struct@tie{}uninorm_filter@tie{}*@var{filter})
 296 Brings data buffered in the filter to its destination, the encapsulated stream.
 297
 298 Returns 0 if successful, or -1 with @code{errno} set upon failure.
 299
 300 Note! If after calling this function, additional characters are written
 301 into the filter, the resulting character sequence in the encapsulated stream
 302 will not necessarily be normalized.
 303 @end deftypefun
 304
 305 @deftypefun int uninorm_filter_free (struct@tie{}uninorm_filter@tie{}*@var{filter})
 306 Brings data buffered in the filter to its destination, the encapsulated stream,
 307 then closes and frees the filter.
 308
 309 Returns 0 if successful, or -1 with @code{errno} set upon failure.
 310 @end deftypefun