`(sigil string)`

(sigil string) - String Formatting and Manipulation

Provides string formatting, searching, and transformation functions. The format function uses printf-style directives for building strings, while utility functions handle common operations like trimming, splitting, and case conversion.

(import (sigil string))

(format "Hello, ~a!" "world")       ; => "Hello, world!"
(string-split "a,b,c" ",")          ; => ("a" "b" "c")
(string-upcase "hello")             ; => "HELLO"

Exports

formatprocedure

Build a formatted string using template directives.

Directives:

~a - Insert argument using display (human-readable)
~s - Insert argument using write (machine-readable, quoted strings)
~% - Insert a newline
~~ - Insert a literal tilde

(format "Name: ~a, Age: ~a" "Alice" 30)
; => "Name: Alice, Age: 30"

(format "Items: ~s" '(1 2 3))
; => "Items: (1 2 3)"

(format "Line 1~%Line 2")
; => "Line 1\nLine 2"

strprocedure

Concatenate values into a single string.

Each argument is converted to its string representation and concatenated. More efficient than multiple string-append calls.

(str "Hello" " " "World")  ; => "Hello World"
(str "Value: " 42)         ; => "Value: 42"
(str "List: " '(a b c))    ; => "List: (a b c)"

string-repeatprocedure

Repeat a string a given number of times.

(string-repeat "ab" 3)   ; => "ababab"
(string-repeat "-" 10)   ; => "----------"
(string-repeat "x" 0)    ; => ""

string-padprocedure

Pad a string to a minimum width.

By default, pads on the left with spaces. Optional arguments specify the padding character and side (left or right).

(string-pad "42" 5)              ; => "   42"
(string-pad "42" 5 #\0)          ; => "00042"
(string-pad "hi" 5 #\space 'right) ; => "hi   "

string-trimprocedure

Remove whitespace from both ends of a string.

Whitespace includes spaces, tabs, and newlines.

(string-trim "  hello  ")    ; => "hello"
(string-trim "\n\ttext\n")   ; => "text"

string-trim-startprocedure

Remove whitespace from the beginning of a string.

(string-trim-start "  hello")  ; => "hello"

string-trim-endprocedure

Remove whitespace from the end of a string.

(string-trim-end "hello  ")    ; => "hello"

string-findprocedure

Find the position of a substring within a string.

Returns the index of the first occurrence, or #f if not found. An optional start index begins the search from that position.

(string-find "hello world" "world")    ; => 6
(string-find "hello world" "x")        ; => #f
(string-find "abcabc" "bc" 2)          ; => 4

string-indexprocedure

Find the first character position matching a predicate.

Searches from left to right. Optional start and end indices limit the search range.

(string-index "hello" char-upper-case?)  ; => #f
(string-index "Hello" char-upper-case?)  ; => 0
(string-index "abc123" char-numeric?)    ; => 3

string-index-rightprocedure

Find the last character position matching a predicate.

Searches from right to left. Optional start and end indices limit the search range.

(string-index-right "hello" (lambda (c) (eq? c #\l)))  ; => 3
(string-index-right "abc" char-upper-case?)            ; => #f

string-contains?procedure

Check if a string contains a substring.

(string-contains? "hello world" "world")  ; => #t
(string-contains? "hello" "x")            ; => #f

string-starts-with?procedure

Check if a string starts with a given prefix.

(string-starts-with? "hello" "he")   ; => #t
(string-starts-with? "hello" "lo")   ; => #f
(string-starts-with? "hello" "")     ; => #t

string-ends-with?procedure

Check if a string ends with a given suffix.

(string-ends-with? "hello" "lo")     ; => #t
(string-ends-with? "hello" "he")     ; => #f
(string-ends-with? "hello" "")       ; => #t

string-countprocedure

Count non-overlapping occurrences of a substring.

Returns the number of times the substring appears in the string. Occurrences do not overlap.

(string-count "abcabc" "bc")    ; => 2
(string-count "aaa" "a")        ; => 3
(string-count "aaa" "aa")       ; => 1 (non-overlapping)
(string-count "hello" "x")      ; => 0
(string-count "" "x")           ; => 0

string-splitprocedure

Split a string into a list of substrings.

The delimiter is not included in the results.

(string-split "a,b,c" ",")        ; => ("a" "b" "c")
(string-split "hello world" " ")  ; => ("hello" "world")
(string-split "no-delim" ",")     ; => ("no-delim")

string-replaceprocedure

Replace all occurrences of a substring.

(string-replace "hello" "l" "L")      ; => "heLLo"
(string-replace "aaa" "a" "bb")       ; => "bbbbbb"
(string-replace "hello" "x" "y")      ; => "hello"

string-upcaseprocedure

Convert a string to uppercase.

(string-upcase "hello")    ; => "HELLO"
(string-upcase "Hello!")   ; => "HELLO!"

string-downcaseprocedure

Convert a string to lowercase.

(string-downcase "HELLO")  ; => "hello"
(string-downcase "Hello!") ; => "hello!"

string-capitalizeprocedure

Capitalize the first character of a string.

The first character is converted to uppercase, and the rest of the string is left unchanged.

(string-capitalize "hello")        ; => "Hello"
(string-capitalize "HELLO")        ; => "HELLO"
(string-capitalize "hello world")  ; => "Hello world"
(string-capitalize "")             ; => ""

string-titlecaseprocedure

Convert a string to title case.

The first character of each word is capitalized, and all other characters are converted to lowercase. Words are separated by whitespace.

(string-titlecase "hello world")   ; => "Hello World"
(string-titlecase "HELLO WORLD")   ; => "Hello World"
(string-titlecase "hello")         ; => "Hello"
(string-titlecase "")              ; => ""

string-empty?procedure

Check if a string has zero length.

(string-empty? "")      ; => #t
(string-empty? "x")     ; => #f
(string-empty? "   ")   ; => #f (use string-blank? for whitespace)

string-blank?procedure

Check if a string is empty or contains only whitespace.

(string-blank? "")        ; => #t
(string-blank? "   ")     ; => #t
(string-blank? "\n\t")    ; => #t
(string-blank? "  x  ")   ; => #f

string<?procedure

Compare strings lexicographically (less than).

Characters are compared by their Unicode code points.

(string<? "apple" "banana")  ; => #t
(string<? "abc" "abd")       ; => #t
(string<? "abc" "abc")       ; => #f

string>?procedure

Compare strings lexicographically (greater than).

(string>? "banana" "apple")  ; => #t
(string>? "abc" "abc")       ; => #f

string<=?procedure

Compare strings lexicographically (less than or equal).

(string<=? "abc" "abd")  ; => #t
(string<=? "abc" "abc")  ; => #t
(string<=? "abd" "abc")  ; => #f

string>=?procedure

Compare strings lexicographically (greater than or equal).

(string>=? "abd" "abc")  ; => #t
(string>=? "abc" "abc")  ; => #t
(string>=? "abc" "abd")  ; => #f