gossamer/string_extra

Extras for gleam/string — Unicode normalization, locale-aware case conversion, and UTF-16 well-formedness checks.

For constructing a string from Unicode code points, use gleam/string.utf_codepoint together with gleam/string.from_utf_codepoints. For locale-aware comparison, use gossamer/intl/collator.

Types

NormalizationForm

</>

A Unicode normalization form used by normalize_to. NFC and NFD preserve equivalence; NFKC and NFKD also apply compatibility decomposition.

pub type NormalizationForm {
  Nfc
  Nfd
  Nfkc
  Nfkd
}

Constructors

```
Nfc
```
Canonical composition — characters are recomposed into the shortest equivalent form. The default for equivalence comparison.
```
Nfd
```
Canonical decomposition — composed characters are decomposed into their canonical sequence (e.g., é → e + ́).
```
Nfkc
```
Compatibility composition — applies compatibility decomposition then canonical composition. Lossy: visually similar forms collapse (e.g., ﬁ → fi).
```
Nfkd
```
Compatibility decomposition — like Nfd but also decomposes compatibility variants. Lossy in the same way as Nfkc.

Values

is_well_formed

</>

pub fn is_well_formed(string: String) -> Bool

True when string is a well-formed UTF-16 sequence — every surrogate is part of a valid pair. Equivalent to JavaScript’s String.prototype.isWellFormed.

normalize

</>

pub fn normalize(string: String) -> String

Returns the NFC-normalized form of string. NFC is the canonical choice for equivalence comparison. Equivalent to JavaScript’s String.prototype.normalize().

normalize_to

</>

pub fn normalize_to(
  string: String,
  form: NormalizationForm,
) -> String

Returns the normalized form of string for the given form. Equivalent to JavaScript’s String.prototype.normalize(form).

to_locale_lowercase

</>

pub fn to_locale_lowercase(
  string: String,
  locales: List(String),
) -> Result(String, Nil)

Returns string lowercased using the first supported locale from locales (or the runtime’s default locale when the list is empty). Differs from gleam/string.lowercase for locale-specific casing rules (e.g., Turkish lowercases "I" to dotless "ı", not "i"). Returns Error(Nil) if any tag in locales is structurally invalid. Equivalent to JavaScript’s String.prototype.toLocaleLowerCase.

to_locale_uppercase

</>

pub fn to_locale_uppercase(
  string: String,
  locales: List(String),
) -> Result(String, Nil)

Returns string uppercased using the first supported locale from locales (or the runtime’s default locale when the list is empty). Differs from gleam/string.uppercase for locale-specific casing rules. Returns Error(Nil) if any tag in locales is structurally invalid. Equivalent to JavaScript’s String.prototype.toLocaleUpperCase.

to_well_formed

</>

pub fn to_well_formed(string: String) -> String

Returns string with any lone surrogate replaced by U+FFFD (replacement character). Equivalent to JavaScript’s String.prototype.toWellFormed.