Docs / Standard Library / String

String

The String module provides functions for working with UTF-8 encoded text. Strings in Kit are immutable sequences of characters.

String Interpolation

Kit supports string interpolation using ${...} syntax. 

name = "Alice"
age = 30
println "Hello, ${name}! You are ${age} years old."
# => Hello, Alice! You are 30 years old.

Basics

String.concat / ++
String -> String -> String
Concatenates two strings. The ++ operator is an alias. 
println (String.concat "Hello, " "World!")
# => "Hello, World!"

println ("Hello, " ++ "World!")
# => "Hello, World!"
String.length
String -> Int
Returns the number of characters in the string. 
println (String.length "Hello")
# => 5
String.repeat
String -> Int -> String
Repeats a string the specified number of times. 
println (String.repeat "ab" 3)
# => "ababab"
String.reverse
String -> String
Reverses the string. 
println (String.reverse "Hello")
# => "olleH"

Accessing Characters

String.char-at
String -> Int -> Option String
Returns Some character at the specified index (0-based) as a single-character string, or None if out of bounds. 
println (String.char-at "Hello" 1)
# => Some("e")

println (String.char-at "Hi" 10)
# => None
String.substring
String -> Int -> Int -> String
Returns a substring from start index to end index (exclusive). 
println (String.substring "Hello, World!" 0 5)
# => "Hello"
String.slice
String -> Int -> Int -> String
Returns a substring from start index to end index (exclusive). Similar to substring. 
println (String.slice "Hello, World!" 7 12)
# => "World"

Splitting and Joining

String.split
String -> String -> List String
Splits a string by a delimiter. 
println (String.split "a,b,c" ",")
# => ["a", "b", "c"]
String.join
String -> List String -> String
Joins a list of strings with a separator. 
println (String.join ", " ["a", "b", "c"])
# => "a, b, c"
String.lines
String -> List String
Splits a string into lines. See also the built-in unlines for the inverse operation. 
println (String.lines "line1\nline2\nline3")
# => ["line1", "line2", "line3"]
String.words
String -> List String
Splits a string into words (by whitespace). 
println (String.words "hello world foo")
# => ["hello", "world", "foo"]
String.split-spaces
String -> List String
Splits by whitespace, similar to words. 
println (String.split-spaces "a  b   c")
# => ["a", "b", "c"]

Transforming

String.trim
String -> String
Removes leading and trailing whitespace. 
println (String.trim "  hello  ")
# => "hello"
String.trim-left / String.trim-right
String -> String
Removes leading or trailing whitespace only. 
println (String.trim-left "  hello  ")
# => "hello  "

println (String.trim-right "  hello  ")
# => "  hello"
String.replace
String -> String -> String -> String
Replaces all occurrences of a substring with another. 
println (String.replace "Hello, World!" "World" "Kit")
# => "Hello, Kit!"
String.remove-spaces
String -> String
Removes all whitespace from a string. 
println (String.remove-spaces "h e l l o")
# => "hello"
String.capitalize
String -> String
Capitalizes the first character. 
println (String.capitalize "hello")
# => "Hello"

Searching

String.contains?
String -> String -> Bool
Returns true if the string contains the substring. 
println (String.contains? "Hello, World!" "World")
# => true
String.starts-with?
String -> String -> Bool
Returns true if the string starts with the prefix. 
println (String.starts-with? "Hello, World!" "Hello")
# => true
String.ends-with?
String -> String -> Bool
Returns true if the string ends with the suffix. 
println (String.ends-with? "Hello, World!" "!")
# => true
String.index-of
String -> String -> Int
Returns the index of the first occurrence of a substring, or -1 if not found. 
println (String.index-of "Hello, World!" "World")
# => 7

println (String.index-of "Hello" "xyz")
# => -1
String.last-index-of
String -> String -> Int
Returns the index of the last occurrence of a substring, or -1 if not found. 
println (String.last-index-of "hello world world" "world")
# => 12

println (String.last-index-of "hello" "xyz")
# => -1
String.indices-of
String -> String -> List Int
Returns a list of all starting positions where the substring occurs (non-overlapping matches). 
println (String.indices-of "abcabcabc" "abc")
# => [0, 3, 6]

println (String.indices-of "hello" "xyz")
# => []
String.find-any
String -> String -> Int
Finds the first occurrence of any character from the given character set. Returns the index or -1 if no character matches. 
# Find first vowel
println (String.find-any "hello" "aeiou")
# => 1

# Find first digit
println (String.find-any "abc123" "0123456789")
# => 3
String.find-any-last
String -> String -> Int
Finds the last occurrence of any character from the given character set. Returns the index or -1 if no character matches. 
# Find last vowel
println (String.find-any-last "hello" "aeiou")
# => 4

# Find last digit
println (String.find-any-last "a1b2c3" "0123456789")
# => 5
String.count
String -> String -> Int
Counts the occurrences of a substring. 
println (String.count "abracadabra" "a")
# => 5

Predicates

String.is-empty?
String -> Bool
Returns true if the string has no characters. 
println (String.is-empty? "")       # => true
println (String.is-empty? "hi")     # => false
String.is-blank?
String -> Bool
Returns true if the string is empty or contains only whitespace. 
println (String.is-blank? "   ")    # => true
println (String.is-blank? " hi ")   # => false

Case Conversion

String.to-upper / String.to-lower
String -> String
Converts the string to uppercase or lowercase. 
println (String.to-upper "hello")    # => "HELLO"
println (String.to-lower "HELLO")    # => "hello"
String.to-kebab
String -> String
Converts to kebab-case. 
println (String.to-kebab "helloWorld")
# => "hello-world"
String.to-camel
String -> String
Converts to camelCase. 
println (String.to-camel "hello-world")
# => "helloWorld"
String.to-snake
String -> String
Converts to snake_case. 
println (String.to-snake "helloWorld")
# => "hello_world"
String.to-pascal
String -> String
Converts to PascalCase. 
println (String.to-pascal "hello-world")
# => "HelloWorld"

Padding

String.pad-left
String -> Int -> String -> String
Pads the string on the left to the specified length. 
println (String.pad-left "42" 5 "0")
# => "00042"
String.pad-right
String -> Int -> String -> String
Pads the string on the right to the specified length. 
println (String.pad-right "hi" 5 ".")
# => "hi..."

Comparison

String.eq? / String.ne?
String -> String -> Bool
Tests equality or inequality of two strings. 
println (String.eq? "hello" "hello")    # => true
println (String.ne? "hello" "world")    # => true
String.lt? / String.gt? / String.le? / String.ge?
String -> String -> Bool
Lexicographic comparison of strings. 
println (String.lt? "apple" "banana")    # => true
println (String.gt? "zebra" "apple")     # => true
String.compare
String -> String -> Int
Returns -1 if first is less, 0 if equal, 1 if greater. 
println (String.compare "apple" "banana")    # => -1
println (String.compare "hello" "hello")     # => 0
String.show
String -> String
Returns a quoted string representation, useful for debugging. 
println (String.show "hello")
# => "\"hello\""
String.force
String -> String
Forces evaluation of a string value. Useful for strict evaluation in lazy contexts. 
s = String.force "hello"
println s
# => "hello"

Bytes and Characters

String.chars
String -> List Char
Converts a string to a list of Char values (Unicode code points). 
println (String.chars "hello")
# => ['h', 'e', 'l', 'l', 'o']

# Iterate over characters
"Kit" |> String.chars |> each (fn(c) => println c)
String.from-chars
List Char -> String
Constructs a string from a list of Char values. 
println (String.from-chars ['h', 'i'])
# => "hi"
String.to-bytes
String -> List Int
Converts a string to a list of UTF-8 byte values. 
println (String.to-bytes "hi")
# => [104, 105]
String.from-bytes
List Int -> String
Creates a string from a list of UTF-8 byte values. 
println (String.from-bytes [104, 105])
# => "hi"
String.byte-at
String -> Int -> Int
Returns the byte value at the specified index. 
println (String.byte-at "hi" 0)
# => 104

Char Module

Kit has a Char type representing a single Unicode code point. Characters are written with single quotes: 'a', 'Z', '\n'.

About Char

The Char type represents a single Unicode scalar value (code point). Use String.chars to convert a string to a list of characters, and String.from-chars to convert back.

Char.to-int
Char -> Int
Returns the Unicode code point as an integer. 
println (Char.to-int 'A')
# => 65

println (Char.to-int 'a')
# => 97
Char.from-int
Int -> Char
Creates a character from a Unicode code point. 
println (Char.from-int 65)
# => 'A'

println (Char.from-int 128512)
# => Unicode emoji character
Char.to-string
Char -> String
Converts a character to a single-character string. 
println (Char.to-string 'K')
# => "K"

Character Classification

Char.is-alpha?
Char -> Bool
Returns true if the character is alphabetic (a-z, A-Z). 
println (Char.is-alpha? 'a')   # => true
println (Char.is-alpha? '5')   # => false
Char.is-digit?
Char -> Bool
Returns true if the character is a digit (0-9). 
println (Char.is-digit? '5')   # => true
println (Char.is-digit? 'a')   # => false
Char.is-alphanumeric?
Char -> Bool
Returns true if the character is alphabetic or numeric. 
println (Char.is-alphanumeric? 'a')   # => true
println (Char.is-alphanumeric? '5')   # => true
println (Char.is-alphanumeric? '!')   # => false
Char.is-whitespace?
Char -> Bool
Returns true if the character is whitespace (space, tab, newline, etc.). 
println (Char.is-whitespace? ' ')    # => true
println (Char.is-whitespace? '\n')   # => true
println (Char.is-whitespace? 'a')    # => false
Char.is-upper?
Char -> Bool
Returns true if the character is uppercase. 
println (Char.is-upper? 'A')   # => true
println (Char.is-upper? 'a')   # => false
Char.is-lower?
Char -> Bool
Returns true if the character is lowercase. 
println (Char.is-lower? 'a')   # => true
println (Char.is-lower? 'A')   # => false

Case Conversion

Char.to-upper
Char -> Char
Converts a character to uppercase. 
println (Char.to-upper 'a')
# => 'A'
Char.to-lower
Char -> Char
Converts a character to lowercase. 
println (Char.to-lower 'A')
# => 'a'

Built-ins

These functions are available without a module prefix.

chars
String -> List Char
Converts a string to a list of Char values (Unicode code points). Equivalent to String.chars. 
println (chars "Kit")
# => ['K', 'i', 't']
unlines
List String -> String
Joins a list of strings with newlines. The inverse of String.lines. 
lines = ["line1", "line2", "line3"]
println (unlines lines)
# => "line1\nline2\nline3"
show
a -> String
Converts any value to its string representation, useful for debugging. For strings, returns a quoted representation. 
println (show "hello")
# => "\"hello\""

println (show [1, 2, 3])
# => "[1, 2, 3]"

println (show {name: "Kit", version: 1})
# => "{name: \"Kit\", version: 1}"