The string extensions provide functions for manipulating strings, converting between strings and other types, and searching strings. These extensions may or may not be present depending on the platform and configuration of LispBM.

In LispBM, strings are byte arrays terminated by a null byte. String indices are zero-based and measured in bytes.

Conversion

str-from-n

str-from-n converts a number to its string representation. The form is (str-from-n number) or (str-from-n number format) where format is an optional printf-style format string. Floats default to "%g" format, integers default to "%d". The result is at most 100 characters long.

(str-from-n 42)

"42"

(str-from-n 3.140000f32)

"3.14"

(str-from-n 255 "%x")

"ff"

(str-from-n 3.141590f32 "%.2f")

"3.14"

str-to-i

str-to-i parses a string as an integer. The form is (str-to-i string) or (str-to-i string base). The optional base argument specifies the number base. Base 0 auto-detects the base from the string prefix (0x for hex, 0 for octal, otherwise decimal). Returns an i32.

(str-to-i "42")

42i32

(str-to-i "-100")

-100i32

(str-to-i "ff" 16)

255i32

(str-to-i "0xff" 0)

255i32

(str-to-i "101" 2)

5i32

str-to-f

str-to-f parses a string as a floating-point number. The form is (str-to-f string). Returns an f32.

(str-to-f "3.14")

3.140000f32

(str-to-f "-2.718")

-2.718000f32

(str-to-f "1e10")

10000000000.000000f32

to-str

to-str converts one or more LispBM values to a string. The form is (to-str val1 val2 ...). Multiple values are separated by a single space. The result is at most 300 characters long.

(to-str 42)

"42"

(to-str 3.140000f32)

"3.140000f32"

(to-str 'hello)

"hello"

(to-str 1 2 3)

"1 2 3"

(to-str "hello" "world")

"hello world"

to-str-delim

to-str-delim converts one or more LispBM values to a string using a custom delimiter between values. The form is (to-str-delim delimiter val1 val2 ...). The first argument is the delimiter string. The result is at most 300 characters long.

(to-str-delim ", " 1 2 3)

"1, 2, 3"

(to-str-delim " | " 'a 'b 'c)

"a | b | c"

(to-str-delim [0] "Hello" " " "World")

"Hello World"

String Operations

str-len

str-len returns the length of a string in characters, not counting the null terminator. The form is (str-len string).

(str-len "Hello")

5

(str-len [0])

0

(str-len "Hello, World!")

13

str-part

str-part extracts a substring from a string. The form is (str-part string start) or (str-part string start length). Returns a new string starting at character index start, optionally limited to length characters. Returns an error if start is beyond the end of the string.

(str-part "Hello, World!" 7)

"World!"

(str-part "Hello, World!" 0 5)

"Hello"

(str-part "Hello, World!" 7 5)

"World"

str-join

str-join concatenates a list of strings into a single string. The form is (str-join strings) or (str-join strings delimiter) where delimiter is an optional string inserted between each element. The default delimiter is the empty string.

(str-join (list "Hello" " " "World"))

"Hello World"

(str-join (list "a" "b" "c") "-")

"a-b-c"

(str-join (list "one" "two" "three") ", ")

"one, two, three"

str-split

str-split splits a string into a list of substrings. The form is (str-split string delimiter) where delimiter is either a string or an integer.

When delimiter is a string, the input is split at any character found in the delimiter string.

When delimiter is an integer, the input is split into chunks of that many characters.

(str-split "hello world" " ")

("hello" "world")

(str-split "a,b;c,d" ",;")

("a" "b" "c" "d")

(str-split "abcdef" 2)

("ab" "cd" "ef")

str-replace

str-replace replaces all occurrences of a pattern in a string. The form is (str-replace string pattern replacement) or (str-replace string pattern) to remove all occurrences. Returns a new string with all occurrences of pattern replaced.

(str-replace "hello world" "world" "LispBM")

"hello LispBM"

(str-replace "aabbcc" "bb" "XX")

"aaXXcc"

(str-replace "hello world" "o")

"hell wrld"

str-replicate

str-replicate creates a string by repeating a character. The form is (str-replicate n char) where n is the number of characters and char is the character as a byte value. Returns a new string of length n.

(str-replicate 5 97b)

"aaaaa"

(str-replicate 3 45b)

"---"

(str-replicate 8 120b)

"xxxxxxxx"

Searching and Comparing

str-cmp

str-cmp compares two strings lexicographically. The form is (str-cmp str1 str2) or (str-cmp str1 str2 n) where n limits the comparison to the first n characters. Returns a negative integer if str1 is less than str2, zero if they are equal, and a positive integer if str1 is greater.

(str-cmp "abc" "abc")

0

(str-cmp "abc" "abd")

-1

(str-cmp "abd" "abc")

1

(str-cmp "abcdef" "abcxyz" 3)

0

str-find

str-find searches for a substring within a string. The form is (str-find string substr) with optional additional arguments. Returns the index of the first match, or -1 if not found. The substr argument can also be a list of strings, in which case the search finds any of them.

Optional arguments (may be given in any order after substr):

• An integer sets the start position for the search.
• A second integer sets which occurrence to find (0 = first).
• 'left searches from right to left.
• 'nocase performs a case-insensitive search.

(str-find "hello world" "world")

6

(str-find "hello world" "xyz")

-1

(str-find "abcabc" "bc" 0 1)

4

(str-find "Hello World" "world" 'nocase)

6

(str-find "abcabc" "bc" 'left)

4

Case Conversion

str-to-lower

str-to-lower converts a string to lowercase. The form is (str-to-lower string). Returns a new string with all characters converted to lowercase.

(str-to-lower "Hello, World!")

"hello, world!"

(str-to-lower "LISPBM")

"lispbm"

str-to-upper

str-to-upper converts a string to uppercase. The form is (str-to-upper string). Returns a new string with all characters converted to uppercase.

(str-to-upper "Hello, World!")

"HELLO, WORLD!"

(str-to-upper "lispbm")

"LISPBM"

This document was generated by LispBM version 0.38.0