str

Unicode-aware string utilities for Gleam.

This is the main public API for the str library. All functionality is re-exported from internal modules for your convenience.

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

Core Functions

Grapheme operations: take, drop, at, reverse, length
Truncation: truncate, ellipsis, truncate_strict, truncate_preserve
Padding: pad_left, pad_right, center
Search: index_of, last_index_of, contains, starts_with, ends_with
Validation: is_blank, is_empty, is_ascii, is_uppercase, etc.
Similarity: distance, similarity, hamming_distance
Text manipulation: words, lines, capitalize, normalize_whitespace
HTML: escape_html, unescape_html

Extra Functions

Slugification: slugify, slugify_opts
ASCII folding: ascii_fold, ascii_fold_no_decompose
Case conversion: to_snake_case, to_camel_case, to_pascal_case, to_kebab_case, to_title_case

Advanced Features

Search strategies: KMP and sliding window algorithms with automatic selection
Grapheme tokenization: Pure Gleam Unicode segmentation
Configuration: Customizable search heuristics via str/config

Note on Internal Modules

The str/internal/* modules are implementation details and should not be imported directly. They may change without notice between minor versions. Always use import str for stable public API.

Types

FillPosition

</>

Position for fill operations.

pub type FillPosition {
  Left
  Right
  Both
}

Constructors

```
Left
```
```
Right
```
```
Both
```

SearchStrategy

</>

Search strategy selection (automatic, KMP, or sliding window).

pub type SearchStrategy {
  Sliding
  Kmp
}

Constructors

```
Sliding
```
```
Kmp
```

Values

ascii_fold

</>

pub fn ascii_fold(text: String) -> String

Converts text to ASCII equivalents.

Examples

ascii_fold("Café")
// -> "Cafe"

ascii_fold_no_decompose

</>

pub fn ascii_fold_no_decompose(text: String) -> String

ASCII folding without Unicode decomposition.

ascii_fold_no_decompose_with_normalizer

</>

pub fn ascii_fold_no_decompose_with_normalizer(
  text: String,
  normalizer: fn(String) -> String,
) -> String

ASCII folding without decomposition, with custom normalizer.

ascii_fold_with_normalizer

</>

pub fn ascii_fold_with_normalizer(
  text: String,
  normalizer: fn(String) -> String,
) -> String

ASCII folding with custom normalizer.

at

</>

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

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

Examples

at("Hello", 1)
// -> Ok("e")

build_kmp_maps

</>

pub fn build_kmp_maps(
  pattern: String,
) -> #(dict.Dict(Int, String), dict.Dict(Int, Int))

Builds optimized KMP lookup maps.

build_prefix_table

</>

pub fn build_prefix_table(pattern: String) -> List(Int)

Builds KMP prefix table for pattern.

capitalize

</>

pub fn capitalize(text: String) -> String

Capitalizes text: first letter uppercase, rest lowercase.

Examples

capitalize("hello WORLD")
// -> "Hello world"

center

</>

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

Centers text within the specified width.

Examples

center("Hi", 6, " ")
// -> "  Hi  "

chars

</>

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

Pure Gleam grapheme tokenizer (approximates Unicode segmentation).

This is an experimental pure-Gleam implementation that approximates Unicode grapheme cluster segmentation without external dependencies.

chars_stdlib

</>

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

BEAM stdlib grapheme tokenizer (uses platform’s Unicode support).

This wraps the standard library’s grapheme segmentation for comparison and compatibility.

chomp

</>

pub fn chomp(text: String) -> String

Removes trailing newline from text.

choose_search_strategy

</>

pub fn choose_search_strategy(
  text: String,
  pattern: String,
) -> SearchStrategy

Chooses optimal search strategy based on input.

chunk

</>

pub fn chunk(text: String, size: Int) -> List(String)

Splits text into chunks of the specified size.

common_prefix

</>

pub fn common_prefix(strings: List(String)) -> String

Finds common prefix of all strings.

common_suffix

</>

pub fn common_suffix(strings: List(String)) -> String

Finds common suffix of all strings.

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.

count

</>

pub fn count(
  haystack: String,
  needle: String,
  overlapping: Bool,
) -> Int

Counts occurrences of needle in haystack.

count_auto

</>

pub fn count_auto(
  haystack: String,
  needle: String,
  overlapping: Bool,
) -> Int

Automatic search strategy selection for count.

count_simple

</>

pub fn count_simple(
  haystack: String,
  needle: String,
  overlapping: Bool,
) -> Int

Simple (direct) count algorithm — stable, straightforward implementation. Use count_auto for heuristic/optimized selection.

count_strategy

</>

pub fn count_strategy(
  haystack: String,
  needle: String,
  overlapping: Bool,
  strategy: SearchStrategy,
) -> Int

Count with explicit strategy selection.

dedent

</>

pub fn dedent(text: String) -> String

Removes common leading whitespace from all lines.

distance

</>

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

Calculates Levenshtein distance between two strings.

Examples

distance("kitten", "sitting")
// -> 3

drop

</>

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

Drops the first N grapheme clusters from text.

Examples

drop("Hello World", 6)
// -> "World"

drop_right

</>

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

Drops the last 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.

ends_with_any

</>

pub fn ends_with_any(
  text: String,
  suffixes: List(String),
) -> Bool

Returns True if text ends with any of the suffixes.

ensure_prefix

</>

pub fn ensure_prefix(text: String, prefix: String) -> String

Ensures text starts with prefix.

ensure_suffix

</>

pub fn ensure_suffix(text: String, suffix: String) -> String

Ensures text ends with suffix.

escape_html

</>

pub fn escape_html(text: String) -> String

Escapes HTML special characters.

Examples

escape_html("<div>Hello & goodbye</div>")
// -> "&lt;div&gt;Hello &amp; goodbye&lt;/div&gt;"

escape_regex

</>

pub fn escape_regex(text: String) -> String

Escapes special regex characters.

fill

</>

pub fn fill(
  text: String,
  width: Int,
  pad: String,
  position: FillPosition,
) -> String

Fills text to specified width with padding at position.

hamming_distance

</>

pub fn hamming_distance(a: String, b: String) -> Result(Int, Nil)

Calculates Hamming distance between strings of equal length.

indent

</>

pub fn indent(text: String, spaces: Int) -> String

Adds indentation to each line.

index_of

</>

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

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

Examples

index_of("Hello World", "World")
// -> Ok(6)

index_of_auto

</>

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

Automatic search strategy selection for index_of.

index_of_simple

</>

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

Simple (direct) index algorithm — stable, straightforward implementation. Use index_of_auto for heuristic/optimized selection.

index_of_strategy

</>

pub fn index_of_strategy(
  text: String,
  needle: String,
  strategy: SearchStrategy,
) -> Result(Int, Nil)

Search with explicit strategy selection.

initials

</>

pub fn initials(text: String) -> String

Extracts initials from text.

is_alpha

</>

pub fn is_alpha(text: String) -> Bool

Checks if text contains only alphabetic characters.

is_alphanumeric

</>

pub fn is_alphanumeric(text: String) -> Bool

Checks if text contains only alphanumeric characters.

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_hex

</>

pub fn is_hex(text: String) -> Bool

Checks if text is a valid hexadecimal string.

is_lowercase

</>

pub fn is_lowercase(text: String) -> Bool

Checks if all cased characters are lowercase.

is_numeric

</>

pub fn is_numeric(text: String) -> Bool

Checks if text contains only numeric characters.

is_printable

</>

pub fn is_printable(text: String) -> Bool

Checks if text contains only printable characters.

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.

kmp_border_multiplier

</>

pub fn kmp_border_multiplier() -> Int

Multiplier applied to max border to decide repetitiveness.

kmp_index_of

</>

pub fn kmp_index_of(
  text: String,
  pattern: String,
) -> Result(Int, Nil)

KMP search for first occurrence.

kmp_index_of_with_maps

</>

pub fn kmp_index_of_with_maps(
  text: String,
  pattern: String,
  pmap: dict.Dict(Int, String),
  pimap: dict.Dict(Int, Int),
) -> Result(Int, Nil)

KMP search with pre-built maps.

kmp_large_text_min_pat

</>

pub fn kmp_large_text_min_pat() -> Int

Minimum pattern length to consider KMP on large texts.

kmp_large_text_threshold

</>

pub fn kmp_large_text_threshold() -> Int

Threshold for “large” text lengths where KMP may be preferred.

kmp_min_pattern_len

</>

pub fn kmp_min_pattern_len() -> Int

Minimum pattern length to consider KMP algorithm.

kmp_search_all

</>

pub fn kmp_search_all(text: String, pattern: String) -> List(Int)

Finds all occurrences using KMP algorithm.

kmp_search_all_with_maps

</>

pub fn kmp_search_all_with_maps(
  text: String,
  pmap: dict.Dict(Int, String),
  pimap: dict.Dict(Int, Int),
) -> List(Int)

KMP search with pre-built maps for better performance.

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.

Examples

length("Hello 👨‍👩‍👧‍👦")
// -> 7

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.

Examples

pad_left("Hi", 5, " ")
// -> "   Hi"

pad_right

</>

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

Pads text on the right to reach the specified width.

partition

</>

pub fn partition(
  text: String,
  sep: String,
) -> #(String, String, String)

Splits text at separator, returning before, separator, and after.

remove_prefix

</>

pub fn remove_prefix(text: String, prefix: String) -> String

Removes prefix from text if present.

remove_suffix

</>

pub fn remove_suffix(text: String, suffix: String) -> String

Removes suffix from text if present.

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.

Examples

reverse("Hello 👋")
// -> "👋 olleH"

reverse_words

</>

pub fn reverse_words(text: String) -> String

Reverses the order of words in text.

rpartition

</>

pub fn rpartition(
  text: String,
  sep: String,
) -> #(String, String, String)

Splits text at last occurrence of separator.

similarity

</>

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

Calculates similarity as a percentage (0.0 to 1.0).

Examples

similarity("hello", "hallo")
// -> 0.8

sliding_index_of

</>

pub fn sliding_index_of(
  text: String,
  pattern: String,
) -> Result(Int, Nil)

Sliding window search for first occurrence.

sliding_search_all

</>

pub fn sliding_search_all(
  text: String,
  pattern: String,
) -> List(Int)

Finds all occurrences using sliding window algorithm.

slugify

</>

pub fn slugify(text: String) -> String

Creates a URL-friendly slug from text.

Examples

slugify("Crème Brûlée")
// -> "creme-brulee"

slugify_opts

</>

pub fn slugify_opts(
  text: String,
  max_len: Int,
  sep: String,
  preserve_unicode: Bool,
) -> String

Creates slug with detailed options.

slugify_opts_with_normalizer

</>

pub fn slugify_opts_with_normalizer(
  text: String,
  max_len: Int,
  sep: String,
  preserve_unicode: Bool,
  normalizer: fn(String) -> String,
) -> String

Creates slug with options and custom normalizer.

slugify_with_normalizer

</>

pub fn slugify_with_normalizer(
  text: String,
  normalizer: fn(String) -> String,
) -> String

Creates slug with custom normalizer.

smart_search_enabled

</>

pub fn smart_search_enabled() -> Bool

Returns True when smart search is enabled.

splitn

</>

pub fn splitn(text: String, sep: String, n: Int) -> List(String)

Splits text into at most n parts.

squeeze

</>

pub fn squeeze(text: String, char: String) -> String

Reduces consecutive occurrences of char to a single occurrence.

starts_with

</>

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

Returns True if text starts with prefix on grapheme boundaries.

starts_with_any

</>

pub fn starts_with_any(
  text: String,
  prefixes: List(String),
) -> Bool

Returns True if text starts with any of the prefixes.

strip

</>

pub fn strip(text: String, chars: String) -> String

Strips specified characters from both ends.

surround

</>

pub fn surround(
  text: String,
  prefix: String,
  suffix: String,
) -> String

Adds prefix and suffix to text.

swapcase

</>

pub fn swapcase(text: String) -> String

Swaps case of all characters.

take

</>

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

Returns the first N grapheme clusters from text.

Examples

take("Hello 👨‍👩‍👧‍👦", 6)
// -> "Hello "

take_right

</>

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

Returns the last 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.

Examples

to_snake_case("HelloWorld")
// -> "hello_world"

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, adding suffix if truncated.

Examples

truncate("Hello World", 8, "...")
// -> "Hello..."

truncate_default

</>

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

Truncates to max_len with empty suffix.

truncate_preserve

</>

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

Truncates preserving emoji sequences, may exceed max_len slightly.

truncate_strict

</>

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

Truncates strictly at max_len, even if it breaks emoji sequences.

truncate_with_flag

</>

pub fn truncate_with_flag(
  text: String,
  max_len: Int,
  suffix: String,
  keep_whole_emoji: Bool,
) -> String

Truncates with emoji handling control.

unescape_html

</>

pub fn unescape_html(text: String) -> String

Unescapes HTML entities.

unwrap

</>

pub fn unwrap(
  text: String,
  prefix: String,
  suffix: String,
) -> String

Removes prefix and suffix from text if present.

words

</>

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

Splits text into words by whitespace.

wrap_at

</>

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

Wraps text at specified width.