package core:strings

Source

dynamic byte buffer / string builder with helper procedures

the dynamic array is wrapped inside the struct to be more opaque
you can use `fmt.sbprint*` procedures with a `^strings.Builder` directly

"intern" is a more memory efficient string map allocator is used to allocate the actual Intern_Entry strings

custom string entry struct

io stream data for a string reader that can read based on bytes or runes

implements the vtable when using the io.Reader variants
"read" calls advance the current reading offset `i`

state for the split multi iterator

return the cap of the builder byte buffer

delete and clear the builder byte buffer content

create an empty builder with the same slice length as its cap

uses the `mem.nil_allocator` to avoid allocation and keep a fixed length
used in `fmt.bprint*`

bytes: [8]byte // <-- gets filled
builder := strings.builder_from_bytes(bytes[:])
strings.write_byte(&builder, 'a') -> "a"
strings.write_byte(&builder, 'b') -> "ab"

create an empty builder with the same slice length as its cap

uses the `mem.nil_allocator` to avoid allocation and keep a fixed length
used in `fmt.bprint*`

bytes: [8]byte // <-- gets filled
builder := strings.builder_from_bytes(bytes[:])
strings.write_byte(&builder, 'a') -> "a"
strings.write_byte(&builder, 'b') -> "ab"

reserve the builfer byte buffer to a specific cap, when it's higher than before

initialize a builder, with a set length len and cap 16 byte buffer replaces the existing buf

initialize a builder, with a set length len byte buffer and a custom cap replaces the existing buf

initialize a builder, default length 0 / cap 16 are done through make replaces the existing buf

return the length of the builder byte buffer

return a builder, with a set length len and cap 16 byte buffer

return a builder, with a set length len byte buffer and a custom cap

return a builder, default length 0 / cap 16 are done through make

clear the builder byte buffer content

returns the space left in the builder byte buffer to use up

centre_justify returns a string with a pad string at boths sides if the str's rune length is smaller than length

centre_justify returns a string with a pad string at boths sides if the str's rune length is smaller than length

returns a clone of the string s allocated using the allocator

returns a cloned string of the byte array s using the allocator appends a leading nul byte

returns a clone of the cstring s using the allocator as a string

returns a cloned string from the cstring ptr and a byte length len using the allocator truncates till the first nul byte it finds or the byte len

returns a cloned string from the pointer ptr and a byte length len using the allocator same to string_from_ptr but allocates

returns a clone of the string s allocated using the allocator

returns a clone of the string s allocated using the allocator as a cstring a nul byte is appended to the clone, to make the cstring safe

Compares two strings, returning a value representing which one comes first lexiographically. -1 for lhs; 1 for rhs, or 0 if they are equal.

returns a combined string from the slice of strings a without a seperator

allocates the string using the `allocator`


a := [?]string { "a", "b", "c" }
b := strings.concatenate(a[:]) -> "abc"

returns true when the string substr is contained inside the string s

strings.contains("testing", "test") -> true
strings.contains("testing", "ing") -> true
strings.contains("testing", "text") -> false

returns true when the string s contains any of the characters inside the string chars

strings.contains_any("test", "test") -> true
strings.contains_any("test", "ts") -> true
strings.contains_any("test", "et") -> true
strings.contains_any("test", "a") -> false

returns the byte offset of the rune r in the string s, -1 when not found

returns the count of the string substr found in the string s

returns the rune_count + 1 of the string `s` on empty `substr`

strings.count("abbccc", "a") -> 1
strings.count("abbccc", "b") -> 2
strings.count("abbccc", "c") -> 3
strings.count("abbccc", "ab") -> 1
strings.count("abbccc", " ") -> 0

rune_offset and rune_length are in runes, not bytes.

If `rune_length` <= 0, then it'll return the remainder of the string starting at `rune_offset`.

strings.cut("some example text", 0, 4) -> "some"
strings.cut("some example text", 2, 2) -> "me"
strings.cut("some example text", 5, 7) -> "example"

returns wether the strings u and v are the same alpha characters

works with utf8 string content and ignores different casings

strings.equal_fold("test", "test") -> true
strings.equal_fold("Test", "test") -> true
strings.equal_fold("Test", "tEsT") -> true
strings.equal_fold("test", "tes") -> false

expands the string to a grid spaced by tab_size whenever a \t character appears

returns the tabbed string, panics on tab_size <= 0

strings.expand_tabs("abc1\tabc2\tabc3", 4) -> abc1    abc2    abc3
strings.expand_tabs("abc1\tabc2\tabc3", 5) -> abc1 abc2 abc3
strings.expand_tabs("abc1\tabc2\tabc3", 6) -> abc1  abc2  abc3

fields splits the string s around each instance of one or more consecutive white space character, defined by unicode.is_space returning a slice of substrings of s or an empty slice if s only contains white space

fields_iterator returns the first run of characters in s that does not contain white space, defined by unicode.is_space s will then start from any space after the substring, or be an empty string if the substring was the remaining characters

fields_proc splits the string s at each run of unicode code points ch satisfying f(ch) returns a slice of substrings of s If all code points in s satisfy f(ch) or string is empty, an empty slice is returned

fields_proc makes no guarantee about the order in which it calls f(ch) it assumes that f always returns the same value for a given ch

return true when the string prefix is contained at the start of the string s

strings.has_prefix("testing", "test") -> true
strings.has_prefix("testing", "te") -> true
strings.has_prefix("telephone", "te") -> true
strings.has_prefix("testing", "est") -> false

returns true when the string suffix is contained at the end of the string s

good example to use this is for file extensions

strings.has_suffix("todo.txt", ".txt") -> true
strings.has_suffix("todo.doc", ".txt") -> false
strings.has_suffix("todo.doc.txt", ".txt") -> true

returns the byte offset of the string substr in the string s, -1 when not found

strings.index("test", "t") -> 0
strings.index("test", "te") -> 0
strings.index("test", "st") -> 2
strings.index("test", "tt") -> -1

returns the index of any first char of chars found in s, -1 if not found

strings.index_any("test", "s") -> 2
strings.index_any("test", "se") -> 1
strings.index_any("test", "et") -> 0
strings.index_any("test", "set") -> 0
strings.index_any("test", "x") -> -1

returns the byte offset of the first byte c in the string s it finds, -1 when not found

can't find utf8 based runes

strings.index_byte("test", 't') -> 0
strings.index_byte("test", 'e') -> 1
strings.index_byte("test", 'x') -> -1
strings.index_byte("teäst", 'ä') -> -1

runs trough the s string linearly and watches wether the p procedure matches the truth bool

returns the rune offset or -1 when no match was found

call :: proc(r: rune) -> bool {
	return r == 'a'
}
strings.index_proc("abcabc", call) -> 0
strings.index_proc("cbacba", call) -> 2
strings.index_proc("cbacba", call, false) -> 0
strings.index_proc("abcabc", call, false) -> 1
strings.index_proc("xyz", call) -> -1

same as index_proc but with a p procedure taking a rawptr for state

returns the byte offset of the first rune r in the string s it finds, -1 when not found

avoids invalid runes

strings.index_rune("abcädef", 'x') -> -1
strings.index_rune("abcädef", 'a') -> 0
strings.index_rune("abcädef", 'b') -> 1
strings.index_rune("abcädef", 'c') -> 2
strings.index_rune("abcädef", 'ä') -> 3
strings.index_rune("abcädef", 'd') -> 5
strings.index_rune("abcädef", 'e') -> 6
strings.index_rune("abcädef", 'f') -> 7

free the map and all its content allocated using the .allocator

returns the text string from the intern map - gets set if it didnt exist yet the returned string lives as long as the map entry lives

returns the text cstring from the intern map - gets set if it didnt exist yet the returned cstring lives as long as the map entry lives

initialize the entries map and set the allocator for the string entries

return true when the r rune is '\t', '\n', '\v', '\f', '\r' or ' '

returns true when the c rune is a space, '-' or '_' useful when treating strings like words in a text editor or html paths

procedure for trim_*_proc variants, which has a string rawptr cast + rune comparison

returns true when the r rune is a nul byte

returns true when the r rune is a non alpha or unicode.is_space rune

returns true when the r rune is any asci or utf8 based whitespace

returns a combined string from the slice of strings a seperated with the sep string

allocates the string using the `allocator`

a := [?]string { "a", "b", "c" }
b := strings.join(a[:], " ") -> "a b c"
c := strings.join(a[:], "-") -> "a-b-c"
d := strings.join(a[:], "...") -> "a...b...c"

returns the last byte offset of the string substr in the string s, -1 when not found

strings.index("test", "t") -> 3
strings.index("test", "te") -> 0
strings.index("test", "st") -> 2
strings.index("test", "tt") -> -1

returns the last matching index in s of any char in chars found in s, -1 if not found

iterates the string in reverse

strings.last_index_any("test", "s") -> 2
strings.last_index_any("test", "se") -> 2
strings.last_index_any("test", "et") -> 3
strings.last_index_any("test", "set") -> 3
strings.last_index_any("test", "x") -> -1

returns the byte offset of the last byte c in the string s it finds, -1 when not found

can't find utf8 based runes

strings.index_byte("test", 't') -> 3
strings.index_byte("test", 'e') -> 1
strings.index_byte("test", 'x') -> -1
strings.index_byte("teäst", 'ä') -> -1

same as index_proc but runs through the string in reverse

same as index_proc_with_state but runs through the string in reverse

left_justify returns a string with a pad string at right side if the str's rune length is smaller than length

levenshtein_distance returns the Levenshtein edit distance between 2 strings. This is a single-row-version of the Wagner–Fischer algorithm, based on C code by Martin Ettl. Note: allocator isn't used if the length of string b in runes is smaller than 64.

splits the str string by the seperator sep string and returns 3 parts

`head`: before the split, `match`: the seperator, `tail`: the end of the split
returns the input string when the `sep` was not found

text := "testing this out"
strings.partition(text, " this ") -> head: "testing", match: " this ", tail: "out"
strings.partition(text, "hi") -> head: "testing t", match: "hi", tail: "s out"
strings.partition(text, "xyz") -> head: "testing this out", match: "", tail: ""

pops and returns the last byte in the builder returns 0 when the builder is empty

pops the last rune in the builder and returns the popped rune and its rune width returns 0, 0 when the builder is empty

return the prefix length common between strings a and b.

strings.prefix_length("testing", "test") -> 4
strings.prefix_length("testing", "te") -> 2
strings.prefix_length("telephone", "te") -> 2
strings.prefix_length("testing", "est") -> 0

returns the raw ^byte start of the string str

init the reader to the string s

remaining length of the reader

reads len(p) bytes into the slice from the string in the reader returns n amount of read bytes and an io.Error

reads len(p) bytes into the slice from the string in the reader at an offset returns n amount of read bytes and an io.Error

reads and returns a single byte - error when out of bounds

reads and returns a single rune and the rune size - error when out bounds

seeks the reader offset to a wanted offset

returns the string length stored by the reader

returns a stream from the reader data

decreases the reader offset - error when below 0

decreases the reader offset by the last rune can only be used once and after a valid read_rune call

writes the string content left to read into the io.Writer w

removes the key string n times from the s string

if n < 0, no limit on the number of removes
returns the `output` string and true when an a allocation through a remove happened

strings.remove("abcabc", "abc", 1) -> "abc", true
strings.remove("abcabc", "abc", -1) -> "", true
strings.remove("abcabc", "a", -1) -> "bcbc", true
strings.remove("abcabc", "x", -1) -> "abcabc", false

removes all the key string instanes from the s string

returns the `output` string and true when an a allocation through a remove happened

strings.remove("abcabc", "abc") -> "", true
strings.remove("abcabc", "a") -> "bcbc", true
strings.remove("abcabc", "x") -> "abcabc", false

repeats the string s multiple count times and returns the allocated string

panics when `count` is below 0

strings.repeat("abc", 2) -> "abcabc"

replaces n instances of old in the string s with the new string

if n < 0, no limit on the number of replacements
returns the `output` string and true when an a allocation through a replace happened

strings.replace("xyzxyz", "xyz", "abc", 2) -> "abcabc", true
strings.replace("xyzxyz", "xyz", "abc", 1) -> "abcxyz", true
strings.replace("xyzxyz", "abc", "xyz", -1) -> "xyzxyz", false
strings.replace("xyzxyz", "xy", "z", -1) -> "zzzz", true

replaces all instances of old in the string s with the new string

returns the `output` string and true when an a allocation through a replace happened

strings.replace_all("xyzxyz", "xyz", "abc") -> "abcabc", true
strings.replace_all("xyzxyz", "abc", "xyz") -> "xyzxyz", false
strings.replace_all("xyzxyz", "xy", "z") -> "zzzz", true

returns a reversed version of the s string

a := "abcxyz"
b := strings.reverse(a)
fmt.eprintln(a, b) // abcxyz zyxcba

right_justify returns a string with a pad string at left side if the str's rune length is smaller than length

returns the utf8 rune count of the string s

strings.rune_count("test") -> 4
strings.rune_count("testö") -> 5, where len("testö") -> 6

scrub scruvs invalid utf-8 characters and replaces them with the replacement string Adjacent invalid bytes are only replaced once

Splits a string into parts, based on a separator.

Returned strings are substrings of 's'.
```
s := "aaa.bbb.ccc.ddd.eee" // 5 parts
ss := split(s, ".")
fmt.println(ss)            // [aaa, bbb, ccc, ddd, eee]
```

splits the string s after the seperator string sep appears

returns the slice of split strings allocated using `allocator`

a := "aaa.bbb.ccc.ddd.eee"
aa := strings.split_after(a, ".")
fmt.eprintln(aa) // [aaa., bbb., ccc., ddd., eee]

split the ^string s after every seperator string sep in an iterator fashion

consumes the original string till the end

text := "a.b.c.d.e"
for str in strings.split_after_iterator(&text, ".") {
	fmt.eprintln(str) // every loop -> a. b. c. d. e
}

splits the string s after the seperator string sep appears into a total of n parts

returns the slice of split strings allocated using `allocator`

a := "aaa.bbb.ccc.ddd.eee"
aa := strings.split_after(a, ".")
fmt.eprintln(aa) // [aaa., bbb., ccc., ddd., eee]

split the ^string s by the byte seperator sep in an iterator fashion

consumes the original string till the end, leaving the string `s` with len == 0

text := "a.b.c.d.e"
for str in strings.split_by_byte_iterator(&text, '.') {
	fmt.eprintln(str) // every loop -> a b c d e
}

split the ^string s by the seperator string sep in an iterator fashion

consumes the original string till the end

text := "a.b.c.d.e"
for str in strings.split_iterator(&text, ".") {
	fmt.eprintln(str) // every loop -> a b c d e
}

split the string s at every line break '\n'

return an allocated slice of strings

a := "a\nb\nc\nd\ne"
b := strings.split_lines(a)
fmt.eprintln(b) // [a, b, c, d, e]

split the string s at every line break '\n' leaving the '\n' in the resulting strings

return an allocated slice of strings

a := "a\nb\nc\nd\ne"
b := strings.split_lines_after(a)
fmt.eprintln(b) // [a\n, b\n, c\n, d\n, e\n]

split the string s at every line break '\n'

returns the current split string every iteration till the string is consumed

text := "a\nb\nc\nd\ne"
for str in strings.split_lines_after_iterator(&text) {
	fmt.eprintln(text) // every loop -> a\n b\n c\n d\n e\n
}

split the string s at every line break '\n' leaving the '\n' in the resulting strings

only runs for `n` parts
return an allocated slice of strings

a := "a\nb\nc\nd\ne"
b := strings.split_lines_after_n(a, 3)
fmt.eprintln(b) // [a\n, b\n, c\n, d\ne\n]

split the string s at every line break '\n'

returns the current split string every iteration till the string is consumed

text := "a\nb\nc\nd\ne"
for str in strings.split_lines_iterator(&text) {
	fmt.eprintln(text) // every loop -> a b c d e
}

split the string s at every line break '\n' for n parts

return an allocated slice of strings

a := "a\nb\nc\nd\ne"
b := strings.split_lines_n(a, 3)
fmt.eprintln(b) // [a, b, c, d\ne\n]

splits the input string s by all possible substrs []string

returns the allocated []string, nil on any empty substring or no matches

splits := [?]string { "---", "~~~", ".", "_", "," }
res := strings.split_multi("testing,this.out_nice---done~~~last", splits[:])
fmt.eprintln(res) // -> [testing, this, out, nice, done, last]

returns split multi state with sorted substrs

splits the input string s by all possible substrs []string in an iterator fashion

returns the split string every iteration, the full string on no match

splits := [?]string { "---", "~~~", ".", "_", "," }
state := strings.split_multi_init("testing,this.out_nice---done~~~last", splits[:])
for str in strings.split_multi_iterate(&state) {
	fmt.eprintln(str) // every iteration -> [testing, this, out, nice, done, last]
}

Splits a string into a total of 'n' parts, based on a separator.

Returns fewer parts if there wasn't enough occurrences of the separator.
Returned strings are substrings of 's'.
```
s := "aaa.bbb.ccc.ddd.eee" // 5 parts present
ss := split_n(s, ".", 3)   // total of 3 wanted
fmt.println(ss)            // [aaa, bbb, ccc.ddd.eee]
```

iterator that loops through the string and calls the callback with the prev, curr and next rune

on empty string `s` the callback gets called once with empty runes

returns a string from a byte pointer `ptr and byte length `len` searches for a nul byte from 0..len will be the end size

returns a string from a byte pointer ptr and byte length len the string is valid as long as the parameters stay alive

converts the s string to "Ada_case"

converts the s string to "lowerCamelCase"

returns the s string to words seperated by the given delimiter rune

all runes will be upper or lowercased based on the `all_uppercase` bool

strings.to_delimiter_case("Hello World", '_', false) -> hello_world
strings.to_delimiter_case("Hello World", ' ', true) -> HELLO WORLD
strings.to_delimiter_case("Hello World", ' ', true) -> HELLO WORLD
strings.to_delimiter_case("aBC", '_', false) -> a_b_c

converts the s string to "kebab-case" with all runes lowercased

returns the input string s with all runes set to lowered case

always allocates using the `allocator`

strings.to_lower("test") -> test
strings.to_lower("Test") -> test

converts the s string to "lowerCamelCase"

converts the s string to "PascalCase"

init a reader to the string s and return an io.Reader

init a reader to the string s and return an io.Reader_At

converts the s string to "SNAKE_CASE" with all runes uppercased

converts the s string to "snake_case" with all runes lowercased

strings.to_snake_case("HelloWorld") -> hello_world
strings.to_snake_case("Hello World") -> hello_world

return an io.Stream from a builder

cast the builder byte buffer to a string and return it

returns the input string s with all runes set to upper case

always allocates using the `allocator`

strings.to_lower("test") -> TEST
strings.to_lower("Test") -> TEST

converts the s string to "PascalCase"

converts the s string to "KEBAB-CASE" with all runes uppercased

converts the s string to "SNAKE_CASE" with all runes uppercased

return an io.Writer from a builder

trims the cutset string from the s string, both from left and right

trims the cutset string from the s string

trims nul runes from the left: "\x00\x00testing\x00\x00" -> "testing\x00\x00"

trims the input string s until the procedure p returns false

does not allocate - only returns a cut variant of the input string
returns an empty string when no match was found at all

find :: proc(r: rune) -> bool {
	return r != 'i'
}
strings.trim_left_proc("testing", find) -> "ing"

trims the input string s until the procedure p with state returns false

returns an empty string when no match was found at all

trims until a valid non space rune: "\t\txyz\t\t" -> "xyz\t\t"

trims nul runes from both sides: "\x00\x00testing\x00\x00" -> "testing"

trims a prefix string from the start of the s string and returns the trimmed string

returns the input string `s` when no prefix was found

strings.trim_prefix("testing", "test") -> "ing"
strings.trim_prefix("testing", "abc") -> "testing"

trims the cutset string from the s string from the right

trims nul runes from the right: "\x00\x00testing\x00\x00" -> "\x00\x00testing"

trims the input string s from the right until the procedure p returns false

does not allocate - only returns a cut variant of the input string
returns an empty string when no match was found at all

find :: proc(r: rune) -> bool {
	return r != 't'
}
strings.trim_left_proc("testing", find) -> "test"

trims the input string s from the right until the procedure p with state returns false

returns an empty string when no match was found at all

trims from the right until a valid non space rune: "\t\txyz\t\t" -> "\t\txyz"

trims from both sides until a valid non space rune: "\t\txyz\t\t" -> "xyz"

trims a suffix string from the end of the s string and returns the trimmed string

returns the input string `s` when no suffix was found

strings.trim_suffix("todo.txt", ".txt") -> "todo"
strings.trim_suffix("todo.doc", ".txt") -> "todo.doc"

returns a string truncated to the first time it finds the byte b uses the len of the string str when it couldn't find the input

returns a string truncated to the first time it finds the rune r uses the len of the string str when it couldn't find the input

returns the transmute of string str to a cstring not safe since the origin string may not contain a nul byte

appends a byte to the builder, returns the append diff

builder := strings.builder_make()
strings.write_byte(&builder, 'a') // 1
strings.write_byte(&builder, 'b') // 1
strings.write_byte(&builder, 'c') // 1
fmt.println(strings.to_string(builder)) // -> abc

appends a slice of bytes to the builder, returns the append diff

builder := strings.builder_make()
bytes := [?]byte { 'a', 'b', 'c' }
strings.write_bytes(&builder, bytes[:]) // 3
fmt.println(strings.to_string(builder)) // -> abc

appends a rune to the builder, optional write_quote boolean tag, returns the written rune size

appends a rune to the builder, fully written out in case of escaped runes e.g. '\a' will be written as such when r and quote match and quote is \\ - they will be written as two slashes html_safe flag in case the runes '<', '>', '&' should be encoded as digits e.g. \u0026

writes a i64 value i in base = 10 into the builder, returns the written amount of characters

writes a int value i in base = 10 into the builder, returns the written amount of characters

appends a quoted rune into the builder, returns written size

builder := strings.builder_make()
strings.write_string(&builder, "abc") // 3
strings.write_quoted_rune(&builder, 'ä') // 4
strings.write_string(&builder, "abc") // 3
fmt.println(strings.to_string(builder)) // -> abc'ä'abc

append a quoted string into the builder, return the written byte size

builder := strings.builder_make()
strings.write_quoted_string(&builder, "a") // 3
strings.write_quoted_string(&builder, "bc", '\'') // 4
strings.write_quoted_string(&builder, "xyz") // 5
fmt.println(strings.to_string(builder)) // -> "a"'bc'xyz"

appends a single rune into the builder, returns written rune size and an io.Error

builder := strings.builder_make()
strings.write_rune(&builder, 'ä') // 2 None
strings.write_rune(&builder, 'b') // 1 None
strings.write_rune(&builder, 'c') // 1 None
fmt.println(strings.to_string(builder)) // -> äbc

appends a string to the builder, return the written byte size

builder := strings.builder_make()
strings.write_string(&builder, "a") // 1
strings.write_string(&builder, "bc") // 2
strings.write_string(&builder, "xyz") // 3
fmt.println(strings.to_string(builder)) // -> abcxyz

writes a u64 value i in base = 10 into the builder, returns the written amount of characters

writes a uint value i in base = 10 into the builder, returns the written amount of characters

overload simple builder_init_* with or without len / ap parameters

overload simple builder_make_* with or without len / cap parameters

overload to clone from a string, []byte, cstring or a ^byte + length to a string