README
¶
Str Package
The str package provides a comprehensive set of string manipulation utilities for the Dracory framework.
It offers a wide range of functions for string operations, validation, transformation, and formatting.
Overview
This package includes utilities for:
- String Manipulation: Functions for modifying, extracting, and transforming strings
- String Validation: Functions for checking string properties and patterns
- String Formatting: Functions for formatting strings in various ways
- String Conversion: Functions for converting between different string formats and encodings
- String Generation: Functions for generating random strings and hashes
- Price Formatting: Functions for formatting prices with currency symbols
Key Features
- Pattern Matching: Check if strings match patterns using glob syntax
- String Extraction: Extract substrings based on various criteria
- String Transformation: Convert strings to different formats (camelCase, snake_case, etc.)
- String Validation: Check if strings are empty, UUIDs, ULIDs, etc.
- String Encoding: Encode and decode strings using various encodings (Base32, Base64, etc.)
- String Hashing: Generate hashes from strings (MD5, BCrypt, etc.)
- String Formatting: Format strings with padding, truncation, etc.
- String Generation: Generate random strings and identifiers
- Price Formatting: Format prices with currency symbols (USD, GBP, EUR)
Usage Examples
String Validation
import "github.com/dracory/str"
// Check if a string is empty
isEmpty := str.IsEmpty("") // true
// Check if a string is not empty
isNotEmpty := str.IsNotEmpty("Hello") // true
// Check if a string is a UUID
isUUID := str.IsUUID("123e4567-e89b-12d3-a456-426614174000") // true
// Check if a string is a ULID
isULID := str.IsULID("01H9Z8K2P3M4N5Q6R7S8T9U0V") // true
// Check if a string matches a pattern
matches := str.Is("hello.txt", "*.txt") // true
String Manipulation
import "github.com/dracory/str"
// Extract substring between two strings
between := str.Between("Hello [World] Test", "[", "]") // "World"
// Extract substring before a string
before := str.Before("Hello World", "World") // "Hello "
// Extract substring after a string
after := str.After("Hello World", "Hello ") // "World"
// Extract substring before the last occurrence of a string
beforeLast := str.BeforeLast("Hello World World", "World") // "Hello "
// Extract substring after the last occurrence of a string
afterLast := str.AfterLast("Hello World World", "World") // ""
// Extract substring from the left
leftFrom := str.LeftFrom("Hello World", 5) // "Hello"
// Extract substring from the right
rightFrom := str.RightFrom("Hello World", 5) // "World"
// Truncate a string
truncated := str.Truncate("Hello World", 8, "...") // "Hello..."
// Convert to snake_case
snake := str.ToSnake("HelloWorld") // "hello_world"
// Convert to camelCase
camel := str.ToCamel("hello_world") // "helloWorld"
// Convert first character to uppercase
ucFirst := str.UcFirst("hello") // "Hello"
// Convert string to uppercase
upper := str.Upper("hello") // "HELLO"
// Split string into words
words := str.Words("Hello World") // ["Hello", "World"]
// Count words in a string
wordCount := str.WordCount("Hello World") // 2
// Create a URL-friendly slug
slug := str.Slugify("Hello World!", '-') // "hello-world"
String Encoding and Hashing
import "github.com/dracory/str"
// Encode string to Base64
base64 := str.Base64Encode("Hello World") // "SGVsbG8gV29ybGQ="
// Decode Base64 string
decoded := str.Base64Decode("SGVsbG8gV29ybGQ=") // "Hello World"
// Encode string to Base32 Extended
base32 := str.Base32ExtendedEncode("Hello World") // "91IMOR3FCPBI41"
// Decode Base32 Extended string
decoded := str.Base32ExtendedDecode("91IMOR3FCPBI41") // "Hello World"
// Generate MD5 hash
md5 := str.MD5("Hello World") // "b10a8db164e0754105b7a99be72e3fe5"
// Generate BCrypt hash
bcrypt := str.ToBcryptHash("password") // "$2a$10$..."
// Compare password with BCrypt hash
matches := str.BcryptHashCompare("password", bcrypt) // true
String Generation
import "github.com/dracory/str"
// Generate a random string
random := str.Random(10) // "a1b2c3d4e5"
// Generate a random string from a gamma distribution
randomGamma := str.RandomFromGamma(10, 2.0, 1.0) // "a1b2c3d4e5"
// Convert integer to Base32
base32 := str.IntToBase32(12345) // "3RP"
// Convert integer to Base36
base36 := str.IntToBase36(12345) // "9IX"
Price Formatting
import "github.com/dracory/str"
// Get currency symbol (Unicode by default)
symbol := str.CurrencySymbol("USD") // "$"
symbol := str.CurrencySymbol("GBP") // "£"
symbol := str.CurrencySymbol("EUR") // "€"
symbol := str.CurrencySymbol("JPY") // "¥"
symbol := str.CurrencySymbol("INR") // "₹"
// Get currency symbol as HTML entity
symbol := str.CurrencySymbol("GBP", true) // "£"
symbol := str.CurrencySymbol("EUR", true) // "€"
// Supports 40+ currencies including:
// Major: USD, EUR, GBP, JPY, CNY, INR, KRW, RUB, TRY
// Dollar variants: AUD, CAD, HKD, SGD, NZD, MXN, BRL, ARS
// European: CHF, SEK, NOK, DKK, PLN, CZK, HUF, RON, BGN
// Middle East & Africa: SAR, AED, ILS, ZAR, EGP, NGN, KES
// Asian: THB, IDR, MYR, PHP, VND, PKR, BDT
// Crypto: BTC, ETH
// Convert float to formatted price string (Unicode by default)
price := str.ToPrice(19.99, "USD") // "$19.99"
price := str.ToPrice(100.00, "GBP") // "£100.00"
price := str.ToPrice(5000.50, "JPY") // "¥5000.50"
// Convert float to formatted price string with HTML entity
price := str.ToPrice(19.99, "GBP", true) // "£19.99"
price := str.ToPrice(45.50, "EUR", true) // "€45.50"
// Convert string to formatted price string (with error handling)
price, err := str.ToPriceFromString("19.99", "USD") // "$19.99", nil
price, err := str.ToPriceFromString("invalid", "USD") // "", error
// Convert string to formatted price string with HTML entity
price, err := str.ToPriceFromString("19.99", "GBP", true) // "£19.99", nil
// Convert string to formatted price string (with default fallback)
price := str.ToPriceFromStringOrDefault("19.99", "USD", "n/a") // "$19.99"
price := str.ToPriceFromStringOrDefault("invalid", "USD", "n/a") // "n/a"
// Convert string to formatted price string with HTML entity and default fallback
price := str.ToPriceFromStringOrDefault("19.99", "EUR", "n/a", true) // "€19.99"
Best Practices
- Use Appropriate Functions: Choose the most specific function for your task
- Handle Errors: Check for errors when using functions that can fail
- Consider Performance: Some functions may be more efficient than others for your use case
- Validate Input: Always validate input strings before processing them
- Use Constants: Use constants for repeated string values
License
This package is part of the dracory/base project and is licensed under the same terms.
Documentation
¶
Index ¶
- func AddSlashes(str string) string
- func AddSlashesCustom(str string, escapeChars string) string
- func After(str, needle string) string
- func AfterLast(str, needle string) string
- func Append(values ...string) string
- func Base32ExtendedDecode(data []byte) (text []byte, err error)
- func Base32ExtendedEncode(data []byte) (text []byte, err error)
- func Base64Decode(text []byte) (data []byte, err error)
- func Base64Encode(data []byte) (text []byte, err error)
- func Basename(p string, suffix ...string) string
- func BcryptHashCompare(str string, hash string) bool
- func Before(str, needle string) string
- func BeforeLast(str, needle string) string
- func Between(str string, startNeedle string, endNeedle string) (result string, found bool)
- func BetweenFirst(str, start, end string) string
- func CharAt(str string, index int) string
- func ChopEnd(str string, needle string, more ...string) string
- func ChopStart(str string, needle string, more ...string) string
- func Contains(str string, values ...string) bool
- func ContainsAll(str string, values ...string) bool
- func ContainsAnyChar(str string, charset string) bool
- func ContainsOnly(str string, charset string) bool
- func CurrencySymbol(currencyCode string, htmlEntity ...bool) string
- func Dirname(p string, levels ...int) string
- func EndsWith(str string, values ...string) bool
- func Exactly(str, value string) bool
- func Excerpt(str, phrase string, options ...ExcerptOption) string
- func Explode(str, delimiter string, limit ...int) []string
- func Finish(str, suffix string) string
- func Headline(in string) string
- func IntToBase32(num int) string
- func IntToBase36(num int) string
- func Is(str string, patterns ...string) bool
- func IsAscii(str string) bool
- func IsEmpty(str string) bool
- func IsMap(str string) bool
- func IsMatch(str string, patterns ...string) bool
- func IsNotEmpty(str string) bool
- func IsSlice(str string) bool
- func IsUlid(str string) bool
- func IsUuid(str string) bool
- func LTrim(in string, characters ...string) string
- func LcFirst(in string) string
- func LeftFrom(str, needle string) string
- func LeftPad(s string, padStr string, overallLen int) string
- func Length(in string) int
- func Lower(in string) string
- func MD5(text string) string
- func Mask(in, character string, index int, length ...int) string
- func Match(in, pattern string) string
- func MatchAll(in, pattern string) []string
- func Maximum(a, b int) int
- func NewLine(in string, count ...int) string
- func PadBoth(str string, length int, pad ...string) string
- func PadLeft(str string, length int, pad ...string) string
- func PadRight(str string, length int, pad ...string) string
- func Pipe(in string, callback func(string) string) string
- func Random(length int) string
- func RandomFromGamma(length int, gamma string) string
- func RemovePrefix(str string, prefix string) string
- func RemoveSuffix(str string, suffix string) string
- func RightFrom(str, needle string) string
- func RightPad(s string, padStr string, overallLen int) string
- func Slugify(s string, replaceWith rune) string
- func Studly(in string) string
- func Substr(str string, start int, length ...int) string
- func Title(in string) string
- func ToBcryptHash(str string) (string, error)
- func ToBytes(s string) []byte
- func ToCamel(in string) string
- func ToPrice(price float64, currencyCode string, htmlEntity ...bool) string
- func ToPriceFromString(priceStr string, currencyCode string, htmlEntity ...bool) (string, error)
- func ToPriceFromStringOrDefault(priceStr string, currencyCode string, defaultValue string, htmlEntity ...bool) string
- func ToSnake(in string) string
- func Truncate(str string, length int, ellipsis string) string
- func UcFirst(str string) string
- func UcSplit(s string) []string
- func Upper(str string) string
- func WordCount(str string) int
- func Words(str string, limit int, end ...string) string
- type ExcerptOption
- type StringBuilder
- func (sb *StringBuilder) Append(parts ...string) *StringBuilder
- func (sb *StringBuilder) Exactly(str string) bool
- func (sb *StringBuilder) LTrim(chars ...string) *StringBuilder
- func (sb *StringBuilder) Prepend(prefix string) *StringBuilder
- func (sb *StringBuilder) RTrim(chars ...string) *StringBuilder
- func (sb *StringBuilder) String() string
- func (sb *StringBuilder) Unless(predicate func(*StringBuilder) bool, ...) *StringBuilder
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AddSlashes ¶
AddSlashes returns a string with backslashes added before characters that need to be escaped.
These characters are: single quote (') double quote (") backslash (\)
func AddSlashesCustom ¶
AddSlashesCustom returns a string with backslashes added before characters specified in the escapeChars string.
func Base32ExtendedDecode ¶
Base32ExtendedDecode encodes binary data to base32 extended (RFC 4648) encoded text.
func Base32ExtendedEncode ¶
Base32ExtendedEncode encodes binary data to base32 extended (RFC 4648) encoded text.
func Base64Decode ¶
Base64Decode decodes base64 text to binary data.
func Base64Encode ¶
Base64Encode encodes binary data to base64 encoded text.
func Basename ¶ added in v0.6.0
Basename returns the basename of the file path string, and trims the suffix based on the parameter (optional). Example: Basename("/path/to/file.txt") returns "file.txt" Example: Basename("/path/to/file.txt", ".txt") returns "file"
func BcryptHashCompare ¶
BcryptHashCompare compares the string to a bcrypt hash
func Before ¶
Before returns the substring before the first occurrence of the specified search string.
func BeforeLast ¶
BeforeLast returns the substring before the last occurrence of the specified search string.
func BetweenFirst ¶ added in v0.6.0
BetweenFirst returns the substring between the first occurrence of the start string and the first occurrence of the end string after the start. If either start or end is empty or not found, returns empty string. Example: BetweenFirst("Hello [World] and [Universe]", "[", "]") returns "World"
func CharAt ¶
CharAt returns the character at the specified index.
If the specified index is negative, it is counted from the end of the string.
Business logic: 1. Convert the string to a rune slice for proper handling of UTF-8 encoding. 2. Get the length of the rune slice. 3. Handle negative indices by converting them to positive indices (e.g. -1 -> length - 1). 4. Check if the index is out of bounds. 5. If the index is out of bounds, return an empty string. 6. Return the character at the specified index.
Example:
str.CharAt("Hello World", 0) // Returns "H"
str.CharAt("Hello World", -1) // Returns "d"
str.CharAt("Hello World", 20) // Returns ""
Parameters: - str: The string to get the character from. - index: The index of the character to get.
Returns: - The character at the specified index.
func ChopEnd ¶ added in v0.6.0
ChopEnd removes the first matching suffix found in needle or more from the end of str. If none of the provided suffixes match, the original string is returned unchanged.
func ChopStart ¶ added in v0.6.0
ChopStart removes the first matching prefix found in needle or more from the start of str. If none of the provided prefixes match, the original string is returned unchanged.
func Contains ¶ added in v0.6.0
Contains returns true if str contains any of the provided values. Empty values are ignored. If no non-empty values are provided, returns false.
func ContainsAll ¶ added in v0.6.0
ContainsAll returns true if str contains all the provided values. Empty values are treated as matches (consistent with strings.Contains behaviour).
func ContainsAnyChar ¶
ContainsAnyChar returns true if the string contains any of the characters in the provided charset
func ContainsOnly ¶
ContainsOnly returns true is the string contains only charcters from the specified charset
func CurrencySymbol ¶ added in v0.5.0
CurrencySymbol returns the symbol for the given ISO 4217 currency code. By default, returns the Unicode symbol. Pass true to get HTML entity instead. Returns the original currency code if not recognized. Example: CurrencySymbol("USD") returns "$" Example: CurrencySymbol("GBP", true) returns "£"
func Dirname ¶ added in v0.7.0
Dirname returns the directory portion of the provided path. By default it returns the parent directory; provide levels to traverse multiple parents.
func EndsWith ¶ added in v0.7.0
EndsWith returns true if str ends with any of the provided values. Empty values are ignored. If no non-empty values are provided, returns false.
func Excerpt ¶ added in v0.7.0
func Excerpt(str, phrase string, options ...ExcerptOption) string
Excerpt returns a substring surrounding the first occurrence of phrase. The radius controls how many runes are kept on each side of the phrase, and omission specifies the string to append when content is truncated. If phrase is not found, the original string is returned unchanged.
func Explode ¶ added in v0.7.0
Explode splits the input string using the provided delimiter. An optional limit mirrors PHP's explode semantics:
>0 keeps at most limit elements, combining the remainder into the last element. <0 omits the last |limit| elements. 0 is treated as if no limit was provided.
func Finish ¶ added in v0.7.0
Finish appends the suffix to str, ensuring it appears only once at the end.
func Headline ¶ added in v0.7.0
Headline converts a string into headline case. When the input already contains whitespace, it is simply title-cased. Otherwise, the string is normalized, converted to studly case, split on uppercase boundaries, and the resulting words are joined with spaces.
func IntToBase32 ¶
func IntToBase36 ¶
func IsNotEmpty ¶
IsNotEmpty returns true if the string is not empty.
func LTrim ¶ added in v0.8.0
LTrim removes leading characters from the input string. When no character set is provided, leading Unicode whitespace is trimmed.
func Mask ¶ added in v0.8.0
Mask replaces a portion of the string with a repeated masking character. The index marks the starting rune offset, with negative values counting backwards from the end. If length is omitted the remainder of the string is masked. When the masking character is empty or the target segment is empty, the original string is returned unchanged.
func Match ¶ added in v0.8.0
Match returns the first substring that matches the provided regular expression. If the pattern is empty, the original string is returned unchanged.
func MatchAll ¶ added in v0.8.0
MatchAll returns all substrings that match the provided regular expression. If the pattern is empty, the entire string is returned as the single result.
func NewLine ¶ added in v0.8.0
NewLine appends new line characters to the input string. When no count is provided, a single newline is appended. Otherwise, count[0] specifies how many newline characters to add.
func PadBoth ¶ added in v0.8.0
PadBoth pads the string on both sides to reach the desired length. Padding is evenly split between the left and right; when an odd number of characters is required, the extra character is added to the right side. The optional pad argument specifies the padding characters; it defaults to a single space when omitted or empty.
func PadLeft ¶ added in v0.8.0
PadLeft pads the string on the left to reach the specified length. When the pad argument is omitted or empty, spaces are used.
func PadRight ¶ added in v0.8.0
PadRight pads the string on the right to reach the specified length. When the pad argument is omitted or empty, spaces are used.
func Pipe ¶ added in v0.8.0
Pipe passes the string through the provided callback and returns the result. If callback is nil, the original string is returned unchanged.
func RandomFromGamma ¶
RandomFromGamma generates random string of specified length with the characters specified in the gamma string
func RemovePrefix ¶
func RemoveSuffix ¶
func Slugify ¶
StrSlugify replaces each run of characters which are not ASCII letters or numbers with the Replacement character, except for leading or trailing runs. Letters will be stripped of diacritical marks and lowercased. Letter or number codepoints that do not have combining marks or a lower-cased variant will be passed through unaltered.
func Studly ¶ added in v0.7.0
Studly converts a string to StudlyCase (also known as UpperCamelCase).
func Substr ¶
Substr returns a substring of a given string, starting at the specified index and with a specified length. It handles UTF-8 encoded strings.
func Title ¶ added in v0.7.0
Title returns the input string converted to title case using the default language-independent rules.
func ToBcryptHash ¶
ToBcryptHash converts the string to bcrypt hash
func ToPrice ¶ added in v0.5.0
ToPrice converts a float64 price to a formatted string with the given ISO 4217 currency code. The price is formatted to 2 decimal places. By default, returns Unicode symbol. Pass true to get HTML entity instead. Example: ToPrice(19.99, "USD") returns "$19.99" Example: ToPrice(19.99, "GBP", true) returns "£19.99"
func ToPriceFromString ¶ added in v0.5.0
ToPriceFromString converts a string price to a formatted price string with the given ISO 4217 currency code. Returns an error if the string cannot be parsed as a float. The price is formatted to 2 decimal places. By default, returns Unicode symbol. Pass true to get HTML entity instead. Example: ToPriceFromString("19.99", "USD") returns "$19.99", nil Example: ToPriceFromString("19.99", "GBP", true) returns "£19.99", nil
func ToPriceFromStringOrDefault ¶ added in v0.5.0
func ToPriceFromStringOrDefault(priceStr string, currencyCode string, defaultValue string, htmlEntity ...bool) string
ToPriceFromStringOrDefault converts a string price to a formatted price string with the given ISO 4217 currency code. Returns the defaultValue if the string cannot be parsed as a float. The price is formatted to 2 decimal places. By default, returns Unicode symbol. Pass true to get HTML entity instead. Example: ToPriceFromStringOrDefault("19.99", "USD", "n/a") returns "$19.99" Example: ToPriceFromStringOrDefault("invalid", "USD", "n/a") returns "n/a" Example: ToPriceFromStringOrDefault("19.99", "GBP", "n/a", true) returns "£19.99"
func ToSnake ¶
ToSnake convert the given string to snake case following the Golang format: acronyms are converted to lower-case and preceded by an underscore.
Types ¶
type ExcerptOption ¶ added in v0.7.0
ExcerptOption configures the behaviour of Excerpt.
type StringBuilder ¶ added in v0.7.0
type StringBuilder struct {
// contains filtered or unexported fields
}
func Of ¶ added in v0.7.0
func Of(value string) *StringBuilder
func (*StringBuilder) Append ¶ added in v0.7.0
func (sb *StringBuilder) Append(parts ...string) *StringBuilder
func (*StringBuilder) Exactly ¶ added in v0.7.0
func (sb *StringBuilder) Exactly(str string) bool
func (*StringBuilder) LTrim ¶ added in v0.7.0
func (sb *StringBuilder) LTrim(chars ...string) *StringBuilder
func (*StringBuilder) Prepend ¶ added in v0.7.0
func (sb *StringBuilder) Prepend(prefix string) *StringBuilder
func (*StringBuilder) RTrim ¶ added in v0.7.0
func (sb *StringBuilder) RTrim(chars ...string) *StringBuilder
func (*StringBuilder) String ¶ added in v0.7.0
func (sb *StringBuilder) String() string
func (*StringBuilder) Unless ¶ added in v0.7.0
func (sb *StringBuilder) Unless(predicate func(*StringBuilder) bool, fallback func(*StringBuilder) *StringBuilder) *StringBuilder
Source Files
¶
- add_slashes.go
- after.go
- after_last.go
- append.go
- base32_extended_decode.go
- base32_extended_encode.go
- base64_decode.go
- base64_encode.go
- basename.go
- bcrypt_hash_compare.go
- before.go
- before_last.go
- between.go
- between_first.go
- builders.go
- char_at.go
- chop_end.go
- chop_start.go
- contains.go
- contains_all.go
- contains_any_char.go
- contains_only.go
- currency_symbol.go
- dirname.go
- ends_with.go
- exactly.go
- excerpt.go
- explode.go
- finish.go
- functions.go
- headline.go
- int_to_base32.go
- int_to_base36.go
- is.go
- is_match.go
- isascii.go
- isempty.go
- ismap.go
- isnotempty.go
- isslice.go
- isulid.go
- isuuid.go
- lc_first.go
- left_from.go
- left_pad.go
- length.go
- lower.go
- ltrim.go
- mask.go
- match.go
- match_all.go
- maximum.go
- md5.go
- newline.go
- pad_both.go
- pad_left.go
- pad_right.go
- pipe.go
- random.go
- random_from_gamma.go
- remove_prefix.go
- remove_suffix.go
- right_from.go
- right_pad.go
- slugify.go
- str.go
- studly.go
- substr.go
- title.go
- to_bcrypt_hash.go
- to_bytes.go
- to_camel.go
- to_price.go
- to_price_from_string.go
- to_snake.go
- truncate.go
- uc_first.go
- uc_split.go
- upper.go
- word_count.go
- words.go