# ICU4Lua

## Contents

- icu
  The root ICU module. This is currently quite sparse, most functionality is in the submodules.
- icu.ustring
  Utility functions for encoding, decoding and manipulating ustrings, a Unicode-friendly alternative string data type to regular Lua strings. Provides a full equivalent set of functions to Lua's standard string table.
- icu.utf8
  Utility functions for dealing with UTF-8 encoded text in standard Lua strings. Provides a full equivalent set of functions to Lua's standard string table.
- icu.collator
  for some of ICU's locale-sensitive collation facilities.
- icu.regex
  Lua wrapper for ICU's regular expressions library.
- icu.stringprep
  ICU's implementation of the StringPrep algorithm.
- icu.idna
  ICU's utilities for dealing with International Domain Names for Applications.
- icu.ufile
  Read and write ustrings to/from files in arbitrary text encoding.
- icu.normalizer
  Utilities for Unicode normalization.

### icu._VERSION

The ICU version number, as a string.

### icu.defaultencoding ()

Returns the name of the default text encoding of the process/application.

### icu.convert (text, current_encoding, new_encoding)

Convert a Lua string, text, from one encoding (current_encoding) to another (new_encoding).

If either of the encoding parameters are passed as `nil`, the default encoding is used for that end of the conversion.

## icu.ustring

"Ustrings" are an alternative type of text string data to standard Lua strings. Internally, a ustring is an array of ICU UChars, stored in a "userdata" structure. The `icu.ustring` submodule provides ways to convert ustrings to and from standard Lua strings, and to do the same things on a ustring that you can on a Lua string.

Since ustrings and Lua strings are fundamentally different types, if you try to compare a ustring to a Lua string using the `==` equality operator, the result will always be `false`, and if you try to compare them using the less-than/greater-than operators, Lua will throw an error. Ustrings can only be compared to other ustrings.

Using `icu.ustring(...)` as a function is the same as calling `icu.ustring.decode(...)`. A recommended convention for this is:

    local U = require 'icu.ustring'

    local ustr = U"Hello World!"

This is the full list of functions provided by `icu.ustring`. They can also be called as methods on a ustring instance. Functions in bold are intended to be directly equivalent to a function in the standard `string` library.

- icu.ustring.decode
- icu.ustring.encode
- icu.ustring.lessthan
- icu.ustring.lessorequal
- icu.ustring.unescape
- icu.ustring.isustring
- icu.ustring.codepoint
- icu.ustring.char
- icu.ustring.len
- icu.ustring.rep
- icu.ustring.sub
- icu.ustring.reverse
- icu.ustring.lower
- icu.ustring.upper
- icu.ustring.match
- icu.ustring.find
- icu.ustring.gmatch
- icu.ustring.gsub
- icu.ustring.format
- icu.ustring.empty

### icu.ustring.decode (str[, encoding])

Create a new ustring containing the text encoded in Lua string s, using the encoding specified by encoding (as a Lua string, for example `'windows-1252'`) or UTF-8 by default.

### icu.ustring.encode (ustr[, encoding])

Encode the text in the given ustring ustr into a Lua string, using the encoding specified by encoding or UTF-8 by default.

Note: Calling the standard Lua function `tostring` on a ustring will internally call `encode` with no encoding specified, so the result will be UTF-8 encoded. Also, `print` uses `tostring` internally, so printing a ustring will write it UTF-8 encoded to the output.

### icu.ustring.lessthan (a, b)

Returns `true` if ustring `a` is less than `b` in a codepoint-wise comparison, `false` otherwise.

You can also use `a < b` instead.

### icu.ustring.lessorequal (a, b)

Returns `true` if ustring `a` is less than or equal to `b` in a codepoint-wise comparison, `false` otherwise.

You can also use `a <= b` instead.

### icu.ustring.unescape (str)

Similar to `icu.ustring.decode`, except that `unescape` does its own run-time backslash-escaping, and supports escapes that Lua normally doesn't such as `\x3F` and `\u0030` for specifying characters using a hexadecimal value. The rest of the text is expected to be encoded by the default codepage.

### icu.ustring.isustring (v)

Returns `true` if the given value `v` is a ustring, `false` otherwise. (This function is necessary as the Lua function `type(v)` will always return `'userdata'` for a ustring.)

### icu.ustring.codepoint (ustr[, i[, j]])

The ustring equivalent to `string.byte` (renamed to be more correct).

### icu.ustring.char (...)

The ustring equivalent to `string.char`.

### icu.ustring.len (ustr)

The ustring equivalent to `string.len`. Using the length operator `#` on a ustring will also work.

### icu.ustring.rep (ustr, n)

The ustring equivalent to `string.rep`.

### icu.ustring.sub (ustr, i[, j])

The ustring equivalent to `string.sub`.

### icu.ustring.reverse (ustr)

The ustring equivalent to `string.reverse`.

### icu.ustring.lower (ustr)

The ustring equivalent to `string.lower`.

### icu.ustring.upper (ustr)

The ustring equivalent to `string.upper`.

### icu.ustring.match (ustr, patt[, start_index])

The ustring equivalent to `string.match`.

The character classes used when matching are, by default, still only the ASCII set. For example, `%a` is still only equivalent to `[A-Za-z]`. To use the full Unicode-set character classes, there is a new syntax specific to ICU4Lua. Add an exclamation mark `!` after `%`, in this example `%!a` to match the set of all "letter" characters defined in Unicode.

### icu.ustring.find (ustr, patt[, start_index])

The ustring equivalent to `string.find`, with the difference to character classes described in the documentation for `icu.ustring.match`.

### icu.ustring.gmatch (ustr, patt)

The ustring equivalent to `string.gmatch`, with the difference to character classes described in the documentation for `icu.ustring.match`.

### icu.ustring.gsub (ustr, patt, replacement[, n])

The ustring equivalent to `string.gsub`, with the difference to character classes described in the documentation for `icu.ustring.match`.

### icu.ustring.format (ustr, ...)

The ustring equivalent to `string.format`.

### icu.ustring.empty

A constant value holding the zero-length ustring.

## icu.utf8

If switching to using ustrings seems like a radical change and you'd rather stay in the domain of standard Lua strings, you might find the `icu.utf8` submodule useful. It is like a copy of all of the functions in `icu.ustring` where every Lua string input parameter is decoded as UTF-8 into a ustring, and every ustring return value is encoded into a UTF-8 Lua string.

As in `icu.ustring`, functions in bold are intended to be directly equivalent to a function in the standard `string` library.

- icu.utf8.unescape
- icu.utf8.lessthan
- icu.utf8.lessorequal
- icu.utf8.codepoint
- icu.utf8.char
- icu.utf8.len
- icu.utf8.rep
- icu.utf8.sub
- icu.utf8.reverse
- icu.utf8.upper
- icu.utf8.lower
- icu.utf8.match
- icu.utf8.find
- icu.utf8.gmatch
- icu.utf8.gsub
- icu.utf8.format
- icu.utf8.bom

### icu.utf8.unescape (str)

Create a UTF-8 string using run-time backslash-escaping. This includes support for escapes that Lua normally doesn't allow, such as `\x3F` and `\u0030` for specifying characters using a hexadecimal value. The rest of the text is expected to be encoded by the default codepage.

### icu.utf8.lessthan (a, b)

Returns `true` if UTF-8 encoded Lua string a is less than b in a codepoint-wise comparison, `false` otherwise.

You can use this function as the second parameter of the standard Lua function `table.sort` to sort an array of UTF-8 encoded strings.

(There's no equivalent function for `a >= b` - use `not icu.utf8.lessthan(a,b)` instead.)

### icu.utf8.lessorequal (a, b)

Returns `true` if UTF-8 string `a` is less than or equal to `b` in a codepoint-wise comparison, `false` otherwise.

(There's no equivalent function for `a > b` - use `not icu.utf8.lessorequal(a,b)` instead.)

### icu.utf8.codepoint (s[, i[, j]])

The UTF-8 equivalent to `string.byte` (renamed to be more correct).

### icu.utf8.char (...)

The UTF-8 equivalent to `string.char`.

### icu.utf8.len (s)

The UTF-8 equivalent to `string.len`. Using the length operator `#` on a utf8 will also work.

### icu.utf8.rep (s, n)

The UTF-8 equivalent to `string.rep`.

### icu.utf8.sub (s, i[, j])

The UTF-8 equivalent to `string.sub`.

### icu.utf8.reverse (s)

The UTF-8 equivalent to `string.reverse`.

### icu.utf8.lower (s)

The UTF-8 equivalent to `string.lower`.

### icu.utf8.upper (s)

The UTF-8 equivalent to `string.upper`.

### icu.utf8.match (ustr, patt[, start_index])

The UTF-8 equivalent to `string.match`, with the difference to character classes described in the documentation for `icu.ustring.match`.

### icu.utf8.find (ustr, patt[, start_index])

The UTF-8 equivalent to `string.find`, with the difference to character classes described in the documentation for `icu.ustring.match`.

### icu.utf8.gmatch (ustr, patt)

The UTF-8 equivalent to `string.gmatch`, with the difference to character classes described in the documentation for `icu.ustring.match`.

### icu.utf8.gsub (ustr, patt, replacement[, n])

The UTF-8 equivalent to `string.gsub`, with the difference to character classes described in the documentation for `icu.ustring.match`.

### icu.utf8.format (ustr, ...)

The UTF-8 equivalent to `string.format`.

### icu.utf8.bom

A string containing the (so-called) UTF-8 byte order mark.

## icu.collator

- icu.collator.open
- icu.collator.strength
- icu.collator.equals
- icu.collator.lessthan
- icu.collator.lessorequal

### icu.collator.open (locale)

Open a collator for the given locale, which must be given as a Lua string, not a ustring. If the collator could not be opened, returns `nil` and an error message.

Note: You can also call `icu.collator(...)` instead of `icu.collator.open(...)`

### icu.collator.strength (col[, new_value])

Either sets the strength of the collator, or returns the current strength setting if no new value is given. (If a new value is set, the collator itself is returned.)

Valid strength values are:

- `icu.collator.PRIMARY`
- `icu.collator.SECONDARY`
- `icu.collator.TERTIARY`
- `icu.collator.QUATERNARY`
- `icu.collator.IDENTICAL`
- `icu.collator.DEFAULT_STRENGTH`

### icu.collator.equals (col, a, b)

Returns `true` if ustring a is equal to ustring b according to the collator col, `false` otherwise.

### icu.collator.lessthan (col, a, b)

Returns `true` if ustring a is less than ustring b according to the collator col, `false` otherwise.

### icu.collator.lessorequal (col, a, b)

Returns `true` if ustring a is less than or equal to ustring b according to the collator col, `false` otherwise.

## icu.regex

For details on the pattern syntax supported by ICU's regular expressions engine, see the ICU User Guide page at http://userguide.icu-project.org/strings/regexp/.

There are two "levels" of functions available in `icu.regex`:

1. A high-level set of "full" operations that people who have used regular expressions are likely to be familiar with - find the first match if any (`match`), iterate through all matches (`gmatch`), replace all matches (`replace`) and split on each match (`split`).

   For these functions, the regex object represents only a compiled pattern.

2. A low-level set of "atomic" operations. When using these functions, the regex object does not only represent a compiled pattern - it also encapsulates the state of the matching engine:

   - The target text that the pattern is currently being matched against (`text`).
   - The details of the most recent match (`groupcount`, `value`, `range`).

   The low-level matching operations themselves (`matches`, `lookingat`, `find`) only test for a single match at a time, and only return `true` or `false` to say whether they succeeded.

   These functions are marked as bold in the function list below:

- icu.regex.compile
- icu.regex.match
- icu.regex.gmatch
- icu.regex.replace
- icu.regex.split
- icu.regex.escape
- icu.regex.decompile
- icu.regex.text
- icu.regex.bounds
- icu.regex.transparentbounds
- icu.regex.anchoringbounds
- icu.regex.matches
- icu.regex.lookingat
- icu.regex.find
- icu.regex.groupcount
- icu.regex.value
- icu.regex.range
- icu.regex.reset
- icu.regex.clone

### icu.regex.compile (pattern[, flags])

Creates a new compiled regex pattern object. pattern can be a ustring or a Lua string. If a Lua string, it is expected to be encoded in the default codepage.

flags can be one of two things:

1. A Lua string containing one or more of the following letters:
   - '`i`' - Case-insensitive matching.
   - '`x`' - Comments mode. Whitespace and comments (the rest of the line after `#` and the character itself) are ignored.
   - '`s`' - With this flag enabled the `.` character will successfully match on a new-line. By default, it will not.
   - '`m`' - Multiline mode. The anchors `^` and `$` will match at the beginning and end of each line, rather than just the beginning and end of the entire target text.
   - '`w`' - Affects the behaviour of `\b` by redefining word boundaries according to the definitions of word in Unicode UAX 29.
2. A combination of the following constant values. Combine them with the `+` operator.
   - `icu.regex.CASE_INSENSITIVE` - Case-insensitive matching.
   - `icu.regex.COMMENTS` - Comments mode. Whitespace and comments (the rest of the line after `#` and the character itself) are ignored.
   - `icu.regex.DOTALL` - With this flag enabled the `.` character will successfully match on a new-line. By default, it will not.
   - `icu.regex.LITERAL` - Treat all special characters in the pattern as if they had no special meaning. (At the time of writing, this flag seems to be failing in ICU 4.2. As an alternative, you can use icu.regex.escape on the pattern before passing it.)
   - `icu.regex.MULTILINE` - Multiline mode. The anchors `^` and `$` will match at the beginning and end of each line, rather than just the beginning and end of the entire target text.
   - `icu.regex.UNIX_LINES` - Multiline mode. The anchors `^` and `$` will match at the beginning and end of each line, rather than just the beginning and end of the entire target text.
   - `icu.regex.UWORD` - Affects the behaviour of `\b` by redefining word boundaries according to the definitions of word in Unicode UAX 29.

Note: You can also call icu.regex(...) as an alternative to icu.regex.compile(...)

### icu.regex.match (regex, text[, start_index])

Find the first match, or `false` if there is no match to be found, optionally starting the search at the given start_index (one-based).

For a successful result the returned value is a match object that contains these named fields:

- `value`: The matching substring, as a ustring
- `start`, `stop`: Substring indices in the target text (one-based, inclusive)

The match object will also have an array component 1 to n, where n is the number of captures in the pattern. These entries will each be either the boolean value `false` (if the capture is an optional one and was not used) or an object with the same named fields as the parent match object as described above. The 0th element of the match object will always be the match object itself.

### icu.regex.gmatch (regex, text)

Returns an iterator over all of the matches found for a compiled regular expression, designed to be used in a `for` loop, e.g.:

    for match in icu.regex.gmatch(myRegex, inputText) do
        -- the "match" object is the same as described in the documentation for icu.regex.match
    end

### icu.regex.replace (regex, text, replacement)

Find all places where the given regular expression matches in text, replace them with a new value, and return the result.

text must be a ustring, and replacement must be one of the following:

- A ustring. You can use `$0`, `$1`, `$2` etc. to use captured substrings from the match. A `$` followed by any other character will be replaced with that second character - use `$$` to include a literal dollar sign.
- A table. It will be indexed with the entire matching substring (as a ustring), and the value found must be either a new ustring or `nil`/`false`, in which case the original value will be retained.
- A function. It will be called with a single parameter - a match object as described in the documentation for icu.regex.match(). It must return either a new ustring to replace the match with or `nil`/`false` to keep the original value.

### icu.regex.split (regex, text[, maximum])

Returns an array of the substrings found by splitting ustring text using the given regex, with an optional maximum number of splits.

### icu.regex.isregex (v)

Returns `true` if the value v is a regex object, `false` otherwise.

### icu.regex.escape (s)

Returns a copy of s (which must be either a ustring or a Lua string) with all "special" regex characters (like `.`, `^`, `$` etc.) prepended with a backslash.

### icu.regex.decompile (regex)

Returns two values - the original pattern of the regex as a ustring, and the flags that it was compiled with, as a number.

### icu.regex.clone (regex)

Create a clone of regex. It only clones the compiled pattern, and not any stateful matching information like the target text. It is like a faster, more efficient alternative to `icu.regex.compile(icu.regex.decompile(regex))`.

### icu.regex.text (regex[, new_value])

Get or set the target text. If a new_value is passed (which must be a ustring) it is set, and the function returns the regex object. If there is no new_value passed, the current text is returned (which might be `nil` if it was never set).

### icu.regex.bounds (regex[, new_start, new_stop])

Get or set the region bounds on the target text. This is a pair of indices that describe where matching should start and stop in an atomic matching operation (unless they are overridden by supplying a start index).

The target text must have been specified using icu.regex.text before calling this function. If new_start and new_stop are specified, they are set as the new region. If not, the current bounds are returned. The indices are one-based and inclusive.

### icu.regex.transparentbounds (regex[, enable])

Get or set whether to use transparent bounds. If enable is specified (it must be a boolean value), this is used to set the property, and the regex object is returned. If not, the current setting is returned as a boolean value.

Transparent bounds alter the behaviour of "lookahead" and "lookbehind" captures when the region bounds have been set (see icu.regex.bounds). If the bounds are "transparent", this means that these captures can "look" past the bounds.

By default, transparent bounds are disabled.

### icu.regex.anchoringbounds (regex[, enable])

Get or set whether to use anchoring bounds. If enable is specified (it must be a boolean value), this is used to set the property, and the regex object is returned. If not, the current setting is returned as a boolean value.

Anchoring bounds alter the behaviour of the `^` and `$` anchors. If enabled, the anchors will match at the start and end of the region bounds, wherever they are in the target text. If disabled, they will only match at the start and end of the entire text (or each line, if the relevant flag has been set).

By default, anchoring bounds are enabled.

### icu.regex.matches (regex[, start_index])

Atomic match operation that attempts to match the entire matchable region of the target text (which must have been previously set using icu.regex.text) against the whole regex pattern from beginning to end (regardless of anchors in the pattern).

This function will only return `true` or `false` to indicate whether the match was successful. Use icu.regex.groupcount, icu.regex.value and icu.regex.range to extract information about the "current" successful match.

If start_index is specified then the matchable region is from this index (one-based) to the end of the whole text, otherwise the matching region will be the one specified by icu.regex.bounds (by default the entire text).

### icu.regex.lookingat (regex[, start_index])

Atomic match operation that attempts to match from the first character of the entire matchable region of the target text (which must have been previously set using icu.regex.text) against the whole regex pattern from beginning to end.

This function will only return `true` or `false` to indicate whether the match was successful. Use icu.regex.groupcount, icu.regex.value and icu.regex.range to extract information about the "current" successful match.

If start_index is specified then the matchable region is from this index (one-based) to the end of the whole text, otherwise the matching region will be the one specified by icu.regex.bounds (by default the entire text).

### icu.regex.find (regex[, start_index])

If `find` has already been called at least once on this regex and successfully found a match, the next time it is called it will start from after the previous match. Attempts to match from the first character of the entire matchable region of the target text (which must have been previously set using icu.regex.text) against the whole regex pattern from beginning to end.

This function will only return `true` or `false` to indicate whether the match was successful. Use icu.regex.groupcount, icu.regex.value and icu.regex.range to extract information about the "current" successful match.

If start_index is specified then the matchable region is from this index (one-based) to the end of the whole text, otherwise the matching region will be the one specified by icu.regex.bounds (by default the entire text).

## icu.stringprep

- icu.stringprep.open
- icu.stringprep.openbytype
- icu.stringprep.prepare

### icu.stringprep.open (path, filename)

Open a StringPrep profile from a data file. path and filename must be Lua strings. Returns the loaded profile object, or `nil` and an error message on failure.

### icu.stringprep.openbytype (type)

Open a StringPrep profile from a predefined profile type. type can be one of:

- `icu.stringprep.RFC3491_NAMEPREP`
- `icu.stringprep.RFC3530_NFS4_CS_PREP`
- `icu.stringprep.RFC3530_NFS4_CS_PREP_CI`
- `icu.stringprep.RFC3530_NFS4_CIS_PREP`
- `icu.stringprep.NFS4_MIXED_PREP_PREFIX`
- `icu.stringprep.RFC3530_NFS4_MIXED_PREP_SUFFIX`
- `icu.stringprep.RFC3722_ISCSI`
- `icu.stringprep.RFC3920_NODEPREP`
- `icu.stringprep.RFC3920_RESOURCEPREP`
- `icu.stringprep.RFC4011_MIB`
- `icu.stringprep.RFC4013_SASLPREP`
- `icu.stringprep.RFC4505_TRACE`
- `icu.stringprep.RFC4518_LDAP`
- `icu.stringprep.RFC4518_LDAP_CI`

### icu.stringprep.prepare (profile, ustr)

Prepare the given ustring ustr against the StringPrep profile, profile. Returns a new ustring, or `nil` and an error message on failure.

## icu.idna

- icu.idna.toascii
- icu.idna.tounicode
- icu.idna.idntoascii
- icu.idna.idntounicode
- icu.idna.equals
- icu.idna.lessthan
- icu.idna.lessorequal

### icu.idna.toascii (label[, options])

Implementation of the ToASCII operation as defined in RFC 3490. label is a ustring that holds a single label (e.g. "www", "lua" or "org") rather than a full domain name. Returns either a new ustring or `nil` and an error.

options, if specified, should be some combination of these flags:

- `icu.idna.ALLOW_UNASSIGNED`
  Do not return with an error if an unassigned codepoint is found.
- `icu.idna.USE_STD3_RULES`
  Return with an error if the input breaks STD3 restrictions.

Combine them with the `+` operator. The default is neither - i.e. return with an error on unassigned codepoints, and do not check for STD3 violations.

### icu.idna.tounicode (label[, options])

Implementation of the ToUnicode operation as defined in RFC 3490. label is a ustring that holds a single label (e.g. "www", "lua" or "org") rather than a full domain name.

See icu.idna.toascii for details on the flags for options.

### icu.idna.idntoascii (domain_name[, options])

Convenience function. An equivalent to icu.idna.toascii that operates on a full domain_name (e.g. "www.lua.org") instead of individual labels.

See icu.idna.toascii for details on the flags for options.

### icu.idna.idntounicode (domain_name[, options])

Convenience function. An equivalent to icu.idna.tounicode that operates on a full domain_name (e.g. "www.lua.org") instead of individual labels.

See icu.idna.toascii for details on the flags for options.

### icu.idna.equals (a, b)

Return `true` if ustrings a and b are equivalent as IDN strings, `false` otherwise.

### icu.idna.lessthan (a, b)

Return `true` if ustring a is less than ustring b as IDN strings, `false` otherwise.

### icu.idna.lessorequal (a, b)

Return `true` if ustring a is less than or equal to ustring b as IDN strings, `false` otherwise.

## icu.ufile

- icu.ufile.open
- icu.ufile.encoding
- icu.ufile.locale
- icu.ufile.read
- icu.ufile.write
- icu.ufile.lines
- icu.ufile.rewind
- icu.ufile.flush
- icu.ufile.close

### icu.ufile.open (filepath, mode[, encoding[, locale]])

Open a file for reading/writing according to the `mode` parameter, which has the same meaning as the `mode` parameter of `io.open()` except that the "`b`" binary mode qualifier has no meaning and should not be used. The encoding and locale to use will be the current defaults if not supplied as parameters.

Returns a new ufile object. (The rest of the `icu.ufile` functions can also be called as methods on this object.)

### icu.ufile.encoding (ufile[, new_encoding])

Set the encoding to use if `new_encoding` is specified, otherwise return the current encoding.

### icu.ufile.locale (ufile[, new_locale])

Set the locale to use if `new_locale` is specified, otherwise return the current locale.

### icu.ufile.read (ufile, ...)

The equivalent to `file:read(...)` on a standard Lua file, with the same options available:

- (number) - read a ustring of the given number of characters
- `'*l'` - read up to the next new-line character or end of the file (the default if no additional parameters are specified)
- `'*n'` - read a number from the file
- `'*a'` - read the whole file

### icu.ufile.write (ufile, ...)

The equivalent to `file:write(...)` on a standard Lua file, except that the values to write must all be ustrings.

### icu.ufile.lines (ufile)

Create a for-loop iterator over lines of text from the given ufile, equivalent to `file:lines()`.

### icu.ufile.rewind (ufile)

Unlike standard Lua files which allow full seeking operations, ufiles can only have the cursor position returned to the beginning of the file by calling this function.

### icu.ufile.flush (ufile)

Save any written data to the `ufile`.

### icu.ufile.close (ufile)

Close the ufile. This will also occur automatically if the ufile object is garbage collected.

### icu.normalizer

- icu.normalizer.normalize
- icu.normalizer.quickcheck
- icu.normalizer.isnormalized
- icu.normalizer.concat
- icu.normalizer.equals
- icu.normalizer.lessthan
- icu.normalizer.lessorequal

### icu.normalizer.normalize (ustr[, mode])

Return a normalized version of ustring ustr. If specified, mode must be one of the following values, passed as a Lua string:

- `'nfc'` (Canonical decomposition followed by canonical composition - the default if no mode is specified)
- `'nfd'` (Canonical decomposition)
- `'nfkc'` (Compatibility decomposition followed by canonical composition)
- `'nfkd'` (Compatibility decomposition)
- `'fcd'` ("Fast C or D" form)
- `'none'` (No decomposition or composition)

### icu.normalizer.quickcheck (ustr[, mode])

Attempt to perform a quick check to determine whether ustring ustr is already normalized in the given mode (or the same default as `icu.normalizer.normalize`). This function will not return a boolean as it has three possible states to return, which are the Lua strings `'yes'`, `'no'` and `'maybe'` (when it cannot be determined by a quick check).

### icu.normalizer.isnormalized (ustr[, mode])

Perform a full normalization check on ustr, and return a definite `true` or `false`.

### icu.normalizer.concat (ustr_1, ustr_2[, mode])

Where you have two ustrings that are already known to be normalized, and you want to concatenate them, the result may not be normalized. Re-normalizing the entire new string can be inefficient, especially compared to using this function which will normalize only where the two strings join.

### icu.normalizer.equals (ustr_1, ustr_2)

### icu.normalizer.lessthan (ustr_1, ustr_2)

### icu.normalizer.lessorequal (ustr_1, ustr_2)

When you want to compare two ustrings which have not been normalized but you want to compare them as if they had been, these functions can be a more efficient way than normalizing and then comparing them.