tinystring

README

TinyString

TinyString is a lightweight Go library that provides conv manipulation 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
• 🔄 Common conv transformations - All essential string operations included
• 🧵 Concurrency safe - Thread-safe operations
• 📦 Zero standard library dependencies - No fmt, strings, or strconv imports
• 🎯 TinyGo compatible - Optimized for minimal binary size and embedded systems
• 🌐 Web-ready - Perfect for WebAssembly deployments
• 🔄 Universal type conversion - Support for converting any data type to string
• ⚡ Performance optimized - Manual implementations avoid standard library overhead
• �️ Easily extensible - Clean architecture for adding new operations

Why TinyString?

Traditional Go string libraries rely heavily on the standard library (fmt, strings, strconv), which can significantly increase binary size when using TinyGo for embedded systems or WebAssembly targets. TinyString provides all essential string operations with manual implementations that:

• ✅ Reduce binary size by avoiding standard library imports
• ✅ Ensure TinyGo compatibility without compilation issues
• ✅ Provide predictable performance without hidden allocations
• ✅ Enable deployment to resource-constrained environments
• ✅ Support WebAssembly with minimal overhead

Installation

go get github.com/cdvelop/tinystring

TinyGo Optimization

TinyString is specifically designed for environments where binary size matters. Unlike other string libraries that import standard packages like fmt, strings, and strconv, TinyString implements all functionality manually to achieve significant binary size reductions and optimal WebAssembly compatibility.

Technical Implementation

TinyString achieves its goals through manual implementations of commonly used standard library functions:

Replaced Standard Library Functions

Standard Library	TinyString Implementation	Purpose
strconv.ParseFloat	parseFloatManual	String to float conversion
strconv.FormatFloat	floatToStringManual	Float to string conversion
strconv.ParseInt	parseIntManual	String to integer conversion
strconv.FormatInt	intToStringOptimized	Integer to string conversion
strings.IndexByte	indexByteManual	Byte search in strings
fmt.Sprintf	Custom sprintf implementation	String formatting

Performance Benefits

• No hidden allocations from standard library calls
• Predictable memory usage with manual control
• Reduced binary bloat from unused standard library code
• TinyGo compatibility without compilation warnings
• Custom optimizations for common use cases

Usage

import "github.com/cdvelop/tinystring"

// Basic example with string
conv := tinystring.Convert("MÍ téxtO").RemoveTilde().String()
// Result: "MI textO"

// Examples with other data types
numText := tinystring.Convert(42).String()
// Result: "42"

boolText := tinystring.Convert(true).ToUpper().String()
// Result: "TRUE"

floatText := tinystring.Convert(3.14).String()
// Result: "3.14"

// Chaining operations
conv := tinystring.Convert("Él Múrcielago Rápido")
    .RemoveTilde()
    .CamelCaseLower()
    .String()
// Result: "elMurcielagoRapido"

// Working with string pointers (avoids extra allocations)
// This method reduces memory allocations by modifying the original string directly
originalText := "Él Múrcielago Rápido"
tinystring.Convert(&originalText).RemoveTilde().CamelCaseLower().Apply()
// originalText is now modified directly: "elMurcielagoRapido"

Available Operations

• Convert(v any): Initialize conv processing with any data type (string, *string, int, float, bool, etc.). When using a string pointer (*string) along with the Apply() method, the original string will be modified directly, avoiding extra memory allocations.
• Apply(): Updates the original string pointer with the current content. This method should be used when you want to modify the original string directly without additional allocations.
• String(): Returns the content of the conv as a string without modifying any original pointers.
• RemoveTilde(): Removes accents and diacritics (e.g. "café" -> "cafe")
• ToLower(): Converts to lowercase (e.g. "HELLO" -> "hello")
• ToUpper(): Converts to uppercase (e.g. "hello" -> "HELLO")
• Capitalize(): Capitalizes the first letter of each word (e.g. "hello world" -> "Hello World")
• CamelCaseLower(): Converts to camelCase (e.g. "hello world" -> "helloWorld")
• CamelCaseUpper(): Convert to UpperCase (e.g. "hello world" -> "HelloWorld")
• ToSnakeCaseLower(): Converts to snake_case (e.g. "hello world" -> "hello_world"), With Other Params: ToSnakeCaseLower("-") -> "hello-world"
• ToSnakeCaseUpper(): Convert to SNAKE_CASE (e.g. "hello world" -> "HELLO_WORLD"), With Other Params: ToSnakeCaseUpper("-") -> "HELLO-WORLD"
• Split(data, separator string): Divides a string by a separator and returns a slice of substrings
• Join(sep ...string): Joins elements of a string slice with a specified separator (default: space). (e.g. Convert([]string{"Hello", "World"}).Join() -> "Hello World" or Convert([]string{"Hello", "World"}).Join("-") -> "Hello-World")
• ParseKeyValue(input string, delimiter string): Extracts the value from a key:value string format (e.g. ParseKeyValue("name:John") -> "John", nil)
• Replace(old, new any, n ...int): Replaces occurrences of a substring. If n is provided, replaces up to n occurrences. If n < 0 or not provided, replaces all. The old and new parameters can be of any type (string, int, float, bool) and will be converted to string automatically. (e.g. "hello world" -> "hello universe" or "value 123 here" -> "value 456 here")
• TrimPrefix(prefix string): Removes a specified prefix from the beginning of a string (e.g. "prefix-content" -> "content")
• TrimSuffix(suffix string): Removes a specified suffix from the end of a string (e.g. "file.txt" -> "file")
• Trim(): Removes spaces from the beginning and end of a string (e.g. " hello " -> "hello")
• Contains(conv, search string): Checks if a string contains another, returns boolean (e.g. Contains("hello world", "world") -> true)
• CountOccurrences(conv, search string): Counts how many times a string appears in another (e.g. CountOccurrences("hello hello world", "hello") -> 2)
• Repeat(n int): Repeats the string n times (e.g. "abc".Repeat(3) -> "abcabcabc")
• Truncate(maxWidth any, reservedChars ...any): Truncates conv so that it does not exceed the specified width, adding ellipsis if necessary. If the conv is shorter or equal, it remains unchanged. The maxWidth parameter accepts any numeric type. The reservedChars parameter is optional and also accepts any numeric type. (e.g. "Hello, World!".Truncate(10) -> "Hello, ..." or "Hello, World!".Truncate(10, 3) -> "Hell...")
• TruncateName(maxCharsPerWord any, maxWidth any): Truncates names and surnames in a user-friendly way for displaying in limited spaces like chart labels. It adds abbreviation dots where appropriate and handles the first word specially when there are more than 2 words. Parameters: maxCharsPerWord (maximum characters per word), maxWidth (maximum total length). (e.g. Convert("Jeronimo Dominguez").TruncateName(3, 15) -> "Jer. Dominguez")
• RoundDecimals(decimals int): Rounds a numeric value to the specified number of decimal places with ceiling rounding by default (e.g. Convert(3.154).RoundDecimals(2).String() -> "3.16")
• Down(): Modifies rounding behavior to floor rounding (must be used after RoundDecimals, e.g. Convert(3.154).RoundDecimals(2).Down().String() -> "3.15")
• FormatNumber(): Formats a number with thousand separators and removes trailing zeros after the decimal point (e.g. Convert(2189009.00).FormatNumber().String() -> "2.189.009")
• Format(format string, args ...any): Static function for sprintf-style string formatting with support for %s, %d, %f, %b, %x, %o, %v, %% specifiers (e.g. Format("Hello %s, you have %d messages", "John", 5) -> "Hello John, you have 5 messages")
• StringError(): Returns both the string result and any error that occurred during processing (e.g. result, err := Convert("123").ToInt(); conv, err2 := Convert(result).StringError())
• Quote(): Wraps the string content in quotes with proper escaping of special characters (e.g. Convert("hello").Quote().String() -> "\"hello\"")
• ToBool(): Converts conv content to boolean, supporting string boolean values and numeric values where non-zero = true (e.g. Convert("true").ToBool() -> true, nil or Convert(42).ToBool() -> true, nil)
• ToInt(base ...int): Converts conv content to integer with optional base, supports float truncation (e.g. Convert("123").ToInt() -> 123, nil)
• ToUint(base ...int): Converts conv content to unsigned integer with optional base, supports float truncation (e.g. Convert("456").ToUint() -> 456, nil)
• ToFloat(): Converts conv content to float64 (e.g. Convert("3.14").ToFloat() -> 3.14, nil)

Enhanced Type Conversion and Formatting

TinyString now supports comprehensive type conversion with error handling and advanced formatting features:

String Formatting with Variable Arguments

// Format strings with sprintf-style formatting
result := tinystring.Format("Hello %s, you have %d messages", "John", 5)
// Result: "Hello John, you have 5 messages"

// Support for various format specifiers
result := tinystring.Format("Number: %d, Float: %.2f, Bool: %v", 42, 3.14159, true)
// Result: "Number: 42, Float: 3.14, Bool: true"

// Format with hex, binary, and octal
result := tinystring.Format("Hex: %x, Binary: %b, Octal: %o", 255, 10, 8)
// Result: "Hex: ff, Binary: 1010, Octal: 10"

Advanced Numeric Rounding

// Default rounding behavior (ceiling/up rounding)
result := tinystring.Convert(3.154).RoundDecimals(2).String()
// Result: "3.16"

// Explicit down rounding using Down() method
result := tinystring.Convert(3.154).RoundDecimals(2).Down().String() 
// Result: "3.15"

// Chain with other operations
result := tinystring.Convert(123.987).RoundDecimals(1).Down().ToUpper().String()
// Result: "123.9"

Boolean Conversion

// String to boolean conversion
result, err := tinystring.Convert("true").ToBool()
// Result: true, err: nil

// Numeric to boolean (non-zero = true)
result, err := tinystring.Convert(42).ToBool()
// Result: true, err: nil

result, err := tinystring.Convert(0).ToBool() 
// Result: false, err: nil

// Boolean to string
result := tinystring.Convert(true).String()
// Result: "true"

Enhanced Numeric Conversions

// Integer conversions with float handling
result, err := tinystring.Convert("123").ToInt()
// Result: 123, err: nil

result, err := tinystring.Convert("123.45").ToInt() // Truncates float
// Result: 123, err: nil

// Unsigned integer conversions  
result, err := tinystring.Convert("456").ToUint()
// Result: 456, err: nil

result, err := tinystring.Convert("789.99").ToUint() // Truncates float
// Result: 789, err: nil

// Float conversions
result, err := tinystring.Convert("3.14159").ToFloat()
// Result: 3.14159, err: nil

// Creating from numeric types
result := tinystring.Convert(42).String()
// Result: "42"

result := tinystring.Convert(123).String() 
// Result: "123"

result := tinystring.Convert(3.14).String()
// Result: "3.14"

String Quoting

// Add quotes around strings with proper escaping
result := tinystring.Convert("hello").Quote().String()
// Result: "\"hello\""

// Handle special characters
result := tinystring.Convert("say \"hello\"").Quote().String()
// Result: "\"say \\\"hello\\\"\""

// Quote with newlines and tabs
result := tinystring.Convert("line1\nline2\ttab").Quote().String()
// Result: "\"line1\\nline2\\ttab\""

Error Handling with StringError()

// Get both result and error information
result, err := tinystring.Convert("invalid").ToInt()
if err != nil {
    fmt.Printf("Conversion failed: %v", err)
}

// Use StringError() method for operations that might fail
conv := tinystring.Convert("123.45").RoundDecimals(2)
result, err := conv.StringError()
// Result: "123.45", err: nil (or error if conversion failed)

Chaining New Operations

// Complex chaining with new functionality
result := tinystring.Format("User %s has %d points", "Alice", 95)
formatted := tinystring.Convert(result).Quote().ToUpper().String()
// Result: "\"USER ALICE HAS 95 POINTS\""

// Numeric processing chain
result := tinystring.Convert(123.987)
    .RoundDecimals(2)
    .Down()
    .FormatNumber()
    .String()
// Result: "123.98"

// Type conversion chain
result, err := tinystring.Convert("42")
    .ToInt()
if err == nil {
    formatted := tinystring.Convert(result * 2).Quote().String()
    // Result: "\"84\""
}

Examples

// Remove accents
tinystring.Convert("áéíóú").RemoveTilde().String()
// Result: "aeiou"

// Convert to camelCase
tinystring.Convert("hello world").CamelCaseLower().String()
// Result: "helloWorld"

// Combining operations
tinystring.Convert("HÓLA MÚNDO")
    .RemoveTilde()
    .ToLower()
    .String()
// Result: "hola mundo"

// Converting different data types
tinystring.Convert(123).String()
// Result: "123"

tinystring.Convert(45.67).String()
// Result: "45.67"

tinystring.Convert(true).String()
// Result: "true"

// Convert and transform other data types
tinystring.Convert(456).CamelCaseUpper().String()
// Result: "456"

tinystring.Convert(false).ToUpper().String()
// Result: "FALSE"

// Format number with decimal places
tinystring.Convert(3.12221).RoundDecimals(2).String()
// Result: "3.12"

// Format number with thousand separators
tinystring.Convert(2189009.00).FormatNumber().String()
// Result: "2.189.009"
// Result: "FALSE"

// Split a string by separator
result := tinystring.Split("apple,banana,cherry", ",")
// Result: []string{"apple", "banana", "cherry"}

// Split a string by whitespace (default)
result := tinystring.Split("hello world  test")
// Result: []string{"hello", "world", "test"}

// Split with mixed whitespace characters
result := tinystring.Split("hello\tworld\nnew")
// Result: []string{"hello", "world", "new"}

// Parse key-value string
value, err := tinystring.ParseKeyValue("user:admin")
// Result: value = "admin", err = nil

// Parse with custom delimiter
value, err := tinystring.ParseKeyValue("count=42", "=")
// Result: value = "42", err = nil

// Multiple values with same delimiter
value, err := tinystring.ParseKeyValue("path:usr:local:bin")
// Result: value = "usr:local:bin", err = nil

// Handle error when delimiter is not found
value, err := tinystring.ParseKeyValue("invalidstring")
// Result: value = "", err = error("delimiter ':' not found in string invalidstring")

// Join string slices with default space separator
result := tinystring.Convert([]string{"Hello", "World"}).Join().String()
// Result: "Hello World" 

// Join with custom separator
result := tinystring.Convert([]string{"apple", "banana", "orange"}).Join("-").String()
// Result: "apple-banana-orange"

// Join and chain with other transformations
result := tinystring.Convert([]string{"hello", "world"}).Join().ToUpper().String()
// Result: "HELLO WORLD"

// Replace conv
tinystring.Convert("hello world").Replace("world", "universe").String()
// Result: "hello universe"

// Trim prefix and suffix
tinystring.Convert("prefix-content.txt").TrimPrefix("prefix-").TrimSuffix(".txt").String()
// Result: "content"

// Trim spaces and remove file extension
tinystring.Convert("  file.txt  ").Trim().TrimSuffix(".txt").String()
// Result: "file"

// Chain multiple operations
conv := tinystring.Convert(" User Name ")
    .Trim()
    .Replace(" ", "_")
    .ToLower()
    .String()
// Result: "user_name"

// Search examples
// Check if a string contains another
result := tinystring.Contains("hello world", "world")
// Result: true

// Count occurrences
count := tinystring.CountOccurrences("abracadabra", "abra")
// Result: 2

// Capitalize each word
tinystring.Convert("hello world").Capitalize().String()
// Result: "Hello World"

// Capitalize with accent removal
tinystring.Convert("hólá múndo")
    .RemoveTilde()
    .Capitalize()
    .String()
// Result: "Hola Mundo"

// Repeat a string multiple times
tinystring.Convert("hello ").Repeat(3).String()
// Result: "hello hello hello "

// Repeat with other transformations
tinystring.Convert("test")
    .ToUpper()
    .Repeat(2)
    .String()
// Result: "TESTTEST"

// Zero or negative repetitions returns an empty string
tinystring.Convert("test").Repeat(0).String()
// Result: ""

// Truncate a long string to specific width
tinystring.Convert("Hello, World!").Truncate(10).String()
// Result: "Hello, ..."

// Truncate with reserved characters (explicitly provided)
tinystring.Convert("Hello, World!").Truncate(10, 3).String()
// Result: "Hell..."

// conv shorter than max width remains unchanged
tinystring.Convert("Hello").Truncate(10).String()
// Result: "Hello"

// Truncate names and surnames for display in charts or limited spaces
tinystring.Convert("Jeronimo Dominguez").TruncateName(3, 15).String()
// Result: "Jer. Dominguez"

// Truncate multiple names and surnames with total length limit
tinystring.Convert("Ana Maria Rodriguez").TruncateName(2, 10).String()
// Result: "An. Mar..."

// Handle first word specially when more than 2 words
tinystring.Convert("Juan Carlos Rodriguez").TruncateName(3, 20).String()
// Result: "Jua. Car. Rodriguez"

// Truncate and transform
tinystring.Convert("hello world")
    .ToUpper()
    .Truncate(8)
    .String()
// Result: "HELLO..."

// Truncate with different numeric types
tinystring.Convert("Hello, World!").Truncate(uint8(10), float64(3)).String()
// Result: "Hell..."

// Chaining truncate and repeat
tinystring.Convert("hello")
    .Truncate(6) // Truncate(6) doesn't change "hello"
    .Repeat(2)
    .String()
// Result: "hellohello"

Working with String Pointers

TinyString supports working directly with string pointers to avoid additional memory allocations. This can be especially useful in performance-critical applications or when processing large volumes of conv.

// Create a string variable
conv := "Él Múrcielago Rápido"

// Modify it directly using string pointer and Apply()
// No need to reassign the result
Convert(&conv).RemoveTilde().ToLower().Apply()

// The original variable is modified
fmt.Println(conv) // Output: "el murcielago rapido"

// This approach can reduce memory pressure in high-performance scenarios
// by avoiding temporary string allocations

String() vs Apply()

The library offers two ways to finish a chain of operations:

// 1. Using String() - Returns the result without modifying the original
originalText := "Él Múrcielago Rápido"
result := Convert(&originalText).RemoveTilde().ToLower().String()
fmt.Println(result)        // Output: "el murcielago rapido"
fmt.Println(originalText)  // Output: "Él Múrcielago Rápido" (unchanged)

// 2. Using Apply() - Modifies the original string directly
originalText = "Él Múrcielago Rápido"
Convert(&originalText).RemoveTilde().ToLower().Apply()
fmt.Println(originalText)  // Output: "el murcielago rapido" (modified)

Performance benchmarks show that using string pointers can reduce memory allocations when processing large volumes of conv, which can be beneficial in high-throughput applications or systems with memory constraints.

// Sample benchmark results:

Binary Size Comparison

Last updated: 2025-06-04 12:19:09

Default Optimization

Default TinyGo optimization (-opt=z)

Platform	Standard Library	TinyString	Improvement
Native	1.3 MB	1.1 MB	16.7% smaller
WebAssembly	580.7 KB	232.4 KB	60.0% smaller

Ultra Optimization

Ultra size optimization

Platform	Standard Library	TinyString	Improvement
WebAssembly	141.1 KB	22.8 KB	83.9% smaller

Speed Optimization

Speed optimization

Platform	Standard Library	TinyString	Improvement
WebAssembly	816.0 KB	331.6 KB	59.4% smaller

Debug Optimization

Debug build

Platform	Standard Library	TinyString	Improvement
WebAssembly	1.8 MB	681.5 KB	62.8% smaller

Summary

TinyString consistently produces smaller binaries across all optimization levels and platforms:

• Average binary size reduction: 16.7%
• Consistent improvements across all optimization levels
• WebAssembly builds show similar or better improvements
• Best results with ultra optimization settings

Memory Usage Comparison

Last updated: 2025-06-04 12:19:20

Performance benchmarks comparing memory allocation patterns:

Benchmark	Library	Bytes/Op	Allocs/Op	Time/Op	Memory Improvement	Alloc Improvement
String Processing	Standard	1.2 KB	48	3.0μs	-	-
	TinyString	2.5 KB	46	11.6μs	115.3% more	4.2% less
Number Processing	Standard	1.2 KB	132	4.1μs	-	-
	TinyString	12.9 KB	394	12.2μs	1000.0% more	198.5% more
Mixed Operations	Standard	546 B	44	2.1μs	-	-
	TinyString	3.8 KB	112	6.2μs	615.0% more	154.5% more
String Processing (Pointer Optimization)	Standard	1.2 KB	48	3.0μs	-	-
	TinyString	2.4 KB	38	11.5μs	104.7% more	20.8% less

Trade-offs Analysis

The benchmarks reveal important trade-offs between binary size and runtime performance:

Binary Size Benefits:

• Significantly smaller compiled binaries (16-84% reduction)
• Better compression for WebAssembly targets
• Reduced distribution and deployment overhead

Runtime Memory Considerations:

• Higher memory allocation overhead during execution
• Increased GC pressure due to more allocations
• Trade-off optimizes for storage/distribution size over runtime efficiency

Recommendation:

• Use TinyString for size-constrained environments (embedded, edge computing)
• Consider standard library for memory-intensive runtime workloads
• Evaluate based on specific deployment constraints

Contributing

Contributions are welcome. Please open an issue to discuss proposed changes.

License

MIT License

Documentation

Overview

Example (StringPointerBasic)

Estos ejemplos ilustran cómo usar los punteros a strings para evitar asignaciones adicionales

// Creamos una variable string que queremos modificar
myText := "héllô wórld"

// En lugar de crear una nueva variable con el resultado,
// modificamos directamente la variable original usando Apply()
Convert(&myText).RemoveTilde().ToLower().Apply()

// La variable original ha sido modificada
fmt.Println(myText)

Output:

hello world

Example (StringPointerCamelCase)

// Ejemplo de uso con múltiples transformaciones
originalText := "Él Múrcielago Rápido"

// Las transformaciones modifican la variable original directamente
// usando el método Apply() para actualizar el puntero
Convert(&originalText).RemoveTilde().CamelCaseLower().Apply()

fmt.Println(originalText)

Output:

elMurcielagoRapido

Example (StringPointerEfficiency)

// En aplicaciones de alto rendimiento, reducir asignaciones de memoria
// puede ser importante para evitar la presión sobre el garbage collector
// Método tradicional (crea nuevas asignaciones de memoria)
traditionalText := "Texto con ACENTOS"
processedText := Convert(traditionalText).RemoveTilde().ToLower().String()
fmt.Println(processedText)

// Método con punteros (modifica directamente la variable original)
directText := "Otro TEXTO con ACENTOS"
Convert(&directText).RemoveTilde().ToLower().Apply()
fmt.Println(directText)

Output:

texto con acentos
otro texto con acentos

Index

• func Contains(conv, search string) bool
• func Convert(v any) *conv
• func CountOccurrences(conv, search string) int
• func Format(format string, args ...any) *conv
• func ParseKeyValue(input string, delimiters ...string) (value string, err error)
• func Split(data string, separator ...string) (result []string)
• func TestFixedNegativeNumbers(t *testing.T)

Examples

• Package (StringPointerBasic)
• Package (StringPointerCamelCase)
• Package (StringPointerEfficiency)

Functions

func Contains

func Contains(conv, search string) bool

Contains checks if the string 'search' is present in 'conv' Returns true if found, false otherwise This matches the behavior of the standard library strings.Contains

func Convert

func Convert(v any) *conv

Convert initializes a new conv struct with any type of value for string,bool and number manipulation. Uses the centralized convInit function to avoid code duplication.

func CountOccurrences

func CountOccurrences(conv, search string) int

CountOccurrences checks how many times the string 'search' is present in 'conv' eg: "hello world" with search "world" will return 1

func Format

func Format(format string, args ...any) *conv

Format creates a new conv instance with variadic formatting similar to fmt.Sprintf Example: tinystring.Format("Hello %s, you have %d messages", "Alice", 5).String()

func ParseKeyValue

func ParseKeyValue(input string, delimiters ...string) (value string, err error)

ParseKeyValue extracts the value part from a "key:value" formatted string. By default, it uses ":" as the delimiter but accepts an optional custom delimiter. The function returns the value part and an error (nil if successful).

Examples:

value, err := ParseKeyValue("name:John")
// value = "John", err = nil

value, err := ParseKeyValue("data=123", "=")
// value = "123", err = nil

value, err := ParseKeyValue("invalid-string")
// value = "", err = error containing "delimiter ':' not found in string invalid-string"

func Split

func Split(data string, separator ...string) (result []string)

func TestFixedNegativeNumbers

func TestFixedNegativeNumbers(t *testing.T)