strchain

package
v0.1.24 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 13, 2026 License: GPL-3.0 Imports: 6 Imported by: 0

README

StrChain — Fluent String Builder for Go

A high-performance string builder for Go that wraps strings.Builder with a fluent, chainable API. Choose between a pure implementation for maximum throughput or a thread-safe variant for concurrent workloads.

✨ Features

  • ⛓️ Fluent API — All methods return Weaver for expressive chainable calls
  • 🚀 Zero Overhead — StringWeaver wraps strings.Builder directly, no mutex
  • 🔒 Thread-Safe Option — SafeStringWeaver adds sync.Mutex protection
  • 🎯 Type-Safe — Full numeric type support (int8–64, uint8–64, float32/64, bool)
  • 📦 Zero Dependencies — Built entirely on Go's standard library
  • 🧩 Interface-Driven — Weaver interface enables polymorphism between implementations
  • 💡 Intuitive — Natural, readable syntax that mirrors how you think about string construction

📥 Installation

go get github.com/sivaosorg/replify

Import:

import "github.com/sivaosorg/replify/pkg/strchain"

🏗️ Architecture

                    ┌────────────┐
                    │   Weaver   │ (interface)
                    │  48 methods│
                    └─────┬──────┘
                          │
              ┌───────────┴───────────┐
              │                       │
     ┌────────┴────────┐    ┌─────────┴─────────┐
     │  StringWeaver   │    │ SafeStringWeaver   │
     │  (no mutex)     │    │ (sync.Mutex)       │
     │  max performance│    │ thread-safe        │
     └─────────────────┘    └────────────────────┘

Choose the right type:

When to use Type Constructor
Single goroutine, max performance StringWeaver New(), From(), NewWithCapacity()
Multiple goroutines, concurrent access SafeStringWeaver NewSafe(), SafeFrom(), NewSafeWithCapacity()

🚀 Quick Start

Basic Usage (Single-Threaded)
result := strchain.New().
    Append("Hello").
    Space().
    Append("World").
    Build()

fmt.Println(result) // Output: Hello World
Thread-Safe Usage
logger := strchain.NewSafe()
var wg sync.WaitGroup

for i := 1; i <= 5; i++ {
    wg.Add(1)
    go func(id int) {
        defer wg.Done()
        logger.LineF("[Thread %d] Processing completed", id)
    }(i)
}

wg.Wait()
fmt.Println(logger.Build())
Polymorphism via Weaver Interface
func buildGreeting(w strchain.Weaver, name string) string {
    return w.Append("Hello, ").Append(name).Append("!").Build()
}

// Works with either implementation
buildGreeting(strchain.New(), "Alice")         // fast, single-threaded
buildGreeting(strchain.NewSafe(), "Bob")       // safe, multi-threaded

📚 Core API

Both StringWeaver and SafeStringWeaver share the same method set, unified by the Weaver interface.

Constructors
// StringWeaver (non-thread-safe, maximum performance)
strchain.New()                    // Create new instance
strchain.NewWithCapacity(1000)    // Pre-allocate capacity
strchain.From("initial text")     // Start from existing string

// SafeStringWeaver (thread-safe with mutex)
strchain.NewSafe()                // Create new instance
strchain.NewSafeWithCapacity(1000)// Pre-allocate capacity
strchain.SafeFrom("initial text") // Start from existing string
String Operations
.Append("text")                   // Append string
.AppendF("Hello %s", name)        // Formatted append (printf-style)
.AppendByte('A')                  // Single byte
.AppendRune('🔒')                 // Single rune
.AppendBytes([]byte{...})         // Byte slice
Type-Specific Appends
.AppendInt(42)                    // int
.AppendInt8(8)                    // int8
.AppendInt16(16)                  // int16
.AppendInt32(32)                  // int32
.AppendInt64(64)                  // int64
.AppendUint(42)                   // uint
.AppendUint8(8)                   // uint8
.AppendUint16(16)                 // uint16
.AppendUint32(32)                 // uint32
.AppendUint64(64)                 // uint64
.AppendUintptr(100)               // uintptr
.AppendFloat32(3.14)              // float32
.AppendFloat64(2.718)             // float64
.AppendBool(true)                 // bool
Whitespace
.Space()                          // Single space
.Spaces(5)                        // Multiple spaces
.Tab()                            // Single tab
.Tabs(3)                          // Multiple tabs
.NewLine()                        // Single newline
.NewLines(2)                      // Multiple newlines
.Line("text")                     // Text + newline
.LineF("Hello %s", name)          // Formatted + newline
Collections
.Join(", ", "A", "B", "C")        // Join with separator
.Repeat("*", 10)                  // Repeat string n times
.Each(items, func(sw, item) {     // Iterate over slice
    sw.Append(item)
})
Conditional Building
.AppendIf(condition, "text")      // Append if true
.AppendIfF(condition, "%s", val)  // Formatted append if true
.When(condition, func(sw) {       // Execute block if true
    sw.Append("text")
})
.Unless(condition, func(sw) {     // Execute block if false
    sw.Append("text")
})

Note: When, Unless, and Each accept callbacks with concrete receiver types (*StringWeaver or *SafeStringWeaver). These methods are not part of the Weaver interface.

Formatting
.Indent(2, "text")                // Indent (2 spaces per level)
.IndentLine(1, "text")            // Indent + newline
.Quote("text")                    // "text"
.SingleQuote("text")              // 'text'
.Parenthesize("text")             // (text)
.Bracket("text")                  // [text]
.Brace("text")                    // {text}
.Wrap("<", "text", ">")           // <text>
Punctuation
.Comma()                          // ,
.Dot()                            // .
.Colon()                          // :
.Semicolon()                      // ;
.Equals()                         // =
.Arrow()                          // ->
.FatArrow()                       // =>
Utilities
.Grow(1000)                       // Pre-allocate capacity
.Reset()                          // Clear and reuse
.Len()                            // Current length
.Cap()                            // Current capacity
.Clone()                          // Create independent copy
.Inspect(func(current) {          // Debug current state
    fmt.Println(current)
})
Output
.Build()                          // Get final string
.String()                         // Alias for Build()

🎯 Real-World Examples

SQL Query Building
query := strchain.New().
    Append("SELECT ").
    Join(", ", "id", "name", "email").NewLine().
    Append("FROM users").NewLine().
    Append("WHERE active = true").NewLine().
    Append("ORDER BY created_at DESC").
    Build()
JSON Construction
json := strchain.New().
    Line("{").
    IndentLine(1, `"name": "John",`).
    IndentLine(1, `"age": 30,`).
    IndentLine(1, `"active": true`).
    Append("}").
    Build()
HTML Generation
html := strchain.New().
    Append("<div class=").Quote("container").Append(">").NewLine().
    Indent(1, "<h1>").Append("Welcome").Append("</h1>").NewLine().
    Indent(1, "<p>").Append("Content").Append("</p>").NewLine().
    Append("</div>").
    Build()
Concurrent Log Aggregation
logger := strchain.NewSafe()

go logger.LineF("[%s] Service started", time.Now())
go logger.LineF("[%s] Database connected", time.Now())
go logger.LineF("[%s] Cache initialized", time.Now())

// All logs are safely aggregated — no external locking needed
Concurrent CSV Generation
csv := strchain.NewSafe()
csv.Line("ID,Name,Value")
var wg sync.WaitGroup

for i := 1; i <= 100; i++ {
    wg.Add(1)
    go func(id int) {
        defer wg.Done()
        csv.Join(",",
            fmt.Sprintf("%d", id),
            fmt.Sprintf("Item%d", id),
            fmt.Sprintf("%d", id*100),
        ).NewLine()
    }(i)
}

wg.Wait()
Safe Cloning for Branching
template := strchain.NewSafe()
template.Append("Dear ")

for _, name := range []string{"Alice", "Bob", "Charlie"} {
    go func(n string) {
        personalized := template.Clone() // Thread-safe clone
        personalized.Append(n).Append(",").NewLine()
        fmt.Println(personalized.Build())
    }(name)
}

⚡ Performance

Design Philosophy

The strchain package provides two implementations to avoid forcing a one-size-fits-all trade-off:

Implementation Overhead Use Case
StringWeaver Zero — direct strings.Builder wrapper Single-threaded, hot paths
SafeStringWeaver ~10–20ns/op — mutex lock/unlock per call Concurrent access

Both implementations produce zero allocations beyond the initial builder allocation — identical to strings.Builder.

Performance Tips
// ✅ Use StringWeaver for single-threaded code
sw := strchain.New()

// ✅ Pre-allocate capacity when the approximate size is known
sw := strchain.NewWithCapacity(4096)

// ✅ Reuse with Reset to avoid re-allocation
sw.Reset()

// ✅ Use SafeStringWeaver only when concurrent access is required
sw := strchain.NewSafe()

// ⚠️ Avoid calling Len() in tight loops with SafeStringWeaver — each call acquires a lock

🔒 Thread-Safety Details

StringWeaver

StringWeaver is NOT thread-safe. It is designed for single-goroutine use where maximum performance is required. Using it concurrently without external synchronization will cause data races.

SafeStringWeaver

SafeStringWeaver is thread-safe. All methods use internal mutex synchronization:

  • ✅ All Append operations
  • ✅ All formatting and punctuation methods
  • ✅ Len(), Cap(), String(), Build()
  • ✅ Reset(), Grow(), Clone()
  • ✅ Inspect() — locks during state read, unlocks before callback execution

Callback methods (When, Unless, Each) do not hold the lock during callback execution. The callback receives the builder instance and can safely call any method (each of which acquires its own lock individually).

Concurrent Patterns
// ✅ Pattern 1: Shared SafeStringWeaver
logger := strchain.NewSafe()
go logger.Line("A")
go logger.Line("B")

// ✅ Pattern 2: Clone for branching
template := strchain.NewSafe()
template.Append("Base: ")
go func() {
    branch := template.Clone()
    branch.Append("Branch 1")
}()

// ✅ Pattern 3: Separate instances per goroutine
go func() {
    local := strchain.New() // No mutex needed
    local.Append("Local work")
}()

🆚 Comparison

StringWeaver vs SafeStringWeaver
Feature StringWeaver SafeStringWeaver
Thread-Safe ❌ No ✅ Yes
Performance Baseline (zero overhead) ~10–20ns/op mutex cost
Allocations 0 0
Use Case Single goroutine, max perf Concurrent access
vs. strings.Builder
Feature StringWeaver SafeStringWeaver strings.Builder
Thread-Safe ❌ No ✅ Yes ❌ No
Fluent API ✅ Yes ✅ Yes ❌ No
Type Methods ✅ Full ✅ Full ⚠️ Limited
Performance ≈ Baseline ~10–20ns overhead Baseline
Allocations 0 0 0
vs. strings.Join / fmt.Sprintf
Feature Weaver strings.Join fmt.Sprintf
Zero Allocs ✅ Yes ❌ No ❌ No
Fluent API ✅ Yes ❌ No ❌ No
Flexibility ✅ High ⚠️ Limited ⚠️ Medium

🤝 Contributing

Contributions welcome! Please feel free to submit a Pull Request.

📄 License

MIT License — see LICENSE file for details.

🙏 Credits

Built with ❤️ on top of Go's excellent strings.Builder. Thread-safety powered by sync.Mutex.

Documentation

Overview

Package strchain provides a fluent, chainable string builder API built on top of Go's strings.Builder. It offers two implementations with identical APIs:

  • StringWeaver: A high-performance, non-thread-safe builder for single-goroutine usage. It wraps strings.Builder directly with zero overhead beyond the method call indirection.

  • SafeStringWeaver: A thread-safe builder protected by sync.Mutex, suitable for concurrent access from multiple goroutines. Each operation acquires a lock, adding approximately 10–20ns of overhead per call.

Both types implement the Weaver interface, which defines the full set of chainable methods. This allows writing functions that accept either implementation polymorphically.

Choosing Between StringWeaver and SafeStringWeaver

Use StringWeaver (via New, NewWithCapacity, or From) when:

  • The builder is confined to a single goroutine.
  • Maximum throughput is required (zero synchronization overhead).

Use SafeStringWeaver (via NewSafe, NewSafeWithCapacity, or SafeFrom) when:

  • Multiple goroutines write to the same builder concurrently.
  • Thread safety is required without external locking.

Fluent API

All chainable methods return the Weaver interface, enabling expressive method chains: 

result := strchain.New().
    Append("SELECT ").
    Join(", ", "id", "name", "email").
    Append(" FROM users").
    Build()

Callback Methods

The StringWeaver.When, StringWeaver.Unless, and StringWeaver.Each methods accept callbacks with concrete receiver types. These methods are not part of the Weaver interface because their function signatures differ between implementations. They are available directly on each concrete type.

Polymorphism

Functions that build strings can accept Weaver to work with either implementation: 

func buildGreeting(w strchain.Weaver, name string) string {
    return w.Append("Hello, ").Append(name).Append("!").Build()
}

// Single-threaded
buildGreeting(strchain.New(), "Alice")

// Thread-safe
buildGreeting(strchain.NewSafe(), "Bob")

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Chain added in v0.1.17 

type Chain string

Chain is a lightweight fluent string wrapper that enables method chaining directly from a string value without needing to create a StringWeaver constructor.

Usage: 

result := strchain.Chain("Hello").Space().Append("World").Upper().String()
// Output: "HELLO WORLD"

result := strchain.Chain("  trimmed  ").Trim().Quote().String()
// Output: "\"trimmed\""

func C added in v0.1.17 

func C(s ...string) Chain

C is a shorthand alias for Chain.

Example: 

result := strchain.C("Hello").Space().Append("World").String()

func Empty added in v0.1.17 

func Empty() Chain

Empty creates an empty Chain for building strings from scratch.

Example: 

result := strchain.Empty().Append("Built").Space().Append("from scratch").String()

func (Chain) Append added in v0.1.17 

func (c Chain) Append(s string) Chain

Append adds a string to the end.

func (Chain) AppendBool added in v0.1.17 

func (c Chain) AppendBool(b bool) Chain

AppendBool adds a boolean.

func (Chain) AppendByte added in v0.1.17 

func (c Chain) AppendByte(b byte) Chain

AppendByte adds a single byte.

func (Chain) AppendBytes added in v0.1.17 

func (c Chain) AppendBytes(b []byte) Chain

AppendBytes adds a byte slice.

func (Chain) AppendF added in v0.1.17 

func (c Chain) AppendF(format string, args ...any) Chain

AppendF adds a formatted string (printf-style).

func (Chain) AppendFloat64 added in v0.1.17 

func (c Chain) AppendFloat64(f float64) Chain

AppendFloat64 adds a float64.

func (Chain) AppendIf added in v0.1.17 

func (c Chain) AppendIf(condition bool, s string) Chain

AppendIf appends a string if the condition is true.

func (Chain) AppendIfF added in v0.1.17 

func (c Chain) AppendIfF(condition bool, format string, args ...any) Chain

AppendIfF appends a formatted string if the condition is true.

func (Chain) AppendInt added in v0.1.17 

func (c Chain) AppendInt(i int) Chain

AppendInt adds an integer.

func (Chain) AppendInt64 added in v0.1.17 

func (c Chain) AppendInt64(i int64) Chain

AppendInt64 adds an int64.

func (Chain) AppendRune added in v0.1.17 

func (c Chain) AppendRune(r rune) Chain

AppendRune adds a single rune.

func (Chain) Arrow added in v0.1.17 

func (c Chain) Arrow() Chain

Arrow adds an arrow (->).

func (Chain) Brace added in v0.1.17 

func (c Chain) Brace() Chain

Brace wraps the string in curly braces.

func (Chain) Bracket added in v0.1.17 

func (c Chain) Bracket() Chain

Bracket wraps the string in square brackets.

func (Chain) Bytes added in v0.1.17 

func (c Chain) Bytes() []byte

Bytes returns the string as a byte slice.

func (Chain) Center added in v0.1.17 

func (c Chain) Center(width int, pad string) Chain

Center centers the string within the specified width.

func (Chain) Colon added in v0.1.17 

func (c Chain) Colon() Chain

Colon adds a colon.

func (Chain) Comma added in v0.1.17 

func (c Chain) Comma() Chain

Comma adds a comma.

func (Chain) Contains added in v0.1.17 

func (c Chain) Contains(substr string) bool

Contains returns true if the string contains substr.

func (Chain) Count added in v0.1.17 

func (c Chain) Count(substr string) int

Count returns the number of non-overlapping occurrences of substr.

func (Chain) Dot added in v0.1.17 

func (c Chain) Dot() Chain

Dot adds a period.

func (Chain) Equals added in v0.1.17 

func (c Chain) Equals() Chain

Equals adds an equals sign.

func (Chain) FatArrow added in v0.1.17 

func (c Chain) FatArrow() Chain

FatArrow adds a fat arrow (=>).

func (Chain) Filter added in v0.1.17 

func (c Chain) Filter(fn func(rune) bool) Chain

Filter keeps only runes that satisfy the predicate.

func (Chain) HasPrefix added in v0.1.17 

func (c Chain) HasPrefix(prefix string) bool

HasPrefix returns true if the string starts with prefix.

func (Chain) HasSuffix added in v0.1.17 

func (c Chain) HasSuffix(suffix string) bool

HasSuffix returns true if the string ends with suffix.

func (Chain) IfEmpty added in v0.1.17 

func (c Chain) IfEmpty(fallback string) Chain

IfEmpty returns the fallback if the string is empty.

func (Chain) IfNotEmpty added in v0.1.17 

func (c Chain) IfNotEmpty(fn func(Chain) Chain) Chain

IfNotEmpty applies a transformation if the string is not empty.

func (Chain) Indent added in v0.1.17 

func (c Chain) Indent(level int) Chain

Indent adds indentation (2 spaces per level) before the current text.

func (Chain) IndentLine added in v0.1.17 

func (c Chain) IndentLine(level int) Chain

IndentLine adds indentation before the text and appends a newline.

func (Chain) Index added in v0.1.17 

func (c Chain) Index(substr string) int

Index returns the index of the first occurrence of substr, or -1.

func (Chain) IsEmpty added in v0.1.17 

func (c Chain) IsEmpty() bool

IsEmpty returns true if the string is empty.

func (Chain) IsNotEmpty added in v0.1.17 

func (c Chain) IsNotEmpty() bool

IsNotEmpty returns true if the string is not empty.

func (Chain) Join added in v0.1.17 

func (c Chain) Join(elements ...string) Chain

Join joins multiple strings using the current string as separator.

func (Chain) JoinSlice added in v0.1.17 

func (c Chain) JoinSlice(elements []string) Chain

JoinSlice joins a slice of strings using the current string as separator.

func (Chain) Len added in v0.1.17 

func (c Chain) Len() int

Len returns the length of the string.

func (Chain) Line added in v0.1.17 

func (c Chain) Line(s string) Chain

Line adds a string followed by a newline.

func (Chain) LineF added in v0.1.17 

func (c Chain) LineF(format string, args ...any) Chain

LineF adds a formatted string followed by a newline.

func (Chain) Lower added in v0.1.17 

func (c Chain) Lower() Chain

Lower converts the string to lowercase.

func (Chain) Map added in v0.1.17 

func (c Chain) Map(fn func(string) string) Chain

Map applies a transformation function to the string.

func (Chain) MapRunes added in v0.1.17 

func (c Chain) MapRunes(fn func(rune) rune) Chain

MapRunes applies a function to each rune.

func (Chain) NewLine added in v0.1.17 

func (c Chain) NewLine() Chain

NewLine adds a newline character.

func (Chain) NewLines added in v0.1.17 

func (c Chain) NewLines(n int) Chain

NewLines adds n newline characters.

func (Chain) PadLeft added in v0.1.17 

func (c Chain) PadLeft(width int, pad string) Chain

PadLeft pads the string on the left to reach the specified width.

func (Chain) PadRight added in v0.1.17 

func (c Chain) PadRight(width int, pad string) Chain

PadRight pads the string on the right to reach the specified width.

func (Chain) Parenthesize added in v0.1.17 

func (c Chain) Parenthesize() Chain

Parenthesize wraps the string in parentheses.

func (Chain) Prepend added in v0.1.17 

func (c Chain) Prepend(s string) Chain

Prepend adds a string to the beginning.

func (Chain) PrependF added in v0.1.17 

func (c Chain) PrependF(format string, args ...any) Chain

PrependF adds a formatted string to the beginning.

func (Chain) PrependIf added in v0.1.17 

func (c Chain) PrependIf(condition bool, s string) Chain

PrependIf prepends a string if the condition is true.

func (Chain) Quote added in v0.1.17 

func (c Chain) Quote() Chain

Quote wraps the string in double quotes.

func (Chain) Repeat added in v0.1.17 

func (c Chain) Repeat(n int) Chain

Repeat repeats the string n times.

func (Chain) Replace added in v0.1.17 

func (c Chain) Replace(old, new string) Chain

Replace replaces all occurrences of old with new.

func (Chain) ReplaceN added in v0.1.17 

func (c Chain) ReplaceN(old, new string, n int) Chain

ReplaceN replaces the first n occurrences of old with new.

func (Chain) Reverse added in v0.1.17 

func (c Chain) Reverse() Chain

Reverse reverses the string (rune-aware).

func (Chain) Runes added in v0.1.17 

func (c Chain) Runes() []rune

Runes returns the string as a rune slice.

func (Chain) Semicolon added in v0.1.17 

func (c Chain) Semicolon() Chain

Semicolon adds a semicolon.

func (Chain) SingleQuote added in v0.1.17 

func (c Chain) SingleQuote() Chain

SingleQuote wraps the string in single quotes.

func (Chain) Space added in v0.1.17 

func (c Chain) Space() Chain

Space adds a single space.

func (Chain) Spaces added in v0.1.17 

func (c Chain) Spaces(n int) Chain

Spaces adds n spaces.

func (Chain) Split added in v0.1.17 

func (c Chain) Split(sep string) []string

Split splits the string by separator and returns the parts.

func (Chain) SplitN added in v0.1.17 

func (c Chain) SplitN(sep string, n int) []string

SplitN splits the string by separator into at most n parts.

func (Chain) String added in v0.1.17 

func (c Chain) String() string

String returns the underlying string value.

func (Chain) Tab added in v0.1.17 

func (c Chain) Tab() Chain

Tab adds a single tab.

func (Chain) Tabs added in v0.1.17 

func (c Chain) Tabs(n int) Chain

Tabs adds n tabs.

func (Chain) Title added in v0.1.17 

func (c Chain) Title() Chain

Title converts the string to title case.

func (Chain) ToSafeWeaver added in v0.1.17 

func (c Chain) ToSafeWeaver() *SafeStringWeaver

ToSafeWeaver converts the Chain to a SafeStringWeaver for thread-safe operations.

func (Chain) ToWeaver added in v0.1.17 

func (c Chain) ToWeaver() *StringWeaver

ToWeaver converts the Chain to a StringWeaver for more complex operations.

func (Chain) Trim added in v0.1.17 

func (c Chain) Trim() Chain

Trim removes leading and trailing whitespace.

func (Chain) TrimChars added in v0.1.17 

func (c Chain) TrimChars(cutset string) Chain

TrimChars removes leading and trailing characters in cutset.

func (Chain) TrimLeft added in v0.1.17 

func (c Chain) TrimLeft(cutset string) Chain

TrimLeft removes leading characters in cutset.

func (Chain) TrimPrefix added in v0.1.17 

func (c Chain) TrimPrefix(prefix string) Chain

TrimPrefix removes the specified prefix.

func (Chain) TrimRight added in v0.1.17 

func (c Chain) TrimRight(cutset string) Chain

TrimRight removes trailing characters in cutset.

func (Chain) TrimSuffix added in v0.1.17 

func (c Chain) TrimSuffix(suffix string) Chain

TrimSuffix removes the specified suffix.

func (Chain) Truncate added in v0.1.17 

func (c Chain) Truncate(length int) Chain

Truncate truncates the string to the specified length.

func (Chain) TruncateWithSuffix added in v0.1.17 

func (c Chain) TruncateWithSuffix(length int, suffix string) Chain

TruncateWithSuffix truncates and adds a suffix if truncated.

func (Chain) Unless added in v0.1.17 

func (c Chain) Unless(condition bool, fn func(Chain) Chain) Chain

Unless applies a transformation function if the condition is false.

func (Chain) Upper added in v0.1.17 

func (c Chain) Upper() Chain

Upper converts the string to uppercase.

func (Chain) When added in v0.1.17 

func (c Chain) When(condition bool, fn func(Chain) Chain) Chain

When applies a transformation function if the condition is true.

func (Chain) Wrap added in v0.1.17 

func (c Chain) Wrap(prefix, suffix string) Chain

Wrap wraps the current string with prefix and suffix.

type SafeStringWeaver 

type SafeStringWeaver struct {
	// contains filtered or unexported fields
}

SafeStringWeaver wraps strings.Builder with a fluent API for chainable operations. This implementation is THREAD-SAFE and can be used concurrently by multiple goroutines. Each method acquires a mutex lock to ensure safe concurrent access.

For single-threaded usage where maximum performance is desired, use StringWeaver instead.

Example: 

sw := strchain.NewSafe().Append("Hello").Space().Append("World")
fmt.Println(sw.Build()) // Output: Hello World

func NewSafe 

func NewSafe() *SafeStringWeaver

NewSafe creates a new SafeStringWeaver instance.

Example: 

sw := strchain.NewSafe()

func NewSafeWithCapacity 

func NewSafeWithCapacity(capacity int) *SafeStringWeaver

NewSafeWithCapacity creates a new SafeStringWeaver with an initial capacity hint.

Example: 

sw := strchain.NewSafeWithCapacity(1024)

func SafeFrom 

func SafeFrom(s string) *SafeStringWeaver

SafeFrom creates a new SafeStringWeaver initialized with the given string.

Example: 

sw := strchain.SafeFrom("Initial")

func SafeFromPtr added in v0.1.5 

func SafeFromPtr(s *strings.Builder) *SafeStringWeaver

SafeFromPtr creates a new SafeStringWeaver initialized with the given strings.Builder pointer.

Example: 

sw := strchain.SafeFromPtr(&myBuilder)

func (*SafeStringWeaver) Append 

func (sw *SafeStringWeaver) Append(s string) Weaver

Append adds a string and returns the builder for chaining.

Example: 

sw.Append("hello").Append(" world")

func (*SafeStringWeaver) AppendBool 

func (sw *SafeStringWeaver) AppendBool(b bool) Weaver

AppendBool adds a boolean value and returns the builder.

Example: 

sw.AppendBool(true)

func (*SafeStringWeaver) AppendByte 

func (sw *SafeStringWeaver) AppendByte(b byte) Weaver

AppendByte adds a single byte and returns the builder.

Example: 

sw.AppendByte('a')

func (*SafeStringWeaver) AppendBytes 

func (sw *SafeStringWeaver) AppendBytes(b []byte) Weaver

AppendBytes adds a byte slice and returns the builder.

Example: 

sw.AppendBytes([]byte("data"))

func (*SafeStringWeaver) AppendF 

func (sw *SafeStringWeaver) AppendF(format string, args ...any) Weaver

AppendF adds a formatted string (printf-style) and returns the builder.

Example: 

sw.AppendF("value: %d", 42)

func (*SafeStringWeaver) AppendFloat32 

func (sw *SafeStringWeaver) AppendFloat32(f float32) Weaver

AppendFloat32 adds a float32 and returns the builder.

Example: 

sw.AppendFloat32(3.14)

func (*SafeStringWeaver) AppendFloat64 

func (sw *SafeStringWeaver) AppendFloat64(f float64) Weaver

AppendFloat64 adds a float64 and returns the builder.

Example: 

sw.AppendFloat64(3.14159)

func (*SafeStringWeaver) AppendIf 

func (sw *SafeStringWeaver) AppendIf(condition bool, s string) Weaver

AppendIf conditionally adds a string if the condition is true.

Example: 

sw.AppendIf(isValid, " Validated")

func (*SafeStringWeaver) AppendIfF 

func (sw *SafeStringWeaver) AppendIfF(condition bool, format string, args ...any) Weaver

AppendIfF conditionally adds a formatted string if the condition is true.

Example: 

sw.AppendIfF(debugMode, "Debug: %s", msg)

func (*SafeStringWeaver) AppendInt 

func (sw *SafeStringWeaver) AppendInt(i int) Weaver

AppendInt adds an integer and returns the builder.

Example: 

sw.AppendInt(123)

func (*SafeStringWeaver) AppendInt8 

func (sw *SafeStringWeaver) AppendInt8(i int8) Weaver

AppendInt8 adds an int8 and returns the builder.

Example: 

sw.AppendInt8(8)

func (*SafeStringWeaver) AppendInt16 

func (sw *SafeStringWeaver) AppendInt16(i int16) Weaver

AppendInt16 adds an int16 and returns the builder.

Example: 

sw.AppendInt16(16)

func (*SafeStringWeaver) AppendInt32 

func (sw *SafeStringWeaver) AppendInt32(i int32) Weaver

AppendInt32 adds an int32 and returns the builder.

Example: 

sw.AppendInt32(32)

func (*SafeStringWeaver) AppendInt64 

func (sw *SafeStringWeaver) AppendInt64(i int64) Weaver

AppendInt64 adds an int64 and returns the builder.

Example: 

sw.AppendInt64(64)

func (*SafeStringWeaver) AppendRune 

func (sw *SafeStringWeaver) AppendRune(r rune) Weaver

AppendRune adds a single rune and returns the builder.

Example: 

sw.AppendRune('⌘')

func (*SafeStringWeaver) AppendUint 

func (sw *SafeStringWeaver) AppendUint(i uint) Weaver

AppendUint adds a uint and returns the builder.

Example: 

sw.AppendUint(123)

func (*SafeStringWeaver) AppendUint8 

func (sw *SafeStringWeaver) AppendUint8(i uint8) Weaver

AppendUint8 adds a uint8 and returns the builder.

Example: 

sw.AppendUint8(8)

func (*SafeStringWeaver) AppendUint16 

func (sw *SafeStringWeaver) AppendUint16(i uint16) Weaver

AppendUint16 adds a uint16 and returns the builder.

Example: 

sw.AppendUint16(16)

func (*SafeStringWeaver) AppendUint32 

func (sw *SafeStringWeaver) AppendUint32(i uint32) Weaver

AppendUint32 adds a uint32 and returns the builder.

Example: 

sw.AppendUint32(32)

func (*SafeStringWeaver) AppendUint64 

func (sw *SafeStringWeaver) AppendUint64(i uint64) Weaver

AppendUint64 adds a uint64 and returns the builder.

Example: 

sw.AppendUint64(64)

func (*SafeStringWeaver) AppendUintptr 

func (sw *SafeStringWeaver) AppendUintptr(i uintptr) Weaver

AppendUintptr adds a uintptr and returns the builder.

Example: 

sw.AppendUintptr(0xdeadbeef)

func (*SafeStringWeaver) Arrow 

func (sw *SafeStringWeaver) Arrow() Weaver

Arrow adds an arrow (->) to the builder.

Example: 

sw.Append("source").Arrow().Append("target")

func (*SafeStringWeaver) Brace 

func (sw *SafeStringWeaver) Brace(s string) Weaver

Brace wraps text in curly braces.

Example: 

sw.Brace("struct definition") // adds {struct definition}

func (*SafeStringWeaver) Bracket 

func (sw *SafeStringWeaver) Bracket(s string) Weaver

Bracket wraps text in square brackets.

Example: 

sw.Bracket("index") // adds [index]

func (*SafeStringWeaver) Build 

func (sw *SafeStringWeaver) Build() string

Build is an alias for String() for fluent API consistency.

Example: 

result := sw.Append("data").Build()

func (*SafeStringWeaver) Builder added in v0.1.4 

func (sw *SafeStringWeaver) Builder() *strings.Builder

Builder returns the underlying strings.Builder for advanced operations.

WARNING: This method bypasses ALL thread-safety guarantees of SafeStringWeaver. The mutex is NOT held while the caller uses the returned pointer. Any concurrent read or write through this pointer — including calling other SafeStringWeaver methods simultaneously — will cause a data race. Use this method only when the SafeStringWeaver is exclusively owned by a single goroutine at that point in time, or when you have external synchronization. For normal concurrent use, prefer the fluent methods which each acquire and release the lock atomically.

Example: 

builder := sw.Builder()

func (*SafeStringWeaver) Cap 

func (sw *SafeStringWeaver) Cap() int

Cap returns the current capacity of the builder.

Example: 

capacity := sw.Cap()

func (*SafeStringWeaver) Clone 

func (sw *SafeStringWeaver) Clone() Weaver

Clone creates a thread-safe copy of the current builder state.

Example: 

newSw := sw.Clone()

func (*SafeStringWeaver) Colon 

func (sw *SafeStringWeaver) Colon() Weaver

Colon adds a colon to the builder.

Example: 

sw.Append("Label").Colon().Space().Append("Value")

func (*SafeStringWeaver) Comma 

func (sw *SafeStringWeaver) Comma() Weaver

Comma adds a comma to the builder.

Example: 

sw.Append("item1").Comma().Append("item2")

func (*SafeStringWeaver) CommaIfNotLast added in v0.1.6 

func (sw *SafeStringWeaver) CommaIfNotLast(index, total int) Weaver

CommaIfNotLast adds a comma if the index is not the last item.

Example: 

sw.CommaIfNotLast(i, len(items)) // adds "," if i < len(items)-1

func (*SafeStringWeaver) Dot 

func (sw *SafeStringWeaver) Dot() Weaver

Dot adds a period to the builder.

Example: 

sw.Append("End of sentence").Dot()

func (*SafeStringWeaver) Each 

func (sw *SafeStringWeaver) Each(items []string, fn func(*SafeStringWeaver, string)) *SafeStringWeaver

Each iterates over a slice and applies a function for each element.

Example: 

sw.Each([]string{"a", "b", "c"}, func(s *SafeStringWeaver, item string) {
    s.Append(item).Comma()
})

func (*SafeStringWeaver) EachCast added in v0.1.7 

func (sw *SafeStringWeaver) EachCast(items []string, fn func(w Weaver, item string)) Weaver

EachCast executes a function for each item in the slice.

Example: 

sw.EachCast(items, func(w Weaver, item string) {
	w.Append(item).Comma()
})

func (*SafeStringWeaver) EndBrace added in v0.1.10 

func (sw *SafeStringWeaver) EndBrace() Weaver

EndBrace adds a closing brace.

Example: 

sw.EndBrace() // adds '}'

func (*SafeStringWeaver) EndBracket added in v0.1.10 

func (sw *SafeStringWeaver) EndBracket() Weaver

EndBracket adds a closing bracket.

Example: 

sw.EndBracket() // adds ']'

func (*SafeStringWeaver) EndParenthesize added in v0.1.10 

func (sw *SafeStringWeaver) EndParenthesize() Weaver

EndParenthesize adds a closing parenthesis.

Example: 

sw.EndParenthesize() // adds ')'

func (*SafeStringWeaver) Equals 

func (sw *SafeStringWeaver) Equals() Weaver

Equals adds an equals sign to the builder.

Example: 

sw.Append("key").Equals().Append("value")

func (*SafeStringWeaver) FatArrow 

func (sw *SafeStringWeaver) FatArrow() Weaver

FatArrow adds a fat arrow (=>) to the builder.

Example: 

sw.Append("map").FatArrow().Append("result")

func (*SafeStringWeaver) Grow 

func (sw *SafeStringWeaver) Grow(n int) Weaver

Grow grows the builder's capacity by n bytes.

Example: 

sw.Grow(512)

func (*SafeStringWeaver) Indent 

func (sw *SafeStringWeaver) Indent(level int, s string) Weaver

Indent adds indentation (2 spaces per level) before appending text.

Example: 

sw.Indent(2, "Sub-item")

func (*SafeStringWeaver) IndentF added in v0.1.6 

func (sw *SafeStringWeaver) IndentF(level int, format string, args ...any) Weaver

IndentF adds indentation (2 spaces per level) before appending a formatted string.

Example: 

sw.IndentF(1, `"id": %q,`, "abc123")

func (*SafeStringWeaver) IndentLine 

func (sw *SafeStringWeaver) IndentLine(level int, s string) Weaver

IndentLine adds indentation (2 spaces per level) before text and ends with a newline.

Example: 

sw.IndentLine(1, "Point 1")

func (*SafeStringWeaver) IndentLineF added in v0.1.6 

func (sw *SafeStringWeaver) IndentLineF(level int, format string, args ...any) Weaver

IndentLineF adds indentation (2 spaces per level) before a formatted string and ends with a newline.

Example: 

sw.IndentLineF(1, `"id": %q,`, "abc123")

func (*SafeStringWeaver) IndentOnly added in v0.1.10 

func (sw *SafeStringWeaver) IndentOnly(level int) Weaver

IndentOnly adds indentation (2 spaces per level) without appending text.

Example: 

sw.IndentOnly(1) // adds '  '

func (*SafeStringWeaver) IndentOnlyLine added in v0.1.10 

func (sw *SafeStringWeaver) IndentOnlyLine(level int) Weaver

IndentOnlyLine adds indentation (2 spaces per level) followed by a newline.

Example: 

sw.IndentOnlyLine(1) // adds '  \n'

func (*SafeStringWeaver) Inspect 

func (sw *SafeStringWeaver) Inspect(fn func(current string)) Weaver

Inspect executes a function with access to the current state without modification.

Example: 

sw.Inspect(func(current string) {
    log.Printf("Current state: %s", current)
})

func (*SafeStringWeaver) JSONArrayEnd added in v0.1.6 

func (sw *SafeStringWeaver) JSONArrayEnd() Weaver

JSONArrayEnd adds a closing square bracket for a JSON array.

Example: 

sw.JSONArrayEnd() // adds "]"

func (*SafeStringWeaver) JSONArrayStart added in v0.1.6 

func (sw *SafeStringWeaver) JSONArrayStart() Weaver

JSONArrayStart adds an opening square bracket for a JSON array.

Example: 

sw.JSONArrayStart() // adds "["

func (*SafeStringWeaver) JSONFieldArrayEnd added in v0.1.9 

func (sw *SafeStringWeaver) JSONFieldArrayEnd(level int) Weaver

JSONFieldArrayEnd adds an indented JSON array end.

Example: 

sw.JSONFieldArrayEnd(1) // adds '  ]'

func (*SafeStringWeaver) JSONFieldArrayStart added in v0.1.8 

func (sw *SafeStringWeaver) JSONFieldArrayStart(level int, key string) Weaver

JSONFieldArrayStart adds an indented JSON array start.

Example: 

sw.JSONFieldArrayStart(1, "items") // adds '  "items": ['

func (*SafeStringWeaver) JSONFieldBool added in v0.1.7 

func (sw *SafeStringWeaver) JSONFieldBool(level int, key string, value bool, addComma bool) Weaver

JSONFieldBool adds an indented JSON field with a bool value.

Example: 

sw.JSONFieldBool(1, "age", 30, true) // adds '  "age": 30,\n'

func (*SafeStringWeaver) JSONFieldFloat32 added in v0.1.7 

func (sw *SafeStringWeaver) JSONFieldFloat32(level int, key string, value float32, addComma bool) Weaver

JSONFieldFloat32 adds an indented JSON field with a float32 value.

Example: 

sw.JSONFieldFloat32(1, "age", 30, true) // adds '  "age": 30,\n'

func (*SafeStringWeaver) JSONFieldFloat64 added in v0.1.7 

func (sw *SafeStringWeaver) JSONFieldFloat64(level int, key string, value float64, addComma bool) Weaver

JSONFieldFloat64 adds an indented JSON field with a float64 value.

Example: 

sw.JSONFieldFloat64(1, "age", 30, true) // adds '  "age": 30,\n'

func (*SafeStringWeaver) JSONFieldInt added in v0.1.6 

func (sw *SafeStringWeaver) JSONFieldInt(level int, key string, value int, addComma bool) Weaver

JSONFieldInt adds an indented JSON field with an integer value.

Example: 

sw.JSONFieldInt(1, "age", 30, true) // adds '  "age": 30,\n'

func (*SafeStringWeaver) JSONFieldInt8 added in v0.1.7 

func (sw *SafeStringWeaver) JSONFieldInt8(level int, key string, value int8, addComma bool) Weaver

JSONFieldInt8 adds an indented JSON field with an int8 value.

Example: 

sw.JSONFieldInt8(1, "age", 30, true) // adds '  "age": 30,\n'

func (*SafeStringWeaver) JSONFieldInt16 added in v0.1.7 

func (sw *SafeStringWeaver) JSONFieldInt16(level int, key string, value int16, addComma bool) Weaver

JSONFieldInt16 adds an indented JSON field with an int16 value.

Example: 

sw.JSONFieldInt16(1, "age", 30, true) // adds '  "age": 30,\n'

func (*SafeStringWeaver) JSONFieldInt32 added in v0.1.7 

func (sw *SafeStringWeaver) JSONFieldInt32(level int, key string, value int32, addComma bool) Weaver

JSONFieldInt32 adds an indented JSON field with an int32 value.

Example: 

sw.JSONFieldInt32(1, "age", 30, true) // adds '  "age": 30,\n'

func (*SafeStringWeaver) JSONFieldInt64 added in v0.1.7 

func (sw *SafeStringWeaver) JSONFieldInt64(level int, key string, value int64, addComma bool) Weaver

JSONFieldInt64 adds an indented JSON field with an int64 value.

Example: 

sw.JSONFieldInt64(1, "age", 30, true) // adds '  "age": 30,\n'

func (*SafeStringWeaver) JSONFieldString added in v0.1.7 

func (sw *SafeStringWeaver) JSONFieldString(level int, key, value string, addComma bool) Weaver

JSONFieldString adds an indented JSON field (key: value) with optional comma and newline. The value is properly JSON-encoded (RFC 8259).

Example: 

sw.JSONFieldString(1, "name", `"John"`, true) // adds '  "name": "John",\n'

func (*SafeStringWeaver) JSONFieldUint added in v0.1.7 

func (sw *SafeStringWeaver) JSONFieldUint(level int, key string, value uint, addComma bool) Weaver

JSONFieldUint adds an indented JSON field with a uint value.

Example: 

sw.JSONFieldUint(1, "age", 30, true) // adds '  "age": 30,\n'

func (*SafeStringWeaver) JSONFieldUint8 added in v0.1.7 

func (sw *SafeStringWeaver) JSONFieldUint8(level int, key string, value uint8, addComma bool) Weaver

JSONFieldUint8 adds an indented JSON field with a uint8 value.

Example: 

sw.JSONFieldUint8(1, "age", 30, true) // adds '  "age": 30,\n'

func (*SafeStringWeaver) JSONFieldUint16 added in v0.1.7 

func (sw *SafeStringWeaver) JSONFieldUint16(level int, key string, value uint16, addComma bool) Weaver

JSONFieldUint16 adds an indented JSON field with a uint16 value.

Example: 

sw.JSONFieldUint16(1, "age", 30, true) // adds '  "age": 30,\n'

func (*SafeStringWeaver) JSONFieldUint32 added in v0.1.7 

func (sw *SafeStringWeaver) JSONFieldUint32(level int, key string, value uint32, addComma bool) Weaver

JSONFieldUint32 adds an indented JSON field with a uint32 value.

Example: 

sw.JSONFieldUint32(1, "age", 30, true) // adds '  "age": 30,\n'

func (*SafeStringWeaver) JSONFieldUint64 added in v0.1.7 

func (sw *SafeStringWeaver) JSONFieldUint64(level int, key string, value uint64, addComma bool) Weaver

JSONFieldUint64 adds an indented JSON field with a uint64 value.

Example: 

sw.JSONFieldUint64(1, "age", 30, true) // adds '  "age": 30,\n'

func (*SafeStringWeaver) JSONKey added in v0.1.6 

func (sw *SafeStringWeaver) JSONKey(key string) Weaver

JSONKey adds a quoted key followed by a colon and space.

Example: 

sw.JSONKey("name") // adds "name":

func (*SafeStringWeaver) JSONKeyBool added in v0.1.6 

func (sw *SafeStringWeaver) JSONKeyBool(key string, value bool) Weaver

JSONKeyBool adds a key-value pair where the value is a boolean.

Example: 

sw.JSONKeyBool("active", true) // adds "active": true

func (*SafeStringWeaver) JSONKeyFloat added in v0.1.6 

func (sw *SafeStringWeaver) JSONKeyFloat(key string, value float64) Weaver

JSONKeyFloat adds a key-value pair where the value is a float.

Example: 

sw.JSONKeyFloat("price", 19.99) // adds "price": 19.99

func (*SafeStringWeaver) JSONKeyInt added in v0.1.6 

func (sw *SafeStringWeaver) JSONKeyInt(key string, value int) Weaver

JSONKeyInt adds a key-value pair where the value is an integer.

Example: 

sw.JSONKeyInt("age", 30) // adds "age": 30

func (*SafeStringWeaver) JSONKeyString added in v0.1.6 

func (sw *SafeStringWeaver) JSONKeyString(key, value string) Weaver

JSONKeyString adds a key-value pair where the value is a string. The value is properly JSON-encoded (RFC 8259).

Example: 

sw.JSONKeyString("name", "John") // adds "name": "John"

func (*SafeStringWeaver) JSONObjectEnd added in v0.1.6 

func (sw *SafeStringWeaver) JSONObjectEnd() Weaver

JSONObjectEnd adds a closing curly brace for a JSON object.

Example: 

sw.JSONObjectEnd() // adds "}"

func (*SafeStringWeaver) JSONObjectStart added in v0.1.6 

func (sw *SafeStringWeaver) JSONObjectStart() Weaver

JSONObjectStart adds an opening curly brace for a JSON object.

Example: 

sw.JSONObjectStart() // adds "{" (thread-safe)

func (*SafeStringWeaver) JSONString added in v0.1.6 

func (sw *SafeStringWeaver) JSONString(s string) Weaver

JSONString adds a quoted and escaped string value. The output is proper JSON (RFC 8259) — control characters are encoded as \uXXXX sequences, not Go-specific escape sequences.

Example: 

sw.JSONString("hello") // adds "hello"

func (*SafeStringWeaver) Join 

func (sw *SafeStringWeaver) Join(sep string, elements ...string) Weaver

Join adds strings with a separator and returns the builder.

Example: 

sw.Join(", ", "Apple", "Banana", "Cherry")

func (*SafeStringWeaver) Len 

func (sw *SafeStringWeaver) Len() int

Len returns the current length of the built string.

Example: 

length := sw.Len()

func (*SafeStringWeaver) Line 

func (sw *SafeStringWeaver) Line(s string) Weaver

Line adds a string followed by a newline and returns the builder.

Example: 

sw.Line("First Line").Line("Second Line")

func (*SafeStringWeaver) LineF 

func (sw *SafeStringWeaver) LineF(format string, args ...any) Weaver

LineF adds a formatted string followed by a newline and returns the builder.

Example: 

sw.LineF("User ID: %d", 123)

func (*SafeStringWeaver) NewLine 

func (sw *SafeStringWeaver) NewLine() Weaver

NewLine adds a single newline character and returns the builder.

Example: 

sw.Append("Line 1").NewLine().Append("Line 2")

func (*SafeStringWeaver) NewLines 

func (sw *SafeStringWeaver) NewLines(n int) Weaver

NewLines adds n newline characters and returns the builder.

Example: 

sw.Append("Paragraph 1").NewLines(2).Append("Paragraph 2")

func (*SafeStringWeaver) Parenthesize 

func (sw *SafeStringWeaver) Parenthesize(s string) Weaver

Parenthesize wraps text in parentheses.

Example: 

sw.Parenthesize("expression") // adds (expression)

func (*SafeStringWeaver) Quote 

func (sw *SafeStringWeaver) Quote(s string) Weaver

Quote wraps text in double quotes.

Example: 

sw.Quote("quoted string") // adds "quoted string"

func (*SafeStringWeaver) Repeat 

func (sw *SafeStringWeaver) Repeat(s string, n int) Weaver

Repeat adds a string n times and returns the builder.

Example: 

sw.Repeat("-", 10) // adds "----------"

func (*SafeStringWeaver) Reset 

func (sw *SafeStringWeaver) Reset() Weaver

Reset clears the builder and returns it for reuse.

Example: 

sw.Reset().Append("Fresh start")

func (*SafeStringWeaver) Semicolon 

func (sw *SafeStringWeaver) Semicolon() Weaver

Semicolon adds a semicolon to the builder.

Example: 

sw.Append("x = 1").Semicolon()

func (*SafeStringWeaver) SingleQuote 

func (sw *SafeStringWeaver) SingleQuote(s string) Weaver

SingleQuote wraps text in single quotes.

Example: 

sw.SingleQuote("char") // adds 'char'

func (*SafeStringWeaver) Space 

func (sw *SafeStringWeaver) Space() Weaver

Space adds a single space character and returns the builder.

Example: 

sw.Append("Hello").Space().Append("World")

func (*SafeStringWeaver) Spaces 

func (sw *SafeStringWeaver) Spaces(n int) Weaver

Spaces adds n space characters and returns the builder.

Example: 

sw.Append("Key:").Spaces(4).Append("Value")

func (*SafeStringWeaver) StartBrace added in v0.1.10 

func (sw *SafeStringWeaver) StartBrace() Weaver

StartBrace adds an opening brace.

Example: 

sw.StartBrace() // adds '{'

func (*SafeStringWeaver) StartBracket added in v0.1.10 

func (sw *SafeStringWeaver) StartBracket() Weaver

StartBracket adds an opening bracket.

Example: 

sw.StartBracket() // adds '['

func (*SafeStringWeaver) StartParenthesize added in v0.1.10 

func (sw *SafeStringWeaver) StartParenthesize() Weaver

StartParenthesize adds an opening parenthesis.

Example: 

sw.StartParenthesize() // adds '('

func (*SafeStringWeaver) String 

func (sw *SafeStringWeaver) String() string

String returns the final built string.

Example: 

result := sw.String()

func (*SafeStringWeaver) Tab 

func (sw *SafeStringWeaver) Tab() Weaver

Tab adds a single tab character and returns the builder.

Example: 

sw.Append("Column1").Tab().Append("Column2")

func (*SafeStringWeaver) Tabs 

func (sw *SafeStringWeaver) Tabs(n int) Weaver

Tabs adds n tab characters and returns the builder.

Example: 

sw.Tabs(2).Append("Indented text")

func (*SafeStringWeaver) Unless 

func (sw *SafeStringWeaver) Unless(condition bool, fn func(*SafeStringWeaver)) *SafeStringWeaver

Unless executes a function on the builder if the condition is false.

Example: 

sw.Unless(isMinified, func(s *SafeStringWeaver) {
    s.NewLine().Indent(1, "")
})

func (*SafeStringWeaver) UnlessCast added in v0.1.7 

func (sw *SafeStringWeaver) UnlessCast(condition bool, fn func(w Weaver)) Weaver

UnlessCast executes a function with access to the current state without modification.

Example: 

sw.UnlessCast(isHeader, func(w Weaver) {
	w.Append("Header: ")
})

func (*SafeStringWeaver) When 

func (sw *SafeStringWeaver) When(condition bool, fn func(*SafeStringWeaver)) *SafeStringWeaver

When executes a function on the builder if the condition is true.

Example: 

sw.When(isHeader, func(s *SafeStringWeaver) {
    s.Append("# ").Line(title)
})

func (*SafeStringWeaver) WhenCast added in v0.1.7 

func (sw *SafeStringWeaver) WhenCast(condition bool, fn func(w Weaver)) Weaver

WhenCast executes a function with access to the current state without modification.

Example: 

sw.WhenCast(isHeader, func(w Weaver) {
	w.Append("Header: ")
})

func (*SafeStringWeaver) Wrap 

func (sw *SafeStringWeaver) Wrap(prefix, text, suffix string) Weaver

Wrap wraps text with a prefix and suffix.

Example: 

sw.Wrap("**", "Bold text", "**")

type StringWeaver 

type StringWeaver struct {
	// contains filtered or unexported fields
}

StringWeaver wraps strings.Builder with a fluent API for chainable operations. This implementation is NOT thread-safe and should only be used from a single goroutine. For concurrent access, use SafeStringWeaver instead.

Example: 

sw := strchain.New().Append("Hello").Space().Append("World")
fmt.Println(sw.String()) // Output: Hello World

func From 

func From(s string) *StringWeaver

From creates a new StringWeaver initialized with the given string.

Example: 

sw := strchain.From("Initial")

func FromPtr added in v0.1.5 

func FromPtr(s *strings.Builder) *StringWeaver

FromPtr creates a new StringWeaver initialized with the given strings.Builder pointer.

Example: 

sw := strchain.FromPtr(&myBuilder)

func New 

func New() *StringWeaver

New creates a new StringWeaver instance.

Example: 

sw := strchain.New()

func NewWithCapacity 

func NewWithCapacity(capacity int) *StringWeaver

NewWithCapacity creates a new StringWeaver with an initial capacity hint.

Example: 

sw := strchain.NewWithCapacity(1024)

func (*StringWeaver) Append 

func (sw *StringWeaver) Append(s string) Weaver

Append adds a string and returns the builder for chaining.

Example: 

sw.Append("hello").Append(" world")

func (*StringWeaver) AppendBool 

func (sw *StringWeaver) AppendBool(b bool) Weaver

AppendBool adds a boolean value and returns the builder.

Example: 

sw.AppendBool(true)

func (*StringWeaver) AppendByte 

func (sw *StringWeaver) AppendByte(b byte) Weaver

AppendByte adds a single byte and returns the builder.

Example: 

sw.AppendByte('a')

func (*StringWeaver) AppendBytes 

func (sw *StringWeaver) AppendBytes(b []byte) Weaver

AppendBytes adds a byte slice and returns the builder.

Example: 

sw.AppendBytes([]byte("data"))

func (*StringWeaver) AppendF 

func (sw *StringWeaver) AppendF(format string, args ...any) Weaver

AppendF adds a formatted string (printf-style) and returns the builder.

Example: 

sw.AppendF("value: %d", 42)

func (*StringWeaver) AppendFloat32 

func (sw *StringWeaver) AppendFloat32(f float32) Weaver

AppendFloat32 adds a float32 and returns the builder.

Example: 

sw.AppendFloat32(3.14)

func (*StringWeaver) AppendFloat64 

func (sw *StringWeaver) AppendFloat64(f float64) Weaver

AppendFloat64 adds a float64 and returns the builder.

Example: 

sw.AppendFloat64(3.14159)

func (*StringWeaver) AppendIf 

func (sw *StringWeaver) AppendIf(condition bool, s string) Weaver

AppendIf conditionally adds a string if the condition is true.

Example: 

sw.AppendIf(isValid, " Validated")

func (*StringWeaver) AppendIfF 

func (sw *StringWeaver) AppendIfF(condition bool, format string, args ...any) Weaver

AppendIfF conditionally adds a formatted string if the condition is true.

Example: 

sw.AppendIfF(debugMode, "Debug: %s", msg)

func (*StringWeaver) AppendInt 

func (sw *StringWeaver) AppendInt(i int) Weaver

AppendInt adds an integer and returns the builder.

Example: 

sw.AppendInt(123)

func (*StringWeaver) AppendInt8 

func (sw *StringWeaver) AppendInt8(i int8) Weaver

AppendInt8 adds an int8 and returns the builder.

Example: 

sw.AppendInt8(8)

func (*StringWeaver) AppendInt16 

func (sw *StringWeaver) AppendInt16(i int16) Weaver

AppendInt16 adds an int16 and returns the builder.

Example: 

sw.AppendInt16(16)

func (*StringWeaver) AppendInt32 

func (sw *StringWeaver) AppendInt32(i int32) Weaver

AppendInt32 adds an int32 and returns the builder.

Example: 

sw.AppendInt32(32)

func (*StringWeaver) AppendInt64 

func (sw *StringWeaver) AppendInt64(i int64) Weaver

AppendInt64 adds an int64 and returns the builder.

Example: 

sw.AppendInt64(64)

func (*StringWeaver) AppendRune 

func (sw *StringWeaver) AppendRune(r rune) Weaver

AppendRune adds a single rune and returns the builder.

Example: 

sw.AppendRune('⌘')

func (*StringWeaver) AppendUint 

func (sw *StringWeaver) AppendUint(i uint) Weaver

AppendUint adds a uint and returns the builder.

Example: 

sw.AppendUint(123)

func (*StringWeaver) AppendUint8 

func (sw *StringWeaver) AppendUint8(i uint8) Weaver

AppendUint8 adds a uint8 and returns the builder.

Example: 

sw.AppendUint8(8)

func (*StringWeaver) AppendUint16 

func (sw *StringWeaver) AppendUint16(i uint16) Weaver

AppendUint16 adds a uint16 and returns the builder.

Example: 

sw.AppendUint16(16)

func (*StringWeaver) AppendUint32 

func (sw *StringWeaver) AppendUint32(i uint32) Weaver

AppendUint32 adds a uint32 and returns the builder.

Example: 

sw.AppendUint32(32)

func (*StringWeaver) AppendUint64 

func (sw *StringWeaver) AppendUint64(i uint64) Weaver

AppendUint64 adds a uint64 and returns the builder.

Example: 

sw.AppendUint64(64)

func (*StringWeaver) AppendUintptr 

func (sw *StringWeaver) AppendUintptr(i uintptr) Weaver

AppendUintptr adds a uintptr and returns the builder.

Example: 

sw.AppendUintptr(0xdeadbeef)

func (*StringWeaver) Arrow 

func (sw *StringWeaver) Arrow() Weaver

Arrow adds an arrow (->) to the builder.

Example: 

sw.Append("source").Arrow().Append("target")

func (*StringWeaver) Brace 

func (sw *StringWeaver) Brace(s string) Weaver

Brace wraps text in curly braces.

Example: 

sw.Brace("struct definition") // adds {struct definition}

func (*StringWeaver) Bracket 

func (sw *StringWeaver) Bracket(s string) Weaver

Bracket wraps text in square brackets.

Example: 

sw.Bracket("index") // adds [index]

func (*StringWeaver) Build 

func (sw *StringWeaver) Build() string

Build is an alias for String() for fluent API consistency.

Example: 

result := sw.Append("data").Build()

func (*StringWeaver) Builder added in v0.1.4 

func (sw *StringWeaver) Builder() *strings.Builder

Builder returns the underlying strings.Builder for advanced operations.

Example: 

builder := sw.Builder()

func (*StringWeaver) Cap 

func (sw *StringWeaver) Cap() int

Cap returns the current capacity of the builder.

Example: 

capacity := sw.Cap()

func (*StringWeaver) Clone 

func (sw *StringWeaver) Clone() Weaver

Clone creates an independent copy of the current builder state.

Example: 

newSw := sw.Clone()

func (*StringWeaver) Colon 

func (sw *StringWeaver) Colon() Weaver

Colon adds a colon to the builder.

Example: 

sw.Append("Label").Colon().Space().Append("Value")

func (*StringWeaver) Comma 

func (sw *StringWeaver) Comma() Weaver

Comma adds a comma to the builder.

Example: 

sw.Append("item1").Comma().Append("item2")

func (*StringWeaver) CommaIfNotLast added in v0.1.6 

func (sw *StringWeaver) CommaIfNotLast(index, total int) Weaver

CommaIfNotLast adds a comma if the index is not the last item.

Example: 

sw.CommaIfNotLast(i, len(items)) // adds "," if i < len(items)-1

func (*StringWeaver) Dot 

func (sw *StringWeaver) Dot() Weaver

Dot adds a period to the builder.

Example: 

sw.Append("End of sentence").Dot()

func (*StringWeaver) Each 

func (sw *StringWeaver) Each(items []string, fn func(*StringWeaver, string)) *StringWeaver

Each iterates over a slice and applies a function for each element.

Example: 

sw.Each([]string{"a", "b", "c"}, func(s *StringWeaver, item string) {
    s.Append(item).Comma()
})

func (*StringWeaver) EachCast added in v0.1.7 

func (sw *StringWeaver) EachCast(items []string, fn func(w Weaver, item string)) Weaver

EachCast executes a function for each item in the slice.

Example: 

sw.EachCast(items, func(w Weaver, item string) {
	w.Append(item)
})

func (*StringWeaver) EndBrace added in v0.1.10 

func (sw *StringWeaver) EndBrace() Weaver

EndBrace adds a closing brace.

Example: 

sw.EndBrace() // adds '}'

func (*StringWeaver) EndBracket added in v0.1.10 

func (sw *StringWeaver) EndBracket() Weaver

EndBracket adds a closing bracket.

Example: 

sw.EndBracket() // adds ']'

func (*StringWeaver) EndParenthesize added in v0.1.10 

func (sw *StringWeaver) EndParenthesize() Weaver

EndParenthesize adds a closing parenthesis.

Example: 

sw.EndParenthesize() // adds ')'

func (*StringWeaver) Equals 

func (sw *StringWeaver) Equals() Weaver

Equals adds an equals sign to the builder.

Example: 

sw.Append("key").Equals().Append("value")

func (*StringWeaver) FatArrow 

func (sw *StringWeaver) FatArrow() Weaver

FatArrow adds a fat arrow (=>) to the builder.

Example: 

sw.Append("map").FatArrow().Append("result")

func (*StringWeaver) Grow 

func (sw *StringWeaver) Grow(n int) Weaver

Grow grows the builder's capacity by n bytes.

Example: 

sw.Grow(512)

func (*StringWeaver) Indent 

func (sw *StringWeaver) Indent(level int, s string) Weaver

Indent adds indentation (2 spaces per level) before appending text.

Example: 

sw.Indent(2, "Sub-item")

func (*StringWeaver) IndentF added in v0.1.6 

func (sw *StringWeaver) IndentF(level int, format string, args ...any) Weaver

IndentF adds indentation (2 spaces per level) before appending a formatted string.

Example: 

sw.IndentF(1, `"id": %q,`, "abc123")

func (*StringWeaver) IndentLine 

func (sw *StringWeaver) IndentLine(level int, s string) Weaver

IndentLine adds indentation (2 spaces per level) before text and ends with a newline.

Example: 

sw.IndentLine(1, "Point 1")

func (*StringWeaver) IndentLineF added in v0.1.6 

func (sw *StringWeaver) IndentLineF(level int, format string, args ...any) Weaver

IndentLineF adds indentation (2 spaces per level) before a formatted string and ends with a newline.

Example: 

sw.IndentLineF(1, `"id": %q,`, "abc123")

func (*StringWeaver) IndentOnly added in v0.1.10 

func (sw *StringWeaver) IndentOnly(level int) Weaver

IndentOnly adds indentation (2 spaces per level) without appending text.

Example: 

sw.IndentOnly(1) // adds '  '

func (*StringWeaver) IndentOnlyLine added in v0.1.10 

func (sw *StringWeaver) IndentOnlyLine(level int) Weaver

IndentOnlyLine adds indentation (2 spaces per level) followed by a newline.

Example: 

sw.IndentOnlyLine(1) // adds '  \n'

func (*StringWeaver) Inspect 

func (sw *StringWeaver) Inspect(fn func(current string)) Weaver

Inspect executes a function with access to the current state without modification.

Example: 

sw.Inspect(func(current string) {
    log.Printf("Current state: %s", current)
})

func (*StringWeaver) JSONArrayEnd added in v0.1.6 

func (sw *StringWeaver) JSONArrayEnd() Weaver

JSONArrayEnd adds a closing square bracket for a JSON array.

Example: 

sw.JSONArrayEnd() // adds "]"

func (*StringWeaver) JSONArrayStart added in v0.1.6 

func (sw *StringWeaver) JSONArrayStart() Weaver

JSONArrayStart adds an opening square bracket for a JSON array.

Example: 

sw.JSONArrayStart() // adds "["

func (*StringWeaver) JSONFieldArrayEnd added in v0.1.9 

func (sw *StringWeaver) JSONFieldArrayEnd(level int) Weaver

JSONFieldArrayEnd adds an indented JSON array end.

Example: 

sw.JSONFieldArrayEnd(1) // adds '  ]'

func (*StringWeaver) JSONFieldArrayStart added in v0.1.8 

func (sw *StringWeaver) JSONFieldArrayStart(level int, key string) Weaver

JSONFieldArrayStart adds an indented JSON array start.

Example: 

sw.JSONFieldArrayStart(1, "items", true) // adds '  "items": ['

func (*StringWeaver) JSONFieldBool added in v0.1.7 

func (sw *StringWeaver) JSONFieldBool(level int, key string, value bool, addComma bool) Weaver

JSONFieldBool adds an indented JSON field with a bool value.

Example: 

sw.JSONFieldBool(1, "age", 30, true) // adds '  "age": 30,\n'

func (*StringWeaver) JSONFieldFloat32 added in v0.1.7 

func (sw *StringWeaver) JSONFieldFloat32(level int, key string, value float32, addComma bool) Weaver

JSONFieldFloat32 adds an indented JSON field with a float32 value.

Example: 

sw.JSONFieldFloat32(1, "age", 30, true) // adds '  "age": 30,\n'

func (*StringWeaver) JSONFieldFloat64 added in v0.1.7 

func (sw *StringWeaver) JSONFieldFloat64(level int, key string, value float64, addComma bool) Weaver

JSONFieldFloat64 adds an indented JSON field with a float64 value.

Example: 

sw.JSONFieldFloat64(1, "age", 30, true) // adds '  "age": 30,\n'

func (*StringWeaver) JSONFieldInt added in v0.1.6 

func (sw *StringWeaver) JSONFieldInt(level int, key string, value int, addComma bool) Weaver

JSONFieldInt adds an indented JSON field with an integer value.

Example: 

sw.JSONFieldInt(1, "age", 30, true) // adds '  "age": 30,\n'

func (*StringWeaver) JSONFieldInt8 added in v0.1.7 

func (sw *StringWeaver) JSONFieldInt8(level int, key string, value int8, addComma bool) Weaver

JSONFieldInt8 adds an indented JSON field with an int8 value.

Example: 

sw.JSONFieldInt8(1, "age", 30, true) // adds '  "age": 30,\n'

func (*StringWeaver) JSONFieldInt16 added in v0.1.7 

func (sw *StringWeaver) JSONFieldInt16(level int, key string, value int16, addComma bool) Weaver

JSONFieldInt16 adds an indented JSON field with an int16 value.

Example: 

sw.JSONFieldInt16(1, "age", 30, true) // adds '  "age": 30,\n'

func (*StringWeaver) JSONFieldInt32 added in v0.1.7 

func (sw *StringWeaver) JSONFieldInt32(level int, key string, value int32, addComma bool) Weaver

JSONFieldInt32 adds an indented JSON field with an int32 value.

Example: 

sw.JSONFieldInt32(1, "age", 30, true) // adds '  "age": 30,\n'

func (*StringWeaver) JSONFieldInt64 added in v0.1.7 

func (sw *StringWeaver) JSONFieldInt64(level int, key string, value int64, addComma bool) Weaver

JSONFieldInt64 adds an indented JSON field with an int64 value.

Example: 

sw.JSONFieldInt64(1, "age", 30, true) // adds '  "age": 30,\n'

func (*StringWeaver) JSONFieldString added in v0.1.7 

func (sw *StringWeaver) JSONFieldString(level int, key, value string, addComma bool) Weaver

JSONFieldString adds an indented JSON field (key: value) with optional comma and newline. The value is properly JSON-encoded (RFC 8259).

Example: 

sw.JSONFieldString(1, "name", `"John"`, true) // adds '  "name": "John",\n'

func (*StringWeaver) JSONFieldUint added in v0.1.7 

func (sw *StringWeaver) JSONFieldUint(level int, key string, value uint, addComma bool) Weaver

JSONFieldUint adds an indented JSON field with a uint value.

Example: 

sw.JSONFieldUint(1, "age", 30, true) // adds '  "age": 30,\n'

func (*StringWeaver) JSONFieldUint8 added in v0.1.7 

func (sw *StringWeaver) JSONFieldUint8(level int, key string, value uint8, addComma bool) Weaver

JSONFieldUint8 adds an indented JSON field with a uint8 value.

Example: 

sw.JSONFieldUint8(1, "age", 30, true) // adds '  "age": 30,\n'

func (*StringWeaver) JSONFieldUint16 added in v0.1.7 

func (sw *StringWeaver) JSONFieldUint16(level int, key string, value uint16, addComma bool) Weaver

JSONFieldUint16 adds an indented JSON field with a uint16 value.

Example: 

sw.JSONFieldUint16(1, "age", 30, true) // adds '  "age": 30,\n'

func (*StringWeaver) JSONFieldUint32 added in v0.1.7 

func (sw *StringWeaver) JSONFieldUint32(level int, key string, value uint32, addComma bool) Weaver

JSONFieldUint32 adds an indented JSON field with a uint32 value.

Example: 

sw.JSONFieldUint32(1, "age", 30, true) // adds '  "age": 30,\n'

func (*StringWeaver) JSONFieldUint64 added in v0.1.7 

func (sw *StringWeaver) JSONFieldUint64(level int, key string, value uint64, addComma bool) Weaver

JSONFieldUint64 adds an indented JSON field with a uint64 value.

Example: 

sw.JSONFieldUint64(1, "age", 30, true) // adds '  "age": 30,\n'

func (*StringWeaver) JSONKey added in v0.1.6 

func (sw *StringWeaver) JSONKey(key string) Weaver

JSONKey adds a quoted key followed by a colon and space.

Example: 

sw.JSONKey("name") // adds "name":

func (*StringWeaver) JSONKeyBool added in v0.1.6 

func (sw *StringWeaver) JSONKeyBool(key string, value bool) Weaver

JSONKeyBool adds a key-value pair where the value is a boolean.

Example: 

sw.JSONKeyBool("active", true) // adds "active": true

func (*StringWeaver) JSONKeyFloat added in v0.1.6 

func (sw *StringWeaver) JSONKeyFloat(key string, value float64) Weaver

JSONKeyFloat adds a key-value pair where the value is a float.

Example: 

sw.JSONKeyFloat("price", 19.99) // adds "price": 19.99

func (*StringWeaver) JSONKeyInt added in v0.1.6 

func (sw *StringWeaver) JSONKeyInt(key string, value int) Weaver

JSONKeyInt adds a key-value pair where the value is an integer.

Example: 

sw.JSONKeyInt("age", 30) // adds "age": 30

func (*StringWeaver) JSONKeyString added in v0.1.6 

func (sw *StringWeaver) JSONKeyString(key, value string) Weaver

JSONKeyString adds a key-value pair where the value is a string. The value is properly JSON-encoded (RFC 8259).

Example: 

sw.JSONKeyString("name", "John") // adds "name": "John"

func (*StringWeaver) JSONObjectEnd added in v0.1.6 

func (sw *StringWeaver) JSONObjectEnd() Weaver

JSONObjectEnd adds a closing curly brace for a JSON object.

Example: 

sw.JSONObjectEnd() // adds "}"

func (*StringWeaver) JSONObjectStart added in v0.1.6 

func (sw *StringWeaver) JSONObjectStart() Weaver

JSONObjectStart adds an opening curly brace for a JSON object.

Example: 

sw.JSONObjectStart() // adds "{"

func (*StringWeaver) JSONString added in v0.1.6 

func (sw *StringWeaver) JSONString(s string) Weaver

JSONString adds a quoted and escaped string value. The output is proper JSON (RFC 8259) — control characters are encoded as \uXXXX sequences, not Go-specific escape sequences.

Example: 

sw.JSONString("hello") // adds "hello"

func (*StringWeaver) Join 

func (sw *StringWeaver) Join(sep string, elements ...string) Weaver

Join adds strings with a separator and returns the builder.

Example: 

sw.Join(", ", "Apple", "Banana", "Cherry")

func (*StringWeaver) Len 

func (sw *StringWeaver) Len() int

Len returns the current length of the built string.

Example: 

length := sw.Len()

func (*StringWeaver) Line 

func (sw *StringWeaver) Line(s string) Weaver

Line adds a string followed by a newline and returns the builder.

Example: 

sw.Line("First Line").Line("Second Line")

func (*StringWeaver) LineF 

func (sw *StringWeaver) LineF(format string, args ...any) Weaver

LineF adds a formatted string followed by a newline and returns the builder.

Example: 

sw.LineF("User ID: %d", 123)

func (*StringWeaver) NewLine 

func (sw *StringWeaver) NewLine() Weaver

NewLine adds a single newline character and returns the builder.

Example: 

sw.Append("Line 1").NewLine().Append("Line 2")

func (*StringWeaver) NewLines 

func (sw *StringWeaver) NewLines(n int) Weaver

NewLines adds n newline characters and returns the builder.

Example: 

sw.Append("Paragraph 1").NewLines(2).Append("Paragraph 2")

func (*StringWeaver) Parenthesize 

func (sw *StringWeaver) Parenthesize(s string) Weaver

Parenthesize wraps text in parentheses.

Example: 

sw.Parenthesize("expression") // adds (expression)

func (*StringWeaver) Quote 

func (sw *StringWeaver) Quote(s string) Weaver

Quote wraps text in double quotes.

Example: 

sw.Quote("quoted string") // adds "quoted string"

func (*StringWeaver) Repeat 

func (sw *StringWeaver) Repeat(s string, n int) Weaver

Repeat adds a string n times and returns the builder.

Example: 

sw.Repeat("-", 10) // adds "----------"

func (*StringWeaver) Reset 

func (sw *StringWeaver) Reset() Weaver

Reset clears the builder and returns it for reuse.

Example: 

sw.Reset().Append("Fresh start")

func (*StringWeaver) Semicolon 

func (sw *StringWeaver) Semicolon() Weaver

Semicolon adds a semicolon to the builder.

Example: 

sw.Append("x = 1").Semicolon()

func (*StringWeaver) SingleQuote 

func (sw *StringWeaver) SingleQuote(s string) Weaver

SingleQuote wraps text in single quotes.

Example: 

sw.SingleQuote("char") // adds 'char'

func (*StringWeaver) Space 

func (sw *StringWeaver) Space() Weaver

Space adds a single space character and returns the builder.

Example: 

sw.Append("Hello").Space().Append("World")

func (*StringWeaver) Spaces 

func (sw *StringWeaver) Spaces(n int) Weaver

Spaces adds n space characters and returns the builder.

Example: 

sw.Append("Key:").Spaces(4).Append("Value")

func (*StringWeaver) StartBrace added in v0.1.10 

func (sw *StringWeaver) StartBrace() Weaver

StartBrace adds an opening brace.

Example: 

sw.StartBrace() // adds '{'

func (*StringWeaver) StartBracket added in v0.1.10 

func (sw *StringWeaver) StartBracket() Weaver

StartBracket adds an opening bracket.

Example: 

sw.StartBracket() // adds '['

func (*StringWeaver) StartParenthesize added in v0.1.10 

func (sw *StringWeaver) StartParenthesize() Weaver

StartParenthesize adds an opening parenthesis.

Example: 

sw.StartParenthesize() // adds '('

func (*StringWeaver) String 

func (sw *StringWeaver) String() string

String returns the final built string.

Example: 

result := sw.String()

func (*StringWeaver) Tab 

func (sw *StringWeaver) Tab() Weaver

Tab adds a single tab character and returns the builder.

Example: 

sw.Append("Column1").Tab().Append("Column2")

func (*StringWeaver) Tabs 

func (sw *StringWeaver) Tabs(n int) Weaver

Tabs adds n tab characters and returns the builder.

Example: 

sw.Tabs(2).Append("Indented text")

func (*StringWeaver) Unless 

func (sw *StringWeaver) Unless(condition bool, fn func(*StringWeaver)) *StringWeaver

Unless executes a function on the builder if the condition is false.

Example: 

sw.Unless(isMinified, func(s *StringWeaver) {
    s.NewLine().Indent(1, "")
})

func (*StringWeaver) UnlessCast added in v0.1.7 

func (sw *StringWeaver) UnlessCast(condition bool, fn func(w Weaver)) Weaver

UnlessCast executes a function with access to the current state without modification.

Example: 

sw.UnlessCast(isHeader, func(w Weaver) {
	w.Append("Header: ")
})

func (*StringWeaver) When 

func (sw *StringWeaver) When(condition bool, fn func(*StringWeaver)) *StringWeaver

When executes a function on the builder if the condition is true.

Example: 

sw.When(isHeader, func(s *StringWeaver) {
    s.Append("# ").Line(title)
})

func (*StringWeaver) WhenCast added in v0.1.7 

func (sw *StringWeaver) WhenCast(condition bool, fn func(w Weaver)) Weaver

WhenCast executes a function with access to the current state without modification.

Example: 

sw.WhenCast(isHeader, func(w Weaver) {
	w.Append("Header: ")
})

func (*StringWeaver) Wrap 

func (sw *StringWeaver) Wrap(prefix, text, suffix string) Weaver

Wrap wraps text with a prefix and suffix.

Example: 

sw.Wrap("**", "Bold text", "**")

type Weaver 

type Weaver interface {

	// Append adds a string and returns the builder for chaining.
	Append(s string) Weaver

	// AppendF adds a formatted string (printf-style) and returns the builder.
	AppendF(format string, args ...any) Weaver

	// AppendByte adds a single byte and returns the builder.
	AppendByte(b byte) Weaver

	// AppendRune adds a single rune and returns the builder.
	AppendRune(r rune) Weaver

	// AppendBytes adds a byte slice and returns the builder.
	AppendBytes(b []byte) Weaver

	// AppendInt adds an integer and returns the builder.
	AppendInt(i int) Weaver

	// AppendInt8 adds an int8 and returns the builder.
	AppendInt8(i int8) Weaver

	// AppendInt16 adds an int16 and returns the builder.
	AppendInt16(i int16) Weaver

	// AppendInt32 adds an int32 and returns the builder.
	AppendInt32(i int32) Weaver

	// AppendInt64 adds an int64 and returns the builder.
	AppendInt64(i int64) Weaver

	// AppendUint adds a uint and returns the builder.
	AppendUint(i uint) Weaver

	// AppendUint8 adds a uint8 and returns the builder.
	AppendUint8(i uint8) Weaver

	// AppendUint16 adds a uint16 and returns the builder.
	AppendUint16(i uint16) Weaver

	// AppendUint32 adds a uint32 and returns the builder.
	AppendUint32(i uint32) Weaver

	// AppendUint64 adds a uint64 and returns the builder.
	AppendUint64(i uint64) Weaver

	// AppendUintptr adds a uintptr and returns the builder.
	AppendUintptr(i uintptr) Weaver

	// AppendFloat32 adds a float32 and returns the builder.
	AppendFloat32(f float32) Weaver

	// AppendFloat64 adds a float64 and returns the builder.
	AppendFloat64(f float64) Weaver

	// AppendBool adds a boolean value and returns the builder.
	AppendBool(b bool) Weaver

	// Space adds a single space character and returns the builder.
	Space() Weaver

	// Spaces adds n space characters and returns the builder.
	Spaces(n int) Weaver

	// Tab adds a single tab character and returns the builder.
	Tab() Weaver

	// Tabs adds n tab characters and returns the builder.
	Tabs(n int) Weaver

	// NewLine adds a single newline character and returns the builder.
	NewLine() Weaver

	// NewLines adds n newline characters and returns the builder.
	NewLines(n int) Weaver

	// Line adds a string followed by a newline and returns the builder.
	Line(s string) Weaver

	// LineF adds a formatted string followed by a newline and returns the builder.
	LineF(format string, args ...any) Weaver

	// Repeat adds a string n times and returns the builder.
	Repeat(s string, n int) Weaver

	// Join adds strings with a separator and returns the builder.
	Join(sep string, elements ...string) Weaver

	// AppendIf conditionally adds a string if the condition is true.
	AppendIf(condition bool, s string) Weaver

	// AppendIfF conditionally adds a formatted string if the condition is true.
	AppendIfF(condition bool, format string, args ...any) Weaver

	// Indent adds indentation (2 spaces per level) before appending text.
	Indent(level int, s string) Weaver

	// IndentLine adds indentation (2 spaces per level) before text and ends with a newline.
	IndentLine(level int, s string) Weaver

	// Wrap wraps text with a prefix and suffix.
	Wrap(prefix, text, suffix string) Weaver

	// Quote wraps text in double quotes.
	Quote(s string) Weaver

	// SingleQuote wraps text in single quotes.
	SingleQuote(s string) Weaver

	// Parenthesize wraps text in parentheses.
	Parenthesize(s string) Weaver

	// Bracket wraps text in square brackets.
	Bracket(s string) Weaver

	// Brace wraps text in curly braces.
	Brace(s string) Weaver

	// Comma adds a comma to the builder.
	Comma() Weaver

	// Dot adds a period to the builder.
	Dot() Weaver

	// Colon adds a colon to the builder.
	Colon() Weaver

	// Semicolon adds a semicolon to the builder.
	Semicolon() Weaver

	// Equals adds an equals sign to the builder.
	Equals() Weaver

	// Arrow adds an arrow (->) to the builder.
	Arrow() Weaver

	// FatArrow adds a fat arrow (=>) to the builder.
	FatArrow() Weaver

	// Grow grows the builder's capacity by n bytes.
	Grow(n int) Weaver

	// Reset clears the builder and returns it for reuse.
	Reset() Weaver

	// Len returns the current length of the built string.
	Len() int

	// Cap returns the current capacity of the builder.
	Cap() int

	// String returns the final built string.
	String() string

	// Build is an alias for String() for fluent API consistency.
	Build() string

	// Clone creates an independent copy of the current builder state.
	Clone() Weaver

	// Inspect executes a function with access to the current state without modification.
	Inspect(fn func(current string)) Weaver

	// Builder returns the underlying strings.Builder for advanced operations.
	Builder() *strings.Builder

	// IndentF adds indentation (2 spaces per level) before appending a formatted string.
	IndentF(level int, format string, args ...any) Weaver

	// IndentLineF adds indentation (2 spaces per level) before a formatted string and ends with a newline.
	IndentLineF(level int, format string, args ...any) Weaver

	// JSONObjectStart adds an opening curly brace for a JSON object.
	JSONObjectStart() Weaver

	// JSONObjectEnd adds a closing curly brace for a JSON object.
	JSONObjectEnd() Weaver

	// JSONArrayStart adds an opening square bracket for a JSON array.
	JSONArrayStart() Weaver

	// JSONArrayEnd adds a closing square bracket for a JSON array.
	JSONArrayEnd() Weaver

	// JSONString adds a quoted and escaped string value.
	JSONString(s string) Weaver

	// JSONKey adds a quoted key followed by a colon and space.
	JSONKey(key string) Weaver

	// JSONKeyString adds a key-value pair where the value is a string.
	JSONKeyString(key, value string) Weaver

	// JSONKeyInt adds a key-value pair where the value is an integer.
	JSONKeyInt(key string, value int) Weaver

	// JSONKeyBool adds a key-value pair where the value is a boolean.
	JSONKeyBool(key string, value bool) Weaver

	// JSONKeyFloat adds a key-value pair where the value is a float.
	JSONKeyFloat(key string, value float64) Weaver

	// JSONFieldString adds an indented JSON field (key: value) with optional comma and newline.
	JSONFieldString(level int, key, value string, addComma bool) Weaver

	// JSONFieldInt adds an indented JSON field with an integer value.
	JSONFieldInt(level int, key string, value int, addComma bool) Weaver

	// JSONFieldInt8 adds an indented JSON field with an int8 value.
	JSONFieldInt8(level int, key string, value int8, addComma bool) Weaver

	// JSONFieldInt16 adds an indented JSON field with an int16 value.
	JSONFieldInt16(level int, key string, value int16, addComma bool) Weaver

	// JSONFieldInt32 adds an indented JSON field with an int32 value.
	JSONFieldInt32(level int, key string, value int32, addComma bool) Weaver

	// JSONFieldInt64 adds an indented JSON field with an int64 value.
	JSONFieldInt64(level int, key string, value int64, addComma bool) Weaver

	// JSONFieldUint adds an indented JSON field with a uint value.
	JSONFieldUint(level int, key string, value uint, addComma bool) Weaver

	// JSONFieldUint8 adds an indented JSON field with a uint8 value.
	JSONFieldUint8(level int, key string, value uint8, addComma bool) Weaver

	// JSONFieldUint16 adds an indented JSON field with a uint16 value.
	JSONFieldUint16(level int, key string, value uint16, addComma bool) Weaver

	// JSONFieldUint32 adds an indented JSON field with a uint32 value.
	JSONFieldUint32(level int, key string, value uint32, addComma bool) Weaver

	// JSONFieldUint64 adds an indented JSON field with a uint64 value.
	JSONFieldUint64(level int, key string, value uint64, addComma bool) Weaver

	// JSONFieldFloat32 adds an indented JSON field with a float32 value.
	JSONFieldFloat32(level int, key string, value float32, addComma bool) Weaver

	// JSONFieldFloat64 adds an indented JSON field with a float64 value.
	JSONFieldFloat64(level int, key string, value float64, addComma bool) Weaver

	// JSONFieldBool adds an indented JSON field with a bool value.
	JSONFieldBool(level int, key string, value bool, addComma bool) Weaver

	// CommaIfNotLast adds a comma if the index is not the last item.
	CommaIfNotLast(index, total int) Weaver

	// WhenCast executes a function with access to the current state without modification.
	WhenCast(condition bool, fn func(w Weaver)) Weaver

	// UnlessCast executes a function with access to the current state without modification.
	UnlessCast(condition bool, fn func(w Weaver)) Weaver

	// EachCast executes a function for each item in the slice.
	EachCast(items []string, fn func(w Weaver, item string)) Weaver

	// JSONFieldArrayStart adds an indented JSON array start.
	//
	// Example:
	//
	//	sw.JSONFieldArrayStart(1, "items") // adds '  "items": ['
	JSONFieldArrayStart(level int, key string) Weaver

	// JSONFieldArrayEnd adds an indented JSON array end.
	//
	// Example:
	//
	//	sw.JSONFieldArrayEnd(1) // adds '  ]'
	JSONFieldArrayEnd(level int) Weaver

	// StartParenthesize adds an opening parenthesis.
	//
	// Example:
	//
	//	sw.StartParenthesize() // adds '('
	StartParenthesize() Weaver

	// EndParenthesize adds a closing parenthesis.
	//
	// Example:
	//
	//	sw.EndParenthesize() // adds ')'
	EndParenthesize() Weaver

	// StartBracket adds an opening bracket.
	//
	// Example:
	//
	//	sw.StartBracket() // adds '['
	StartBracket() Weaver

	// EndBracket adds a closing bracket.
	//
	// Example:
	//
	//	sw.EndBracket() // adds ']'
	EndBracket() Weaver

	// StartBrace adds an opening curly brace.
	//
	// Example:
	//
	//	sw.StartBrace() // adds '{'
	StartBrace() Weaver

	// EndBrace adds a closing curly brace.
	//
	// Example:
	//
	//	sw.EndBrace() // adds '}'
	EndBrace() Weaver

	// IndentOnly adds indentation (2 spaces per level) without appending text.
	//
	// Example:
	//
	//	sw.IndentOnly(1) // adds '  '
	IndentOnly(level int) Weaver

	// IndentOnlyLine adds indentation (2 spaces per level) followed by a newline.
	//
	// Example:
	//
	//	sw.IndentOnlyLine(1) // adds '  \n'
	IndentOnlyLine(level int) Weaver
}

Weaver defines the common interface for fluent string builder operations. Both StringWeaver (non-thread-safe, maximum performance) and SafeStringWeaver (thread-safe with mutex synchronization) implement this interface.

Use Weaver when you need polymorphism — for example, a function that accepts either a StringWeaver or a SafeStringWeaver as a parameter.

Methods that accept callback functions with concrete receiver types (When, Unless, Each) are not included in this interface because their function parameter types differ between StringWeaver and SafeStringWeaver. These methods are available only on the concrete types.

Example: 

var w strchain.Weaver = strchain.New()
result := w.Append("Hello").Space().Append("World").Build()

var sw strchain.Weaver = strchain.NewSafe()
result = sw.Append("Hello").Space().Append("World").Build()

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.