doc/unictype.texi

   1 @node unictype.h
   2 @chapter Unicode character classification and properties @code{<unictype.h>}
   3
   4 This include file declares functions that classify Unicode characters
   5 and that test whether Unicode characters have specific properties.
   6
   7 The classification assigns a ``general category'' to every Unicode
   8 character.  This is similar to the classification provided by ISO C in
   9 @code{<wctype.h>}.
  10
  11 Properties are the data that guides various text processing algorithms
  12 in the presence of specific Unicode characters.
  13
  14 @menu
  15 * General category::
  16 * Canonical combining class::
  17 * Bidi class::
  18 * Decimal digit value::
  19 * Digit value::
  20 * Numeric value::
  21 * Mirrored character::
  22 * Arabic shaping::
  23 * Properties::
  24 * Scripts::
  25 * Blocks::
  26 * ISO C and Java syntax::
  27 * Classifications like in ISO C::
  28 @end menu
  29
  30 @node General category
  31 @section General category
  32
  33 @cindex general category
  34 @cindex Unicode character, general category
  35 @cindex Unicode character, classification
  36 Every Unicode character or code point has a @emph{general category} assigned
  37 to it.  This classification is important for most algorithms that work on
  38 Unicode text.
  39
  40 The GNU libunistring library provides two kinds of API for working with
  41 general categories.  The object oriented API uses a variable to denote
  42 every predefined general category value or combinations thereof.  The
  43 low-level API uses a bit mask instead.  The advantage of the object oriented
  44 API is that if only a few predefined general category values are used,
  45 the data tables are relatively small.  When you combine general category
  46 values (using @code{uc_general_category_or}, @code{uc_general_category_and},
  47 or @code{uc_general_category_and_not}), or when you use the low level
  48 bit masks, a big table is used thats holds the complete general category
  49 information for all Unicode characters.
  50
  51 @menu
  52 * Object oriented API::
  53 * Bit mask API::
  54 @end menu
  55
  56 @node Object oriented API
  57 @subsection The object oriented API for general category
  58
  59 @deftp Type uc_general_category_t
  60 This data type denotes a general category value.  It is an immediate type that
  61 can be copied by simple assignment, without involving memory allocation.  It is
  62 not an array type.
  63 @end deftp
  64
  65 The following are the predefined general category value.  Additional general
  66 categories may be added in the future.
  67
  68 @deftypevr Constant uc_general_category_t UC_CATEGORY_L
  69 @deftypevrx Constant uc_general_category_t UC_CATEGORY_LC
  70 @deftypevrx Constant uc_general_category_t UC_CATEGORY_Lu
  71 @deftypevrx Constant uc_general_category_t UC_CATEGORY_Ll
  72 @deftypevrx Constant uc_general_category_t UC_CATEGORY_Lt
  73 @deftypevrx Constant uc_general_category_t UC_CATEGORY_Lm
  74 @deftypevrx Constant uc_general_category_t UC_CATEGORY_Lo
  75 @deftypevrx Constant uc_general_category_t UC_CATEGORY_M
  76 @deftypevrx Constant uc_general_category_t UC_CATEGORY_Mn
  77 @deftypevrx Constant uc_general_category_t UC_CATEGORY_Mc
  78 @deftypevrx Constant uc_general_category_t UC_CATEGORY_Me
  79 @deftypevrx Constant uc_general_category_t UC_CATEGORY_N
  80 @deftypevrx Constant uc_general_category_t UC_CATEGORY_Nd
  81 @deftypevrx Constant uc_general_category_t UC_CATEGORY_Nl
  82 @deftypevrx Constant uc_general_category_t UC_CATEGORY_No
  83 @deftypevrx Constant uc_general_category_t UC_CATEGORY_P
  84 @deftypevrx Constant uc_general_category_t UC_CATEGORY_Pc
  85 @deftypevrx Constant uc_general_category_t UC_CATEGORY_Pd
  86 @deftypevrx Constant uc_general_category_t UC_CATEGORY_Ps
  87 @deftypevrx Constant uc_general_category_t UC_CATEGORY_Pe
  88 @deftypevrx Constant uc_general_category_t UC_CATEGORY_Pi
  89 @deftypevrx Constant uc_general_category_t UC_CATEGORY_Pf
  90 @deftypevrx Constant uc_general_category_t UC_CATEGORY_Po
  91 @deftypevrx Constant uc_general_category_t UC_CATEGORY_S
  92 @deftypevrx Constant uc_general_category_t UC_CATEGORY_Sm
  93 @deftypevrx Constant uc_general_category_t UC_CATEGORY_Sc
  94 @deftypevrx Constant uc_general_category_t UC_CATEGORY_Sk
  95 @deftypevrx Constant uc_general_category_t UC_CATEGORY_So
  96 @deftypevrx Constant uc_general_category_t UC_CATEGORY_Z
  97 @deftypevrx Constant uc_general_category_t UC_CATEGORY_Zs
  98 @deftypevrx Constant uc_general_category_t UC_CATEGORY_Zl
  99 @deftypevrx Constant uc_general_category_t UC_CATEGORY_Zp
 100 @deftypevrx Constant uc_general_category_t UC_CATEGORY_C
 101 @deftypevrx Constant uc_general_category_t UC_CATEGORY_Cc
 102 @deftypevrx Constant uc_general_category_t UC_CATEGORY_Cf
 103 @deftypevrx Constant uc_general_category_t UC_CATEGORY_Cs
 104 @deftypevrx Constant uc_general_category_t UC_CATEGORY_Co
 105 @deftypevrx Constant uc_general_category_t UC_CATEGORY_Cn
 106 @end deftypevr
 107
 108 The following are alias names for predefined General category values.
 109
 110 @deftypevr Macro uc_general_category_t UC_LETTER
 111 This is another name for @code{UC_CATEGORY_L}.
 112 @end deftypevr
 113
 114 @deftypevr Macro uc_general_category_t UC_CASED_LETTER
 115 This is another name for @code{UC_CATEGORY_LC}.
 116 @end deftypevr
 117
 118 @deftypevr Macro uc_general_category_t UC_UPPERCASE_LETTER
 119 This is another name for @code{UC_CATEGORY_Lu}.
 120 @end deftypevr
 121
 122 @deftypevr Macro uc_general_category_t UC_LOWERCASE_LETTER
 123 This is another name for @code{UC_CATEGORY_Ll}.
 124 @end deftypevr
 125
 126 @deftypevr Macro uc_general_category_t UC_TITLECASE_LETTER
 127 This is another name for @code{UC_CATEGORY_Lt}.
 128 @end deftypevr
 129
 130 @deftypevr Macro uc_general_category_t UC_MODIFIER_LETTER
 131 This is another name for @code{UC_CATEGORY_Lm}.
 132 @end deftypevr
 133
 134 @deftypevr Macro uc_general_category_t UC_OTHER_LETTER
 135 This is another name for @code{UC_CATEGORY_Lo}.
 136 @end deftypevr
 137
 138 @deftypevr Macro uc_general_category_t UC_MARK
 139 This is another name for @code{UC_CATEGORY_M}.
 140 @end deftypevr
 141
 142 @deftypevr Macro uc_general_category_t UC_NON_SPACING_MARK
 143 This is another name for @code{UC_CATEGORY_Mn}.
 144 @end deftypevr
 145
 146 @deftypevr Macro uc_general_category_t UC_COMBINING_SPACING_MARK
 147 This is another name for @code{UC_CATEGORY_Mc}.
 148 @end deftypevr
 149
 150 @deftypevr Macro uc_general_category_t UC_ENCLOSING_MARK
 151 This is another name for @code{UC_CATEGORY_Me}.
 152 @end deftypevr
 153
 154 @deftypevr Macro uc_general_category_t UC_NUMBER
 155 This is another name for @code{UC_CATEGORY_N}.
 156 @end deftypevr
 157
 158 @deftypevr Macro uc_general_category_t UC_DECIMAL_DIGIT_NUMBER
 159 This is another name for @code{UC_CATEGORY_Nd}.
 160 @end deftypevr
 161
 162 @deftypevr Macro uc_general_category_t UC_LETTER_NUMBER
 163 This is another name for @code{UC_CATEGORY_Nl}.
 164 @end deftypevr
 165
 166 @deftypevr Macro uc_general_category_t UC_OTHER_NUMBER
 167 This is another name for @code{UC_CATEGORY_No}.
 168 @end deftypevr
 169
 170 @deftypevr Macro uc_general_category_t UC_PUNCTUATION
 171 This is another name for @code{UC_CATEGORY_P}.
 172 @end deftypevr
 173
 174 @deftypevr Macro uc_general_category_t UC_CONNECTOR_PUNCTUATION
 175 This is another name for @code{UC_CATEGORY_Pc}.
 176 @end deftypevr
 177
 178 @deftypevr Macro uc_general_category_t UC_DASH_PUNCTUATION
 179 This is another name for @code{UC_CATEGORY_Pd}.
 180 @end deftypevr
 181
 182 @deftypevr Macro uc_general_category_t UC_OPEN_PUNCTUATION
 183 This is another name for @code{UC_CATEGORY_Ps} (``start punctuation'').
 184 @end deftypevr
 185
 186 @deftypevr Macro uc_general_category_t UC_CLOSE_PUNCTUATION
 187 This is another name for @code{UC_CATEGORY_Pe} (``end punctuation'').
 188 @end deftypevr
 189
 190 @deftypevr Macro uc_general_category_t UC_INITIAL_QUOTE_PUNCTUATION
 191 This is another name for @code{UC_CATEGORY_Pi}.
 192 @end deftypevr
 193
 194 @deftypevr Macro uc_general_category_t UC_FINAL_QUOTE_PUNCTUATION
 195 This is another name for @code{UC_CATEGORY_Pf}.
 196 @end deftypevr
 197
 198 @deftypevr Macro uc_general_category_t UC_OTHER_PUNCTUATION
 199 This is another name for @code{UC_CATEGORY_Po}.
 200 @end deftypevr
 201
 202 @deftypevr Macro uc_general_category_t UC_SYMBOL
 203 This is another name for @code{UC_CATEGORY_S}.
 204 @end deftypevr
 205
 206 @deftypevr Macro uc_general_category_t UC_MATH_SYMBOL
 207 This is another name for @code{UC_CATEGORY_Sm}.
 208 @end deftypevr
 209
 210 @deftypevr Macro uc_general_category_t UC_CURRENCY_SYMBOL
 211 This is another name for @code{UC_CATEGORY_Sc}.
 212 @end deftypevr
 213
 214 @deftypevr Macro uc_general_category_t UC_MODIFIER_SYMBOL
 215 This is another name for @code{UC_CATEGORY_Sk}.
 216 @end deftypevr
 217
 218 @deftypevr Macro uc_general_category_t UC_OTHER_SYMBOL
 219 This is another name for @code{UC_CATEGORY_So}.
 220 @end deftypevr
 221
 222 @deftypevr Macro uc_general_category_t UC_SEPARATOR
 223 This is another name for @code{UC_CATEGORY_Z}.
 224 @end deftypevr
 225
 226 @deftypevr Macro uc_general_category_t UC_SPACE_SEPARATOR
 227 This is another name for @code{UC_CATEGORY_Zs}.
 228 @end deftypevr
 229
 230 @deftypevr Macro uc_general_category_t UC_LINE_SEPARATOR
 231 This is another name for @code{UC_CATEGORY_Zl}.
 232 @end deftypevr
 233
 234 @deftypevr Macro uc_general_category_t UC_PARAGRAPH_SEPARATOR
 235 This is another name for @code{UC_CATEGORY_Zp}.
 236 @end deftypevr
 237
 238 @deftypevr Macro uc_general_category_t UC_OTHER
 239 This is another name for @code{UC_CATEGORY_C}.
 240 @end deftypevr
 241
 242 @deftypevr Macro uc_general_category_t UC_CONTROL
 243 This is another name for @code{UC_CATEGORY_Cc}.
 244 @end deftypevr
 245
 246 @deftypevr Macro uc_general_category_t UC_FORMAT
 247 This is another name for @code{UC_CATEGORY_Cf}.
 248 @end deftypevr
 249
 250 @deftypevr Macro uc_general_category_t UC_SURROGATE
 251 This is another name for @code{UC_CATEGORY_Cs}.  All code points in this
 252 category are invalid characters.
 253 @end deftypevr
 254
 255 @deftypevr Macro uc_general_category_t UC_PRIVATE_USE
 256 This is another name for @code{UC_CATEGORY_Co}.
 257 @end deftypevr
 258
 259 @deftypevr Macro uc_general_category_t UC_UNASSIGNED
 260 This is another name for @code{UC_CATEGORY_Cn}.  Some code points in this
 261 category are invalid characters.
 262 @end deftypevr
 263
 264 The following functions combine general categories, like in a boolean algebra,
 265 except that there is no @samp{not} operation.
 266
 267 @deftypefun uc_general_category_t uc_general_category_or (uc_general_category_t @var{category1}, uc_general_category_t @var{category2})
 268 Returns the union of two general categories.
 269 This corresponds to the unions of the two sets of characters.
 270 @end deftypefun
 271
 272 @deftypefun uc_general_category_t uc_general_category_and (uc_general_category_t @var{category1}, uc_general_category_t @var{category2})
 273 Returns the intersection of two general categories as bit masks.
 274 This @emph{does not} correspond to the intersection of the two sets of
 275 characters.
 276 @c Really??
 277 @end deftypefun
 278
 279 @deftypefun uc_general_category_t uc_general_category_and_not (uc_general_category_t @var{category1}, uc_general_category_t @var{category2})
 280 Returns the intersection of a general category with the complement of a
 281 second general category, as bit masks.
 282 This @emph{does not} correspond to the intersection with complement, when
 283 viewing the categories as sets of characters.
 284 @c Really??
 285 @end deftypefun
 286
 287 The following functions associate general categories with their name.
 288
 289 @deftypefun {const char *} uc_general_category_name (uc_general_category_t @var{category})
 290 Returns the name of a general category, more precisely, the abbreviated name.
 291 Returns NULL if the general category corresponds to a bit mask that does not
 292 have a name.
 293 @end deftypefun
 294
 295 @deftypefun {const char *} uc_general_category_long_name (uc_general_category_t @var{category})
 296 Returns the long name of a general category.
 297 Returns NULL if the general category corresponds to a bit mask that does not
 298 have a name.
 299 @end deftypefun
 300
 301 @deftypefun uc_general_category_t uc_general_category_byname (const char *@var{category_name})
 302 Returns the general category given by name, e.g@. @code{"Lu"}, or by long
 303 name, e.g@. @code{"Uppercase Letter"}.
 304 This lookup ignores spaces, underscores, or hyphens as word separators and is
 305 case-insignificant.
 306 @end deftypefun
 307
 308 The following functions view general categories as sets of Unicode characters.
 309
 310 @deftypefun uc_general_category_t uc_general_category (ucs4_t @var{uc})
 311 Returns the general category of a Unicode character.
 312
 313 This function uses a big table.
 314 @end deftypefun
 315
 316 @deftypefun bool uc_is_general_category (ucs4_t @var{uc}, uc_general_category_t @var{category})
 317 Tests whether a Unicode character belongs to a given category.
 318 The @var{category} argument can be a predefined general category or the
 319 combination of several predefined general categories.
 320 @end deftypefun
 321
 322 @node Bit mask API
 323 @subsection The bit mask API for general category
 324
 325 The following are the predefined general category value as bit masks.
 326 Additional general categories may be added in the future.
 327
 328 @deftypevr Macro uint32_t UC_CATEGORY_MASK_L
 329 @deftypevrx Macro uint32_t UC_CATEGORY_MASK_LC
 330 @deftypevrx Macro uint32_t UC_CATEGORY_MASK_Lu
 331 @deftypevrx Macro uint32_t UC_CATEGORY_MASK_Ll
 332 @deftypevrx Macro uint32_t UC_CATEGORY_MASK_Lt
 333 @deftypevrx Macro uint32_t UC_CATEGORY_MASK_Lm
 334 @deftypevrx Macro uint32_t UC_CATEGORY_MASK_Lo
 335 @deftypevrx Macro uint32_t UC_CATEGORY_MASK_M
 336 @deftypevrx Macro uint32_t UC_CATEGORY_MASK_Mn
 337 @deftypevrx Macro uint32_t UC_CATEGORY_MASK_Mc
 338 @deftypevrx Macro uint32_t UC_CATEGORY_MASK_Me
 339 @deftypevrx Macro uint32_t UC_CATEGORY_MASK_N
 340 @deftypevrx Macro uint32_t UC_CATEGORY_MASK_Nd
 341 @deftypevrx Macro uint32_t UC_CATEGORY_MASK_Nl
 342 @deftypevrx Macro uint32_t UC_CATEGORY_MASK_No
 343 @deftypevrx Macro uint32_t UC_CATEGORY_MASK_P
 344 @deftypevrx Macro uint32_t UC_CATEGORY_MASK_Pc
 345 @deftypevrx Macro uint32_t UC_CATEGORY_MASK_Pd
 346 @deftypevrx Macro uint32_t UC_CATEGORY_MASK_Ps
 347 @deftypevrx Macro uint32_t UC_CATEGORY_MASK_Pe
 348 @deftypevrx Macro uint32_t UC_CATEGORY_MASK_Pi
 349 @deftypevrx Macro uint32_t UC_CATEGORY_MASK_Pf
 350 @deftypevrx Macro uint32_t UC_CATEGORY_MASK_Po
 351 @deftypevrx Macro uint32_t UC_CATEGORY_MASK_S
 352 @deftypevrx Macro uint32_t UC_CATEGORY_MASK_Sm
 353 @deftypevrx Macro uint32_t UC_CATEGORY_MASK_Sc
 354 @deftypevrx Macro uint32_t UC_CATEGORY_MASK_Sk
 355 @deftypevrx Macro uint32_t UC_CATEGORY_MASK_So
 356 @deftypevrx Macro uint32_t UC_CATEGORY_MASK_Z
 357 @deftypevrx Macro uint32_t UC_CATEGORY_MASK_Zs
 358 @deftypevrx Macro uint32_t UC_CATEGORY_MASK_Zl
 359 @deftypevrx Macro uint32_t UC_CATEGORY_MASK_Zp
 360 @deftypevrx Macro uint32_t UC_CATEGORY_MASK_C
 361 @deftypevrx Macro uint32_t UC_CATEGORY_MASK_Cc
 362 @deftypevrx Macro uint32_t UC_CATEGORY_MASK_Cf
 363 @deftypevrx Macro uint32_t UC_CATEGORY_MASK_Cs
 364 @deftypevrx Macro uint32_t UC_CATEGORY_MASK_Co
 365 @deftypevrx Macro uint32_t UC_CATEGORY_MASK_Cn
 366 @end deftypevr
 367
 368 The following function views general categories as sets of Unicode characters.
 369
 370 @deftypefun bool uc_is_general_category_withtable (ucs4_t @var{uc}, uint32_t @var{bitmask})
 371 Tests whether a Unicode character belongs to a given category.
 372 The @var{bitmask} argument can be a predefined general category bitmask or the
 373 combination of several predefined general category bitmasks.
 374
 375 This function uses a big table comprising all general categories.
 376 @end deftypefun
 377
 378 @node Canonical combining class
 379 @section Canonical combining class
 380
 381 @cindex canonical combining class
 382 @cindex Unicode character, canonical combining class
 383 Every Unicode character or code point has a @emph{canonical combining class}
 384 assigned to it.
 385
 386 What is the meaning of the canonical combining class?  Essentially, it
 387 indicates the priority with which a combining character is attached to its
 388 base character.  The characters for which the canonical combining class is 0
 389 are the base characters, and the characters for which it is greater than 0 are
 390 the combining characters.  Combining characters are rendered
 391 near/attached/around their base character, and combining characters with small
 392 combining classes are attached "first" or "closer" to the base character.
 393
 394 The canonical combining class of a character is a number in the range
 395 0..255.  The possible values are described in the Unicode Character Database
 396 @texnl{}@url{http://www.unicode.org/Public/UNIDATA/UCD.html}.  The list here is
 397 not definitive; more values can be added in future versions.
 398
 399 @deftypevr Constant int UC_CCC_NR
 400 The canonical combining class value for ``Not Reordered'' characters.
 401 The value is 0.
 402 @end deftypevr
 403
 404 @deftypevr Constant int UC_CCC_OV
 405 The canonical combining class value for ``Overlay'' characters.
 406 @end deftypevr
 407
 408 @deftypevr Constant int UC_CCC_NK
 409 The canonical combining class value for ``Nukta'' characters.
 410 @end deftypevr
 411
 412 @deftypevr Constant int UC_CCC_KV
 413 The canonical combining class value for ``Kana Voicing'' characters.
 414 @end deftypevr
 415
 416 @deftypevr Constant int UC_CCC_VR
 417 The canonical combining class value for ``Virama'' characters.
 418 @end deftypevr
 419
 420 @deftypevr Constant int UC_CCC_ATBL
 421 The canonical combining class value for ``Attached Below Left'' characters.
 422 @end deftypevr
 423
 424 @deftypevr Constant int UC_CCC_ATB
 425 The canonical combining class value for ``Attached Below'' characters.
 426 @end deftypevr
 427
 428 @deftypevr Constant int UC_CCC_ATA
 429 The canonical combining class value for ``Attached Above'' characters.
 430 @end deftypevr
 431
 432 @deftypevr Constant int UC_CCC_ATAR
 433 The canonical combining class value for ``Attached Above Right'' characters.
 434 @end deftypevr
 435
 436 @deftypevr Constant int UC_CCC_BL
 437 The canonical combining class value for ``Below Left'' characters.
 438 @end deftypevr
 439
 440 @deftypevr Constant int UC_CCC_B
 441 The canonical combining class value for ``Below'' characters.
 442 @end deftypevr
 443
 444 @deftypevr Constant int UC_CCC_BR
 445 The canonical combining class value for ``Below Right'' characters.
 446 @end deftypevr
 447
 448 @deftypevr Constant int UC_CCC_L
 449 The canonical combining class value for ``Left'' characters.
 450 @end deftypevr
 451
 452 @deftypevr Constant int UC_CCC_R
 453 The canonical combining class value for ``Right'' characters.
 454 @end deftypevr
 455
 456 @deftypevr Constant int UC_CCC_AL
 457 The canonical combining class value for ``Above Left'' characters.
 458 @end deftypevr
 459
 460 @deftypevr Constant int UC_CCC_A
 461 The canonical combining class value for ``Above'' characters.
 462 @end deftypevr
 463
 464 @deftypevr Constant int UC_CCC_AR
 465 The canonical combining class value for ``Above Right'' characters.
 466 @end deftypevr
 467
 468 @deftypevr Constant int UC_CCC_DB
 469 The canonical combining class value for ``Double Below'' characters.
 470 @end deftypevr
 471
 472 @deftypevr Constant int UC_CCC_DA
 473 The canonical combining class value for ``Double Above'' characters.
 474 @end deftypevr
 475
 476 @deftypevr Constant int UC_CCC_IS
 477 The canonical combining class value for ``Iota Subscript'' characters.
 478 @end deftypevr
 479
 480 The following functions associate canonical combining classes with their name.
 481
 482 @deftypefun {const char *} uc_combining_class_name (int @var{ccc})
 483 Returns the name of a canonical combining class, more precisely, the
 484 abbreviated name.
 485 Returns NULL if the canonical combining class is a numeric value without a
 486 name.
 487 @end deftypefun
 488
 489 @deftypefun {const char *} uc_combining_class_long_name (int @var{ccc})
 490 Returns the long name of a canonical combining class.
 491 Returns NULL if the canonical combining class is a numeric value without a
 492 name.
 493 @end deftypefun
 494
 495 @deftypefun int uc_combining_class_byname (const char *@var{ccc_name})
 496 Returns the canonical combining class given by name, e.g@. @code{"BL"}, or by
 497 long name, e.g@. @code{"Below Left"}.
 498 This lookup ignores spaces, underscores, or hyphens as word separators and is
 499 case-insignificant.
 500 @end deftypefun
 501
 502 The following function looks up the canonical combining class of a character.
 503
 504 @deftypefun int uc_combining_class (ucs4_t @var{uc})
 505 Returns the canonical combining class of a Unicode character.
 506 @end deftypefun
 507
 508 @node Bidi class
 509 @section Bidi class
 510
 511 @cindex bidi class
 512 @cindex bidirectional category
 513 @cindex Unicode character, bidi class
 514 @cindex Unicode character, bidirectional category
 515 Every Unicode character or code point has a @emph{bidi class} assigned to it.
 516 Before Unicode 4.0, this concept was known as @emph{bidirectional category}.
 517
 518 The bidi class guides the bidirectional algorithm@texnl{}
 519 (@url{http://www.unicode.org/reports/tr9/}).  The possible values are
 520 the following.
 521
 522 @deftypevr Constant int UC_BIDI_L
 523 The bidi class for `Left-to-Right`'' characters.
 524 @end deftypevr
 525
 526 @deftypevr Constant int UC_BIDI_LRE
 527 The bidi class for ``Left-to-Right Embedding'' characters.
 528 @end deftypevr
 529
 530 @deftypevr Constant int UC_BIDI_LRO
 531 The bidi class for ``Left-to-Right Override'' characters.
 532 @end deftypevr
 533
 534 @deftypevr Constant int UC_BIDI_R
 535 The bidi class for ``Right-to-Left'' characters.
 536 @end deftypevr
 537
 538 @deftypevr Constant int UC_BIDI_AL
 539 The bidi class for ``Right-to-Left Arabic'' characters.
 540 @end deftypevr
 541
 542 @deftypevr Constant int UC_BIDI_RLE
 543 The bidi class for ``Right-to-Left Embedding'' characters.
 544 @end deftypevr
 545
 546 @deftypevr Constant int UC_BIDI_RLO
 547 The bidi class for ``Right-to-Left Override'' characters.
 548 @end deftypevr
 549
 550 @deftypevr Constant int UC_BIDI_PDF
 551 The bidi class for ``Pop Directional Format'' characters.
 552 @end deftypevr
 553
 554 @deftypevr Constant int UC_BIDI_EN
 555 The bidi class for ``European Number'' characters.
 556 @end deftypevr
 557
 558 @deftypevr Constant int UC_BIDI_ES
 559 The bidi class for ``European Number Separator'' characters.
 560 @end deftypevr
 561
 562 @deftypevr Constant int UC_BIDI_ET
 563 The bidi class for ``European Number Terminator'' characters.
 564 @end deftypevr
 565
 566 @deftypevr Constant int UC_BIDI_AN
 567 The bidi class for ``Arabic Number'' characters.
 568 @end deftypevr
 569
 570 @deftypevr Constant int UC_BIDI_CS
 571 The bidi class for ``Common Number Separator'' characters.
 572 @end deftypevr
 573
 574 @deftypevr Constant int UC_BIDI_NSM
 575 The bidi class for ``Non-Spacing Mark'' characters.
 576 @end deftypevr
 577
 578 @deftypevr Constant int UC_BIDI_BN
 579 The bidi class for ``Boundary Neutral'' characters.
 580 @end deftypevr
 581
 582 @deftypevr Constant int UC_BIDI_B
 583 The bidi class for ``Paragraph Separator'' characters.
 584 @end deftypevr
 585
 586 @deftypevr Constant int UC_BIDI_S
 587 The bidi class for ``Segment Separator'' characters.
 588 @end deftypevr
 589
 590 @deftypevr Constant int UC_BIDI_WS
 591 The bidi class for ``Whitespace'' characters.
 592 @end deftypevr
 593
 594 @deftypevr Constant int UC_BIDI_ON
 595 The bidi class for ``Other Neutral'' characters.
 596 @end deftypevr
 597
 598 The following functions implement the association between a bidirectional
 599 category and its name.
 600
 601 @deftypefun {const char *} uc_bidi_class_name (int @var{bidi_class})
 602 @deftypefunx {const char *} uc_bidi_category_name (int @var{category})
 603 Returns the name of a bidi class, more precisely, the abbreviated name.
 604 @end deftypefun
 605
 606 @deftypefun {const char *} uc_bidi_class_long_name (int @var{bidi_class})
 607 Returns the long name of a bidi class.
 608 @end deftypefun
 609
 610 @deftypefun int uc_bidi_class_byname (const char *@var{bidi_class_name})
 611 @deftypefunx int uc_bidi_category_byname (const char *@var{category_name})
 612 Returns the bidi class given by name, e.g@. @code{"LRE"}, or by long name,
 613 e.g@. @code{"Left-to-Right Embedding"}.
 614 This lookup ignores spaces, underscores, or hyphens as word separators and is
 615 case-insignificant.
 616 @end deftypefun
 617
 618 The following functions view bidirectional categories as sets of Unicode
 619 characters.
 620
 621 @deftypefun int uc_bidi_class (ucs4_t @var{uc})
 622 @deftypefunx int uc_bidi_category (ucs4_t @var{uc})
 623 Returns the bidi class of a Unicode character.
 624 @end deftypefun
 625
 626 @deftypefun bool uc_is_bidi_class (ucs4_t @var{uc}, int @var{bidi_class})
 627 @deftypefunx bool uc_is_bidi_category (ucs4_t @var{uc}, int @var{category})
 628 Tests whether a Unicode character belongs to a given bidi class.
 629 @end deftypefun
 630
 631 @node Decimal digit value
 632 @section Decimal digit value
 633
 634 @cindex value, of Unicode character
 635 @cindex Unicode character, value
 636 Decimal digits (like the digits from @samp{0} to @samp{9}) exist in many
 637 scripts.  The following function converts a decimal digit character to its
 638 numerical value.
 639
 640 @deftypefun int uc_decimal_value (ucs4_t @var{uc})
 641 Returns the decimal digit value of a Unicode character.
 642 The return value is an integer in the range 0..9, or -1 for characters that
 643 do not represent a decimal digit.
 644 @end deftypefun
 645
 646 @node Digit value
 647 @section Digit value
 648
 649 @cindex value, of Unicode character
 650 @cindex Unicode character, value
 651 Digit characters are like decimal digit characters, possibly in special forms,
 652 like as superscript, subscript, or circled.  The following function converts a
 653 digit character to its numerical value.
 654
 655 @deftypefun int uc_digit_value (ucs4_t @var{uc})
 656 Returns the digit value of a Unicode character.
 657 The return value is an integer in the range 0..9, or -1 for characters that
 658 do not represent a digit.
 659 @end deftypefun
 660
 661 @node Numeric value
 662 @section Numeric value
 663
 664 @cindex value, of Unicode character
 665 @cindex Unicode character, value
 666 There are also characters that represent numbers without a digit system, like
 667 the Roman numerals, and fractional numbers, like 1/4 or 3/4.
 668
 669 The following type represents the numeric value of a Unicode character.
 670 @deftp Type uc_fraction_t
 671 This is a structure type with the following fields:
 672 @smallexample
 673 int numerator;
 674 int denominator;
 675 @end smallexample
 676 An integer @var{n} is represented by @code{numerator = @var{n}},
 677 @code{denominator = 1}.
 678 @end deftp
 679
 680 The following function converts a number character to its numerical value.
 681
 682 @deftypefun uc_fraction_t uc_numeric_value (ucs4_t @var{uc})
 683 Returns the numeric value of a Unicode character.
 684 The return value is a fraction, or the pseudo-fraction @code{@{ 0, 0 @}} for
 685 characters that do not represent a number.
 686 @end deftypefun
 687
 688 @node Mirrored character
 689 @section Mirrored character
 690
 691 @cindex mirroring, of Unicode character
 692 @cindex Unicode character, mirroring
 693 Character mirroring is used to associate the closing parenthesis character
 694 to the opening parenthesis character, the closing brace character with the
 695 opening brace character, and so on.
 696
 697 The following function looks up the mirrored character of a Unicode character.
 698
 699 @deftypefun bool uc_mirror_char (ucs4_t @var{uc}, ucs4_t *@var{puc})
 700 Stores the mirrored character of a Unicode character @var{uc} in
 701 @code{*@var{puc}} and returns @code{true}, if it exists.  Otherwise it
 702 stores @var{uc} unmodified in @code{*@var{puc}} and returns @code{false}.
 703 @end deftypefun
 704
 705 @node Arabic shaping
 706 @section Arabic shaping
 707
 708 @cindex Arabic shaping
 709 @cindex joining of Arabic characters
 710 When Arabic characters are rendered, after bidi reordering has taken
 711 place, the shape of the glyphs are modified so that many adjacent glyphs
 712 are joined.  Two character properties describe how this ``Arabic shaping''
 713 takes place: the joining type and the joining group.
 714
 715 @menu
 716 * Joining type::
 717 * Joining group::
 718 @end menu
 719
 720 @node Joining type
 721 @subsection Joining type of Arabic characters
 722
 723 @cindex joining type
 724 The joining type of a character describes on which of the left and right
 725 neighbour characters the character's shape depends, and which of the two
 726 neighbour characters are rendered depending on this character.
 727
 728 The joining type has the following possible values:
 729
 730 @deftypevr Constant int UC_JOINING_TYPE_U
 731 ``Non joining'': Characters of this joining type prohibit joining.
 732 @end deftypevr
 733
 734 @deftypevr Constant int UC_JOINING_TYPE_T
 735 ``Transparent'': Characters of this joining type are skipped when
 736 considering joining.
 737 @end deftypevr
 738
 739 @deftypevr Constant int UC_JOINING_TYPE_C
 740 ``Join causing'': Characters of this joining type cause their neighbour
 741 characters to change their shapes but don't change their own shape.
 742 @end deftypevr
 743
 744 @deftypevr Constant int UC_JOINING_TYPE_L
 745 ``Left joining'': Characters of this joining type have two shapes,
 746 isolated and initial.  Such characters currently don't exist.
 747 @end deftypevr
 748
 749 @deftypevr Constant int UC_JOINING_TYPE_R
 750 ``Right joining'': Characters of this joining type have two shapes,
 751 isolated and final.
 752 @end deftypevr
 753
 754 @deftypevr Constant int UC_JOINING_TYPE_D
 755 ``Dual joining'': Characters of this joining type have four shapes,
 756 initial, medial, final, and isolated.
 757 @end deftypevr
 758
 759 The following functions implement the association between a joining type
 760 and its name.
 761
 762 @deftypefun {const char *} uc_joining_type_name (int @var{joining_type})
 763 Returns the name of a joining type.
 764 @end deftypefun
 765
 766 @deftypefun {const char *} uc_joining_type_long_name (int @var{joining_type})
 767 Returns the long name of a joining type.
 768 @end deftypefun
 769
 770 @deftypefun int uc_joining_type_byname (const char *@var{joining_type_name})
 771 Returns the joining type given by name, e.g@. @code{"D"}, or by long name,
 772 e.g@. @code{"Dual Joining}.
 773 This lookup ignores spaces, underscores, or hyphens as word separators and is
 774 case-insignificant.
 775 @end deftypefun
 776
 777 The following function gives the joining type of every Unicode character.
 778
 779 @deftypefun int uc_joining_type (ucs4_t @var{uc})
 780 Returns the joining type of a Unicode character.
 781 @end deftypefun
 782
 783 @node Joining group
 784 @subsection Joining group of Arabic characters
 785
 786 @cindex joining group
 787 The joining group of a character describes how the character's shape
 788 is modified in the four contexts of dual-joining characters or in the
 789 two contexts of right-joining characters.
 790
 791 The joining group has the following possible values:
 792
 793 @deftypevr Constant int UC_JOINING_GROUP_NONE
 794 @deftypevrx Constant int UC_JOINING_GROUP_AIN
 795 @deftypevrx Constant int UC_JOINING_GROUP_ALAPH
 796 @deftypevrx Constant int UC_JOINING_GROUP_ALEF
 797 @deftypevrx Constant int UC_JOINING_GROUP_BEH
 798 @deftypevrx Constant int UC_JOINING_GROUP_BETH
 799 @deftypevrx Constant int UC_JOINING_GROUP_BURUSHASKI_YEH_BARREE
 800 @deftypevrx Constant int UC_JOINING_GROUP_DAL
 801 @deftypevrx Constant int UC_JOINING_GROUP_DALATH_RISH
 802 @deftypevrx Constant int UC_JOINING_GROUP_E
 803 @deftypevrx Constant int UC_JOINING_GROUP_FARSI_YEH
 804 @deftypevrx Constant int UC_JOINING_GROUP_FE
 805 @deftypevrx Constant int UC_JOINING_GROUP_FEH
 806 @deftypevrx Constant int UC_JOINING_GROUP_FINAL_SEMKATH
 807 @deftypevrx Constant int UC_JOINING_GROUP_GAF
 808 @deftypevrx Constant int UC_JOINING_GROUP_GAMAL
 809 @deftypevrx Constant int UC_JOINING_GROUP_HAH
 810 @deftypevrx Constant int UC_JOINING_GROUP_HE
 811 @deftypevrx Constant int UC_JOINING_GROUP_HEH
 812 @deftypevrx Constant int UC_JOINING_GROUP_HEH_GOAL
 813 @deftypevrx Constant int UC_JOINING_GROUP_HETH
 814 @deftypevrx Constant int UC_JOINING_GROUP_KAF
 815 @deftypevrx Constant int UC_JOINING_GROUP_KAPH
 816 @deftypevrx Constant int UC_JOINING_GROUP_KHAPH
 817 @deftypevrx Constant int UC_JOINING_GROUP_KNOTTED_HEH
 818 @deftypevrx Constant int UC_JOINING_GROUP_LAM
 819 @deftypevrx Constant int UC_JOINING_GROUP_LAMADH
 820 @deftypevrx Constant int UC_JOINING_GROUP_MEEM
 821 @deftypevrx Constant int UC_JOINING_GROUP_MIM
 822 @deftypevrx Constant int UC_JOINING_GROUP_NOON
 823 @deftypevrx Constant int UC_JOINING_GROUP_NUN
 824 @deftypevrx Constant int UC_JOINING_GROUP_NYA
 825 @deftypevrx Constant int UC_JOINING_GROUP_PE
 826 @deftypevrx Constant int UC_JOINING_GROUP_QAF
 827 @deftypevrx Constant int UC_JOINING_GROUP_QAPH
 828 @deftypevrx Constant int UC_JOINING_GROUP_REH
 829 @deftypevrx Constant int UC_JOINING_GROUP_REVERSED_PE
 830 @deftypevrx Constant int UC_JOINING_GROUP_SAD
 831 @deftypevrx Constant int UC_JOINING_GROUP_SADHE
 832 @deftypevrx Constant int UC_JOINING_GROUP_SEEN
 833 @deftypevrx Constant int UC_JOINING_GROUP_SEMKATH
 834 @deftypevrx Constant int UC_JOINING_GROUP_SHIN
 835 @deftypevrx Constant int UC_JOINING_GROUP_SWASH_KAF
 836 @deftypevrx Constant int UC_JOINING_GROUP_SYRIAC_WAW
 837 @deftypevrx Constant int UC_JOINING_GROUP_TAH
 838 @deftypevrx Constant int UC_JOINING_GROUP_TAW
 839 @deftypevrx Constant int UC_JOINING_GROUP_TEH_MARBUTA
 840 @deftypevrx Constant int UC_JOINING_GROUP_TEH_MARBUTA_GOAL
 841 @deftypevrx Constant int UC_JOINING_GROUP_TETH
 842 @deftypevrx Constant int UC_JOINING_GROUP_WAW
 843 @deftypevrx Constant int UC_JOINING_GROUP_YEH
 844 @deftypevrx Constant int UC_JOINING_GROUP_YEH_BARREE
 845 @deftypevrx Constant int UC_JOINING_GROUP_YEH_WITH_TAIL
 846 @deftypevrx Constant int UC_JOINING_GROUP_YUDH
 847 @deftypevrx Constant int UC_JOINING_GROUP_YUDH_HE
 848 @deftypevrx Constant int UC_JOINING_GROUP_ZAIN
 849 @deftypevrx Constant int UC_JOINING_GROUP_ZHAIN
 850 @end deftypevr
 851
 852 The following functions implement the association between a joining group
 853 and its name.
 854
 855 @deftypefun {const char *} uc_joining_group_name (int @var{joining_group})
 856 Returns the name of a joining group.
 857 @end deftypefun
 858
 859 @deftypefun int uc_joining_group_byname (const char *@var{joining_group_name})
 860 Returns the joining group given by name, e.g@. @code{"Teh_Marbuta"}.
 861 This lookup ignores spaces, underscores, or hyphens as word separators and is
 862 case-insignificant.
 863 @end deftypefun
 864
 865 The following function gives the joining group of every Unicode character.
 866
 867 @deftypefun int uc_joining_group (ucs4_t @var{uc})
 868 Returns the joining group of a Unicode character.
 869 @end deftypefun
 870
 871 @node Properties
 872 @section Properties
 873
 874 @cindex properties, of Unicode character
 875 @cindex Unicode character, properties
 876 This section defines boolean properties of Unicode characters.  This
 877 means, a character either has the given property or does not have it.
 878 In other words, the property can be viewed as a subset of the set of
 879 Unicode characters.
 880
 881 The GNU libunistring library provides two kinds of API for working with
 882 properties.  The object oriented API uses a type @code{uc_property_t}
 883 to designate a property.  In the function-based API, which is a bit more
 884 low level, a property is merely a function.
 885
 886 @menu
 887 * Properties as objects::
 888 * Properties as functions::
 889 @end menu
 890
 891 @node Properties as objects
 892 @subsection Properties as objects -- the object oriented API
 893
 894 The following type designates a property on Unicode characters.
 895
 896 @deftp Type uc_property_t
 897 This data type denotes a boolean property on Unicode characters. It is an
 898 immediate type that can be copied by simple assignment, without involving
 899 memory allocation.  It is not an array type.
 900 @end deftp
 901
 902 Many Unicode properties are predefined.
 903
 904 The following are general properties.
 905
 906 @deftypevr Constant uc_property_t UC_PROPERTY_WHITE_SPACE
 907 @deftypevrx Constant uc_property_t UC_PROPERTY_ALPHABETIC
 908 @deftypevrx Constant uc_property_t UC_PROPERTY_OTHER_ALPHABETIC
 909 @deftypevrx Constant uc_property_t UC_PROPERTY_NOT_A_CHARACTER
 910 @deftypevrx Constant uc_property_t UC_PROPERTY_DEFAULT_IGNORABLE_CODE_POINT
 911 @deftypevrx Constant uc_property_t UC_PROPERTY_OTHER_DEFAULT_IGNORABLE_CODE_POINT
 912 @deftypevrx Constant uc_property_t UC_PROPERTY_DEPRECATED
 913 @deftypevrx Constant uc_property_t UC_PROPERTY_LOGICAL_ORDER_EXCEPTION
 914 @deftypevrx Constant uc_property_t UC_PROPERTY_VARIATION_SELECTOR
 915 @deftypevrx Constant uc_property_t UC_PROPERTY_PRIVATE_USE
 916 @deftypevrx Constant uc_property_t UC_PROPERTY_UNASSIGNED_CODE_VALUE
 917 @end deftypevr
 918
 919 The following properties are related to case folding.
 920
 921 @deftypevr Constant uc_property_t UC_PROPERTY_UPPERCASE
 922 @deftypevrx Constant uc_property_t UC_PROPERTY_OTHER_UPPERCASE
 923 @deftypevrx Constant uc_property_t UC_PROPERTY_LOWERCASE
 924 @deftypevrx Constant uc_property_t UC_PROPERTY_OTHER_LOWERCASE
 925 @deftypevrx Constant uc_property_t UC_PROPERTY_TITLECASE
 926 @deftypevrx Constant uc_property_t UC_PROPERTY_CASED
 927 @deftypevrx Constant uc_property_t UC_PROPERTY_CASE_IGNORABLE
 928 @deftypevrx Constant uc_property_t UC_PROPERTY_CHANGES_WHEN_LOWERCASED
 929 @deftypevrx Constant uc_property_t UC_PROPERTY_CHANGES_WHEN_UPPERCASED
 930 @deftypevrx Constant uc_property_t UC_PROPERTY_CHANGES_WHEN_TITLECASED
 931 @deftypevrx Constant uc_property_t UC_PROPERTY_CHANGES_WHEN_CASEFOLDED
 932 @deftypevrx Constant uc_property_t UC_PROPERTY_CHANGES_WHEN_CASEMAPPED
 933 @deftypevrx Constant uc_property_t UC_PROPERTY_SOFT_DOTTED
 934 @end deftypevr
 935
 936 The following properties are related to identifiers.
 937
 938 @deftypevr Constant uc_property_t UC_PROPERTY_ID_START
 939 @deftypevrx Constant uc_property_t UC_PROPERTY_OTHER_ID_START
 940 @deftypevrx Constant uc_property_t UC_PROPERTY_ID_CONTINUE
 941 @deftypevrx Constant uc_property_t UC_PROPERTY_OTHER_ID_CONTINUE
 942 @deftypevrx Constant uc_property_t UC_PROPERTY_XID_START
 943 @deftypevrx Constant uc_property_t UC_PROPERTY_XID_CONTINUE
 944 @deftypevrx Constant uc_property_t UC_PROPERTY_PATTERN_WHITE_SPACE
 945 @deftypevrx Constant uc_property_t UC_PROPERTY_PATTERN_SYNTAX
 946 @end deftypevr
 947
 948 The following properties have an influence on shaping and rendering.
 949
 950 @deftypevr Constant uc_property_t UC_PROPERTY_JOIN_CONTROL
 951 @deftypevrx Constant uc_property_t UC_PROPERTY_GRAPHEME_BASE
 952 @deftypevrx Constant uc_property_t UC_PROPERTY_GRAPHEME_EXTEND
 953 @deftypevrx Constant uc_property_t UC_PROPERTY_OTHER_GRAPHEME_EXTEND
 954 @deftypevrx Constant uc_property_t UC_PROPERTY_GRAPHEME_LINK
 955 @end deftypevr
 956
 957 The following properties relate to bidirectional reordering.
 958
 959 @deftypevr Constant uc_property_t UC_PROPERTY_BIDI_CONTROL
 960 @deftypevrx Constant uc_property_t UC_PROPERTY_BIDI_LEFT_TO_RIGHT
 961 @deftypevrx Constant uc_property_t UC_PROPERTY_BIDI_HEBREW_RIGHT_TO_LEFT
 962 @deftypevrx Constant uc_property_t UC_PROPERTY_BIDI_ARABIC_RIGHT_TO_LEFT
 963 @deftypevrx Constant uc_property_t UC_PROPERTY_BIDI_EUROPEAN_DIGIT
 964 @deftypevrx Constant uc_property_t UC_PROPERTY_BIDI_EUR_NUM_SEPARATOR
 965 @deftypevrx Constant uc_property_t UC_PROPERTY_BIDI_EUR_NUM_TERMINATOR
 966 @deftypevrx Constant uc_property_t UC_PROPERTY_BIDI_ARABIC_DIGIT
 967 @deftypevrx Constant uc_property_t UC_PROPERTY_BIDI_COMMON_SEPARATOR
 968 @deftypevrx Constant uc_property_t UC_PROPERTY_BIDI_BLOCK_SEPARATOR
 969 @deftypevrx Constant uc_property_t UC_PROPERTY_BIDI_SEGMENT_SEPARATOR
 970 @deftypevrx Constant uc_property_t UC_PROPERTY_BIDI_WHITESPACE
 971 @deftypevrx Constant uc_property_t UC_PROPERTY_BIDI_NON_SPACING_MARK
 972 @deftypevrx Constant uc_property_t UC_PROPERTY_BIDI_BOUNDARY_NEUTRAL
 973 @deftypevrx Constant uc_property_t UC_PROPERTY_BIDI_PDF
 974 @deftypevrx Constant uc_property_t UC_PROPERTY_BIDI_EMBEDDING_OR_OVERRIDE
 975 @deftypevrx Constant uc_property_t UC_PROPERTY_BIDI_OTHER_NEUTRAL
 976 @end deftypevr
 977
 978 The following properties deal with number representations.
 979
 980 @deftypevr Constant uc_property_t UC_PROPERTY_HEX_DIGIT
 981 @deftypevrx Constant uc_property_t UC_PROPERTY_ASCII_HEX_DIGIT
 982 @end deftypevr
 983
 984 The following properties deal with CJK.
 985
 986 @deftypevr Constant uc_property_t UC_PROPERTY_IDEOGRAPHIC
 987 @deftypevrx Constant uc_property_t UC_PROPERTY_UNIFIED_IDEOGRAPH
 988 @deftypevrx Constant uc_property_t UC_PROPERTY_RADICAL
 989 @deftypevrx Constant uc_property_t UC_PROPERTY_IDS_BINARY_OPERATOR
 990 @deftypevrx Constant uc_property_t UC_PROPERTY_IDS_TRINARY_OPERATOR
 991 @end deftypevr
 992
 993 Other miscellaneous properties are:
 994
 995 @deftypevr Constant uc_property_t UC_PROPERTY_ZERO_WIDTH
 996 @deftypevrx Constant uc_property_t UC_PROPERTY_SPACE
 997 @deftypevrx Constant uc_property_t UC_PROPERTY_NON_BREAK
 998 @deftypevrx Constant uc_property_t UC_PROPERTY_ISO_CONTROL
 999 @deftypevrx Constant uc_property_t UC_PROPERTY_FORMAT_CONTROL
1000 @deftypevrx Constant uc_property_t UC_PROPERTY_DASH
1001 @deftypevrx Constant uc_property_t UC_PROPERTY_HYPHEN
1002 @deftypevrx Constant uc_property_t UC_PROPERTY_PUNCTUATION
1003 @deftypevrx Constant uc_property_t UC_PROPERTY_LINE_SEPARATOR
1004 @deftypevrx Constant uc_property_t UC_PROPERTY_PARAGRAPH_SEPARATOR
1005 @deftypevrx Constant uc_property_t UC_PROPERTY_QUOTATION_MARK
1006 @deftypevrx Constant uc_property_t UC_PROPERTY_SENTENCE_TERMINAL
1007 @deftypevrx Constant uc_property_t UC_PROPERTY_TERMINAL_PUNCTUATION
1008 @deftypevrx Constant uc_property_t UC_PROPERTY_CURRENCY_SYMBOL
1009 @deftypevrx Constant uc_property_t UC_PROPERTY_MATH
1010 @deftypevrx Constant uc_property_t UC_PROPERTY_OTHER_MATH
1011 @deftypevrx Constant uc_property_t UC_PROPERTY_PAIRED_PUNCTUATION
1012 @deftypevrx Constant uc_property_t UC_PROPERTY_LEFT_OF_PAIR
1013 @deftypevrx Constant uc_property_t UC_PROPERTY_COMBINING
1014 @deftypevrx Constant uc_property_t UC_PROPERTY_COMPOSITE
1015 @deftypevrx Constant uc_property_t UC_PROPERTY_DECIMAL_DIGIT
1016 @deftypevrx Constant uc_property_t UC_PROPERTY_NUMERIC
1017 @deftypevrx Constant uc_property_t UC_PROPERTY_DIACRITIC
1018 @deftypevrx Constant uc_property_t UC_PROPERTY_EXTENDER
1019 @deftypevrx Constant uc_property_t UC_PROPERTY_IGNORABLE_CONTROL
1020 @end deftypevr
1021
1022 The following function looks up a property by its name.
1023
1024 @deftypefun uc_property_t uc_property_byname (const char *@var{property_name})
1025 Returns the property given by name, e.g@. @code{"White space"}.  If a property
1026 with the given name exists, the result will satisfy the
1027 @code{uc_property_is_valid} predicate.  Otherwise the result will not satisfy
1028 this predicate and must not be passed to functions that expect an
1029 @code{uc_property_t} argument.
1030
1031 This lookup ignores spaces, underscores, or hyphens as word separators, is
1032 case-insignificant, and supports the aliases listed in Unicode's
1033 @file{PropertyAliases.txt} file.
1034
1035 This function references a big table of all predefined properties.  Its use
1036 can significantly increase the size of your application.
1037 @end deftypefun
1038
1039 @deftypefun bool uc_property_is_valid (uc_property_t property)
1040 Returns @code{true} when the given property is valid, or @code{false}
1041 otherwise.
1042 @end deftypefun
1043
1044 The following function views a property as a set of Unicode characters.
1045
1046 @deftypefun bool uc_is_property (ucs4_t @var{uc}, uc_property_t @var{property})
1047 Tests whether the Unicode character @var{uc} has the given property.
1048 @end deftypefun
1049
1050 @node Properties as functions
1051 @subsection Properties as functions -- the functional API
1052
1053 The following are general properties.
1054
1055 @deftypefun bool uc_is_property_white_space (ucs4_t @var{uc})
1056 @deftypefunx bool uc_is_property_alphabetic (ucs4_t @var{uc})
1057 @deftypefunx bool uc_is_property_other_alphabetic (ucs4_t @var{uc})
1058 @deftypefunx bool uc_is_property_not_a_character (ucs4_t @var{uc})
1059 @deftypefunx bool uc_is_property_default_ignorable_code_point (ucs4_t @var{uc})
1060 @deftypefunx bool uc_is_property_other_default_ignorable_code_point (ucs4_t @var{uc})
1061 @deftypefunx bool uc_is_property_deprecated (ucs4_t @var{uc})
1062 @deftypefunx bool uc_is_property_logical_order_exception (ucs4_t @var{uc})
1063 @deftypefunx bool uc_is_property_variation_selector (ucs4_t @var{uc})
1064 @deftypefunx bool uc_is_property_private_use (ucs4_t @var{uc})
1065 @deftypefunx bool uc_is_property_unassigned_code_value (ucs4_t @var{uc})
1066 @end deftypefun
1067
1068 The following properties are related to case folding.
1069
1070 @deftypefun bool uc_is_property_uppercase (ucs4_t @var{uc})
1071 @deftypefunx bool uc_is_property_other_uppercase (ucs4_t @var{uc})
1072 @deftypefunx bool uc_is_property_lowercase (ucs4_t @var{uc})
1073 @deftypefunx bool uc_is_property_other_lowercase (ucs4_t @var{uc})
1074 @deftypefunx bool uc_is_property_titlecase (ucs4_t @var{uc})
1075 @deftypefunx bool uc_is_property_cased (ucs4_t @var{uc})
1076 @deftypefunx bool uc_is_property_case_ignorable (ucs4_t @var{uc})
1077 @deftypefunx bool uc_is_property_changes_when_lowercased (ucs4_t @var{uc})
1078 @deftypefunx bool uc_is_property_changes_when_uppercased (ucs4_t @var{uc})
1079 @deftypefunx bool uc_is_property_changes_when_titlecased (ucs4_t @var{uc})
1080 @deftypefunx bool uc_is_property_changes_when_casefolded (ucs4_t @var{uc})
1081 @deftypefunx bool uc_is_property_changes_when_casemapped (ucs4_t @var{uc})
1082 @deftypefunx bool uc_is_property_soft_dotted (ucs4_t @var{uc})
1083 @end deftypefun
1084
1085 The following properties are related to identifiers.
1086
1087 @deftypefun bool uc_is_property_id_start (ucs4_t @var{uc})
1088 @deftypefunx bool uc_is_property_other_id_start (ucs4_t @var{uc})
1089 @deftypefunx bool uc_is_property_id_continue (ucs4_t @var{uc})
1090 @deftypefunx bool uc_is_property_other_id_continue (ucs4_t @var{uc})
1091 @deftypefunx bool uc_is_property_xid_start (ucs4_t @var{uc})
1092 @deftypefunx bool uc_is_property_xid_continue (ucs4_t @var{uc})
1093 @deftypefunx bool uc_is_property_pattern_white_space (ucs4_t @var{uc})
1094 @deftypefunx bool uc_is_property_pattern_syntax (ucs4_t @var{uc})
1095 @end deftypefun
1096
1097 The following properties have an influence on shaping and rendering.
1098
1099 @deftypefun bool uc_is_property_join_control (ucs4_t @var{uc})
1100 @deftypefunx bool uc_is_property_grapheme_base (ucs4_t @var{uc})
1101 @deftypefunx bool uc_is_property_grapheme_extend (ucs4_t @var{uc})
1102 @deftypefunx bool uc_is_property_other_grapheme_extend (ucs4_t @var{uc})
1103 @deftypefunx bool uc_is_property_grapheme_link (ucs4_t @var{uc})
1104 @end deftypefun
1105
1106 The following properties relate to bidirectional reordering.
1107
1108 @deftypefun bool uc_is_property_bidi_control (ucs4_t @var{uc})
1109 @deftypefunx bool uc_is_property_bidi_left_to_right (ucs4_t @var{uc})
1110 @deftypefunx bool uc_is_property_bidi_hebrew_right_to_left (ucs4_t @var{uc})
1111 @deftypefunx bool uc_is_property_bidi_arabic_right_to_left (ucs4_t @var{uc})
1112 @deftypefunx bool uc_is_property_bidi_european_digit (ucs4_t @var{uc})
1113 @deftypefunx bool uc_is_property_bidi_eur_num_separator (ucs4_t @var{uc})
1114 @deftypefunx bool uc_is_property_bidi_eur_num_terminator (ucs4_t @var{uc})
1115 @deftypefunx bool uc_is_property_bidi_arabic_digit (ucs4_t @var{uc})
1116 @deftypefunx bool uc_is_property_bidi_common_separator (ucs4_t @var{uc})
1117 @deftypefunx bool uc_is_property_bidi_block_separator (ucs4_t @var{uc})
1118 @deftypefunx bool uc_is_property_bidi_segment_separator (ucs4_t @var{uc})
1119 @deftypefunx bool uc_is_property_bidi_whitespace (ucs4_t @var{uc})
1120 @deftypefunx bool uc_is_property_bidi_non_spacing_mark (ucs4_t @var{uc})
1121 @deftypefunx bool uc_is_property_bidi_boundary_neutral (ucs4_t @var{uc})
1122 @deftypefunx bool uc_is_property_bidi_pdf (ucs4_t @var{uc})
1123 @deftypefunx bool uc_is_property_bidi_embedding_or_override (ucs4_t @var{uc})
1124 @deftypefunx bool uc_is_property_bidi_other_neutral (ucs4_t @var{uc})
1125 @end deftypefun
1126
1127 The following properties deal with number representations.
1128
1129 @deftypefun bool uc_is_property_hex_digit (ucs4_t @var{uc})
1130 @deftypefunx bool uc_is_property_ascii_hex_digit (ucs4_t @var{uc})
1131 @end deftypefun
1132
1133 The following properties deal with CJK.
1134
1135 @deftypefun bool uc_is_property_ideographic (ucs4_t @var{uc})
1136 @deftypefunx bool uc_is_property_unified_ideograph (ucs4_t @var{uc})
1137 @deftypefunx bool uc_is_property_radical (ucs4_t @var{uc})
1138 @deftypefunx bool uc_is_property_ids_binary_operator (ucs4_t @var{uc})
1139 @deftypefunx bool uc_is_property_ids_trinary_operator (ucs4_t @var{uc})
1140 @end deftypefun
1141
1142 Other miscellaneous properties are:
1143
1144 @deftypefun bool uc_is_property_zero_width (ucs4_t @var{uc})
1145 @deftypefunx bool uc_is_property_space (ucs4_t @var{uc})
1146 @deftypefunx bool uc_is_property_non_break (ucs4_t @var{uc})
1147 @deftypefunx bool uc_is_property_iso_control (ucs4_t @var{uc})
1148 @deftypefunx bool uc_is_property_format_control (ucs4_t @var{uc})
1149 @deftypefunx bool uc_is_property_dash (ucs4_t @var{uc})
1150 @deftypefunx bool uc_is_property_hyphen (ucs4_t @var{uc})
1151 @deftypefunx bool uc_is_property_punctuation (ucs4_t @var{uc})
1152 @deftypefunx bool uc_is_property_line_separator (ucs4_t @var{uc})
1153 @deftypefunx bool uc_is_property_paragraph_separator (ucs4_t @var{uc})
1154 @deftypefunx bool uc_is_property_quotation_mark (ucs4_t @var{uc})
1155 @deftypefunx bool uc_is_property_sentence_terminal (ucs4_t @var{uc})
1156 @deftypefunx bool uc_is_property_terminal_punctuation (ucs4_t @var{uc})
1157 @deftypefunx bool uc_is_property_currency_symbol (ucs4_t @var{uc})
1158 @deftypefunx bool uc_is_property_math (ucs4_t @var{uc})
1159 @deftypefunx bool uc_is_property_other_math (ucs4_t @var{uc})
1160 @deftypefunx bool uc_is_property_paired_punctuation (ucs4_t @var{uc})
1161 @deftypefunx bool uc_is_property_left_of_pair (ucs4_t @var{uc})
1162 @deftypefunx bool uc_is_property_combining (ucs4_t @var{uc})
1163 @deftypefunx bool uc_is_property_composite (ucs4_t @var{uc})
1164 @deftypefunx bool uc_is_property_decimal_digit (ucs4_t @var{uc})
1165 @deftypefunx bool uc_is_property_numeric (ucs4_t @var{uc})
1166 @deftypefunx bool uc_is_property_diacritic (ucs4_t @var{uc})
1167 @deftypefunx bool uc_is_property_extender (ucs4_t @var{uc})
1168 @deftypefunx bool uc_is_property_ignorable_control (ucs4_t @var{uc})
1169 @end deftypefun
1170
1171 @node Scripts
1172 @section Scripts
1173
1174 @cindex scripts
1175 The Unicode characters are subdivided into scripts.
1176
1177 The following type is used to represent a script:
1178
1179 @deftp Type uc_script_t
1180 This data type is a structure type that refers to statically allocated
1181 read-only data.  It contains the following fields:
1182 @smallexample
1183 const char *name;
1184 @end smallexample
1185
1186 The @code{name} field contains the name of the script.
1187 @end deftp
1188
1189 @cindex Unicode character, script
1190 The following functions look up a script.
1191
1192 @deftypefun {const uc_script_t *} uc_script (ucs4_t @var{uc})
1193 Returns the script of a Unicode character.  Returns NULL if @var{uc} does not
1194 belong to any script.
1195 @end deftypefun
1196
1197 @deftypefun {const uc_script_t *} uc_script_byname (const char *@var{script_name})
1198 Returns the script given by its name, e.g@. @code{"HAN"}.  Returns NULL if a
1199 script with the given name does not exist.
1200 @end deftypefun
1201
1202 The following function views a script as a set of Unicode characters.
1203
1204 @deftypefun bool uc_is_script (ucs4_t @var{uc}, const uc_script_t *@var{script})
1205 Tests whether a Unicode character belongs to a given script.
1206 @end deftypefun
1207
1208 The following gives a global picture of all scripts.
1209
1210 @deftypefun void uc_all_scripts (const uc_script_t **@var{scripts}, size_t *@var{count})
1211 Get the list of all scripts.  Stores a pointer to an array of all scripts in
1212 @code{*@var{scripts}} and the length of this array in @code{*@var{count}}.
1213 @end deftypefun
1214
1215 @node Blocks
1216 @section Blocks
1217
1218 @cindex block
1219 The Unicode characters are subdivided into blocks.  A block is an interval of
1220 Unicode code points.
1221
1222 The following type is used to represent a block.
1223
1224 @deftp Type uc_block_t
1225 This data type is a structure type that refers to statically allocated data.
1226 It contains the following fields:
1227 @smallexample
1228 ucs4_t start;
1229 ucs4_t end;
1230 const char *name;
1231 @end smallexample
1232
1233 The @code{start} field is the first Unicode code point in the block.
1234
1235 The @code{end} field is the last Unicode code point in the block.
1236
1237 The @code{name} field is the name of the block.
1238 @end deftp
1239
1240 @cindex Unicode character, block
1241 The following function looks up a block.
1242
1243 @deftypefun {const uc_block_t *} uc_block (ucs4_t @var{uc})
1244 Returns the block a character belongs to.
1245 @end deftypefun
1246
1247 The following function views a block as a set of Unicode characters.
1248
1249 @deftypefun bool uc_is_block (ucs4_t @var{uc}, const uc_block_t *@var{block})
1250 Tests whether a Unicode character belongs to a given block.
1251 @end deftypefun
1252
1253 The following gives a global picture of all block.
1254
1255 @deftypefun void uc_all_blocks (const uc_block_t **@var{blocks}, size_t *@var{count})
1256 Get the list of all blocks.  Stores a pointer to an array of all blocks in
1257 @code{*@var{blocks}} and the length of this array in @code{*@var{count}}.
1258 @end deftypefun
1259
1260 @node ISO C and Java syntax
1261 @section ISO C and Java syntax
1262
1263 @cindex C, programming language
1264 @cindex Java, programming language
1265 @cindex identifiers
1266 The following properties are taken from language standards.  The supported
1267 language standards are ISO C 99 and Java.
1268
1269 @deftypefun bool uc_is_c_whitespace (ucs4_t @var{uc})
1270 Tests whether a Unicode character is considered whitespace in ISO C 99.
1271 @end deftypefun
1272
1273 @deftypefun bool uc_is_java_whitespace (ucs4_t @var{uc})
1274 Tests whether a Unicode character is considered whitespace in Java.
1275 @end deftypefun
1276
1277 The following enumerated values are the possible return values of the functions
1278 @code{uc_c_ident_category} and @code{uc_java_ident_category}.
1279
1280 @deftypevr Constant int UC_IDENTIFIER_START
1281 This return value means that the given character is valid as first or
1282 subsequent character in an identifier.
1283 @end deftypevr
1284
1285 @deftypevr Constant int UC_IDENTIFIER_VALID
1286 This return value means that the given character is valid as subsequent
1287 character only.
1288 @end deftypevr
1289
1290 @deftypevr Constant int UC_IDENTIFIER_INVALID
1291 This return value means that the given character is not valid in an identifier.
1292 @end deftypevr
1293
1294 @deftypevr Constant int UC_IDENTIFIER_IGNORABLE
1295 This return value (only for Java) means that the given character is ignorable.
1296 @end deftypevr
1297
1298 The following function determine whether a given character can be a constituent
1299 of an identifier in the given programming language.
1300
1301 @cindex Unicode character, validity in C identifiers
1302 @deftypefun int uc_c_ident_category (ucs4_t @var{uc})
1303 Returns the categorization of a Unicode character with respect to the ISO C 99
1304 identifier syntax.
1305 @end deftypefun
1306
1307 @cindex Unicode character, validity in Java identifiers
1308 @deftypefun int uc_java_ident_category (ucs4_t @var{uc})
1309 Returns the categorization of a Unicode character with respect to the Java
1310 identifier syntax.
1311 @end deftypefun
1312
1313 @node Classifications like in ISO C
1314 @section Classifications like in ISO C
1315
1316 @cindex C-like API
1317 @cindex Unicode character, classification like in C
1318 The following character classifications mimic those declared in the ISO C
1319 header files @code{<ctype.h>} and @code{<wctype.h>}.  These functions are
1320 deprecated, because this set of functions was designed with ASCII in mind and
1321 cannot reflect the more diverse reality of the Unicode character set.  But
1322 they can be a quick-and-dirty porting aid when migrating from @code{wchar_t}
1323 APIs to Unicode strings.
1324
1325 @deftypefun bool uc_is_alnum (ucs4_t @var{uc})
1326 Tests for any character for which @code{uc_is_alpha} or @code{uc_is_digit} is
1327 true.
1328 @end deftypefun
1329
1330 @deftypefun bool uc_is_alpha (ucs4_t @var{uc})
1331 Tests for any character for which @code{uc_is_upper} or @code{uc_is_lower} is
1332 true, or any character that is one of a locale-specific set of characters for
1333 which none of @code{uc_is_cntrl}, @code{uc_is_digit}, @code{uc_is_punct}, or
1334 @code{uc_is_space} is true.
1335 @end deftypefun
1336
1337 @deftypefun bool uc_is_cntrl (ucs4_t @var{uc})
1338 Tests for any control character.
1339 @end deftypefun
1340
1341 @deftypefun bool uc_is_digit (ucs4_t @var{uc})
1342 Tests for any character that corresponds to a decimal-digit character.
1343 @end deftypefun
1344
1345 @deftypefun bool uc_is_graph (ucs4_t @var{uc})
1346 Tests for any character for which @code{uc_is_print} is true and
1347 @code{uc_is_space} is false.
1348 @end deftypefun
1349
1350 @deftypefun bool uc_is_lower (ucs4_t @var{uc})
1351 Tests for any character that corresponds to a lowercase letter or is one
1352 of a locale-specific set of characters for which none of @code{uc_is_cntrl},
1353 @code{uc_is_digit}, @code{uc_is_punct}, or @code{uc_is_space} is true.
1354 @end deftypefun
1355
1356 @deftypefun bool uc_is_print (ucs4_t @var{uc})
1357 Tests for any printing character.
1358 @end deftypefun
1359
1360 @deftypefun bool uc_is_punct (ucs4_t @var{uc})
1361 Tests for any printing character that is one of a locale-specific set of
1362 characters for which neither @code{uc_is_space} nor @code{uc_is_alnum} is true.
1363 @end deftypefun
1364
1365 @deftypefun bool uc_is_space (ucs4_t @var{uc})
1366 Test for any character that corresponds to a locale-specific set of characters
1367 for which none of @code{uc_is_alnum}, @code{uc_is_graph}, or @code{uc_is_punct}
1368 is true.
1369 @end deftypefun
1370
1371 @deftypefun bool uc_is_upper (ucs4_t @var{uc})
1372 Tests for any character that corresponds to an uppercase letter or is one
1373 of a locale-specific set of characters for which none of @code{uc_is_cntrl},
1374 @code{uc_is_digit}, @code{uc_is_punct}, or @code{uc_is_space} is true.
1375 @end deftypefun
1376
1377 @deftypefun bool uc_is_xdigit (ucs4_t @var{uc})
1378 Tests for any character that corresponds to a hexadecimal-digit character.
1379 @end deftypefun
1380
1381 @deftypefun bool uc_is_blank (ucs4_t @var{uc})
1382 Tests for any character that corresponds to a standard blank character or
1383 a locale-specific set of characters for which @code{uc_is_alnum} is false.
1384 @end deftypefun