Generated from the public headers, which are the source of truth: 87 functions across 11 headers.
base.hbidi.hcase.hencoding.hharfbuzz.hidentifier.hnormalize.hproperties.hscript.hsecurity.hsegment.hbase.hThe base of the Maul Unicode API: the library and Unicode versions, the export and attribute macros, and the result codes every fallible function returns.
muniVersion muniGetVersion(void);
Returns the version of the library that was linked, which may differ from the MUNI_VERSION macros a program was compiled with.
Returns: The library version.
Thread safety. Safe from any thread.
muniVersion muniGetUnicodeVersion(void);
Returns the Unicode version every table in the library comes from.
Returns: The Unicode version, 18.0.0 for this release.
Thread safety. Safe from any thread.
uint32_t muniGetResultsVersion(void);
Returns the results version of the library that was linked: it moves up with every change to what muniNormalize, muniGetNfkcCasefold, muniConvertCase or muniGetSkeleton give for some text, or to the verdict of muniCheckIdentifier, muniGetRestrictionLevel, muniCheckMixedNumbers or muniGetResolvedScripts, in any release, and stays the same otherwise: their status and offset, and their output on success, but not the bytes and counts a refusal leaves. A program that stores their results stores it beside them and recomputes them when it changes.
Returns: The results version, MUNI_RESULTS_VERSION of the library.
Thread safety. Safe from any thread.
const char* muniGetResultName(muniResult result);
Returns the name of a result code, for diagnostics.
Parameters:
result: Any value; an unknown one is named as such.Returns: A static, NUL-terminated string such as "muni_errorCapacity".
Thread safety. Safe from any thread.
bidi.hThe Unicode Bidirectional Algorithm (UAX #9): the display order of text that mixes left-to-right scripts, such as Latin, with right-to-left ones, such as Arabic and Hebrew. muniResolveBidi takes a paragraph of UTF-8 and gives every byte an embedding level: even levels run left to right, odd ones right to left. A layout engine breaks the paragraph into lines, and for each line muniReorderBidiLine gives the runs of equal level in the order they appear on screen, left to right. Glyphs of an odd run are laid out right to left, and characters with a muniGetMirroringGlyph are drawn mirrored there, as rule L4 asks. Nothing allocates: the caller gives one level byte and one workspace byte per byte of text, and the fixed stacks of the algorithm (125 embedding levels, 63 open brackets) live on the call stack.
MUNI_NODISCARD MUNI_API muniResult muniResolveBidi(const char* text, size_t length, muniBidiDirection direction, uint8_t* levelsOut, uint8_t* workspace, size_t* paragraphLengthOut, uint8_t* paragraphLevelOut);
Resolves the embedding levels of the first paragraph of a UTF-8 text (rules P1 to I2). The paragraph ends after the first paragraph separator, such as LF, CR LF or U+2029, or at the end of the text; call again on the rest for the next paragraph. Code points that rule X9 removes, such as U+202A to U+202E, take the level before them.
Parameters:
text: The text. May be NULL when length is 0.length: The number of bytes.direction: The paragraph direction, or muni_bidiAuto.levelsOut: Receives one level per byte of the paragraph; holds length bytes. May be NULL when length is 0.workspace: Scratch memory of length bytes. May be NULL when length is 0.paragraphLengthOut: Receives the paragraph's length in bytes.paragraphLevelOut: Receives the paragraph embedding level, 0 or 1. On an error, levelsOut and both outputs are left as they were.Returns: muni_success, or muni_errorInvalid for a NULL paragraphLengthOut or paragraphLevelOut, a NULL text, levelsOut or workspace with a nonzero length, or an unknown direction.
Thread safety. Safe from any thread; the levelsOut and workspace are used by one thread at a time.
MUNI_NODISCARD MUNI_API muniResult muniReorderBidiLine(const char* line, const uint8_t* levels, size_t length, uint8_t paragraphLevel, muniBidiRun* runsOut, size_t capacity, size_t* countOut);
Orders one line of a resolved paragraph for display (rules L1 and L2): writes its runs from left to right. Trailing whitespace and isolate formatting characters, and those before a tab or paragraph separator, take the paragraph level first.
Parameters:
line: The line's text within the paragraph. May be NULL when length is 0.levels: The line's levels from muniResolveBidi. May be NULL when length is 0.length: The line's length in bytes.paragraphLevel: The paragraph embedding level, 0 or 1.runsOut: The output. May be NULL when capacity is 0.capacity: The number of runs the output can hold.countOut: Receives the number of runs, on success and when they do not fit. muni_errorInvalid leaves it and runsOut as they were.Returns: muni_success; muni_errorCapacity when the runs do not fit, and then none is written; muni_errorInvalid for a NULL countOut, a NULL line or levels with a nonzero length, NULL runsOut with a nonzero capacity, a level above 126 or a paragraph level above 1.
Thread safety. Safe from any thread.
MUNI_NODISCARD MUNI_API muniResult muniReorderBidiLevels(const uint8_t* levels, size_t count, size_t* visualToLogicalOut);
Computes a visual order from levels (rule L2), for any units the caller orders: code points, clusters or glyphs of one line, each with its level after rule L1. An error leaves visualToLogicalOut as it was.
Parameters:
levels: One level per unit, in logical order. May be NULL when count is 0.count: The number of units.visualToLogicalOut: Receives, for each position from left to right, the logical index of its unit. May be NULL when count is 0.Returns: muni_success, or muni_errorInvalid for a NULL argument with a nonzero count or a level above 126, the highest rule L1 leaves.
Thread safety. Safe from any thread.
MUNI_NODISCARD MUNI_API muniResult muniInvertBidiMap(const size_t* map, size_t count, size_t* inverseOut);
Inverts a visual-to-logical map into a logical-to-visual one, or the other way round.
Parameters:
map: A permutation of 0 to count - 1. May be NULL when count is 0.count: The number of entries.inverseOut: Receives the inverse permutation. May be NULL when count is 0. A NULL argument or an inverseOut that overlaps map leaves it as it was. Any other refusal clears inverseOut, which the call uses to check the map: telling a permutation from a map that repeats an entry, in linear time and without memory, takes it as scratch.Returns: muni_success, or muni_errorInvalid for a NULL argument with a nonzero count, an inverseOut that overlaps map, an entry out of range or an entry that repeats an earlier one.
Thread safety. Safe from any thread.
case.hCase mapping and case folding (Unicode chapter 3.13): lowercase, uppercase and titlecase, and folding for comparing text without regard to case. Per code point, the simple mappings give one code point for one. Over text, the full mappings may change the length ("ß" uppercases to "SS"), a final sigma lowercases to "ς", and titlecasing starts each word (UAX #29) with a capital. Turkish and Azerbaijani, which pair a dotted and a dotless i, take muni_caseTurkic; Lithuanian, which keeps the dot of an i under other accents, takes muni_caseLithuanian; Greek, whose capitals drop their accents, takes muni_caseGreek; Armenian, whose ligature "և" uppercases to "ԵՎ", takes muni_caseArmenian.
uint32_t muniGetLowercase(uint32_t codePoint);
Returns the simple lowercase mapping of a code point.
Parameters:
codePoint: Any value.Returns: The lowercase code point, or codePoint when it has none.
Thread safety. Safe from any thread.
uint32_t muniGetUppercase(uint32_t codePoint);
Returns the simple uppercase mapping of a code point.
Parameters:
codePoint: Any value.Returns: The uppercase code point, or codePoint when it has none.
Thread safety. Safe from any thread.
uint32_t muniGetTitlecase(uint32_t codePoint);
Returns the simple titlecase mapping of a code point, which differs from the uppercase one for digraphs such as "dž", which titlecases to "Dž".
Parameters:
codePoint: Any value.Returns: The titlecase code point, or codePoint when it has none.
Thread safety. Safe from any thread.
uint32_t muniFoldCase(uint32_t codePoint);
Returns the simple case folding of a code point (statuses C and S of CaseFolding.txt).
Parameters:
codePoint: Any value.Returns: The folded code point, or codePoint when it folds to itself.
Thread safety. Safe from any thread.
bool muniIsCased(uint32_t codePoint);
Returns whether a code point is Cased (a letter with case, or one such as "ª" that counts as one).
Parameters:
codePoint: Any value.Returns: true when it is Cased.
Thread safety. Safe from any thread.
MUNI_NODISCARD MUNI_API muniTextResult muniConvertCase(const char* text, size_t length, muniCaseOperation operation, muniCaseLanguage language, muniConvertMode mode, char* textOut, size_t capacity, size_t* neededOut);
Applies a full case operation to UTF-8 text.
Parameters:
text: The text. May be NULL when length is 0.length: The number of bytes.operation: muni_caseLower, muni_caseUpper, muni_caseTitle or muni_caseFold.language: muni_caseDefault, muni_caseTurkic, muni_caseLithuanian, muni_caseGreek or muni_caseArmenian.mode: What to do with ill-formed input.textOut: The output. May be NULL when capacity is 0.capacity: The number of bytes textOut can hold.neededOut: Receives the number of bytes the whole result needs, which may exceed capacity, or SIZE_MAX when that does not fit in a size_t. On another error, the bytes before it, which textOut holds as far as they fit. muni_errorInvalid leaves both as they were.Returns: muni_success and the length; muni_errorCapacity when the result does not fit (the bytes that fit are written); in strict mode the first UTF-8 error and its offset; muni_errorInvalid for a NULL argument, an unknown operation, language or mode, or a textOut that overlaps text.
Thread safety. Safe from any thread.
MUNI_NODISCARD MUNI_API muniTextResult muniGetNfkcCasefold(const char* text, size_t length, muniConvertMode mode, char* textOut, size_t capacity, size_t* neededOut);
Maps UTF-8 text to NFKC_Casefold: compatibility forms to their plain selves, every case to one, default ignorables removed, and the result in NFC. Two strings match without regard to case or compatibility forms when their NFKC_Casefold texts are equal; UAX #31 uses it to compare identifiers. It needs both the case and the normalization components.
Parameters:
text: The text. May be NULL when length is 0.length: The number of bytes.mode: What to do with ill-formed input.textOut: The output. May be NULL when capacity is 0.capacity: The number of bytes textOut can hold.neededOut: Receives the number of bytes the whole result needs, which may exceed capacity, or SIZE_MAX when that does not fit in a size_t. On a UTF-8 error, the bytes before it, which textOut holds as far as they fit. On muni_errorLimit, the same for the text before the starter whose run of combining marks hit the limit. muni_errorInvalid leaves both as they were.Returns: muni_success and the length; muni_errorCapacity when the result does not fit (the bytes that fit are written); in strict mode the first UTF-8 error and its offset; muni_errorLimit and the offset of the code point that makes a segment longer than MUNI_MAX_NORMALIZATION_SEGMENT, as in muniNormalize; muni_errorInvalid for a NULL argument, an unknown mode or a textOut that overlaps text.
Thread safety. Safe from any thread.
encoding.hUTF-8, UTF-16 and UTF-32: validation of hostile input, decoding and encoding of single code points, and conversion between the three. A sequence is well formed exactly when the Unicode Standard's table of well-formed UTF-8 byte sequences (chapter 3) says so: no overlong forms, no surrogates, nothing past U+10FFFF.
MUNI_NODISCARD MUNI_API muniTextResult muniValidateUtf8(const char* bytes, size_t length);
Validates UTF-8 as hostile input.
Parameters:
bytes: The text. May be NULL when length is 0.length: The number of bytes.Returns: muni_success and the length, or the first error and the offset of its sequence: muni_errorUtf8Lead, muni_errorUtf8Continuation, muni_errorUtf8Truncated, muni_errorUtf8Overlong, muni_errorUtf8Surrogate, muni_errorUtf8TooLarge, or muni_errorInvalid for a NULL pointer with a nonzero length.
Thread safety. Safe from any thread.
MUNI_NODISCARD MUNI_API muniTextResult muniValidateUtf16(const uint16_t* units, size_t length);
Validates UTF-16: every surrogate must be half of a pair.
Parameters:
units: The text. May be NULL when length is 0.length: The number of 16-bit code units.Returns: muni_success and the length, or muni_errorUtf16Surrogate and the offset of the unpaired surrogate, or muni_errorInvalid for a NULL pointer with a nonzero length.
Thread safety. Safe from any thread.
MUNI_NODISCARD MUNI_API muniResult muniDecodeUtf8(const char* bytes, size_t length, uint32_t* codePointOut, size_t* sizeOut);
Decodes the code point at the start of a UTF-8 text.
Parameters:
bytes: The text. May be NULL when length is 0.length: The number of bytes available.codePointOut: Receives the code point, or U+FFFD on a UTF-8 error.sizeOut: Receives the bytes consumed: the sequence's length, or on a UTF-8 error the length of its maximal ill-formed subpart (at least 1). muni_errorInvalid leaves both outputs as they were.Returns: muni_success, one of the UTF-8 errors of muniValidateUtf8, or muni_errorInvalid when length is 0 or an out-parameter is NULL.
Thread safety. Safe from any thread.
MUNI_NODISCARD MUNI_API muniResult muniDecodeUtf16(const uint16_t* units, size_t length, uint32_t* codePointOut, size_t* sizeOut);
Decodes the code point at the start of a UTF-16 text.
Parameters:
units: The text. May be NULL when length is 0.length: The number of 16-bit code units available.codePointOut: Receives the code point, or U+FFFD for an unpaired surrogate.sizeOut: Receives the units consumed: 2 for a surrogate pair, otherwise 1, an unpaired surrogate included. muni_errorInvalid leaves both outputs as they were.Returns: muni_success, muni_errorUtf16Surrogate for an unpaired surrogate, or muni_errorInvalid when length is 0 or an out-parameter is NULL.
Thread safety. Safe from any thread.
MUNI_NODISCARD MUNI_API muniResult muniEncodeUtf8(uint32_t codePoint, char* bytesOut, size_t capacity, size_t* sizeOut);
Encodes one code point as UTF-8.
Parameters:
codePoint: A Unicode scalar value.bytesOut: Receives 1 to 4 bytes. May be NULL when capacity is 0.capacity: The number of bytes bytesOut can hold.sizeOut: Receives the length of the encoding, 1 to 4, on success and when it does not fit. muni_errorInvalid leaves it and bytesOut as they were.Returns: muni_success; muni_errorCapacity when the encoding does not fit, and then no byte is written; muni_errorInvalid for a surrogate, a value past U+10FFFF, a NULL sizeOut or a NULL bytesOut with a nonzero capacity.
Thread safety. Safe from any thread.
MUNI_NODISCARD MUNI_API muniTextResult muniConvertUtf8ToUtf16(const char* bytes, size_t length, muniConvertMode mode, uint16_t* unitsOut, size_t capacity, size_t* neededOut);
Converts UTF-8 to UTF-16.
Parameters:
bytes: The text. May be NULL when length is 0.length: The number of bytes.mode: What to do with ill-formed input.unitsOut: The output. May be NULL when capacity is 0.capacity: The number of 16-bit units unitsOut can hold.neededOut: Receives the number of units the whole conversion needs, which may exceed capacity. In strict mode, on an error in the text, the units before it, which unitsOut holds as far as they fit. muni_errorInvalid leaves both as they were.Returns: muni_success; muni_errorCapacity when the output does not fit, with the offset of the first code point not written: unitsOut holds the conversion of the bytes before it; in strict mode the first UTF-8 error and its offset; muni_errorInvalid for a NULL neededOut, a NULL input with a nonzero length, a NULL output with a nonzero capacity, or a mode other than muni_convertStrict and muni_convertReplace.
Thread safety. Safe from any thread.
MUNI_NODISCARD MUNI_API muniTextResult muniConvertUtf16ToUtf8(const uint16_t* units, size_t length, muniConvertMode mode, char* bytesOut, size_t capacity, size_t* neededOut);
Converts UTF-16 to UTF-8.
Parameters:
units: The text. May be NULL when length is 0.length: The number of 16-bit units.mode: What to do with unpaired surrogates.bytesOut: The output. May be NULL when capacity is 0.capacity: The number of bytes bytesOut can hold.neededOut: Receives the number of bytes the whole conversion needs, which may exceed capacity, or SIZE_MAX when that does not fit in a size_t. In strict mode, on an error in the text, the bytes before it, which bytesOut holds as far as they fit. muni_errorInvalid leaves both as they were.Returns: muni_success; muni_errorCapacity when the output does not fit, with the offset of the first code point not written: bytesOut holds the conversion of the units before it; in strict mode muni_errorUtf16Surrogate and its offset; muni_errorInvalid for a NULL neededOut, a NULL input with a nonzero length, a NULL output with a nonzero capacity, or a mode other than muni_convertStrict and muni_convertReplace.
Thread safety. Safe from any thread.
MUNI_NODISCARD MUNI_API muniTextResult muniConvertUtf8ToUtf32(const char* bytes, size_t length, muniConvertMode mode, uint32_t* codePointsOut, size_t capacity, size_t* neededOut);
Converts UTF-8 to UTF-32.
Parameters:
bytes: The text. May be NULL when length is 0.length: The number of bytes.mode: What to do with ill-formed input.codePointsOut: The output. May be NULL when capacity is 0.capacity: The number of code points codePointsOut can hold.neededOut: Receives the number of code points the whole conversion needs, which may exceed capacity. In strict mode, on an error in the text, the ones before it, which codePointsOut holds as far as they fit. muni_errorInvalid leaves both as they were.Returns: muni_success; muni_errorCapacity when the output does not fit, with the offset of the first code point not written: codePointsOut holds the conversion of the bytes before it; in strict mode the first UTF-8 error and its offset; muni_errorInvalid for a NULL neededOut, a NULL input with a nonzero length, a NULL output with a nonzero capacity, or a mode other than muni_convertStrict and muni_convertReplace.
Thread safety. Safe from any thread.
MUNI_NODISCARD MUNI_API muniTextResult muniConvertUtf32ToUtf8(const uint32_t* codePoints, size_t length, muniConvertMode mode, char* bytesOut, size_t capacity, size_t* neededOut);
Converts UTF-32 to UTF-8.
Parameters:
codePoints: The text. May be NULL when length is 0.length: The number of code points.mode: What to do with values that are no scalar value: surrogates and those past U+10FFFF.bytesOut: The output. May be NULL when capacity is 0.capacity: The number of bytes bytesOut can hold.neededOut: Receives the number of bytes the whole conversion needs, which may exceed capacity. In strict mode, on an error in the text, the bytes before it, which bytesOut holds as far as they fit. muni_errorInvalid leaves both as they were.Returns: muni_success; muni_errorCapacity when the output does not fit, with the offset of the first code point not written: bytesOut holds the conversion of the code points before it; in strict mode muni_errorUtf32Value and its offset; muni_errorInvalid for a NULL neededOut, a NULL input with a nonzero length, a NULL output with a nonzero capacity, or a mode other than muni_convertStrict and muni_convertReplace.
Thread safety. Safe from any thread.
harfbuzz.hMaul Unicode as HarfBuzz's source of Unicode data: general category, combining class, mirroring, script, and the composition and decomposition that HarfBuzz's normalizer uses while shaping. Built as the static library maul-unicode-harfbuzz when the build option MAUL_UNICODE_HARFBUZZ is on; it needs normalization. The header does not include
extern hb_unicode_funcs_t* muniCreateHarfBuzzFunctions(void);
Creates HarfBuzz Unicode functions backed by Maul Unicode. Pass them to hb_buffer_set_unicode_funcs; release them with hb_unicode_funcs_destroy.
Returns: New immutable functions. Like hb_unicode_funcs_create, it returns HarfBuzz's empty functions when HarfBuzz cannot allocate, never NULL.
Thread safety. Safe from any thread. The functions it returns are immutable and may be shared between threads.
identifier.hIdentifiers and pattern syntax (UAX #31): which characters may start and continue a name in a programming or markup language, a file name or a user name, and which are syntax or white space that a pattern language may give meaning to without ever confusing it with a name.
bool muniIsIdentifierStart(uint32_t codePoint);
Returns whether a code point may start an identifier (XID_Start).
Parameters:
codePoint: Any value.Returns: true for XID_Start.
Thread safety. Safe from any thread.
bool muniIsIdentifierContinue(uint32_t codePoint);
Returns whether a code point may continue an identifier (XID_Continue, which includes XID_Start).
Parameters:
codePoint: Any value.Returns: true for XID_Continue.
Thread safety. Safe from any thread.
bool muniIsPatternSyntax(uint32_t codePoint);
Returns whether a code point is Pattern_Syntax: punctuation and symbols reserved for syntax, never part of an identifier.
Parameters:
codePoint: Any value.Returns: true for Pattern_Syntax.
Thread safety. Safe from any thread.
bool muniIsPatternWhiteSpace(uint32_t codePoint);
Returns whether a code point is Pattern_White_Space.
Parameters:
codePoint: Any value.Returns: true for Pattern_White_Space.
Thread safety. Safe from any thread.
MUNI_NODISCARD MUNI_API muniTextResult muniCheckIdentifier(const char* text, size_t length);
Checks that UTF-8 text is a default identifier (UAX #31 R1): an XID_Start code point, then XID_Continue code points.
Parameters:
text: The text. May be NULL when length is 0.length: The number of bytes.Returns: muni_success and the length; muni_errorIdentifier and the offset of the first code point that breaks the rule (0 for empty text); the first UTF-8 error and its offset; muni_errorInvalid for a NULL text with a nonzero length.
Thread safety. Safe from any thread.
normalize.hNormalization (UAX #15): the four normal forms, which make text that looks the same compare the same. NFD takes characters apart ("e" and a combining acute accent for "é") and NFC puts them back together; NFKD and NFKC also fold compatibility characters, such as ligatures and full-width letters, into their plain counterparts. Normalization writes into a caller buffer and allocates nothing. It reorders at most MUNI_MAX_NORMALIZATION_SEGMENT code points at once, a starter and the combining marks after it once fully decomposed, so 31 marks after a starter. A longer run is refused with muni_errorLimit rather than buffered without bound (real text carries a handful; UAX #15's stream-safe text carries at most 30).
MUNI_NODISCARD MUNI_API muniTextResult muniNormalize(const char* text, size_t length, muniNormalForm form, muniConvertMode mode, char* textOut, size_t capacity, size_t* neededOut);
Normalizes UTF-8 text into a normal form.
Parameters:
text: The text. May be NULL when length is 0.length: The number of bytes.form: muni_nfc, muni_nfd, muni_nfkc or muni_nfkd.mode: What to do with ill-formed input.textOut: The output. May be NULL when capacity is 0.capacity: The number of bytes textOut can hold.neededOut: Receives the number of bytes the whole result needs, which may exceed capacity, or SIZE_MAX when that does not fit in a size_t. On a UTF-8 error, the bytes before it, which textOut holds as far as they fit. On muni_errorLimit, the same for the text before the starter whose run of combining marks hit the limit. muni_errorInvalid leaves both as they were.Returns: muni_success and the length; muni_errorCapacity when the result does not fit (the bytes that fit are written); in strict mode the first UTF-8 error and its offset; muni_errorLimit and the offset of the code point that makes a segment longer than MUNI_MAX_NORMALIZATION_SEGMENT; muni_errorInvalid for a NULL argument, an unknown form or a textOut that overlaps text.
Thread safety. Safe from any thread.
MUNI_NODISCARD MUNI_API muniTextResult muniCheckNormalization(const char* text, size_t length, muniNormalForm form, muniQuickCheck* answerOut);
Tells quickly whether UTF-8 text is in a normal form, without normalizing it.
Parameters:
text: The text. May be NULL when length is 0.length: The number of bytes.form: muni_nfc, muni_nfd, muni_nfkc or muni_nfkd.answerOut: Receives muni_quickCheckYes, muni_quickCheckNo or muni_quickCheckMaybe. Left as it was on an error.Returns: muni_success and the length; the first UTF-8 error and its offset; muni_errorInvalid for a NULL argument or an unknown form.
Thread safety. Safe from any thread.
MUNI_NODISCARD MUNI_API muniResult muniDecomposePair(uint32_t codePoint, uint32_t* firstOut, uint32_t* secondOut, size_t* countOut);
Gives the canonical decomposition of a code point one level deep, as shapers such as HarfBuzz ask for it: two code points, one (a singleton), or none. Hangul syllables split into LV + T or L + V.
Parameters:
codePoint: Any value.firstOut: Receives the first code point, or 0 when the count is 0.secondOut: Receives the second code point, or 0 when the count is below 2.countOut: Receives 0 when the code point does not decompose, 1 for a singleton and 2 for a pair.Returns: muni_success, or muni_errorInvalid for a NULL output, and then every output is left as it was.
Thread safety. Safe from any thread.
MUNI_NODISCARD MUNI_API muniResult muniGetDecomposition(uint32_t codePoint, muniNormalForm form, uint32_t* codePointsOut, size_t capacity, size_t* countOut);
Writes the full decomposition of a code point: its NFD or NFKD, every mapping applied until none is left, in canonical order. A code point that does not decompose gives itself, so there is always at least one; Hangul syllables give their jamo.
Parameters:
codePoint: Any value; one above U+10FFFF gives itself.form: muni_nfd for the canonical decomposition, muni_nfkd for the compatibility one.codePointsOut: The output. May be NULL when capacity is 0.capacity: The number of code points the output can hold; MUNI_MAX_DECOMPOSITION always suffice.countOut: Receives the number of code points. muni_errorInvalid leaves both as they were.Returns: muni_success, muni_errorCapacity when they do not all fit (the ones that fit are written), or muni_errorInvalid for a NULL argument or a form other than muni_nfd and muni_nfkd.
Thread safety. Safe from any thread.
uint32_t muniComposePair(uint32_t first, uint32_t second);
Returns the primary composite of two code points (UAX #15 D114), Hangul syllables included.
Parameters:
first: The first code point.second: The second code point.Returns: The composite, or 0 when the pair does not compose.
Thread safety. Safe from any thread.
properties.hCharacter properties from the Unicode Character Database. Every lookup takes a code point, cannot fail and returns the property's value; a value above U+10FFFF gets the value of an unassigned code point. Each property's values are numbered in the library's own order. A value that a new Unicode version adds is appended after the last, and the existing values keep their numbers, so data may store them.
muniGeneralCategory muniGetGeneralCategory(uint32_t codePoint);
Returns the General_Category of a code point.
Parameters:
codePoint: Any value; one above U+10FFFF is unassigned.Returns: The category, one of the muni_gc values.
Thread safety. Safe from any thread.
muniGraphemeBreak muniGetGraphemeBreak(uint32_t codePoint);
Returns the Grapheme_Cluster_Break of a code point.
Parameters:
codePoint: Any value; one above U+10FFFF is Other.Returns: The value, one of the muni_gcb values.
Thread safety. Safe from any thread.
muniWordBreak muniGetWordBreak(uint32_t codePoint);
Returns the Word_Break of a code point.
Parameters:
codePoint: Any value; one above U+10FFFF is Other.Returns: The value, one of the muni_wb values.
Thread safety. Safe from any thread.
muniSentenceBreak muniGetSentenceBreak(uint32_t codePoint);
Returns the Sentence_Break of a code point.
Parameters:
codePoint: Any value; one above U+10FFFF is Other.Returns: The value, one of the muni_sb values.
Thread safety. Safe from any thread.
muniIndicConjunctBreak muniGetIndicConjunctBreak(uint32_t codePoint);
Returns the Indic_Conjunct_Break of a code point.
Parameters:
codePoint: Any value; one above U+10FFFF is None.Returns: The value, one of the muni_incb values.
Thread safety. Safe from any thread.
bool muniIsExtendedPictographic(uint32_t codePoint);
Tells whether a code point has the Extended_Pictographic property (UTS #51), which keeps emoji sequences together.
Parameters:
codePoint: Any value; one above U+10FFFF has it not.Returns: true when the code point is Extended_Pictographic.
Thread safety. Safe from any thread.
bool muniIsEmoji(uint32_t codePoint);
Tells whether a code point has the Emoji property (UTS #51): it can show as an emoji, which digits and '#' can too.
Parameters:
codePoint: Any value; one above U+10FFFF has it not.Returns: true when the code point is Emoji.
Thread safety. Safe from any thread.
bool muniIsEmojiPresentation(uint32_t codePoint);
Tells whether a code point has the Emoji_Presentation property (UTS #51): it shows as an emoji unless a variation selector asks for text.
Parameters:
codePoint: Any value; one above U+10FFFF has it not.Returns: true when the code point is Emoji_Presentation.
Thread safety. Safe from any thread.
bool muniIsEmojiModifier(uint32_t codePoint);
Tells whether a code point has the Emoji_Modifier property (UTS #51): a skin tone modifier.
Parameters:
codePoint: Any value; one above U+10FFFF has it not.Returns: true when the code point is Emoji_Modifier.
Thread safety. Safe from any thread.
bool muniIsEmojiModifierBase(uint32_t codePoint);
Tells whether a code point has the Emoji_Modifier_Base property (UTS #51): a skin tone modifier after it applies to it.
Parameters:
codePoint: Any value; one above U+10FFFF has it not.Returns: true when the code point is Emoji_Modifier_Base.
Thread safety. Safe from any thread.
bool muniIsEmojiComponent(uint32_t codePoint);
Tells whether a code point has the Emoji_Component property (UTS #51): it can be part of an emoji sequence, as regional indicators, keycap parts, tags and the zero width joiner are.
Parameters:
codePoint: Any value; one above U+10FFFF has it not.Returns: true when the code point is Emoji_Component.
Thread safety. Safe from any thread.
bool muniIsWhiteSpace(uint32_t codePoint);
Tells whether a code point has the White_Space property: spaces, tabs and line and paragraph separators, 25 code points in all.
Parameters:
codePoint: Any value; one above U+10FFFF has it not.Returns: true when the code point is White_Space.
Thread safety. Safe from any thread.
bool muniIsDefaultIgnorable(uint32_t codePoint);
Tells whether a code point is Default_Ignorable_Code_Point: a character that shows nothing when a font lacks it, such as a zero width joiner or a variation selector.
Parameters:
codePoint: Any value; one above U+10FFFF has it not.Returns: true for a default ignorable code point.
Thread safety. Safe from any thread.
bool muniIsIdeographic(uint32_t codePoint);
Tells whether a code point has the Ideographic property (PropList.txt): the CJK unified and compatibility ideographs, the Small Seal characters, the characters of Tangut, Khitan Small Script, Jurchen and Nushu, and a few CJK marks and numerals such as U+3007 IDEOGRAPHIC NUMBER ZERO. The CJK radicals, which Script=Han includes, do not have it.
Parameters:
codePoint: Any value; one above U+10FFFF has it not.Returns: true when the code point is Ideographic.
Thread safety. Safe from any thread.
int32_t muniGetDecimalDigitValue(uint32_t codePoint);
Returns the value of a decimal digit: a code point of General Category Nd (Numeric_Type Decimal), such as '7' or the Devanagari seven, which parse as numbers. Superscripts, fractions and Roman numerals have numeric values but are not decimal digits.
Parameters:
codePoint: Any value.Returns: The digit's value, 0 to 9, or -1 when the code point is not a decimal digit.
Thread safety. Safe from any thread.
muniLineBreak muniGetLineBreak(uint32_t codePoint);
Returns the Line_Break class of a code point.
Parameters:
codePoint: Any value; one above U+10FFFF is Unknown (XX).Returns: The class, one of the muni_lb values.
Thread safety. Safe from any thread.
muniEastAsianWidth muniGetEastAsianWidth(uint32_t codePoint);
Returns the East_Asian_Width of a code point.
Parameters:
codePoint: Any value; one above U+10FFFF is Neutral.Returns: The width, one of the muni_eaw values.
Thread safety. Safe from any thread.
muniBidiClass muniGetBidiClass(uint32_t codePoint);
Returns the Bidi_Class of a code point, with the UCD's defaults for unassigned code points in right-to-left blocks.
Parameters:
codePoint: Any value; one above U+10FFFF is Left_To_Right.Returns: The class, one of the muni_bc values.
Thread safety. Safe from any thread.
uint32_t muniGetMirroringGlyph(uint32_t codePoint);
Returns the Bidi_Mirroring_Glyph of a code point: the character whose glyph is its mirror image, such as ')' for '(', which right- to-left text displays in its place.
Parameters:
codePoint: Any value.Returns: The mirror, or codePoint itself when it has none.
Thread safety. Safe from any thread.
muniBracketType muniGetBracketType(uint32_t codePoint);
Returns the Bidi_Paired_Bracket_Type of a code point. The bracket it pairs with is its muniGetMirroringGlyph.
Parameters:
codePoint: Any value.Returns: One of the muni_bracket values.
Thread safety. Safe from any thread.
uint8_t muniGetCombiningClass(uint32_t codePoint);
Returns the Canonical_Combining_Class of a code point.
Parameters:
codePoint: Any value; one above U+10FFFF has class 0.Returns: The class, from 0 (not reordered) to 254.
Thread safety. Safe from any thread.
muniScript muniGetScript(uint32_t codePoint);
Returns the Script of a code point.
Parameters:
codePoint: Any value; one above U+10FFFF is Unknown.Returns: The script's ISO 15924 tag, as MUNI_MAKE_SCRIPT builds it.
Thread safety. Safe from any thread.
MUNI_NODISCARD MUNI_API muniResult muniGetScriptExtensions(uint32_t codePoint, muniScript* scriptsOut, size_t capacity, size_t* countOut);
Writes the Script_Extensions of a code point (UAX #24): the scripts it is used with. A code point without listed extensions has its Script alone, so there is always at least one.
Parameters:
codePoint: Any value.scriptsOut: The output. May be NULL when capacity is 0.capacity: The number of scripts the output can hold; MUNI_MAX_SCRIPT_EXTENSIONS always suffice.countOut: Receives the number of scripts. muni_errorInvalid leaves both as they were.Returns: muni_success, muni_errorCapacity when they do not all fit (the ones that fit are written), or muni_errorInvalid for a NULL argument.
Thread safety. Safe from any thread.
script.hScript runs: the stretches of text a shaper such as HarfBuzz shapes with one script. Characters used with many scripts, such as spaces, digits and punctuation (Script Common), and combining marks (Inherited) join the run around them; a character used with a few scripts (Script_Extensions, UAX #24) narrows the run to those it shares; a closing bracket takes the script of its opening bracket. Leading Common characters take the script of the first run. A run that could still be several scripts takes the first Script of its own, among its characters, that the run could still be when that character came, while the run can still be that script, and otherwise the script whose tag comes first alphabetically. Like the segment iterators, a script iterator is a fixed-size struct the caller keeps, takes text in pieces cut anywhere, and asks for the next piece with muni_needMoreText.
MUNI_NODISCARD MUNI_API muniResult muniInitScriptIterator(muniScriptIterator* iterator, const char* text, size_t length, bool moreFollows);
Starts an iterator over the script runs of a UTF-8 text or its first piece.
Parameters:
iterator: The iterator to initialize.text: The text. May be NULL when length is 0.length: The number of bytes.moreFollows: true when more pieces of the text will be fed.Returns: muni_success, or muni_errorInvalid for a NULL iterator or a NULL text with a nonzero length.
Thread safety. Safe from any thread; an iterator is used by one thread at a time.
MUNI_NODISCARD MUNI_API muniResult muniScriptIterator_Feed(muniScriptIterator* iterator, const char* text, size_t length, bool moreFollows);
Hands a script iterator the next piece of its text, after it returned muni_needMoreText.
Parameters:
iterator: The iterator.text: The next piece. May be NULL when length is 0.length: The number of bytes.moreFollows: true when still more pieces will be fed.Returns: muni_success; muni_errorState for an iterator that did not ask for more text, such as one initialized without more text to follow; muni_errorInvalid for a NULL argument or an iterator no init call set up. muni_errorInvalid is reported before muni_errorState.
Thread safety. Safe from any thread; an iterator is used by one thread at a time.
MUNI_NODISCARD MUNI_API muniResult muniScriptIterator_NextRun(muniScriptIterator* iterator, muniScriptRun* runOut);
Finds the next script run.
Parameters:
iterator: The iterator.runOut: Receives the run: where it ends, as a byte offset from the start of the whole text, and its script. A text of Common and Inherited characters only is one run of Common. Left as it was unless the call returns muni_success.Returns: muni_success with a run; muni_done after the last one; muni_needMoreText when the run's end or script depends on text not yet fed; muni_errorInvalid for a NULL argument or an iterator no init call set up.
Thread safety. Safe from any thread; an iterator is used by one thread at a time.
MUNI_NODISCARD MUNI_API muniResult muniFindScriptRuns(const char* text, size_t length, muniScriptRun* runsOut, size_t capacity, size_t* countOut);
Writes the script runs of a whole UTF-8 text into a caller array.
Parameters:
text: The text. May be NULL when length is 0.length: The number of bytes.runsOut: The output. May be NULL when capacity is 0.capacity: The number of runs the output can hold.countOut: Receives the number of runs, which may exceed capacity; the ones that fit are written. muni_errorInvalid leaves both as they were.Returns: muni_success, muni_errorCapacity when they do not all fit, or muni_errorInvalid for a NULL argument.
Thread safety. Safe from any thread.
security.hSecurity mechanisms (UTS #39) for names people read, such as user names and identifiers: whether two strings can pass for each other, and how far a string mixes scripts. Two strings are confusable when their skeletons are equal: "paypal" written with a Cyrillic "а" has the skeleton of the Latin one. A skeleton is not text to show; store it next to a name, compare it as bytes, and recompute it when muniGetResultsVersion changes. Skeletons follow the reading order bidi gives each string, so the caller supplies bidi's workspace, and nothing allocates. The restriction level grades how a string mixes scripts, from ASCII only to anything, under the General Security Profile: a string with a character the profile does not allow is unrestricted. The level does not check the string's syntax; an identifier should also pass muniCheckIdentifier.
bool muniIsIdentifierAllowed(uint32_t codePoint);
Tells whether a code point has Identifier_Status Allowed, the General Security Profile for identifiers.
Parameters:
codePoint: Any value.Returns: true when the profile allows the code point.
Thread safety. Safe from any thread.
MUNI_NODISCARD MUNI_API muniTextResult muniGetSkeleton(const char* text, size_t length, muniBidiDirection direction, uint8_t* workspace, size_t workspaceSize, char* textOut, size_t capacity, size_t* neededOut);
Computes the skeleton of UTF-8 text as displayed in a paragraph of a direction: bidiSkeleton of UTS #39 section 4. The skeleton of muni_bidiLeftToRight is the one UTS #39 calls skeleton; muni_bidiAuto takes the direction from the first strong character. Text without right-to-left characters has the same skeleton in both automatic and left-to-right paragraphs.
Parameters:
text: The text. May be NULL when length is 0.length: The number of bytes.direction: The paragraph direction.workspace: Scratch memory of at least 2 * length bytes. May be NULL when workspaceSize is 0.workspaceSize: The number of bytes workspace holds.textOut: The output. May be NULL when capacity is 0.capacity: The number of bytes textOut can hold.neededOut: Receives the number of bytes the whole skeleton needs on success and when the output is too small, where it may exceed capacity, or SIZE_MAX when that does not fit in a size_t. On muni_errorLimit, the number of bytes of the skeleton of the text shown before the segment that hit the limit, in display order, which textOut holds as far as they fit; nothing from that segment on is written. 0 on every other error, except muni_errorInvalid, which leaves it and textOut as they were.Returns: muni_success and the length; muni_errorCapacity when the skeleton does not fit (the bytes that fit are written), or with offset 0 and neededOut 0 when workspaceSize is less than 2 * length, before the text is read; the first UTF-8 error and its offset; muni_errorLimit when a segment outgrows MUNI_MAX_NORMALIZATION_SEGMENT, and the offset of the code point being read then, with the start of the skeleton written as neededOut says; muni_errorInvalid for a NULL argument, an unknown direction or a textOut that overlaps text.
Thread safety. Safe from any thread; the workspace and textOut are used by one thread at a time.
MUNI_NODISCARD MUNI_API muniTextResult muniGetResolvedScripts(const char* text, size_t length, muniScript* scriptsOut, size_t capacity, size_t* countOut);
Writes the resolved script set of UTF-8 text (UTS #39 section 5.1): the scripts every character can belong to, counting Han text as also Japanese (Jpan), Korean (Kore) and Han with Bopomofo (Hanb) or Latin (Hntl), Hiragana and Katakana as Japanese, Hangul as Korean, Bopomofo as Hanb and Latin as Hntl. No script means the text mixes scripts. Text of Common and Inherited characters alone, which fits any script, gives the single script Zyyy.
Parameters:
text: The text. May be NULL when length is 0.length: The number of bytes.scriptsOut: The output, in ascending tag order. May be NULL when capacity is 0.capacity: The number of scripts the output can hold; MUNI_MAX_RESOLVED_SCRIPTS always suffice.countOut: Receives the number of scripts, on success and when they do not fit. A UTF-8 error and muni_errorInvalid leave it and scriptsOut as they were.Returns: muni_success and the length; muni_errorCapacity when the scripts do not fit, and then none is written; the first UTF-8 error and its offset; muni_errorInvalid for a NULL argument.
Thread safety. Safe from any thread.
MUNI_NODISCARD MUNI_API muniTextResult muniGetRestrictionLevel(const char* text, size_t length, muniRestrictionLevel* levelOut);
Grades how UTF-8 text mixes scripts (UTS #39 section 5.2).
Parameters:
text: The text. May be NULL when length is 0.length: The number of bytes.levelOut: Receives one of the muni_restriction values. Left as it was on an error.Returns: muni_success and the length; the first UTF-8 error and its offset; muni_errorInvalid for a NULL argument.
Thread safety. Safe from any thread.
MUNI_NODISCARD MUNI_API muniTextResult muniCheckMixedNumbers(const char* text, size_t length, bool* mixedOut);
Tells whether UTF-8 text holds digits of more than one decimal system (UTS #39 section 5.3), such as ASCII and Bengali digits, some of which look alike.
Parameters:
text: The text. May be NULL when length is 0.length: The number of bytes.mixedOut: Receives true when the digits mix systems. Left as it was on an error.Returns: muni_success and the length; the first UTF-8 error and its offset; muni_errorInvalid for a NULL argument.
Thread safety. Safe from any thread.
segment.hText segmentation (UAX #29): the boundaries of grapheme clusters, the units a user perceives as one character, which caret movement, selection and backspace must never split; of words, for double-click selection, word movement and search; and of sentences. Line breaking (UAX #14): the positions where a line may, or must, end. An iterator walks UTF-8 text and reports each boundary after the start of the text, the last one being the end of the text; empty text has none. Offsets are in bytes from the start of the whole text. Each maximal ill-formed UTF-8 subpart counts as one U+FFFD. Word boundaries are the positions UAX #29 defines; between two of them may lie a word, a run of spaces or a punctuation mark, which muniSegmentIterator_GetWordKind tells apart. Text may arrive in pieces. An iterator initialized with more text to follow stops with muni_needMoreText when the next boundary depends on text it has not seen; muniSegmentIterator_Feed hands it the next piece, which may begin in the middle of a UTF-8 sequence. Some rules look ahead: a word boundary may wait for the next code point, and a sentence boundary after an abbreviation's period for the next letter.
MUNI_NODISCARD MUNI_API muniResult muniInitGraphemeIterator(muniSegmentIterator* iterator, const char* text, size_t length, bool moreFollows);
Starts an iterator over the grapheme cluster boundaries of a UTF-8 text or its first piece.
Parameters:
iterator: The iterator to initialize.text: The text. May be NULL when length is 0.length: The number of bytes.moreFollows: true when more pieces of the text will be fed.Returns: muni_success, or muni_errorInvalid for a NULL iterator or a NULL text with a nonzero length.
Thread safety. Safe from any thread; an iterator is used by one thread at a time.
MUNI_NODISCARD MUNI_API muniResult muniInitWordIterator(muniSegmentIterator* iterator, const char* text, size_t length, bool moreFollows);
Starts an iterator over the word boundaries of a UTF-8 text or its first piece.
Parameters:
iterator: The iterator to initialize.text: The text. May be NULL when length is 0.length: The number of bytes.moreFollows: true when more pieces of the text will be fed.Returns: muni_success, or muni_errorInvalid for a NULL iterator or a NULL text with a nonzero length.
Thread safety. Safe from any thread; an iterator is used by one thread at a time.
MUNI_NODISCARD MUNI_API muniResult muniInitSentenceIterator(muniSegmentIterator* iterator, const char* text, size_t length, bool moreFollows);
Starts an iterator over the sentence boundaries of a UTF-8 text or its first piece.
Parameters:
iterator: The iterator to initialize.text: The text. May be NULL when length is 0.length: The number of bytes.moreFollows: true when more pieces of the text will be fed.Returns: muni_success, or muni_errorInvalid for a NULL iterator or a NULL text with a nonzero length.
Thread safety. Safe from any thread; an iterator is used by one thread at a time.
MUNI_NODISCARD MUNI_API muniResult muniInitLineIterator(muniSegmentIterator* iterator, const char* text, size_t length, bool moreFollows);
Starts an iterator over the line break opportunities of a UTF-8 text or its first piece, with the default rules of UAX #14. Thai, Lao, Khmer and Burmese letters (class SA) are resolved as rule LB1 says without a dictionary, with no opportunities between them, unless muniSegmentIterator_SetComplexBreaker supplies a word segmenter.
Parameters:
iterator: The iterator to initialize.text: The text. May be NULL when length is 0.length: The number of bytes.moreFollows: true when more pieces of the text will be fed.Returns: muni_success, or muni_errorInvalid for a NULL iterator or a NULL text with a nonzero length.
Thread safety. Safe from any thread; an iterator is used by one thread at a time.
MUNI_NODISCARD MUNI_API muniResult muniSegmentIterator_SetComplexBreaker( muniSegmentIterator* iterator, muniComplexBreakFunction breaker, void* context);
Sets the word segmenter a line or word iterator hands runs of SA text to. Inside such a run its breaks replace the default ones: line breaking then allows a break between words, and word segmentation finds whole words instead of single letters. A break before a combining mark is ignored. A run lies within one piece of text; a piece boundary inside a run hands the run over in parts. Without a segmenter, SA text follows rule LB1 of UAX #14 and the default word rules.
While the segmenter runs, the iterator is busy: the setters, muniSegmentIterator_Feed, muniSegmentIterator_NextBreak and muniSegmentIterator_NextLineBreak called on it return muni_errorBusy and change nothing, so the outer call finds the same breaks as without them. The segmenter must not initialize the iterator again.
Parameters:
iterator: A line or word iterator not yet asked for a break.breaker: The segmenter, or NULL for the default rules.context: Passed to the segmenter unchanged.Returns: muni_success; muni_errorState for an iterator already asked for a break; muni_errorBusy when called from inside the iterator's word segmenter; muni_errorInvalid for a NULL iterator, one no init call set up or another kind of iterator. muni_errorInvalid is reported before muni_errorBusy, and that before muni_errorState.
Thread safety. Safe from any thread; an iterator is used by one thread at a time, and calls the segmenter on that thread.
MUNI_NODISCARD MUNI_API muniResult muniSegmentIterator_SetBreakClassOverrides( muniSegmentIterator* iterator, const muniBreakClassOverride* overrides, size_t count);
Gives code points other classes in a word iterator (Word_Break values) or a sentence iterator (Sentence_Break values). The rules then treat each such code point as a code point of its new class; what they read from other properties, such as Extended_Pictographic and Line_Break=SA, stays as Unicode assigns it. The table is read in place, so it must stay unchanged while the iterator is used.
Parameters:
iterator: A word or sentence iterator not yet asked for a boundary.overrides: The code points and their classes, in strictly increasing order of code point. May be NULL when count is 0.count: The number of overrides, at most 0x10F800 (one per scalar value); 0 restores the classes Unicode assigns.Returns: muni_success; muni_errorState for an iterator already asked for a boundary; muni_errorInvalid for a NULL iterator or one no init call set up, NULL overrides with a nonzero count, another kind of iterator, a count over 0x10F800, a code point past U+10FFFF or a surrogate, code points out of order or repeated, or a value that is not a class of the iterator's property; muni_errorBusy when called from inside the iterator's word segmenter. muni_errorInvalid is reported before muni_errorBusy, and that before muni_errorState.
Thread safety. Safe from any thread; an iterator and its overrides are used by one thread at a time.
MUNI_NODISCARD MUNI_API muniResult muniSegmentIterator_SetLineBreakStrictness( muniSegmentIterator* iterator, muniLineBreakStrictness strictness);
Sets how strictly a line iterator keeps text together. A new iterator is muni_lineBreakNormal.
Parameters:
iterator: A line iterator not yet asked for a break.strictness: One of the muni_lineBreak values.Returns: muni_success; muni_errorState for an iterator already asked for a break; muni_errorBusy when called from inside the iterator's word segmenter; muni_errorInvalid for a NULL iterator, one no init call set up, another kind of iterator or an unknown strictness. muni_errorInvalid is reported before muni_errorBusy, and that before muni_errorState.
Thread safety. Safe from any thread; an iterator is used by one thread at a time.
muniLineBreakStrictness muniSegmentIterator_GetLineBreakStrictness(const muniSegmentIterator* iterator);
Returns how strictly a line iterator keeps text together.
Parameters:
iterator: The iterator.Returns: The strictness muniSegmentIterator_SetLineBreakStrictness set, muni_lineBreakNormal when none was set, and for a NULL iterator, one no init call set up or another kind of iterator.
Thread safety. Safe from any thread; an iterator is used by one thread at a time.
MUNI_NODISCARD MUNI_API muniResult muniSegmentIterator_SetWritingSystem( muniSegmentIterator* iterator, muniWritingSystem writingSystem);
Sets the writing system of the text a line iterator breaks. A new iterator is muni_writingOther.
Parameters:
iterator: A line iterator not yet asked for a break.writingSystem: One of the muni_writing values.Returns: muni_success; muni_errorState for an iterator already asked for a break; muni_errorBusy when called from inside the iterator's word segmenter; muni_errorInvalid for a NULL iterator, one no init call set up, another kind of iterator or an unknown writing system. muni_errorInvalid is reported before muni_errorBusy, and that before muni_errorState.
Thread safety. Safe from any thread; an iterator is used by one thread at a time.
muniWritingSystem muniSegmentIterator_GetWritingSystem(const muniSegmentIterator* iterator);
Returns the writing system of the text a line iterator breaks.
Parameters:
iterator: The iterator.Returns: The writing system muniSegmentIterator_SetWritingSystem set, muni_writingOther when none was set, and for a NULL iterator, one no init call set up or another kind of iterator.
Thread safety. Safe from any thread; an iterator is used by one thread at a time.
MUNI_NODISCARD MUNI_API muniResult muniSegmentIterator_Feed(muniSegmentIterator* iterator, const char* text, size_t length, bool moreFollows);
Hands an iterator the next piece of its text, after it returned muni_needMoreText. The iterator keeps no pointer to earlier pieces.
Parameters:
iterator: The iterator.text: The next piece. May be NULL when length is 0.length: The number of bytes.moreFollows: true when still more pieces will be fed.Returns: muni_success; muni_errorState for an iterator that did not ask for more text, such as one initialized without more text to follow or one fed before it asked; muni_errorBusy when called from inside the iterator's word segmenter; muni_errorInvalid for a NULL argument or an iterator no init call set up. muni_errorInvalid is reported before muni_errorBusy, and that before muni_errorState.
Thread safety. Safe from any thread; an iterator is used by one thread at a time.
MUNI_NODISCARD MUNI_API muniResult muniSegmentIterator_NextBreak(muniSegmentIterator* iterator, size_t* offsetOut);
Finds the next boundary.
Parameters:
iterator: The iterator.offsetOut: Receives the boundary's byte offset from the start of the whole text. Left as it was unless the call returns muni_success.Returns: muni_success with a boundary; muni_done after the last one; muni_needMoreText when the next boundary depends on text not yet fed; muni_errorBusy when called from inside the iterator's word segmenter, and then the iterator is left as it was; muni_errorInvalid for a NULL argument or an iterator no init call set up.
Thread safety. Safe from any thread; an iterator is used by one thread at a time.
MUNI_NODISCARD MUNI_API muniResult muniSegmentIterator_NextLineBreak( muniSegmentIterator* iterator, size_t* offsetOut, bool* mandatoryOut);
Finds the next line break opportunity of a line iterator, and whether the line must end there: after a mandatory break character (BK, CR, LF or NL) and at the end of the text.
Parameters:
iterator: An iterator from muniInitLineIterator.offsetOut: Receives the opportunity's byte offset from the start of the whole text. Left as it was unless the call returns muni_success.mandatoryOut: Receives true when the break is mandatory. It is false after muni_done and muni_needMoreText; muni_errorBusy and muni_errorInvalid leave it as it was.Returns: As muniSegmentIterator_NextBreak; muni_errorInvalid also for an iterator of another kind.
Thread safety. Safe from any thread; an iterator is used by one thread at a time.
MUNI_NODISCARD MUNI_API muniResult muniSegmentIterator_FindBreaksAround( const muniSegmentIterator* iterator, size_t offset, size_t* beforeOut, size_t* afterOut);
Finds the boundaries around a byte offset: the last at or before it and the first after it, as the iterator would report them, but without reading the text from its start. The call backs up from the offset to a boundary every rule of the iterator's kind and settings makes whatever text came before, and reads forward from there to the boundary after the offset, so its cost grows with that stretch of text alone: in ordinary text a few code points for grapheme clusters, words and lines, and back to the last sentence ending or paragraph separator for sentences. Text with no such boundary (one base and many marks, a long run of regional indicators, or of SA text with a word segmenter set) is read back to its start, at most twice over.
The iterator must hold its whole text: one given to its init call with no more to follow. The call reads the text and settings it holds and leaves it as it was, wherever its own iteration stands. With a word segmenter set, the segmenter may be asked about part of a run, as when a piece boundary falls inside one, and the boundaries found are those of the whole text.
Parameters:
iterator: The iterator.offset: A byte offset into the text, at most its length. Inside a code point, it stands for that code point's start.beforeOut: Receives the last boundary at or before offset, or 0, the start of the text, when there is none. Left as it was unless the call returns muni_success.afterOut: Receives the first boundary after offset, or the text's length when offset is its length. Left as it was unless the call returns muni_success.Returns: muni_success; muni_errorState for an iterator that does not hold its whole text; muni_errorBusy when called from inside the iterator's word segmenter; muni_errorInvalid for a NULL argument, an iterator no init call set up or an offset past the end of the text. muni_errorInvalid is reported before muni_errorBusy, and that before muni_errorState.
Thread safety. Safe from any thread; an iterator is used by one thread at a time, and calls the segmenter on that thread.
MUNI_NODISCARD MUNI_API muniResult muniSegmentIterator_GetWordKind(const muniSegmentIterator* iterator, muniWordKind* kindOut);
Tells what kind of word the segment ending at the boundary a word iterator last reported holds: the text between that boundary and the one before it, or the start of the text.
Parameters:
iterator: An iterator from muniInitWordIterator.kindOut: Receives the kind; muni_wordNone before the first boundary. Left as it was unless the call returns muni_success.Returns: muni_success; muni_errorBusy when called from inside the iterator's word segmenter; muni_errorInvalid for a NULL argument, an iterator no init call set up or one of another kind.
Thread safety. Safe from any thread; an iterator is used by one thread at a time.
MUNI_NODISCARD MUNI_API muniResult muniMeasureUtf8(const char* text, size_t length, muniTextUnit unit, size_t maxBytes, size_t maxUnits, size_t* bytesOut, size_t* unitsOut);
Finds the longest prefix of UTF-8 text that ends at a boundary of unit and has at most maxBytes bytes and at most maxUnits units, and gives its length in bytes and in units. One walk serves four uses: a byte offset as a count of units (maxBytes is the offset, maxUnits SIZE_MAX), a count of units as a byte offset (maxBytes SIZE_MAX, maxUnits the count), text cut to fit a buffer without splitting a character (maxBytes the buffer's size, maxUnits SIZE_MAX), and the units of a whole text. With muni_unitGraphemeCluster it reads at most one cluster past the prefix.
Parameters:
text: The text. May be NULL when length is 0. Each maximal ill-formed subpart counts as one U+FFFD.length: The text's length in bytes.unit: muni_unitCodePoint, muni_unitGraphemeCluster or muni_unitUtf16.maxBytes: The most bytes the prefix may have; the whole text when it is length or more. When it falls inside a code point or a cluster, the prefix ends at the boundary before it.maxUnits: The most units the prefix may have. When it falls inside a code point, between the two UTF-16 units of one past U+FFFF, the prefix ends before that code point, so it has one unit fewer.bytesOut: Receives the prefix's length in bytes, 0 when the first unit does not fit. May be NULL.unitsOut: Receives the prefix's length in units. May be NULL. muni_errorInvalid leaves both as they were.Returns: muni_success, or muni_errorInvalid for a NULL text with a nonzero length or an unknown unit.
Thread safety. Safe from any thread.
MUNI_NODISCARD MUNI_API muniResult muniFindGraphemeBreaks(const char* text, size_t length, size_t* offsetsOut, size_t capacity, size_t* countOut);
Writes the grapheme cluster boundaries of a whole UTF-8 text into a caller array: every boundary after the start, the end included.
Parameters:
text: The text. May be NULL when length is 0.length: The number of bytes.offsetsOut: The output. May be NULL when capacity is 0.capacity: The number of offsets the output can hold.countOut: Receives the number of boundaries, which may exceed capacity; the ones that fit are written. muni_errorInvalid leaves both as they were.Returns: muni_success, muni_errorCapacity when they do not all fit, or muni_errorInvalid for a NULL argument.
Thread safety. Safe from any thread.
MUNI_NODISCARD MUNI_API muniResult muniFindWordBreaks(const char* text, size_t length, size_t* offsetsOut, size_t capacity, size_t* countOut);
Writes the word boundaries of a whole UTF-8 text into a caller array: every boundary after the start, the end included.
Parameters:
text: The text. May be NULL when length is 0.length: The number of bytes.offsetsOut: The output. May be NULL when capacity is 0.capacity: The number of offsets the output can hold.countOut: Receives the number of boundaries, which may exceed capacity; the ones that fit are written. muni_errorInvalid leaves both as they were.Returns: muni_success, muni_errorCapacity when they do not all fit, or muni_errorInvalid for a NULL argument.
Thread safety. Safe from any thread.
MUNI_NODISCARD MUNI_API muniResult muniFindSentenceBreaks(const char* text, size_t length, size_t* offsetsOut, size_t capacity, size_t* countOut);
Writes the sentence boundaries of a whole UTF-8 text into a caller array: every boundary after the start, the end included.
Parameters:
text: The text. May be NULL when length is 0.length: The number of bytes.offsetsOut: The output. May be NULL when capacity is 0.capacity: The number of offsets the output can hold.countOut: Receives the number of boundaries, which may exceed capacity; the ones that fit are written. muni_errorInvalid leaves both as they were.Returns: muni_success, muni_errorCapacity when they do not all fit, or muni_errorInvalid for a NULL argument.
Thread safety. Safe from any thread.
MUNI_NODISCARD MUNI_API muniResult muniFindLineBreaks(const char* text, size_t length, size_t* offsetsOut, bool* mandatoryOut, size_t capacity, size_t* countOut);
Writes the line break opportunities of a whole UTF-8 text into caller arrays: every opportunity after the start, the end included, and optionally whether each is mandatory.
Parameters:
text: The text. May be NULL when length is 0.length: The number of bytes.offsetsOut: The output. May be NULL when capacity is 0.mandatoryOut: NULL, or an array of capacity flags that receive true for each mandatory break.capacity: The number of entries the outputs can hold.countOut: Receives the number of opportunities, which may exceed capacity; the ones that fit are written. muni_errorInvalid leaves the offsets, the flags and the count as they were.Returns: muni_success, muni_errorCapacity when they do not all fit, or muni_errorInvalid for a NULL argument.
Thread safety. Safe from any thread.