22200209868

Committed 19 Feb 2026 09:08PM UTC coverage: 89.376% (-0.4%) from 89.809%

Build # 22200209868

Build Type

push

github

Committed by

enetx

Commit Message

perf: reduce allocations across string, collection, and encoding types

string:
- Lower/Upper/IsLower/IsUpper/IsTitle: Bytes() → BytesUnsafe()/StringUnsafe()
- Random: ASCII fast-path with WriteByte, avoid global charset Runes() alloc
- ReplaceNth: Builder instead of triple string concatenation
- Chunks: ASCII fast-path (zero-copy slicing); Unicode path via
  utf8.DecodeRuneInString, eliminating []rune alloc and per-chunk String([]rune) alloc
- Truncate: ASCII fast-path + single-pass Unicode walk; drop LenRunes()+Runes() double scan
- Center: cache s.LenRunes() and pad.LenRunes() (4 scans → 2)
- writePadding: ASCII fast-path with WriteByte; non-ASCII via utf8.DecodeRuneInString,
  eliminating pad.Runes() alloc on every call
- Reverse: BytesUnsafe()/StringUnsafe()
- Similarity: plain []int for DP table, min() builtins

string/hash: BytesUnsafe()/StringUnsafe() for MD5/SHA1/SHA256/SHA512

string/encode:
- Base64/JSON: BytesUnsafe() to avoid copy
- URL: Grow() pre-allocation
- Hex: inline lookup table — zero per-byte allocs (was: strconv.FormatInt per byte)
- Binary: inline bit shift — zero per-byte allocs (was: fmt.Sprintf per byte)
- Octal: strconv.AppendInt into stack buffer — zero per-rune allocs

string/compress: all five writers use BytesUnsafe() instead of io.WriteString
  (io.WriteString on non-StringWriter falls back to []byte(s) copy)

int: Hex/Octal use strconv.FormatInt instead of fmt.Sprintf

set/map/map_ordered: simplify NewX size param (drop Slice[Int] unwrap indirection)

String() methods: add Grow() pre-allocation to Slice, Set, Map, MapOrd,
  MapSafe, Heap, Deque (n*8 or n*16 estimate reduces realloc churn)

slice: Join pre-computes exact size and uses a single strings.Builder,
  eliminating intermediate []string allocation

Coverage Stats

133 of 164 new or added lines in 12 files covered. (81.1%)

9 existing lines in 4 files now uncovered.

5325 of 5958 relevant lines covered (89.38%)

14237.01 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

88.14

/string.go

package g

import (
        "database/sql/driver"
        "fmt"
        "math/big"
        "slices"
        "strconv"
        "strings"
        "unicode"
        "unicode/utf8"
        "unsafe"

        "github.com/enetx/g/cmp"
        "github.com/enetx/g/f"
        "golang.org/x/text/unicode/norm"
)

// String is an alias for the string type.
type String string

// Named is a map-like type that stores key-value pairs for resolving named
// placeholders in Sprintf.
type Named Map[String, any]

// NewString creates a new String from the provided string.
func NewString[T ~string | rune | byte | ~[]rune | ~[]byte](str T) String { return String(str) }

// Clone returns a copy of the String.
// It ensures that the returned String does not share underlying memory with the original String,
// making it safe to modify or store independently.
func (s String) Clone() String { return String(strings.Clone(s.Std())) }

// Transform applies a transformation function to the String and returns the result.
func (s String) Transform(fn func(String) String) String { return fn(s) }

// Builder returns a new Builder initialized with the content of the String.
func (s String) Builder() *Builder {
        b := new(Builder)
        b.WriteString(s)
        return b
}

// Min returns the minimum of Strings.
func (s String) Min(b ...String) String { return cmp.Min(append(b, s)...) }

// Max returns the maximum of Strings.
func (s String) Max(b ...String) String { return cmp.Max(append(b, s)...) }

// Random generates a random String of the specified length, selecting characters from predefined sets.
// If additional character sets are provided, only those will be used; the default set (ASCII_LETTERS and DIGITS)
// is excluded unless explicitly provided.
//
// Parameters:
// - count (Int): Length of the random String to generate.
// - letters (...String): Additional character sets to consider for generating the random String (optional).
//
// Returns:
// - String: Randomly generated String with the specified length.
//
// Example usage:
//
//        randomString := g.String.Random(10)
//        randomString contains a random String with 10 characters.
func (String) Random(length Int, letters ...String) String {
        var b Builder
        b.Grow(length)

        if len(letters) != 0 {
                var buf Builder

                for _, set := range letters {
                        _, _ = buf.WriteString(set)
                }

                chars := buf.String().Runes()
                n := Int(len(chars))

                for range length {
                        b.WriteRune(chars[n.Random()])
                }
        } else {
                const charset = ASCII_LETTERS + DIGITS
                n := charset.Len()

                for range length {
                        b.WriteByte(charset[n.Random().Std()])
                }
        }

        return b.String()
}

// IsASCII checks if all characters in the String are ASCII bytes.
func (s String) IsASCII() bool {
        for i := range s {
                if s[i] >= 0x80 {
                        return false
                }
        }

        return true
}

// IsDigit checks if all characters in the String are digits.
func (s String) IsDigit() bool {
        if s.IsEmpty() {
                return false
        }

        for _, c := range s {
                if !unicode.IsDigit(c) {
                        return false
                }
        }

        return true
}

// TryInt tries to parse the String as an int and returns an Int.
func (s String) TryInt() Result[Int] {
        hint, err := strconv.ParseInt(s.Std(), 0, 64)
        if err != nil {
                return Err[Int](err)
        }

        return Ok(Int(hint))
}

// TryBigInt attempts to convert the String receiver into an Option containing a *big.Int.
// This function assumes the string represents a numerical value, which can be in decimal,
// hexadecimal (prefixed with "0x"), or octal (prefixed with "0") format. The function
// leverages the SetString method of the math/big package, automatically detecting the
// numeric base when set to 0.
//
// If the string is correctly formatted and represents a valid number, TryBigInt returns
// a Some containing the *big.Int parsed from the string. If the string is empty, contains
// invalid characters, or does not conform to a recognizable numeric format, TryBigInt
// returns a None, indicating that the conversion was unsuccessful.
//
// Returns:
//   - An Option[*big.Int] encapsulating the conversion result. It returns Some[*big.Int]
//     with the parsed value if successful, otherwise None[*big.Int] if the parsing fails.
func (s String) TryBigInt() Option[*big.Int] {
        if bigInt, ok := new(big.Int).SetString(s.Std(), 0); ok {
                return Some(bigInt)
        }

        return None[*big.Int]()
}

// TryFloat tries to parse the String as a float64 and returns an Float.
func (s String) TryFloat() Result[Float] {
        float, err := strconv.ParseFloat(s.Std(), 64)
        if err != nil {
                return Err[Float](err)
        }

        return Ok(Float(float))
}

// Title converts the String to title case.
func (s String) Title() String { return String(title.String(s.Std())) }

// Lower returns the String in lowercase.
func (s String) Lower() String { return s.BytesUnsafe().Lower().StringUnsafe() }

// Upper returns the String in uppercase.
func (s String) Upper() String { return s.BytesUnsafe().Upper().StringUnsafe() }

// IsLower checks if the String consists only of lowercase letters.
func (s String) IsLower() bool { return s.BytesUnsafe().IsLower() }

// IsUpper checks if the String consists only of uppercase letters.
func (s String) IsUpper() bool { return s.BytesUnsafe().IsUpper() }

// IsTitle checks if the String is in title case.
func (s String) IsTitle() bool { return s.BytesUnsafe().IsTitle() }

// Trim removes leading and trailing white space from the String.
func (s String) Trim() String { return String(strings.TrimSpace(s.Std())) }

// TrimStart removes leading white space from the String.
func (s String) TrimStart() String { return String(strings.TrimLeftFunc(s.Std(), unicode.IsSpace)) }

// TrimEnd removes trailing white space from the String.
func (s String) TrimEnd() String { return String(strings.TrimRightFunc(s.Std(), unicode.IsSpace)) }

// TrimSet removes the specified set of characters from both the beginning and end of the String.
func (s String) TrimSet(cutset String) String { return String(strings.Trim(s.Std(), cutset.Std())) }

// TrimStartSet removes the specified set of characters from the beginning of the String.
func (s String) TrimStartSet(cutset String) String {
        return String(strings.TrimLeft(s.Std(), cutset.Std()))
}

// TrimEndSet removes the specified set of characters from the end of the String.
func (s String) TrimEndSet(cutset String) String {
        return String(strings.TrimRight(s.Std(), cutset.Std()))
}

// StripPrefix trims the specified prefix from the String.
func (s String) StripPrefix(prefix String) String {
        return String(strings.TrimPrefix(s.Std(), prefix.Std()))
}

// StripSuffix trims the specified suffix from the String.
func (s String) StripSuffix(suffix String) String {
        return String(strings.TrimSuffix(s.Std(), suffix.Std()))
}

// Replace replaces the 'oldS' String with the 'newS' String for the specified number of
// occurrences.
func (s String) Replace(oldS, newS String, n Int) String {
        return String(strings.Replace(s.Std(), oldS.Std(), newS.Std(), n.Std()))
}

// ReplaceAll replaces all occurrences of the 'oldS' String with the 'newS' String.
func (s String) ReplaceAll(oldS, newS String) String {
        return String(strings.ReplaceAll(s.Std(), oldS.Std(), newS.Std()))
}

// ReplaceMulti creates a custom replacer to perform multiple string replacements.
//
// Parameters:
//
// - oldnew ...String: Pairs of strings to be replaced. Specify as many pairs as needed.
//
// Returns:
//
// - String: A new string with replacements applied using the custom replacer.
//
// Example usage:
//
//        original := g.String("Hello, world! This is a test.")
//        replaced := original.ReplaceMulti(
//            "Hello", "Greetings",
//            "world", "universe",
//            "test", "example",
//        )
//        // replaced contains "Greetings, universe! This is an example."
func (s String) ReplaceMulti(oldnew ...String) String {
        pairs := make([]string, len(oldnew))
        for i, str := range oldnew {
                pairs[i] = str.Std()
        }

        return String(strings.NewReplacer(pairs...).Replace(s.Std()))
}

// Remove removes all occurrences of specified substrings from the String.
//
// Parameters:
//
// - matches ...String: Substrings to be removed from the string. Specify as many substrings as needed.
//
// Returns:
//
// - String: A new string with all specified substrings removed.
//
// Example usage:
//
//        original := g.String("Hello, world! This is a test.")
//        modified := original.Remove(
//            "Hello",
//            "test",
//        )
//        // modified contains ", world! This is a ."
func (s String) Remove(matches ...String) String {
        if len(matches) == 0 {
                return s
        }

        pairs := make([]string, len(matches)*2)
        for i, match := range matches {
                pairs[i*2] = match.Std()
                pairs[i*2+1] = ""
        }

        return String(strings.NewReplacer(pairs...).Replace(s.Std()))
}

// ReplaceNth returns a new String instance with the nth occurrence of oldS
// replaced with newS. If there aren't enough occurrences of oldS, the
// original String is returned. If n is less than -1, the original String
// is also returned. If n is -1, the last occurrence of oldS is replaced with newS.
//
// Returns:
//
// - A new String instance with the nth occurrence of oldS replaced with newS.
//
// Example usage:
//
//        s := g.String("The quick brown dog jumped over the lazy dog.")
//        result := s.ReplaceNth("dog", "fox", 2)
//        fmt.Println(result)
//
// Output: "The quick brown dog jumped over the lazy fox.".
func (s String) ReplaceNth(oldS, newS String, n Int) String {
        if n < -1 || len(oldS) == 0 {
                return s
        }

        count, i := Int(0), Int(0)

        for {
                pos := s[i:].Index(oldS)
                if pos == -1 {
                        break
                }

                pos += i
                count++

                if count == n || (n == -1 && s[pos+oldS.Len():].Index(oldS) == -1) {
                        var b Builder
                        b.WriteString(s[:pos])
                        b.WriteString(newS)
                        b.WriteString(s[pos+oldS.Len():])

                        return b.String()
                }

                i = pos + oldS.Len()
        }

        return s
}

// Contains checks if the String contains the specified substring.
func (s String) Contains(substr String) bool { return f.Contains(substr)(s) }

// ContainsAny checks if the String contains any of the specified substrings.
func (s String) ContainsAny(substrs ...String) bool {
        return slices.ContainsFunc(substrs, s.Contains)
}

// ContainsAll checks if the given String contains all the specified substrings.
func (s String) ContainsAll(substrs ...String) bool {
        for _, substr := range substrs {
                if !s.Contains(substr) {
                        return false
                }
        }

        return true
}

// ContainsAnyChars checks if the String contains any characters from the specified String.
func (s String) ContainsAnyChars(chars String) bool { return f.ContainsAnyChars(chars)(s) }

// StartsWith checks if the String starts with the specified prefix.
// It uses a higher-order function to perform the check.
func (s String) StartsWith(prefix String) bool { return f.StartsWith(prefix)(s) }

// StartsWithAny checks if the String starts with any of the provided prefixes.
// The method accepts a variable number of arguments, allowing for checking against multiple
// prefixes at once. It iterates over the provided prefixes and uses the HasPrefix function from
// the strings package to check if the String starts with each prefix.
// The function returns true if the String starts with any of the prefixes, and false otherwise.
//
// Example usage:
//
//        s := g.String("http://example.com")
//        if s.StartsWithAny("http://", "https://") {
//           // do something
//        }
func (s String) StartsWithAny(prefixes ...String) bool {
        return slices.ContainsFunc(prefixes, s.StartsWith)
}

// EndsWith checks if the String ends with the specified suffix.
// It uses a higher-order function to perform the check.
func (s String) EndsWith(suffix String) bool { return f.EndsWith(suffix)(s) }

// EndsWithAny checks if the String ends with any of the provided suffixes.
// The method accepts a variable number of arguments, allowing for checking against multiple
// suffixes at once. It iterates over the provided suffixes and uses the HasSuffix function from
// the strings package to check if the String ends with each suffix.
// The function returns true if the String ends with any of the suffixes, and false otherwise.
//
// Example usage:
//
//        s := g.String("example.com")
//        if s.EndsWithAny(".com", ".net") {
//           // do something
//        }
func (s String) EndsWithAny(suffixes ...String) bool {
        return slices.ContainsFunc(suffixes, s.EndsWith)
}

// Lines splits the String by lines and returns the iterator.
func (s String) Lines() SeqSlice[String] {
        return transformSeq(strings.Lines(s.Std()), NewString).Map(String.TrimEnd)
}

// Fields splits the String into a slice of substrings, removing any whitespace, and returns the iterator.
func (s String) Fields() SeqSlice[String] {
        return transformSeq(strings.FieldsSeq(s.Std()), NewString)
}

// FieldsBy splits the String into a slice of substrings using a custom function to determine the field boundaries,
// and returns the iterator.
func (s String) FieldsBy(fn func(r rune) bool) SeqSlice[String] {
        return transformSeq(strings.FieldsFuncSeq(s.Std(), fn), NewString)
}

// Split splits the String by the specified separator and returns the iterator.
func (s String) Split(sep ...String) SeqSlice[String] {
        var separator String
        if len(sep) != 0 {
                separator = sep[0]
        }

        return transformSeq(strings.SplitSeq(s.Std(), separator.Std()), NewString)
}

// SplitAfter splits the String after each instance of the specified separator and returns the iterator.
func (s String) SplitAfter(sep String) SeqSlice[String] {
        return transformSeq(strings.SplitAfterSeq(s.Std(), sep.Std()), NewString)
}

// SplitN splits the String into substrings using the provided separator and returns an Slice[String] of the results.
// The n parameter controls the number of substrings to return:
// - If n is negative, there is no limit on the number of substrings returned.
// - If n is zero, an empty Slice[String] is returned.
// - If n is positive, at most n substrings are returned.
func (s String) SplitN(sep String, n Int) Slice[String] {
        return TransformSlice(strings.SplitN(s.Std(), sep.Std(), n.Std()), NewString)
}

// Chunks splits the String into chunks of the specified size.
//
// This function iterates through the String, creating new String chunks of the specified size.
// If size is less than or equal to 0 or the String is empty,
// it returns an empty Slice[String].
// If size is greater than or equal to the length of the String,
// it returns an Slice[String] containing the original String.
//
// Parameters:
//
// - size (Int): The size of the chunks to split the String into.
//
// Returns:
//
// - Slice[String]: A slice of String chunks of the specified size.
//
// Example usage:
//
//        text := g.String("Hello, World!")
//        chunks := text.Chunks(4)
//
// chunks contains {"Hell", "o, W", "orld", "!"}.
func (s String) Chunks(size Int) SeqSlice[String] {
        if size.Lte(0) || s.IsEmpty() {
                return func(func(String) bool) {}
        }

        if s.IsASCII() {
                n := size.Std()
                l := len(s)

                if n >= l {
                        return func(yield func(String) bool) { yield(s) }
                }

                return func(yield func(String) bool) {
                        for i := 0; i < l; i += n {
                                if !yield(s[i:min(i+n, l)]) {
                                        return
                                }
                        }
                }
        }

        n := size.Std()

        return func(yield func(String) bool) {
                rest := s
                for !rest.IsEmpty() {
                        i := 0
                        for count := 0; count < n && i < len(rest); count++ {
                                _, sz := utf8.DecodeRuneInString(string(rest)[i:])
                                i += sz
                        }

                        if !yield(rest[:i]) {
                                return
                        }

                        rest = rest[i:]
                }
        }
}

// Cut returns two String values. The first String contains the remainder of the
// original String after the cut. The second String contains the text between the
// first occurrences of the 'start' and 'end' strings, with tags removed if specified.
//
// The function searches for the 'start' and 'end' strings within the String.
// If both are found, it returns the first String containing the remainder of the
// original String after the cut, followed by the second String containing the text
// between the first occurrences of 'start' and 'end' with tags removed if specified.
//
// If either 'start' or 'end' is empty or not found in the String, it returns the
// original String as the second String, and an empty String as the first.
//
// Parameters:
//
// - start (String): The String marking the beginning of the text to be cut.
//
// - end (String): The String marking the end of the text to be cut.
//
//   - rmtags (bool, optional): An optional boolean parameter indicating whether
//     to remove 'start' and 'end' tags from the cut text. Defaults to false.
//
// Returns:
//
//   - String: The first String containing the remainder of the original String
//     after the cut, with tags removed if specified,
//     or an empty String if 'start' or 'end' is empty or not found.
//
//   - String: The second String containing the text between the first occurrences of
//     'start' and 'end', or the original String if 'start' or 'end' is empty or not found.
//
// Example usage:
//
//        s := g.String("Hello, [world]! How are you?")
//        remainder, cut := s.Cut("[", "]")
//        // remainder: "Hello, ! How are you?"
//        // cut: "world"
func (s String) Cut(start, end String, rmtags ...bool) (String, String) {
        if start.IsEmpty() || end.IsEmpty() {
                return s, ""
        }

        startIndex := s.Index(start)
        if startIndex == -1 {
                return s, ""
        }

        startEnd := startIndex + start.Len()
        endIndex := s[startEnd:].Index(end)
        if endIndex == -1 {
                return s, ""
        }

        cut := s[startEnd : startEnd+endIndex]

        if len(rmtags) != 0 && !rmtags[0] {
                startEnd += end.Len()
                return s[:startIndex] + s[startIndex:startEnd+endIndex] + s[startEnd+endIndex:], cut
        }

        return s[:startIndex] + s[startEnd+endIndex+end.Len():], cut
}

// Similarity calculates the similarity between two Strings using the
// Levenshtein distance algorithm and returns the similarity percentage as an Float.
//
// The function compares two Strings using the Levenshtein distance,
// which measures the difference between two sequences by counting the number
// of single-character edits required to change one sequence into the other.
// The similarity is then calculated by normalizing the distance by the maximum
// length of the two input Strings.
//
// Parameters:
//
// - str (String): The String to compare with s.
//
// Returns:
//
// - Float: The similarity percentage between the two Strings as a value between 0 and 100.
//
// Example usage:
//
//        s1 := g.String("kitten")
//        s2 := g.String("sitting")
//        similarity := s1.Similarity(s2) // 57.14285714285714
func (s String) Similarity(str String) Float {
        if s.Eq(str) {
                return 100
        }

        if s.IsEmpty() || str.IsEmpty() {
                return 0
        }

        s1 := s.Runes()
        s2 := str.Runes()

        n1, n2 := len(s1), len(s2)

        if n1 > n2 {
                s1, s2, n1, n2 = s2, s1, n2, n1
        }

        distance := make([]int, n1+1)

        for i, r2 := range s2 {
                prev := i + 1

                for j, r1 := range s1 {
                        current := distance[j]
                        if r2 != r1 {
                                current = min(distance[j]+1, min(prev+1, distance[j+1]+1))
                        }

                        distance[j], prev = prev, current
                }

                distance[n1] = prev
        }

        return Float(1-float64(distance[n1])/float64(max(n1, n2))) * 100
}

// Cmp compares two Strings and returns an cmp.Ordering indicating their relative order.
// The result will be cmp.Equal if s==str, cmp.Less if s < str, and cmp.Greater if s > str.
func (s String) Cmp(str String) cmp.Ordering { return cmp.Cmp(s, str) }

// Append appends the specified String to the current String.
func (s String) Append(str String) String { return s + str }

// Prepend prepends the specified String to the current String.
func (s String) Prepend(str String) String { return str + s }

// ContainsRune checks if the String contains the specified rune.
func (s String) ContainsRune(r rune) bool { return strings.ContainsRune(s.Std(), r) }

// Count returns the number of non-overlapping instances of the substring in the String.
func (s String) Count(substr String) Int { return Int(strings.Count(s.Std(), substr.Std())) }

// Empty checks if the String is empty.
func (s String) IsEmpty() bool { return len(s) == 0 }

// Eq checks if two Strings are equal.
func (s String) Eq(str String) bool { return s == str }

// EqFold compares two String strings case-insensitively.
func (s String) EqFold(str String) bool { return strings.EqualFold(s.Std(), str.Std()) }

// Gt checks if the String is greater than the specified String.
func (s String) Gt(str String) bool { return s > str }

// Gte checks if the String is greater than or equal to the specified String.
func (s String) Gte(str String) bool { return s >= str }

// Bytes returns the String as an Bytes.
func (s String) Bytes() Bytes { return Bytes(s) }

// BytesUnsafe converts the String into Bytes without copying memory.
// Warning: the resulting Bytes shares the same underlying memory as the original String.
// If the original String is modified through unsafe operations (rare), or if it is garbage collected,
// the Bytes may become invalid or cause undefined behavior.
func (s String) BytesUnsafe() Bytes { return unsafe.Slice(unsafe.StringData(s.Std()), len(s)) }

// Index returns the index of the first instance of the specified substring in the String, or -1
// if substr is not present in s.
func (s String) Index(substr String) Int { return Int(strings.Index(s.Std(), substr.Std())) }

// LastIndex returns the index of the last instance of the specified substring in the String, or -1
// if substr is not present in s.
func (s String) LastIndex(substr String) Int { return Int(strings.LastIndex(s.Std(), substr.Std())) }

// IndexRune returns the index of the first instance of the specified rune in the String.
func (s String) IndexRune(r rune) Int { return Int(strings.IndexRune(s.Std(), r)) }

// Len returns the length of the String.
func (s String) Len() Int { return Int(len(s)) }

// LenRunes returns the number of runes in the String.
func (s String) LenRunes() Int { return Int(utf8.RuneCountInString(s.Std())) }

// Lt checks if the String is less than the specified String.
func (s String) Lt(str String) bool { return s < str }

// Lte checks if the String is less than or equal to the specified String.
func (s String) Lte(str String) bool { return s <= str }

// Map applies the provided function to all runes in the String and returns the resulting String.
func (s String) Map(fn func(rune) rune) String { return String(strings.Map(fn, s.Std())) }

// NormalizeNFC returns a new String with its Unicode characters normalized using the NFC form.
func (s String) NormalizeNFC() String { return String(norm.NFC.String(s.Std())) }

// Ne checks if two Strings are not equal.
func (s String) Ne(str String) bool { return !s.Eq(str) }

// Reader returns a *strings.Reader initialized with the content of String.
func (s String) Reader() *strings.Reader { return strings.NewReader(s.Std()) }

// Repeat returns a new String consisting of the specified count of the original String.
func (s String) Repeat(count Int) String { return String(strings.Repeat(s.Std(), count.Std())) }

// Reverse reverses the String.
func (s String) Reverse() String { return s.BytesUnsafe().Reverse().StringUnsafe() }

// Runes returns the String as a slice of runes.
func (s String) Runes() Slice[rune] { return []rune(s) }

// Chars splits the String into individual characters and returns the iterator.
func (s String) Chars() SeqSlice[String] { return s.Split() }

// SubString extracts a substring from the String starting at the 'start' index and ending before the 'end' index.
// The function also supports an optional 'step' parameter to define the increment between indices in the substring.
// If 'start' or 'end' index is negative, they represent positions relative to the end of the String:
// - A negative 'start' index indicates the position from the end of the String, moving backward.
// - A negative 'end' index indicates the position from the end of the String.
// The function ensures that indices are adjusted to fall within the valid range of the String's length.
// If indices are out of bounds or if 'start' exceeds 'end', the function returns the original String unmodified.
func (s String) SubString(start, end Int, step ...Int) String {
        return String(s.Runes().SubSlice(start, end, step...))
}

// Std returns the String as a string.
func (s String) Std() string { return string(s) }

// Format applies a specified format to the String object.
func (s String) Format(template String) String { return Format(template, s) }

// Truncate shortens the String to the specified maximum length. If the String exceeds the
// specified length, it is truncated, and an ellipsis ("...") is appended to indicate the truncation.
//
// If the length of the String is less than or equal to the specified maximum length, the
// original String is returned unchanged.
//
// The method respects Unicode characters and truncates based on the number of runes,
// not bytes.
//
// Parameters:
//   - max: The maximum number of runes allowed in the resulting String.
//
// Returns:
//   - A new String truncated to the specified maximum length with "..." appended
//     if truncation occurs. Otherwise, returns the original String.
//
// Example usage:
//
//        s := g.String("Hello, World!")
//        result := s.Truncate(5)
//        // result: "Hello..."
//
//        s2 := g.String("Short")
//        result2 := s2.Truncate(10)
//        // result2: "Short"
//
//        s3 := g.String("😊😊😊😊😊")
//        result3 := s3.Truncate(3)
//        // result3: "😊😊😊..."
func (s String) Truncate(max Int) String {
        if max.IsNegative() {
                return s
        }

        if s.IsASCII() {
                if Int(len(s)) <= max {
                        return s
                }

                return s[:max].Append("...")
        }

        i := 0
        for count := Int(0); i < len(s); count++ {
                if count == max {
                        return s[:i].Append("...")
                }

                _, sz := utf8.DecodeRuneInString(string(s)[i:])
                i += sz
        }

        return s
}

// LeftJustify justifies the String to the left by adding padding to the right, up to the
// specified length. If the length of the String is already greater than or equal to the specified
// length, or the pad is empty, the original String is returned.
//
// The padding String is repeated as necessary to fill the remaining length.
// The padding is added to the right of the String.
//
// Parameters:
//   - length: The desired length of the resulting justified String.
//   - pad: The String used as padding.
//
// Example usage:
//
//        s := g.String("Hello")
//        result := s.LeftJustify(10, "...")
//        // result: "Hello....."
func (s String) LeftJustify(length Int, pad String) String {
        rlen := s.LenRunes()
        if rlen >= length || pad.IsEmpty() {
                return s
        }

        var b Builder

        _, _ = b.WriteString(s)
        writePadding(&b, pad, pad.LenRunes(), length-rlen)

        return b.String()
}

// RightJustify justifies the String to the right by adding padding to the left, up to the
// specified length. If the length of the String is already greater than or equal to the specified
// length, or the pad is empty, the original String is returned.
//
// The padding String is repeated as necessary to fill the remaining length.
// The padding is added to the left of the String.
//
// Parameters:
//   - length: The desired length of the resulting justified String.
//   - pad: The String used as padding.
//
// Example usage:
//
//        s := g.String("Hello")
//        result := s.RightJustify(10, "...")
//        // result: ".....Hello"
func (s String) RightJustify(length Int, pad String) String {
        rlen := s.LenRunes()
        if rlen >= length || pad.IsEmpty() {
                return s
        }

        var b Builder

        writePadding(&b, pad, pad.LenRunes(), length-rlen)
        _, _ = b.WriteString(s)

        return b.String()
}

// Center justifies the String by adding padding on both sides, up to the specified length.
// If the length of the String is already greater than or equal to the specified length, or the
// pad is empty, the original String is returned.
//
// The padding String is repeated as necessary to evenly distribute the remaining length on both
// sides.
// The padding is added to the left and right of the String.
//
// Parameters:
//   - length: The desired length of the resulting justified String.
//   - pad: The String used as padding.
//
// Example usage:
//
//        s := g.String("Hello")
//        result := s.Center(10, "...")
//        // result: "..Hello..."
func (s String) Center(length Int, pad String) String {
        slen := s.LenRunes()
        if slen >= length || pad.IsEmpty() {
                return s
        }

        var b Builder

        padlen := pad.LenRunes()
        remains := length - slen

        writePadding(&b, pad, padlen, remains/2)
        _, _ = b.WriteString(s)
        writePadding(&b, pad, padlen, (remains+1)/2)

        return b.String()
}

// writePadding writes the padding String to the output Builder to fill the remaining length.
// It repeats the padding String as necessary and appends any remaining runes from the padding
// String.
func writePadding(b *Builder, pad String, padlen, remains Int) {
        if repeats := remains / padlen; repeats > 0 {
                _, _ = b.WriteString(pad.Repeat(repeats))
        }

        rem := remains % padlen
        if rem == 0 {
                return
        }

        if pad.IsASCII() {
                for i := range rem {
                        b.WriteByte(pad[i])
                }

                return
        }

        i := 0
        for range rem {
                r, sz := utf8.DecodeRuneInString(string(pad)[i:])
                _, _ = b.WriteRune(r)
                i += sz
        }
}

// Print writes the content of the String to the standard output (console)
// and returns the String unchanged.
func (s String) Print() String { fmt.Print(s); return s }

// Println writes the content of the String to the standard output (console) with a newline
// and returns the String unchanged.
func (s String) Println() String { fmt.Println(s); return s }

// Scan implements the database/sql.Scanner interface for g.String.
//
// Behavior:
//   - If src is nil, the String is set to an empty string.
//   - If src is a string, it is directly assigned.
//   - If src is a []byte, it is converted to a string.
//   - Otherwise, an error is returned.
//
// Supported SQL types (common):
//   - TEXT / VARCHAR → string
//   - BLOB / BYTEA  → []byte (converted to string)
//
// Notes:
//   - This method allows g.String to be used directly with database/sql and compatible drivers.
func (s *String) Scan(src any) error {
        if src == nil {
                *s = ""
                return nil
        }

        switch v := src.(type) {
        case string:
                *s = String(v)
                return nil
        case []byte:
                *s = String(v)
                return nil
        default:
                return fmt.Errorf("g.String.Scan: cannot scan %T into g.String", src)
        }
}

// Value implements the database/sql/driver.Valuer interface for g.String.
//
// Behavior:
//   - Returns the underlying string value, ready for database insertion.
//   - Always returns a value compatible with SQL TEXT / VARCHAR types.
func (s String) Value() (driver.Value, error) { return string(s), nil }

enetx / g / 22200209868

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous