Strings

Tova provides a rich set of string manipulation functions. All string functions are non-mutating -- they return new strings.

Method Syntax

String functions can be called in two ways:

// Standalone function call
upper("hello")          // "HELLO"

// Method call on a string
"hello".upper()         // "HELLO"

Both forms are equivalent. The method syntax is often more readable when chaining operations.

String Interpolation

Tova strings support interpolation with {}:

name = "Alice"
age = 30
print("Hello, {name}! You are {age} years old.")
// Hello, Alice! You are 30 years old.

print("2 + 2 = {2 + 2}")
// 2 + 2 = 4

String Repetition

The * operator repeats a string:

"-" * 40
// "----------------------------------------"

"ha" * 3
// "hahaha"

---

Trimming & Splitting

trim

trim(s) -> String

Removes whitespace from both ends of a string.

trim("  hello  ")       // "hello"
trim("\n\thello\n")     // "hello"

trim_start

trimStart(s) -> String

Removes whitespace from the beginning of a string.

trimStart("  hello  ")    // "hello  "

trim_end

trimEnd(s) -> String

Removes whitespace from the end of a string.

trimEnd("  hello  ")      // "  hello"

split

split(s, sep) -> List[String]

Splits a string by a separator and returns an array of parts.

split("a,b,c", ",")            // ["a", "b", "c"]
split("hello world", " ")      // ["hello", "world"]
split("one::two::three", "::")  // ["one", "two", "three"]

join

join(arr, sep) -> String

Joins an array of strings with a separator.

join(["a", "b", "c"], ", ")    // "a, b, c"
join(["hello", "world"], " ")  // "hello world"
join(["one", "two"], "")       // "onetwo"

words

words(s) -> List[String]

Splits a string by whitespace, filtering out empty strings.

words("hello   world")          // ["hello", "world"]
words("  spaced  out  ")        // ["spaced", "out"]

lines

lines(s) -> List[String]

Splits a string by newline characters.

lines("line1\nline2\nline3")   // ["line1", "line2", "line3"]

chars

chars(s) -> List[String]

Splits a string into an array of individual characters.

chars("hello")                  // ["h", "e", "l", "l", "o"]
chars("abc") |> reversed() |> join("")  // "cba"

---

Search & Test

contains

contains(s, sub) -> Bool

Returns true if the string contains the given substring.

contains("hello world", "world")    // true
contains("hello world", "xyz")      // false

// Method syntax
"hello world".contains("ell")       // true

starts_with

startsWith(s, prefix) -> Bool

Returns true if the string starts with the given prefix.

startsWith("hello", "hel")    // true
startsWith("hello", "world")  // false

"hello".startsWith("hel")     // true

ends_with

endsWith(s, suffix) -> Bool

Returns true if the string ends with the given suffix.

endsWith("hello.tova", ".tova")     // true
endsWith("hello.tova", ".js")      // false

"photo.png".endsWith(".png")       // true

---

Replacing

replace

replace(s, from, to) -> String

Replaces occurrences in a string. When from is a plain string, all occurrences are replaced. When from is a regex, the first match is replaced.

replace("hello world", "world", "Tova")
// "hello Tova"

replace("aabbcc", "b", "x")
// "aaxxcc"

replace_first

replaceFirst(s, from, to) -> String

Replaces only the first occurrence of from with to.

replaceFirst("aabb", "a", "x")    // "xabb"
replaceFirst("hello hello", "hello", "hi")  // "hi hello"

repeat

repeat(s, n) -> String

Repeats a string n times.

repeat("ha", 3)         // "hahaha"
repeat("-", 20)          // "--------------------"
repeat("ab", 0)          // ""

---

Padding

pad_start

padStart(s, n, fill?) -> String

Pads the beginning of a string to reach length n. Uses spaces by default, or the optional fill character.

padStart("5", 3, "0")       // "005"
padStart("hi", 5)            // "   hi"
padStart("42", 5, ".")       // "...42"

pad_end

padEnd(s, n, fill?) -> String

Pads the end of a string to reach length n.

padEnd("5", 3, "0")         // "500"
padEnd("hi", 5)              // "hi   "

---

Character Access

char_at

charAt(s, i) -> String | Nil

Returns the character at position i, or nil if out of bounds.

charAt("hello", 0)    // "h"
charAt("hello", 4)    // "o"
charAt("hello", 10)   // nil

---

Case Conversion

upper

upper(s) -> String

Converts a string to uppercase.

upper("hello")           // "HELLO"
"hello".upper()          // "HELLO"

lower

lower(s) -> String

Converts a string to lowercase.

lower("HELLO")           // "hello"
"HELLO".lower()          // "hello"

capitalize

capitalize(s) -> String

Uppercases the first letter of the string.

capitalize("hello")      // "Hello"
capitalize("hello world")  // "Hello world"

title_case

titleCase(s) -> String

Uppercases the first letter of each word.

titleCase("hello world")       // "Hello World"
titleCase("the quick brown fox")  // "The Quick Brown Fox"

snake_case

snakeCase(s) -> String

Converts a string to snake_case. Handles camelCase, spaces, and hyphens.

snakeCase("helloWorld")         // "hello_world"
snakeCase("Hello World")        // "hello_world"
snakeCase("some-thing")         // "some_thing"
snakeCase("XMLParser")          // "xmlparser"

camel_case

camelCase(s) -> String

Converts a string to camelCase. Handles snake_case, spaces, and hyphens.

camelCase("hello_world")       // "helloWorld"
camelCase("Hello World")       // "helloWorld"
camelCase("some-thing")        // "someThing"

kebab_case

kebabCase(s) -> String

Converts a string to kebab-case. Handles camelCase, spaces, and underscores.

kebabCase("helloWorld")         // "hello-world"
kebabCase("Hello World")        // "hello-world"
kebabCase("some_thing")         // "some-thing"

---

Searching & Counting

index_of

indexOf(s, sub) -> Int | Nil

Returns the position of the first occurrence of sub in s. Returns nil if not found.

indexOf("hello world", "world")    // 6
indexOf("abcabc", "bc")            // 1
indexOf("hello", "xyz")            // nil

last_index_of

lastIndexOf(s, sub) -> Int | Nil

Returns the position of the last occurrence of sub in s. Returns nil if not found.

lastIndexOf("abcabc", "bc")      // 4
lastIndexOf("hello", "l")         // 3
lastIndexOf("hello", "xyz")       // nil

count_of

countOf(s, sub) -> Int

Counts the number of non-overlapping occurrences of sub in s.

countOf("banana", "an")            // 2
countOf("mississippi", "s")        // 4
countOf("hello", "xyz")            // 0

---

Substrings & Transformation

substr

substr(s, start, end?) -> String

Extracts a portion of the string from start to end (exclusive). If end is omitted, extracts to the end of the string. Supports negative indices.

substr("hello world", 6)           // "world"
substr("hello world", 0, 5)        // "hello"
substr("hello", -3)                 // "llo"

reverse_str

reverseStr(s) -> String

Reverses a string.

reverseStr("hello")               // "olleh"
reverseStr("racecar")             // "racecar"
reverseStr("")                     // ""

center

center(s, n, fill?) -> String

Center-pads a string to width n. Uses spaces by default, or the optional fill character. Returns the string unchanged if already wider.

center("hi", 6)                    // "  hi  "
center("hi", 7)                    // "  hi   "
center("hi", 6, "*")               // "**hi**"
center("hello", 3)                 // "hello"

is_empty

isEmpty(v) -> Bool

Returns true if a value is empty. Works for strings, arrays, objects, and nil.

isEmpty("")                        // true
isEmpty("hello")                   // false
isEmpty([])                        // true
isEmpty({})                        // true
isEmpty(nil)                       // true

---

Text Processing

truncate

truncate(s, n, suffix?) -> String

Truncates a string to at most n characters, appending suffix (default "...") if truncated.

truncate("Hello World", 8)            // "Hello..."
truncate("Hi", 10)                     // "Hi"
truncate("Hello World", 8, "..")       // "Hello .."

word_wrap

wordWrap(s, width) -> String

Wraps text at word boundaries to fit within width characters per line.

wordWrap("one two three four", 10)
// "one two\nthree four"

wordWrap("the quick brown fox", 12)
// "the quick\nbrown fox"

dedent

dedent(s) -> String

Removes common leading whitespace from all lines. Useful for cleaning up indented multi-line strings.

dedent("  hello\n  world")     // "hello\nworld"
dedent("    line1\n  line2")   // "  line1\nline2"

indent_str

indentStr(s, n, ch?) -> String

Adds n repetitions of ch (default: space) to the beginning of each line.

indentStr("hello\nworld", 2)         // "  hello\n  world"
indentStr("a\nb", 1, ">")            // ">a\n>b"

slugify

slugify(s) -> String

Converts a string to a URL-friendly slug: lowercased, special characters removed, spaces replaced with hyphens.

slugify("Hello World!")            // "hello-world"
slugify("A & B @ C")              // "a-b-c"
slugify("  My Blog Post  ")       // "my-blog-post"

escape_html

escapeHtml(s) -> String

Escapes HTML special characters (<, >, &, ", ').

escapeHtml("<b>Hello</b>")
// "&lt;b&gt;Hello&lt;/b&gt;"

escapeHtml("a > b & c < d")
// "a &gt; b &amp; c &lt; d"

unescape_html

unescapeHtml(s) -> String

Reverses HTML entity escaping.

unescapeHtml("<b>Hello</b>")
// "<b>Hello</b>"

fmt

fmt(template, ...args) -> String

Simple placeholder formatting. Replaces {} placeholders with arguments in order.

fmt("Hello, {}!", "world")         // "Hello, world!"
fmt("{} + {} = {}", 1, 2, 3)      // "1 + 2 = 3"
fmt("{} items at ${}", 3, 9.99)   // "3 items at $9.99"

---

Pipeline Examples

String functions work naturally with the pipe operator |>:

// Clean and normalize user input
input
  |> trim()
  |> lower()
  |> replace("  ", " ")

// Parse CSV line
"Alice,30,Engineer"
  |> split(",")
  |> enumerate()
// [[0, "Alice"], [1, "30"], [2, "Engineer"]]

// Build a slug from a title
"Hello World! This is Tova."
  |> slugify()
// "hello-world-this-is-tova"

// Count vowels
"hello world"
  |> chars()
  |> filter(fn(c) contains("aeiou", c))
  |> len()
// 3

// Escape user input for HTML
user_input
  |> trim()
  |> escapeHtml()

String Concatenation

Use string interpolation for concatenation. The + operator works but produces a type warning:

// Interpolation (preferred -- no warnings)
greeting = "Hello, {name}!"

// Plus operator (works but produces a compiler warning)
"hello" + " " + "world"   // "hello world"

The ++ operator is available in match patterns for string prefix matching:

match url {
  "/api/" ++ rest => handle_api(rest)
  _ => not_found()
}

Terminal Formatting

Functions for styling text output in the terminal.

color

color(text, colorName) -> String

Wraps text with ANSI color codes for terminal output. Supported colors include "red", "green", "blue", "yellow", "cyan", "magenta", "white", "gray".

print(color("Error!", "red"))
print(color("Success", "green"))
print(color("Warning", "yellow"))

bold

bold(text) -> String

Wraps text with ANSI bold codes for terminal output.

print(bold("Important message"))
print(bold(color("Error!", "red")))

dim

dim(text) -> String

Wraps text with ANSI dim codes for terminal output.

print(dim("Less important info"))
print(dim("(optional)"))