Collation & text¶
Locale-aware comparison, sorting, substring search, word/sentence segmentation, truncation, case mapping, and quotation — all backed by ICU's collator and break iterators. Use them when byte ordering, simple substring matching, or basic case conversion does not account for the conventions of the text's language.
| Method | Use it for |
|---|---|
compare(a, b, options?) |
A locale-correct comparator for sorting two strings |
sort(items, key?, options?) |
Sort a whole list (optionally by a field) |
contains(haystack, needle, sensitivity?, options?) |
Accent/case-insensitive substring search |
splitWords / splitSentences / splitGraphemes |
Break text on the locale's boundaries |
ellipsize(text, max, ellipsis?) |
Grapheme-safe truncation |
upper(text) / lower(text) |
Locale-aware case mapping |
quote(text) |
Wrap in the locale's quotation marks |
Compare & sort¶
compare() returns a negative number, 0, or a positive number — exactly what a
sort callback wants. sort() does the whole list for you and returns a new
array (it never mutates the input).
Cosmo sv = new Cosmo("sv");
sv.compare("a", "b"); // -1
sv.sort(List.of("år", "zebra", "ar")); // [ar, zebra, år]
// key accessor — sort objects/maps by a field:
sv.sort(people, p -> p.getName());
The same input sorts differently per locale — å is a distinct letter sorting last
in Swedish, but an accented a in German. A collator accounts for these
language-specific ordering rules.
Collation options¶
Both compare() and sort() (and contains()) take a final options bag to
tailor the collator:
| Key | Values | What it does |
|---|---|---|
numeric |
true / false |
Sort embedded numbers by value, so "file2" < "file10" (natural sort). |
caseFirst |
upper · lower · false |
Whether upper- or lower-case sorts first within a letter. |
Substring search¶
Collation-aware contains() can ignore case and accents — so a search box matches
"café" when the user types "cafe". The sensitivity argument controls how
forgiving the match is:
sensitivity |
Ignores | contains("Café", needle) matches |
|---|---|---|
base (default) |
case and accents | "cafe", "CAFÉ", "café" |
accent |
case only | "café", "CAFÉ" — but not "cafe" |
case |
accents only | "cafe", "café" — but not "CAFÉ" |
variant |
nothing (exact) | "Café" only |
Cosmo c = new Cosmo("en");
c.contains("Café society", "cafe"); // true
c.contains("Café", "cafe", "variant"); // false
The search is grapheme-aware, so it never matches across a combining sequence. An
empty needle returns true (every string contains the empty string).
Word & sentence segmentation¶
Splitting on whitespace fails for Thai, Japanese, and Chinese, which don't put spaces between words. ICU's break iterators use language-specific rules to find word boundaries.
Cosmo c = new Cosmo("en");
c.splitWords("Hello, world! foo"); // [Hello, world, foo]
c.splitSentences("Hi there. How are you?"); // [Hi there., How are you?]
splitWords()keeps only word-like segments — whitespace and punctuation are dropped. Ideal for a word count or building a search index.splitSentences()breaks on sentence boundaries (knows that "Mr." isn't the end of a sentence in English).splitGraphemes()breaks on user-perceived characters, so an emoji ZWJ sequence (👨👩👧) or a combining accent stays a single element — the correct way to count or reverse "characters".
Grapheme-safe truncation¶
ellipsize() truncates to at most N graphemes, prefers to break on a word
boundary, and appends an ellipsis. The ellipsis counts toward the budget and
defaults to … (pass your own as the third argument).
Because it counts graphemes (not bytes or UTF-16 code units), it never cuts a multi-byte character or an emoji in half. Text that already fits is returned unchanged.
Locale-aware case¶
new Cosmo("tr").upper("istanbul"); // "İSTANBUL"
new Cosmo("en").upper("istanbul"); // "ISTANBUL"
new Cosmo("en").lower("HELLO"); // "hello"
These methods honour locale rules, including Turkish dotted and dotless I, German ß, and Lithuanian accents. Convert case using the content's locale, which may differ from the UI language.
Quotation marks¶
quote() wraps text in the locale's quotation marks using CLDR delimiter data.