Home / Docs / String Utilities

string_utils

Rich, immutable string operations for GALA with full functional programming support.

Import

import (
    . "martianoff/gala/string_utils"
)

Overview

The Str type uses lazy dual storage — a Lazy[Array[rune]] and a cached Go string — providing:

• O(1) creation - Rune array construction is deferred until first functional operation
• O(1) ToString, Equals, Contains - Direct access to cached Go string
• Efficient chaining - String-based operations (ToUpper, Trim, etc.) use cached string directly without triggering rune conversion
• Functional methods - Map, Filter, Fold, etc. evaluate the lazy rune array on first use and cache the result
• Pattern matching - NonEmptyStr and EmptyStr extractors

Quick Start

// Create a Str
val s = S("Hello, World!")

// Chain operations
val result = s.Trim().ToLower().ReplaceAll(",", "").ReplaceAll("!", "")
// result.ToString() == "hello world"

// Functional operations
val upper = S("hello").Map((r rune) => unicode.ToUpper(r))
val noSpaces = S("hello world").Filter((r rune) => r != rune(32))

// Pattern matching
S("hello") match {
    case NonEmptyStr(head, tail) => Println(s"First: ${string(head)}")
    case EmptyStr(_) => Println("Empty")
}

API Reference

Constructor

Basic Operations

Slicing

Case Transformations

Trimming

Replacement

Other Transformations

Splitting & Joining

Concatenation

Predicates

Search

Comparison

Functional Operations

These methods delegate to Array[rune] for efficiency:

Conversion

Pattern Matching Extractors

// NonEmptyStr extracts (head, tail)
type NonEmptyStr struct {}
func (n NonEmptyStr) Unapply(s Str) Option[Tuple[rune, Str]]

// EmptyStr matches empty strings
type EmptyStr struct {}
func (e EmptyStr) Unapply(s Str) Option[bool]

Examples

Chained Transformations

val cleaned = S("  Hello, World!  ")
    .Trim()
    .ToLower()
    .ReplaceAll(",", "")
    .ReplaceAll("!", "")
// cleaned.ToString() == "hello world"

Functional Operations

// Map: shift each character
val shifted = S("abc").Map((r rune) => r + 1)
// shifted.ToString() == "bcd"

// Filter: keep only vowels
val vowels = S("hello world").Filter((r rune) => {
    return r == rune(97) || r == rune(101) || r == rune(105) || r == rune(111) || r == rune(117)
})
// vowels.ToString() == "eoo"

// Fold: count characters
val count = S("hello").Fold(0, (acc int, r rune) => acc + 1)
// count == 5

Predicate Methods

// These delegate to ForAll for efficiency
S("hello").IsAlpha()        // true
S("12345").IsNumeric()      // true
S("hello123").IsAlphanumeric() // true
S("   \t").IsWhitespace()   // true
S("HELLO").IsUpper()        // true
S("hello").IsLower()        // true

Pattern Matching

func describe(s Str) string = s match {
    case EmptyStr(_) => "empty"
    case NonEmptyStr(head, tail) => {
        if tail.IsEmpty() {
            return "single character: " + string(head)
        }
        return "starts with " + string(head) + ", rest: " + tail.ToString()
    }
}

describe(S(""))       // "empty"
describe(S("a"))      // "single character: a"
describe(S("hello"))  // "starts with h, rest: ello"

Splitting and Joining

// Split
val parts = S("a,b,c").Split(",")
// parts == Array[Str]{S("a"), S("b"), S("c")}

// SplitAt
val (left, right) = S("hello").SplitAt(2)
// left.ToString() == "he", right.ToString() == "llo"

// Join
val joined = Join(ArrayOf(S("a"), S("b"), S("c")), "-")
// joined.ToString() == "a-b-c"

// Lines
val lines = S("line1\nline2\nline3").Lines()
// lines.Length() == 3

// Words
val words = S("hello  world\tfoo").Words()
// words.Length() == 3

Padding

S("42").PadLeft(5, rune(48))   // "00042" (pad with '0')
S("hi").PadRight(5, rune(45))  // "hi---" (pad with '-')
S("a").Center(5, rune(45))     // "--a--"

StringBuilder

StringBuilder is a mutable string builder for efficient string concatenation, following the same mutable pattern as collection_mutable.

Construction

val sb = NewStringBuilder()                    // empty
val sb2 = NewStringBuilderFrom(S("hello"))     // from Str
val sb3 = NewStringBuilderFromString("hello")  // from Go string

Appending (Chainable)

All append methods return *StringBuilder for chaining:

// Str-based (primary API)
sb.Append(S("hello"))             // append Str
sb.AppendLine(S("hello"))         // append Str + newline
sb.AppendRune('*')                // append single rune

// Go string-based (secondary API)
sb.AppendString("hello")          // append Go string
sb.AppendStringLine("hello")      // append Go string + newline

// Chaining
val result = NewStringBuilder()
    .AppendString("hello")
    .AppendString(" ")
    .AppendString("world")
    .ToString()  // "hello world"

Output

sb.ToStr()     // returns Str (primary)
sb.ToString()  // returns Go string
sb.String()    // Go Stringer interface

State

sb.Length()     // byte length
sb.RuneCount() // character count
sb.IsEmpty()   // true if no content
sb.NonEmpty()  // true if has content
sb.Reset()     // clears content

Performance Benchmarks

Benchmark results comparing GALA Str to Go native string operations on a 1,000-character ASCII string.

Running the Benchmarks

# GALA Str benchmark
bazel run //string_utils:perf_gala

# Go native benchmark
bazel run //string_utils:perf_go

Str vs Go String (ns/op) - 1,000 Characters

Functional Operations (ns/op) - 1,000 Characters

StringBuilder vs strings.Builder (ns/op)

Key Performance Insights

Near Go-native (1.0-1.2x):

• Contains(), Equals(), Concat() — Direct operations on cached Go string
• ToUpper(), ToLower(), ReplaceAll() — Delegates to strings package, lazy runes not triggered
• Creation — Faster than Go native thanks to lazy rune conversion

Moderate overhead (4-14x):

• Map, Filter, Reverse — Immutable Array[rune] trie overhead (first call evaluates lazy)
• Split — ArrayTabulate builds Array[Str] efficiently via arrayBuilder
• StringBuilder — Raw string storage with strings.Join assembly

Higher overhead (16-20x):

• ForEach+Count — Per-element function call overhead on Array[rune]
• AppendRune — string(r) conversion per rune + mutable array growth

Design Notes

Lazy Dual Storage Architecture

Str stores a Lazy[Array[rune]] and a cached Go string:

type Str struct {
    runes *lazy.Lazy[Array[rune]]   // deferred until first functional op
    str string                       // always available
}

• Cached string enables O(1) ToString(), Equals(), Contains(), IndexOf(), and near-native ToUpper(), ToLower(), ReplaceAll()
• Lazy rune array is only evaluated when functional operations (Map, Filter, CharAt, etc.) are called. Once evaluated, the result is cached for subsequent calls.

18 str-only methods (Contains, StartsWith, ToUpper, Split, etc.) never trigger rune conversion. Only 28 rune-accessing methods (Map, Filter, CharAt, Reverse, etc.) evaluate the lazy on first use.

Construction strategies:

• strFromString(s) — defers rune conversion via lazy.New
• strFromRunes(runes) — already-evaluated via lazy.Of
• String-based ops (ToUpper, Trim, etc.) — return new Str with deferred runes
• Concat — defers rune concatenation, immediately concatenates strings

StringBuilder Optimization

StringBuilder stores raw string parts instead of Str values:

• Append/AppendString store Go strings directly (no rune conversion)
• ToString() assembles via strings.Join — O(n) instead of O(n^2)
• ToStr() converts the final string to Str once