tinystring

TinyString

TinyString is a lightweight Go library that provides comprehensive string manipulation, type conversion, formatting, and multilingual error handling with a fluid API, specifically designed for small devices and web applications using TinyGo as the target compiler.

Key Features

• 🚀 Fluid and chainable API - Easy to use and readable operations
• 📝 Complete string toolkit - Transformations, conversions, formatting, and error handling
• 🌍 Multilingual error messages - Built-in dictionary system with 9 languages
• 🧵 Concurrency safe - Thread-safe operations for concurrent environments
• 📦 Zero dependencies - No fmt, strings, strconv, or errors imports
• 🎯 TinyGo optimized - Manual implementations for minimal binary size
• 🌐 WebAssembly-first - Designed for modern web deployment
• 🔄 Universal type support - Works with strings, numbers, booleans, and slices
• ⚡ Performance focused - Predictable allocations and custom optimizations

Why TinyString?

Installation

go get github.com/cdvelop/tinystring

Usage

import "github.com/cdvelop/tinystring"

// Quick start - Basic conversion and transformation
text := tinystring.Convert("Hóla Múndo").Tilde().Low().String()
// out: "hola mundo"

// Working with different data types
numText := tinystring.Convert(42).String()     // out: "42"
boolText := tinystring.Convert(true).String()  // out: "true"

// Memory-efficient approach using string pointers
original := "Él Múrcielago Rápido"
tinystring.Convert(&original).Tilde().CamelLow().Apply()
// original is now: "elMurcielagoRapido"

// Multilingual error messages (NEW!)
import . "github.com/cdvelop/tinystring"

OutLang(ES) // Set Spanish
err := Err(D.Invalid, D.Format)
// out: "inválido formato"

OutLang()   // Auto-detect system language
err = Err(D.Cannot, D.Round, D.NonNumeric, D.Value).Error()
// Output in user's detected language

🔧 Builder API

TinyString features a high-performance builder API for memory-efficient string operations. All operations work on a single internal buffer with object pooling.

Efficient Loop Processing

import "github.com/cdvelop/tinystring"

// Memory-efficient processing in loops
items := []string{"  APPLE  ", "  banana  ", "  Cherry  "}

c := tinystring.Convert() // Empty initialization
for i, item := range items {
    c.Write(item).Trim().Low().Capitalize()
    if i < len(items)-1 {
        c.Write(" - ")
    }
}
result := c.String() // "Apple - Banana - Cherry"

Key Builder Operations

// Reuse builder for multiple operations
builder := tinystring.Convert()

// Operation 1: Reset and build
builder.Reset()
result1 := builder.Write("Hello").Write(" World").String()

// Operation 2: Reset and transform
builder.Reset()
original := "test string"
tinystring.Convert(&original).Up().Tilde().Apply()
// original is now: "TEST STRING" - modified in-place

📚 Standard Library Equivalents

🔤 strings Package

Replace common strings package functions with TinyString equivalents:

Builder API Advantages

The Builder API is especially efficient for complex operations:

// ❌ Standard approach - multiple allocations
result := tinystring.Convert("Hello").Up().String() + " " + 
          tinystring.Convert("World").Low().String() + "!"
// Multiple Convert() calls = multiple allocations

// ✅ Builder approach - single allocation
result := tinystring.Convert().
    Write("Hello").Up().
    Write(" ").
    Write("World").Low().
    Write("!").
    String()
// Single Convert() + reused buffer = optimal performance

Chaining Operations

// Combine multiple operations efficiently
result := tinystring.Convert("  HÓLA MÚNDO  ")
    .Trim()
    .Tilde()
    .Low()
    .Replace(" ", "_")
    .String()
// out: "hola_mundo"

🌍 Unicode & Localization

// Remove accents and diacritics (Ñ/ñ are preserved)
tinystring.Convert("café naïve résumé Ñoño niño").Tilde().String()  
// out: "cafe naive resume Ñono nino"

String Transformations

// Case conversions
tinystring.Convert("HELLO").Low().String()              // out: "hello"
tinystring.Convert("world").Up().String()              // out: "WORLD"
tinystring.Convert("hello world").Capitalize().String()     // out: "Hello World"

// Advanced case styles
tinystring.Convert("hello world").CamelLow().String()   // out: "helloWorld"
tinystring.Convert("hello world").CamelUp().String()   // out: "HelloWorld"
tinystring.Convert("hello world").SnakeLow().String() // out: "hello_world"
tinystring.Convert("hello world").SnakeUp().String() // out: "HELLO_WORLD"

String Search & Operations

// Search and count
found := tinystring.Contains("hello world", "world")              // out: true
count := tinystring.Count("abracadabra", "abra")       // out: 2

// ⚠️ Note: Contains is a global function, not a method.
// Do NOT use: tinystring.Convert(s).Contains(substr) // ❌ Incorrect, will not compile
// Use:        tinystring.Contains(s, substr)         // ✅ Correct

// Replace operations
tinystring.Convert("hello world").Replace("world", "Go").String() // out: "hello Go"
tinystring.Convert("test 123 test").Replace(123, 456).String()    // out: "test 456 test"

String Splitting & Joining

// Split strings
parts := tinystring.Split("apple,banana,cherry", ",")    
// out: []string{"apple", "banana", "cherry"}

parts := tinystring.Split("hello\tworld\nnew")  // Handles whitespace
// out: []string{"hello", "world", "new"}

// Join slices
tinystring.Convert([]string{"Hello", "World"}).Join().String()    // out: "Hello World"
tinystring.Convert([]string{"a", "b", "c"}).Join("-").String()    // out: "a-b-c"

String Trimming & Cleaning

// Trim operations
tinystring.Convert("  hello  ").Trim().String()                    // out: "hello"
tinystring.Convert("prefix-data").TrimPrefix("prefix-").String()    // out: "data"
tinystring.Convert("file.txt").TrimSuffix(".txt").String()          // out: "file"

// Repeat strings
tinystring.Convert("Go").Repeat(3).String()                        // out: "GoGoGo"

🔢 strconv Package

Replace strconv package functions for type conversions:

Type Conversions

// String to numbers
result, err := tinystring.Convert("123").ToInt()        // out: 123, nil
result, err := tinystring.Convert("456").ToUint()       // out: 456, nil  
result, err := tinystring.Convert("3.14").ToFloat64()     // out: 3.14, nil

// Numbers to string
tinystring.Convert(42).String()      // out: "42"
tinystring.Convert(3.14159).String() // out: "3.14159"

// Boolean conversions
result, err := tinystring.Convert("true").ToBool()  // out: true, nil
result, err := tinystring.Convert(42).ToBool()      // out: true, nil (non-zero = true)
result, err := tinystring.Convert(0).ToBool()       // out: false, nil

// String quoting
tinystring.Convert("hello").Quote().String()           // out: "\"hello\""
tinystring.Convert("say \"hello\"").Quote().String()  // out: "\"say \\\"hello\\\"\""

Number Formatting

// Decimal rounding: keep N decimals, round or truncate
// By default, rounds using "round half to even" (bankers rounding)
// Pass true as second argument to truncate instead of round
Convert("3.14159").Round(2)        // "3.14"
Convert("3.155").Round(2)          // "3.16"
Convert("3.14159").Round(2, true)  // "3.14" (truncated)

// Formatting with thousands separator
tinystring.Convert(2189009.00).Thousands().String()        // out: "2.189.009"

🖨️ fmt Package

Replace fmt package functions for formatting:

String Formatting

// Printf-style formatting
result := tinystring.Fmt("Hello %s, you have %d messages", "John", 5)
// out: "Hello John, you have 5 messages"

// Multiple format specifiers
result := tinystring.Fmt("Number: %d, Float: %.2f, Bool: %v", 42, 3.14159, true)
// out: "Number: 42, Float: 3.14, Bool: true"

// Advanced formatting (hex, binary, octal)
result := tinystring.Fmt("Hex: %x, Binary: %b, Octal: %o", 255, 10, 8)
// out: "Hex: ff, Binary: 1010, Octal: 10"

❌ errors Package

Replace errors package functions for error handling with multilingual support:

Error Creation

// Multiple error messages and types
err := tinystring.Err("invalid format", "expected number", 404)
// out: "invalid format expected number 404"

// Formatted errors (like fmt.Errorf)
err := tinystring.Errf("invalid value: %s at position %d", "abc", 5)
// out: "invalid value: abc at position 5"

🚀 TinyString Exclusive Features

🌍 TinyString: Multilingual & Translation Support

TinyString enables multilingual error messages using reusable dictionary terms. It supports 9 languages and allows global or inline language selection.

import . "github.com/cdvelop/tinystring"

OutLang(ES) // Set global language to Spanish or OutLang() without parameters to Auto-detect system/browser language

err := Err(D.Format, D.Invalid)
// → "formato inválido"

// Force French
err = Err(FR, D.Empty, D.String)
// → "vide chaîne"

See dictionary.go for built-in words. Combine D. (default terms) and custom dictionaries for flexible messaging.

📘 Full documentation available in docs/TRANSLATE.md

✂️ Smart Truncation

// Basic truncation with ellipsis
tinystring.Convert("Hello, World!").Truncate(10).String()       
// out: "Hello, ..."

// Name truncation for UI display
tinystring.Convert("Jeronimo Dominguez").TruncateName(3, 15).String()
// out: "Jer. Dominguez"

// Advanced name handling
tinystring.Convert("Juan Carlos Rodriguez").TruncateName(3, 20).String()
// out: "Jua. Car. Rodriguez"

🔧 Advanced Utilities

// Key-value parsing default use :
value, err := tinystring.ParseKeyValue("user:admin")            // out: "admin", nil
value, err := tinystring.ParseKeyValue("count=42", "=")         // out: "42", nil

// Snake case with custom separators
tinystring.Convert("hello world").SnakeLow("-").String() // out: "hello-world"
tinystring.Convert("hello world").SnakeUp("_").String() // out: "HELLO_WORLD"

💡 Performance Tips String() vs Apply()

// String() - Returns the result, original remains unchanged
original := "Él Múrcielago Rápido"
result := tinystring.Convert(original).Tilde().Low().String()
// result: "el murcielago rapido"
// original: "Él Múrcielago Rápido"

// Apply() - Modifies the original string directly (more memory efficient)
// note: only support strings pointer
tinystring.Convert(&original).Tilde().Low().Apply()
// original: "el murcielago rapido"

// There are only two ways to finalize operations: using String() or Apply().

Benchmarking

Contributing