Text Module

The aivi.text module provides core string and character utilities for Text and Char. It focuses on predictable, Unicode-aware behavior, and uses Option/Result instead of sentinel values like -1.

Overview

use aivi.text

greeting = "Hello, AIVI!"

len = length greeting
words = split " " greeting
upper = toUpper greeting

Types

type Bytes
type Encoding = Utf8 | Utf16 | Utf32 | Latin1
type TextError = InvalidEncoding Encoding

Core API (v0.1)

Length and inspection

Function	Explanation
length text Text -> Int	Returns the number of Unicode scalar values in text.
isEmpty text Text -> Bool	Returns true when text has zero length.

Character predicates

Function	Explanation
isDigit char Char -> Bool	Returns whether char is a Unicode digit.
isAlpha char Char -> Bool	Returns whether char is a Unicode letter.
isAlnum char Char -> Bool	Returns whether char is a Unicode letter or digit.
isSpace char Char -> Bool	Returns whether char is a Unicode whitespace.
isUpper char Char -> Bool	Returns whether char is uppercase.
isLower char Char -> Bool	Returns whether char is lowercase.

Search and comparison

Function	Explanation
contains haystack needle Text -> Text -> Bool	Returns whether needle occurs in haystack.
startsWith text prefix Text -> Text -> Bool	Returns whether text starts with prefix.
endsWith text suffix Text -> Text -> Bool	Returns whether text ends with suffix.
indexOf haystack needle Text -> Text -> Option Int	Returns the first index of needle, or None when not found.
lastIndexOf haystack needle Text -> Text -> Option Int	Returns the last index of needle, or None when not found.
count haystack needle Text -> Text -> Int	Returns the number of non-overlapping occurrences.
compare a b Text -> Text -> Int	Returns -1, 0, or 1 in Unicode codepoint order (not locale-aware).

Notes:

• indexOf and lastIndexOf return None when not found.

Slicing and splitting

Function	Explanation
slice start end text Int -> Int -> Text -> Text	Returns the substring from start (inclusive) to end (exclusive).
split sep text Text -> Text -> List Text	Splits text on sep.
splitLines text Text -> List Text	Splits on line endings.
chunk size text Int -> Text -> List Text	Splits into codepoint chunks of length size.

Notes:

• slice start end text is half-open (start inclusive, end exclusive) and clamps out-of-range indices.
• chunk splits by codepoint count, not bytes.

Trimming and padding

Function	Explanation
trim text Text -> Text	Removes Unicode whitespace from both ends.
trimStart text Text -> Text	Removes Unicode whitespace from the start.
trimEnd text Text -> Text	Removes Unicode whitespace from the end.
padStart width fill text Int -> Text -> Text -> Text	Pads on the left to reach width using repeated fill.
padEnd width fill text Int -> Text -> Text -> Text	Pads on the right to reach width using repeated fill.

Notes:

• padStart width fill text repeats fill as needed and truncates extra.

Modification

Function	Explanation
replace text needle replacement Text -> Text -> Text -> Text	Replaces the first occurrence of needle.
replaceAll text needle replacement Text -> Text -> Text -> Text	Replaces all occurrences of needle.
remove text needle Text -> Text -> Text	Removes all occurrences of needle.
repeat count text Int -> Text -> Text	Repeats text count times.
reverse text Text -> Text	Reverses grapheme clusters.
concat parts List Text -> Text	Concatenates all parts into one Text.

Notes:

• replace changes the first occurrence only.
• remove is replaceAll needle "".
• reverse is grapheme-aware and may be linear-time with extra allocations.

Case and normalization

Function	Explanation
toLower text Text -> Text	Converts to lowercase using Unicode rules.
toUpper text Text -> Text	Converts to uppercase using Unicode rules.
capitalize text Text -> Text	Uppercases the first grapheme and lowercases the rest.
titleCase text Text -> Text	Converts to title case using Unicode rules.
caseFold text Text -> Text	Produces a case-folded form for case-insensitive comparisons.
normalizeNFC text Text -> Text	Normalizes to NFC.
normalizeNFD text Text -> Text	Normalizes to NFD.
normalizeNFKC text Text -> Text	Normalizes to NFKC.
normalizeNFKD text Text -> Text	Normalizes to NFKD.

Encoding / decoding

Function	Explanation
toBytes encoding text Encoding -> Text -> Bytes	Encodes text into Bytes using encoding.
fromBytes encoding bytes Encoding -> Bytes -> Result TextError Text	Decodes bytes and returns TextError on invalid input.

Formatting and conversion

Function	Explanation
toText value Show a => a -> Text	Formats any Show instance into Text.
parseInt text Text -> Option Int	Parses a decimal integer, returning None on failure.
parseFloat text Text -> Option Float	Parses a decimal float, returning None on failure.

Usage Examples

use aivi.text

slug = "  Hello World  "
clean = slug |> trim |> toLower |> replaceAll " " "-"

maybePort = parseInt "8080"