str

Unicode-aware string utilities for Gleam.

This module re-exports the most commonly used functions from str/core and str/extra for convenient access. For the full API, import the submodules directly.

Quick Start

import str

str.truncate("Hello 👨‍👩‍👧‍👦 World", 10, "...")  // "Hello 👨‍👩‍👧‍👦..."
str.slugify("Crème Brûlée")                 // "creme-brulee"
str.similarity("hello", "hallo")           // 0.8

Types

FillPosition

</>

pub type FillPosition =
  core.FillPosition

Values

ascii_fold

</>

pub fn ascii_fold(text: String) -> String

Converts text to ASCII equivalents.

at

</>

pub fn at(text: String, index: Int) -> Result(String, Nil)

Returns the grapheme cluster at the given index (0-based).

capitalize

</>

pub fn capitalize(text: String) -> String

Capitalizes text: first letter uppercase, rest lowercase.

center

</>

pub fn center(text: String, width: Int, pad: String) -> String

Centers text within the specified width.

contains

</>

pub fn contains(text: String, needle: String) -> Bool

Returns True if needle is found in text (grapheme-aware).

contains_all

</>

pub fn contains_all(text: String, needles: List(String)) -> Bool

Returns True if all of the needles appear in text.

contains_any

</>

pub fn contains_any(text: String, needles: List(String)) -> Bool

Returns True if any of the needles appear in text.

distance

</>

pub fn distance(a: String, b: String) -> Int

Calculates Levenshtein distance between two strings.

drop

</>

pub fn drop(text: String, n: Int) -> String

Drops the first N grapheme clusters from text.

ellipsis

</>

pub fn ellipsis(text: String, max_len: Int) -> String

Truncates text with ellipsis (…).

ends_with

</>

pub fn ends_with(text: String, suffix: String) -> Bool

Returns True if text ends with suffix on grapheme boundaries.

escape_html

</>

pub fn escape_html(text: String) -> String

Escapes HTML special characters.

index_of

</>

pub fn index_of(text: String, needle: String) -> Result(Int, Nil)

Finds the index of the first occurrence of needle (grapheme-aware).

is_ascii

</>

pub fn is_ascii(text: String) -> Bool

Checks if text contains only ASCII characters.

is_blank

</>

pub fn is_blank(text: String) -> Bool

Checks if a string contains only whitespace.

is_empty

</>

pub fn is_empty(text: String) -> Bool

Returns True if text is an empty string.

is_lowercase

</>

pub fn is_lowercase(text: String) -> Bool

Checks if all cased characters are lowercase.

is_title_case

</>

pub fn is_title_case(text: String) -> Bool

Checks if text is in Title Case format.

is_uppercase

</>

pub fn is_uppercase(text: String) -> Bool

Checks if all cased characters are uppercase.

last_index_of

</>

pub fn last_index_of(
  text: String,
  needle: String,
) -> Result(Int, Nil)

Finds the index of the last occurrence of needle.

length

</>

pub fn length(text: String) -> Int

Returns the number of grapheme clusters in text.

lines

</>

pub fn lines(text: String) -> List(String)

Splits text into lines.

normalize_whitespace

</>

pub fn normalize_whitespace(text: String) -> String

Normalizes whitespace: collapses to single spaces and trims.

pad_left

</>

pub fn pad_left(text: String, width: Int, pad: String) -> String

Pads text on the left to reach the specified width.

pad_right

</>

pub fn pad_right(text: String, width: Int, pad: String) -> String

Pads text on the right to reach the specified width.

replace_first

</>

pub fn replace_first(
  text: String,
  old: String,
  new: String,
) -> String

Replaces only the first occurrence of old with new.

replace_last

</>

pub fn replace_last(
  text: String,
  old: String,
  new: String,
) -> String

Replaces only the last occurrence of old with new.

reverse

</>

pub fn reverse(text: String) -> String

Reverses text at grapheme cluster boundaries.

similarity

</>

pub fn similarity(a: String, b: String) -> Float

Calculates similarity as a percentage (0.0 to 1.0).

slugify

</>

pub fn slugify(text: String) -> String

Creates a URL-friendly slug from text.

starts_with

</>

pub fn starts_with(text: String, prefix: String) -> Bool

Returns True if text starts with prefix on grapheme boundaries.

take

</>

pub fn take(text: String, n: Int) -> String

Returns the first N grapheme clusters from text.

to_camel_case

</>

pub fn to_camel_case(text: String) -> String

Converts text to camelCase.

to_kebab_case

</>

pub fn to_kebab_case(text: String) -> String

Converts text to kebab-case.

to_pascal_case

</>

pub fn to_pascal_case(text: String) -> String

Converts text to PascalCase.

to_snake_case

</>

pub fn to_snake_case(text: String) -> String

Converts text to snake_case.

to_title_case

</>

pub fn to_title_case(text: String) -> String

Converts text to Title Case.

truncate

</>

pub fn truncate(
  text: String,
  max_len: Int,
  suffix: String,
) -> String

Truncates text to max_len graphemes, preserving emoji sequences.

unescape_html

</>

pub fn unescape_html(text: String) -> String

Unescapes HTML entities.

words

</>

pub fn words(text: String) -> List(String)

Splits text into words by whitespace.