Skip to content

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.

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).

new Cosmo("en").ellipsize("The quick brown fox", 12);   // "The quick…"

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.

new Cosmo("en").quote("hello");    // “hello”
new Cosmo("de").quote("hallo");    // „hallo“
new Cosmo("fr").quote("bonjour");  // « bonjour »