package core:strings

Source

Ascii_Set is designed to store ASCII characters efficiently as a bit-array Each bit in the array corresponds to a specific ASCII character, where the value of the bit (0 or 1) indicates if the character is present in the set or not.

A 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

Type definition for a procedure that flushes a Builder

Inputs:
b: A pointer to the Builder

Returns:
A boolean indicating whether the Builder should be reset

Intern is a more memory efficient string map

Uses Specified Allocator for Intern_Entry strings

Fields: allocator: The allocator used for the Intern_Entry strings entries: A map of strings to interned string entries

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

Determines if a given char is contained within an Ascii_Set.

Inputs:
as: The Ascii_Set to search. c: The char to check for in the Ascii_Set.

Returns:
res: A boolean indicating if the byte is contained in the Ascii_Set (true) or not (false).

Creates an Ascii_Set with unique characters from the input string.

Inputs:
chars: A string containing characters to include in the Ascii_Set.

Returns:
as: An Ascii_Set with unique characters from the input string. ok: false if any character in the input string is not a valid ASCII character.

Returns the capacity of the Builder's buffer, in bytes

Inputs:
b: A Builder

Returns:
res: The capacity of the Builder's buffer

Deletes the Builder byte buffer content

Inputs:
b: A pointer to the Builder

Creates a Builder from a slice of bytes with the same slice length as its capacity. Used in fmt.bprint*

Uses Nil Allocator - Does NOT allocate

Inputs:
backing: A slice of bytes to be used as the backing buffer

Returns:
res: The new Builder

import "core:fmt"
import "core:strings"
builder_from_bytes_example :: proc() {
	bytes: [8]byte // <-- gets filled
	builder := strings.builder_from_bytes(bytes[:])
	strings.write_byte(&builder, 'a')
	fmt.println(strings.to_string(builder)) // -> "a"
	strings.write_byte(&builder, 'b')
	fmt.println(strings.to_string(builder)) // -> "ab"
}

a
ab

Creates a Builder from a slice of bytes with the same slice length as its capacity. Used in fmt.bprint*

Uses Nil Allocator - Does NOT allocate

Inputs:
backing: A slice of bytes to be used as the backing buffer

Returns:
res: The new Builder

import "core:fmt"
import "core:strings"
builder_from_bytes_example :: proc() {
	bytes: [8]byte // <-- gets filled
	builder := strings.builder_from_bytes(bytes[:])
	strings.write_byte(&builder, 'a')
	fmt.println(strings.to_string(builder)) // -> "a"
	strings.write_byte(&builder, 'b')
	fmt.println(strings.to_string(builder)) // -> "ab"
}

a
ab

Reserves the Builder byte buffer to a specific capacity, when it's higher than before

Inputs:
b: A pointer to the Builder cap: The desired capacity for the Builder's buffer

Initializes a Builder with specified length and capacity len. It replaces the existing buf

Allocates Using Provided Allocator

Inputs:
b: A pointer to the Builder len: The desired length of the Builder's buffer allocator: (default is context.allocator)

Returns:
res: A pointer to the initialized Builder err: An optional allocator error if one occured, nil otherwise

Initializes a Builder with specified length len and capacity cap. It replaces the existing buf

Inputs:
b: A pointer to the Builder len: The desired length of the Builder's buffer cap: The desired capacity of the Builder's buffer, actual max(len,cap) allocator: (default is context.allocator)

Returns:
res: A pointer to the initialized Builder err: An optional allocator error if one occured, nil otherwise

Initializes an empty Builder It replaces the existing buf

Allocates Using Provided Allocator

Inputs:
b: A pointer to the Builder allocator: (default is context.allocator)

Returns:
res: A pointer to the initialized Builder err: An optional allocator error if one occured, nil otherwise

Returns the length of the Builder's buffer, in bytes

Inputs:
b: A Builder

Returns:
res: The length of the Builder's buffer

Produces a Builder with specified length and capacity len.

Allocates Using Provided Allocator

Inputs:
len: The desired length of the Builder's buffer allocator: (default is context.allocator)

Returns:
res: The new Builder err: An optional allocator error if one occured, nil otherwise

Produces a Builder with specified length len and capacity cap.

Allocates Using Provided Allocator

Inputs:
len: The desired length of the Builder's buffer cap: The desired capacity of the Builder's buffer, cap is max(cap, len) allocator: (default is context.allocator)

Returns:
res: The new Builder err: An optional allocator error if one occured, nil otherwise

Produces an empty Builder

Allocates Using Provided Allocator

Inputs:
allocator: (default is context.allocator)

Returns:
res: The new Builder err: An optional allocator error if one occured, nil otherwise

Clears the Builder byte buffer content (sets len to zero)

Inputs:
b: A pointer to the Builder

The free space left in the Builder's buffer, in bytes

Inputs:
b: A Builder

Returns:
res: The available space left in the Builder's buffer

Centers the input string within a field of specified length by adding pad string on both sides, if its length is less than the target length.

Allocates Using Provided Allocator

Inputs:
str: The input string length: The desired length of the centered string, in runes pad: The string used for padding on both sides allocator: (default is context.allocator)

Returns:
res: A new string centered within a field of the specified length err: An optional allocator error if one occured, nil otherwise

Centers the input string within a field of specified length by adding pad string on both sides, if its length is less than the target length.

Allocates Using Provided Allocator

Inputs:
str: The input string length: The desired length of the centered string, in runes pad: The string used for padding on both sides allocator: (default is context.allocator)

Returns:
res: A new string centered within a field of the specified length err: An optional allocator error if one occured, nil otherwise

Clones a string

Allocates Using Provided Allocator

Inputs:
s: The string to be cloned allocator: (default: context.allocator) loc: The caller location for debugging purposes (default: #caller_location)

Returns:
res: The cloned string err: An optional allocator error if one occured, nil otherwise

Clones a byte array s and appends a null-byte

Allocates Using Provided Allocator

Inputs:
s: The byte array to be cloned allocator: (default: context.allocator) loc: The caller location for debugging purposes (default: #caller_location)

Returns:
res: The cloned string from the byte array with a null-byte err: An optional allocator error if one occured, nil otherwise

Clones a cstring s as a string

Allocates Using Provided Allocator

Inputs:
s: The cstring to be cloned allocator: (default: context.allocator) loc: The caller location for debugging purposes (default: #caller_location)

Returns:
res: The cloned string from the cstring err: An optional allocator error if one occured, nil otherwise

Clones a string from a null-terminated cstring ptr and a byte length len

Allocates Using Provided Allocator

Inputs:
ptr: A pointer to the start of the null-terminated cstring len: The byte length of the cstring allocator: (default: context.allocator) loc: The caller location for debugging purposes (default: #caller_location)

NOTE: Truncates at the first null-byte encountered or the byte length.

Returns:
res: The cloned string from the null-terminated cstring and byte length err: An optional allocator error if one occured, nil otherwise

Clones a string from a byte pointer ptr and a byte length len

Allocates Using Provided Allocator

Inputs:
ptr: A pointer to the start of the byte sequence len: The length of the byte sequence allocator: (default: context.allocator) loc: The caller location for debugging purposes (default: #caller_location)

NOTE: Same as string_from_ptr, but perform an additional clone operation

Returns:
res: The cloned string from the byte pointer and length err: An optional allocator error if one occured, nil otherwise

Clones a string safely (returns early with an allocation error on failure)

Allocates Using Provided Allocator

Inputs:
s: The string to be cloned allocator: (default: context.allocator) loc: The caller location for debugging purposes (default: #caller_location)

Returns:
res: The cloned string err: An allocator error if one occured, nil otherwise

Clones a string and appends a null-byte to make it a cstring

Allocates Using Provided Allocator

Inputs:
s: The string to be cloned allocator: (default: context.allocator) loc: The caller location for debugging purposes (default: #caller_location)

Returns:
res: A cloned cstring with an appended null-byte err: An optional allocator error if one occured, nil otherwise

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

Inputs:
lhs: First string for comparison rhs: Second string for comparison

Returns:
result: -1 if lhs comes first, 1 if rhs comes first, or 0 if they are equal

Returns a combined string from the slice of strings a without a separator

Allocates Using Provided Allocator

Inputs:
a: A slice of strings to concatenate allocator: (default is context.allocator)

Returns:
res: The concatenated string err: An optional allocator error if one occured, nil otherwise

import "core:fmt"
import "core:strings"

concatenate_example :: proc() {
	a := [?]string { "a", "b", "c" }
	fmt.println(strings.concatenate(a[:]))
}

abc

Returns a combined string from the slice of strings a without a separator, or an error if allocation fails

Allocates Using Provided Allocator

Inputs:
a: A slice of strings to concatenate allocator: (default is context.allocator)

Returns:
The concatenated string, and an error if allocation fails

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

Inputs:
s: The input string substr: The substring to search for

Returns:
res: true if substr is contained inside the string s, false otherwise

import "core:fmt"
import "core:strings"

contains_example :: proc() {
	fmt.println(strings.contains("testing", "test"))
	fmt.println(strings.contains("testing", "ing"))
	fmt.println(strings.contains("testing", "text"))
}

true
true
false

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

Inputs:
s: The input string chars: The characters to search for

Returns:
res: true if the string s contains any of the characters in chars, false otherwise

import "core:fmt"
import "core:strings"

contains_any_example :: proc() {
	fmt.println(strings.contains_any("test", "test"))
	fmt.println(strings.contains_any("test", "ts"))
	fmt.println(strings.contains_any("test", "et"))
	fmt.println(strings.contains_any("test", "a"))
}

true
true
true
false

Checks if rune r in the string s

Inputs:
s: The input string r: The rune to search for

Returns:
result: true if the rune r in the string s, false otherwise

Counts the number of non-overlapping occurrences of substr in s

Inputs:
s: The string to search in substr: The substring to count

Returns:
res: The number of occurrences of substr in s, returns the rune_count + 1 of the string s on empty substr

import "core:fmt"
import "core:strings"

count_example :: proc() {
	fmt.println(strings.count("abbccc", "a"))
	fmt.println(strings.count("abbccc", "b"))
	fmt.println(strings.count("abbccc", "c"))
	fmt.println(strings.count("abbccc", "ab"))
	fmt.println(strings.count("abbccc", " "))
}

1
2
3
1
0

Returns a substring of the input string s with the specified rune offset and length

Inputs:
s: The input string to cut rune_offset: The starting rune index (default is 0). In runes, not bytes. rune_length: The number of runes to include in the substring (default is 0, which returns the remainder of the string). In runes, not bytes.

Returns:
res: The substring

import "core:fmt"
import "core:strings"

cut_example :: proc() {
	fmt.println(strings.cut("some example text", 0, 4)) // -> "some"
	fmt.println(strings.cut("some example text", 2, 2)) // -> "me"
	fmt.println(strings.cut("some example text", 5, 7)) // -> "example"
}

some
me
example

Returns a substring of the input string s with the specified rune offset and length

Allocates Using Provided Allocator

Inputs:
s: The input string to cut rune_offset: The starting rune index (default is 0). In runes, not bytes. rune_length: The number of runes to include in the substring (default is 0, which returns the remainder of the string). In runes, not bytes. allocator: (default is context.allocator)

Returns:
res: The substring err: An optional allocator error if one occured, nil otherwise

import "core:fmt"
import "core:strings"

cut_clone_example :: proc() {
	fmt.println(strings.cut_clone("some example text", 0, 4)) // -> "some"
	fmt.println(strings.cut_clone("some example text", 2, 2)) // -> "me"
	fmt.println(strings.cut_clone("some example text", 5, 7)) // -> "example"
}

some
me
example

Determines if a string s ends with a given suffix

Inputs:
s: The string to check for the suffix suffix: The suffix to look for

Returns:
result: true if the string s ends with the suffix, otherwise false

import "core:fmt"
import "core:strings"

has_suffix_example :: proc() {
	fmt.println(strings.has_suffix("todo.txt", ".txt"))
	fmt.println(strings.has_suffix("todo.doc", ".txt"))
	fmt.println(strings.has_suffix("todo.doc.txt", ".txt"))
}

true
false
true

Returns whether the strings u and v are the same alpha characters, ignoring different casings Works with UTF-8 string content

Inputs:
u: The first string for comparison v: The second string for comparison

Returns:
res: true if the strings u and v are the same alpha characters (ignoring case)

import "core:fmt"
import "core:strings"

equal_fold_example :: proc() {
	fmt.println(strings.equal_fold("test", "test"))
	fmt.println(strings.equal_fold("Test", "test"))
	fmt.println(strings.equal_fold("Test", "tEsT"))
	fmt.println(strings.equal_fold("test", "tes"))
}

true
true
true
false

Expands the input string by replacing tab characters with spaces to align to a specified tab size

Allocates Using Provided Allocator

Inputs:
s: The input string tab_size: The number of spaces to use for each tab character allocator: (default is context.allocator)

Returns:
res: A new string with tab characters expanded to the specified tab size err: An optional allocator error if one occured, nil otherwise

WARNING: Panics if tab_size <= 0

import "core:fmt"
import "core:strings"

expand_tabs_example :: proc() {
	text := "abc1\tabc2\tabc3"
	fmt.println(strings.expand_tabs(text, 4))
}

abc1    abc2    abc3

Splits a string into a slice of substrings at each instance of one or more consecutive white space characters, as defined by unicode.is_space

Allocates Using Provided Allocator

Inputs:
s: The input string allocator: (default is context.allocator)

Returns:
res: A slice of substrings of the input string, or an empty slice if the input string only contains white space err: An optional allocator error if one occured, nil otherwise

Retrieves the first non-space substring from a mutable string reference and advances the reference. s is advanced from any space after the substring, or be an empty string if the substring was the remaining characters

Inputs:
s: A mutable string reference to be iterated

Returns:
field: The first non-space substring found ok: A boolean indicating if a non-space substring was found

Splits a string into a slice of substrings at each run of unicode code points r satisfying the predicate f(r)

Allocates Using Provided Allocator

Inputs:
s: The input string f: A predicate function to determine the split points allocator: (default is context.allocator)

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

Returns:
res: A slice of substrings of the input string, or an empty slice if all code points in the input string satisfy the predicate or if the input string is empty err: An optional allocator error if one occured, nil otherwise

Determines if a string s starts with a given prefix

Inputs:
s: The string to check for the prefix prefix: The prefix to look for

Returns:
result: true if the string s starts with the prefix, otherwise false

import "core:fmt"
import "core:strings"

has_prefix_example :: proc() {
	fmt.println(strings.has_prefix("testing", "test"))
	fmt.println(strings.has_prefix("testing", "te"))
	fmt.println(strings.has_prefix("telephone", "te"))
	fmt.println(strings.has_prefix("testing", "est"))
}

true
true
true
false

Determines if a string s ends with a given suffix

Inputs:
s: The string to check for the suffix suffix: The suffix to look for

Returns:
result: true if the string s ends with the suffix, otherwise false

import "core:fmt"
import "core:strings"

has_suffix_example :: proc() {
	fmt.println(strings.has_suffix("todo.txt", ".txt"))
	fmt.println(strings.has_suffix("todo.doc", ".txt"))
	fmt.println(strings.has_suffix("todo.doc.txt", ".txt"))
}

true
false
true

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

Inputs:
s: The input string to search in. substr: The substring to search for.

Returns:
res: The byte offset of the first occurrence of substr in s, or -1 if not found.

import "core:fmt"
import "core:strings"

index_example :: proc() {
	fmt.println(strings.index("test", "t"))
	fmt.println(strings.index("test", "te"))
	fmt.println(strings.index("test", "st"))
	fmt.println(strings.index("test", "tt"))
}

0
0
2
-1

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

Inputs:
s: The input string to search in. chars: The characters to look for

Returns:
res: The index of the first character of chars found in s, or -1 if not found.

import "core:fmt"
import "core:strings"

index_any_example :: proc() {
	fmt.println(strings.index_any("test", "s"))
	fmt.println(strings.index_any("test", "se"))
	fmt.println(strings.index_any("test", "et"))
	fmt.println(strings.index_any("test", "set"))
	fmt.println(strings.index_any("test", "x"))
}

2
1
0
0
-1

Returns the byte offset of the first byte c in the string s it finds, -1 when not found. NOTE: Can't find UTF-8 based runes.

Inputs:
s: The input string to search in. c: The byte to search for.

Returns:
res: The byte offset of the first occurrence of c in s, or -1 if not found.

import "core:fmt"
import "core:strings"

index_byte_example :: proc() {
	fmt.println(strings.index_byte("test", 't'))
	fmt.println(strings.index_byte("test", 'e'))
	fmt.println(strings.index_byte("test", 'x'))
	fmt.println(strings.index_byte("teäst", 'ä'))
}

0
1
-1
-1

Finds the first occurrence of any substring in substrs within s

Inputs:
s: The string to search in substrs: The substrings to look for

Returns:
idx: the index of the first matching substring width: the length of the found substring

Find the index of the first rune r in string s for which procedure p returns the same as truth, or -1 if no such rune appears.

Inputs:
s: The input string p: A procedure that takes a rune and returns a boolean truth: The boolean value to be matched (default: true)

Returns:
res: The index of the first matching rune, or -1 if no match was found

import "core:fmt"
import "core:strings"

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

0
2
0
1
-1

Same as index_proc, but the procedure p takes a raw pointer for state

Returns the byte offset of the first rune r in the string s it finds, -1 when not found. Invalid runes return -1

Inputs:
s: The input string to search in. r: The rune to search for.

Returns:
res: The byte offset of the first occurrence of r in s, or -1 if not found.

import "core:fmt"
import "core:strings"

index_rune_example :: proc() {
	fmt.println(strings.index_rune("abcädef", 'x'))
	fmt.println(strings.index_rune("abcädef", 'a'))
	fmt.println(strings.index_rune("abcädef", 'b'))
	fmt.println(strings.index_rune("abcädef", 'c'))
	fmt.println(strings.index_rune("abcädef", 'ä'))
	fmt.println(strings.index_rune("abcädef", 'd'))
	fmt.println(strings.index_rune("abcädef", 'e'))
	fmt.println(strings.index_rune("abcädef", 'f'))
}

-1
0
1
2
3
5
6
7

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

Inputs:
m: A pointer to the Intern struct to be destroyed

Returns an interned copy of the given text, adding it to the map if not already present.

Allocate using the Intern's Allocator (First time string is seen only)

Inputs:
m: A pointer to the Intern struct text: The string to be interned

NOTE: The returned string lives as long as the map entry lives.

Returns:
str: The interned string err: An allocator error if one occured, nil otherwise

Returns an interned copy of the given text as a cstring, adding it to the map if not already present.

Allocate using the Intern's Allocator (First time string is seen only)

Inputs:
m: A pointer to the Intern struct text: The string to be interned

NOTE: The returned cstring lives as long as the map entry lives

Returns:
str: The interned cstring err: An allocator error if one occured, nil otherwise

Initializes the entries map and sets the allocator for the string entries

Allocates Using Provided Allocators

Inputs:
m: A pointer to the Intern struct to be initialized allocator: The allocator for the Intern_Entry strings (Default: context.allocator) map_allocator: The allocator for the map of entries (Default: context.allocator)

Returns:
err: An allocator error if one occured, nil otherwise

Returns true when the r rune is an ASCII whitespace character.

Inputs:
r: the rune to test

Returns:
-res: true if r is a whitespace character, false if otherwise

Checks if the rune r is a delimiter (' ', '-', or '_').

Inputs:
r: Rune to check for delimiter status.

Returns:
res: True if r is a delimiter, false otherwise.

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

Returns true when the r rune is 0x0

Inputs:
r: the rune to test

Returns:
-res: true if r is 0x0, false if otherwise

Checks if the rune r is a non-alphanumeric or space character.

Inputs:
r: Rune to check for separator status.

Returns:
res: True if r is a non-alpha or unicode.is_space rune.

Returns true when the r rune is an ASCII or UTF-8 whitespace character.

Inputs:
r: the rune to test

Returns:
-res: true if r is a whitespace character, false if otherwise

Joins a slice of strings a with a sep string

Allocates Using Provided Allocator

Inputs:
a: A slice of strings to join sep: The separator string allocator: (default is context.allocator)

Returns:
res: A combined string from the slice of strings a separated with the sep string err: An optional allocator error if one occured, nil otherwise

import "core:fmt"
import "core:strings"

join_example :: proc() {
	a := [?]string { "a", "b", "c" }
	fmt.println(strings.join(a[:], " "))
	fmt.println(strings.join(a[:], "-"))
	fmt.println(strings.join(a[:], "..."))
}

a b c
a-b-c
a...b...c

Joins a slice of strings a with a sep string, returns an error on allocation failure

Allocates Using Provided Allocator

Inputs:
a: A slice of strings to join sep: The separator string allocator: (default is context.allocator)

Returns:
str: A combined string from the slice of strings a separated with the sep string err: An allocator error if one occured, nil otherwise

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

Inputs:
s: The input string to search in. substr: The substring to search for.

Returns:
res: The byte offset of the last occurrence of substr in s, or -1 if not found.

import "core:fmt"
import "core:strings"

last_index_example :: proc() {
	fmt.println(strings.last_index("test", "t"))
	fmt.println(strings.last_index("test", "te"))
	fmt.println(strings.last_index("test", "st"))
	fmt.println(strings.last_index("test", "tt"))
}

3
0
2
-1

Finds the last occurrence of any character in chars within s. Iterates in reverse.

Inputs:
s: The string to search in chars: The characters to look for

Returns:
res: The index of the last matching character, or -1 if not found

import "core:fmt"
import "core:strings"

last_index_any_example :: proc() {
	fmt.println(strings.last_index_any("test", "s"))
	fmt.println(strings.last_index_any("test", "se"))
	fmt.println(strings.last_index_any("test", "et"))
	fmt.println(strings.last_index_any("test", "set"))
	fmt.println(strings.last_index_any("test", "x"))
}

2
2
3
3
-1

Returns the byte offset of the last byte c in the string s, -1 when not found.

Inputs:
s: The input string to search in. c: The byte to search for.

Returns:
res: The byte offset of the last occurrence of c in s, or -1 if not found.

NOTE: Can't find UTF-8 based runes.

import "core:fmt"
import "core:strings"

last_index_byte_example :: proc() {
	fmt.println(strings.last_index_byte("test", 't'))
	fmt.println(strings.last_index_byte("test", 'e'))
	fmt.println(strings.last_index_byte("test", 'x'))
	fmt.println(strings.last_index_byte("teäst", 'ä'))
}

3
1
-1
-1

Finds the index of the last rune in the string s for which the procedure p returns the same value as truth

Same as index_proc_with_state, runs through the string in reverse

Left-justifies the input string within a field of specified length by adding pad string on the right side, if its length is less than the target length.

Allocates Using Provided Allocator

Inputs:
str: The input string length: The desired length of the left-justified string pad: The string used for padding on the right side allocator: (default is context.allocator)

Returns:
res: A new string left-justified within a field of the specified length err: An optional allocator error if one occured, nil otherwise

Computes the Levenshtein edit distance between two strings

Allocates Using Provided Allocator (deletion occurs internal to proc)

NOTE: Does not perform internal allocation if length of string b, in runes, is smaller than 64

Inputs:
a, b: The two strings to compare allocator: (default is context.allocator)

Returns:
res: The Levenshtein edit distance between the two strings err: An optional allocator error if one occured, nil otherwise

NOTE: This implementation is a single-row-version of the Wagner–Fischer algorithm, based on C code by Martin Ettl.

Splits the input string str by the separator sep string and returns 3 parts. The values are slices of the original string.

Inputs:
str: The input string sep: The separator string

Returns:
head: the string before the split match: the seperator string tail: the string after the split

import "core:fmt"
import "core:strings"

partition_example :: proc() {
	text := "testing this out"
	head, match, tail := strings.partition(text, " this ") // -> head: "testing", match: " this ", tail: "out"
	fmt.println(head, match, tail)
	head, match, tail = strings.partition(text, "hi") // -> head: "testing t", match: "hi", tail: "s out"
	fmt.println(head, match, tail)
	head, match, tail = strings.partition(text, "xyz")    // -> head: "testing this out", match: "", tail: ""
	fmt.println(head)
	fmt.println(match == "")
	fmt.println(tail == "")
}

testing  this  out
testing t hi s out
testing this out
true
true

Pops and returns the last byte in the Builder or 0 when the Builder is empty

Inputs:
b: A pointer to the Builder

Returns:
r: The last byte in the Builder or 0 if empty

Pops the last rune in the Builder and returns the popped rune and its rune width or (0, 0) if empty

Inputs:
b: A pointer to the Builder

Returns:
r: The popped rune width: The rune width or 0 if the builder was empty

Returns the prefix length common between strings a and b

Inputs:
a: The first input string b: The second input string

Returns:
n: The prefix length common between strings a and b

import "core:fmt"
import "core:strings"

prefix_length_example :: proc() {
	fmt.println(strings.prefix_length("testing", "test"))
	fmt.println(strings.prefix_length("testing", "te"))
	fmt.println(strings.prefix_length("telephone", "te"))
	fmt.println(strings.prefix_length("testing", "est"))
}

4
2
2
0

Gets the raw byte pointer for the start of a string str

Inputs:
str: The input string

Returns:
res: A pointer to the start of the string's bytes

Initializes a string Reader with the provided string

Inputs:
r: A pointer to a Reader struct s: The input string to be read

Returns the remaining length of the Reader

Inputs:
r: A pointer to a Reader struct

Returns:
res: The remaining length of the Reader

Reads len(p) bytes from the Reader's string and copies into the provided slice.

Inputs:
r: A pointer to a Reader struct p: A byte slice to copy data into

Returns:
n: The number of bytes read err: An io.Error if an error occurs while reading, including .EOF, otherwise nil denotes success.

Reads len(p) bytes from the Reader's string and copies into the provided slice, at the specified offset from the current index.

Inputs:
r: A pointer to a Reader struct p: A byte slice to copy data into off: The offset from which to read

Returns:
n: The number of bytes read err: An io.Error if an error occurs while reading, including .EOF, otherwise nil denotes success.

Reads and returns a single byte from the Reader's string

Inputs:
r: A pointer to a Reader struct

Returns:
The byte read from the Reader err: An io.Error if an error occurs while reading, including .EOF, otherwise nil denotes success.

Reads and returns a single rune and its size from the Reader's string

Inputs:
r: A pointer to a Reader struct

Returns:
rr: The rune read from the Reader size: The size of the rune in bytes err: An io.Error if an error occurs while reading

Seeks the Reader's index to a new position

Inputs:
r: A pointer to a Reader struct offset: The new offset position whence: The reference point for the new position (.Start, .Current, or .End)

Returns:
The absolute offset after seeking err: An io.Error if an error occurs while seeking (.Invalid_Whence, .Invalid_Offset)

Returns the length of the string stored in the Reader

Inputs:
r: A pointer to a Reader struct

Returns:
res: The length of the string stored in the Reader

Converts a Reader into an io.Stream

Inputs:
r: A pointer to a Reader struct

Returns:
s: An io.Stream for the given Reader

Decrements the Reader's index (i) by 1

Inputs:
r: A pointer to a Reader struct

Returns:
err: An io.Error if r.i <= 0 (.Invalid_Unread), otherwise nil denotes success.

Decrements the Reader's index (i) by the size of the last read rune

Inputs:
r: A pointer to a Reader struct

WARNING: May only be used once and after a valid read_rune call

Returns:
err: An io.Error if an error occurs while unreading (.Invalid_Unread), else nil denotes success.

Writes the remaining content of the Reader's string into the provided io.Writer

Inputs:
r: A pointer to a Reader struct w: The io.Writer to write the remaining content into

WARNING: Panics if writer writes more bytes than remainig length of string.

Returns:
n: The number of bytes written err: An io.Error if an error occurs while writing (.Short_Write)

Removes the key string n times from the s string

Allocates Using Provided Allocator

Inputs:
s: The input string key: The substring to be removed n: The number of instances to remove (if n < 0, no limit on the number of removes) allocator: (default: context.allocator)

Returns:
output: The modified string was_allocation: true if an allocation occurred during the replacement, false otherwise

import "core:fmt"
import "core:strings"

remove_example :: proc() {
	fmt.println(strings.remove("abcabc", "abc", 1))
	fmt.println(strings.remove("abcabc", "abc", -1))
	fmt.println(strings.remove("abcabc", "a", -1))
	fmt.println(strings.remove("abcabc", "x", -1))
}

abc true
 true
bcbc true
abcabc false

Removes all the key string instances from the s string

Allocates Using Provided Allocator

Inputs:
s: The input string key: The substring to be removed allocator: (default: context.allocator)

Returns:
output: The modified string was_allocation: true if an allocation occurred during the replacement, false otherwise

import "core:fmt"
import "core:strings"

remove_all_example :: proc() {
	fmt.println(strings.remove_all("abcabc", "abc"))
	fmt.println(strings.remove_all("abcabc", "a"))
	fmt.println(strings.remove_all("abcabc", "x"))
}

 true
bcbc true
abcabc false

Repeats the string s count times, concatenating the result

Allocates Using Provided Allocator

Inputs:
s: The string to repeat count: The number of times to repeat s allocator: (default is context.allocator)

Returns:
res: The concatenated repeated string err: An optional allocator error if one occured, nil otherwise

WARNING: Panics if count < 0

import "core:fmt"
import "core:strings"

repeat_example :: proc() {
	fmt.println(strings.repeat("abc", 2))
}

abcabc

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

Allocates Using Provided Allocator

Inputs:
s: The input string old: The substring to be replaced new: The replacement string n: The number of instances to replace (if n < 0, no limit on the number of replacements) allocator: (default: context.allocator)

Returns:
output: The modified string was_allocation: true if an allocation occurred during the replacement, false otherwise

import "core:fmt"
import "core:strings"

replace_example :: proc() {
	fmt.println(strings.replace("xyzxyz", "xyz", "abc", 2))
	fmt.println(strings.replace("xyzxyz", "xyz", "abc", 1))
	fmt.println(strings.replace("xyzxyz", "abc", "xyz", -1))
	fmt.println(strings.replace("xyzxyz", "xy", "z", -1))
}

abcabc true
abcxyz true
xyzxyz false
zzzz true

Replaces all occurrences of old in s with new

Allocates Using Provided Allocator

Inputs:
s: The string to modify old: The substring to replace new: The substring to replace old with allocator: The allocator to use for the new string (default is context.allocator)

Returns:
output: The modified string was_allocation: true if an allocation occurred during the replacement, false otherwise

import "core:fmt"
import "core:strings"

replace_all_example :: proc() {
	fmt.println(strings.replace_all("xyzxyz", "xyz", "abc"))
	fmt.println(strings.replace_all("xyzxyz", "abc", "xyz"))
	fmt.println(strings.replace_all("xyzxyz", "xy", "z"))
}

abcabc true
xyzxyz false
zzzz true

Reverses the input string s

Allocates Using Provided Allocator

Inputs:
s: The input string allocator: (default is context.allocator)

Returns:
res: A reversed version of the input string err: An optional allocator error if one occured, nil otherwise

import "core:fmt"
import "core:strings"

reverse_example :: proc() {
	a := "abcxyz"
	b := strings.reverse(a)
	fmt.println(a, b)
}

abcxyz zyxcba

Right-justifies the input string within a field of specified length by adding pad string on the left side, if its length is less than the target length.

Allocates Using Provided Allocator

Inputs:
str: The input string length: The desired length of the right-justified string pad: The string used for padding on the left side allocator: (default is context.allocator)

Returns:
res: A new string right-justified within a field of the specified length err: An optional allocator error if one occured, nil otherwise

Returns the UTF-8 rune count of the string s

Inputs:
s: The input string

Returns:
res: The UTF-8 rune count of the string s

import "core:fmt"
import "core:strings"

rune_count_example :: proc() {
	fmt.println(strings.rune_count("test"))
	fmt.println(strings.rune_count("testö")) // where len("testö") == 6
}

4
5

Replaces invalid UTF-8 characters in the input string with a specified replacement string. Adjacent invalid bytes are only replaced once.

Allocates Using Provided Allocator

Inputs:
s: The input string replacement: The string used to replace invalid UTF-8 characters allocator: (default is context.allocator)

Returns:
res: A new string with invalid UTF-8 characters replaced err: An optional allocator error if one occured, nil otherwise

import "core:fmt"
import "core:strings"

scrub_example :: proc() {
	text := "Hello\xC0\x80World"
	fmt.println(strings.scrub(text, "?")) // -> "Hello?World"
}

Hello?

Splits a string into parts based on a separator.

Allocates Using Provided Allocator

Inputs:
s: The string to split. sep: The separator string used to split the input string. allocator: (default is context.allocator).

Returns:
res: The slice of strings, each representing a part of the split string. err: An optional allocator error if one occured, nil otherwise

NOTE: Allocation occurs for the array, the splits are all views of the original string.

import "core:fmt"
import "core:strings"

split_example :: proc() {
	s := "aaa.bbb.ccc.ddd.eee"    // 5 parts
	ss := strings.split(s, ".")
	fmt.println(ss)
}

["aaa", "bbb", "ccc", "ddd", "eee"]

Splits a string into parts after the separator, retaining it in the substrings.

Allocates Using Provided Allocator

Inputs:
s: The string to split. sep: The separator string used to split the input string. allocator: (default is context.allocator).

Returns:
res: The slice of strings, each representing a part of the split string after the separator err: An optional allocator error if one occured, nil otherwise

NOTE: Allocation occurs for the array, the splits are all views of the original string.

import "core:fmt"
import "core:strings"

split_after_example :: proc() {
	a := "aaa.bbb.ccc.ddd.eee"         // 5 parts
	aa := strings.split_after(a, ".")
	fmt.println(aa)
}

["aaa.", "bbb.", "ccc.", "ddd.", "eee"]

Splits the input string after every separator string in an iterator fashion.

Inputs:
s: Pointer to the input string, which is modified during the search. sep: The separator string to search for.

Returns:
res: The resulting substring ok: true if an iteration result was returned, false if the iterator has reached the end

import "core:fmt"
import "core:strings"

split_after_iterator_example :: proc() {
	text := "a.b.c.d.e"
	for str in strings.split_after_iterator(&text, ".") {
		fmt.println(str)
	}
}

a.
b.
c.
d.
e

Splits a string into a total of n parts after the separator.

Allocates Using Provided Allocator

Inputs:
s: The string to split. sep: The separator string used to split the input string. n: The maximum number of parts to split the string into. allocator: (default is context.allocator)

Returns:
res: The slice of strings with n parts or fewer if there weren't err: An optional allocator error if one occured, nil otherwise

NOTE: Allocation occurs for the array, the splits are all views of the original string.

import "core:fmt"
import "core:strings"

split_after_n_example :: proc() {
	a := "aaa.bbb.ccc.ddd.eee"
	aa := strings.split_after_n(a, ".", 3)
	fmt.println(aa)
}

["aaa.", "bbb.", "ccc.ddd.eee"]

Splits the input string by the byte separator in an iterator fashion.

Inputs:
s: Pointer to the input string, which is modified during the search. sep: The byte separator to search for.

Returns:
res: The resulting substring ok: true if an iteration result was returned, false if the iterator has reached the end

import "core:fmt"
import "core:strings"

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

a
b
c
d
e

Splits the input string by the separator string in an iterator fashion.

Inputs:
s: Pointer to the input string, which is modified during the search. sep: The separator string to search for.

Returns:
res: The resulting substring ok: true if an iteration result was returned, false if the iterator has reached the end

import "core:fmt"
import "core:strings"

split_iterator_example :: proc() {
	text := "a.b.c.d.e"
	for str in strings.split_iterator(&text, ".") {
		fmt.println(str)
	}
}

a
b
c
d
e

Splits the input string at every line break \n.

Allocates Using Provided Allocator

Inputs:
s: The input string to split. allocator: (default is context.allocator)

Returns:
res: The slice (allocated) of the split string (slices into original string) err: An optional allocator error if one occured, nil otherwise

import "core:fmt"
import "core:strings"

split_lines_example :: proc() {
	a := "a\nb\nc\nd\ne"
	b := strings.split_lines(a)
	fmt.println(b)
}

["a", "b", "c", "d", "e"]

Splits the input string at every line break \n leaving the \n in the resulting strings.

Allocates Using Provided Allocator

Inputs:
s: The input string to split. allocator: (default is context.allocator)

Returns:
res: The slice (allocated) of the split string (slices into original string), with \n included err: An optional allocator error if one occured, nil otherwise

NOTE: Allocation occurs for the array, the splits are all views of the original string.

import "core:fmt"
import "core:strings"

split_lines_after_example :: proc() {
	a := "a\nb\nc\nd\ne"
	b := strings.split_lines_after(a)
	fmt.println(b)
}

["a\n", "b\n", "c\n", "d\n", "e"]

Splits the input string at every line break \n. Returns the current split string with line breaks included every iteration until the string is consumed.

Inputs:
s: Pointer to the input string, which is modified during the search.

Returns:
line: The resulting substring with line breaks included ok: true if an iteration result was returned, false if the iterator has reached the end

import "core:fmt"
import "core:strings"

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

a
b
c
d
e

Splits the input string at every line break \n leaving the \n in the resulting strings. Only runs for n parts.

Allocates Using Provided Allocator

Inputs:
s: The input string to split. n: The number of parts to split into. allocator: (default is context.allocator)

Returns:
res: The slice (allocated) of the split string (slices into original string), with \n included err: An optional allocator error if one occured, nil otherwise

NOTE: Allocation occurs for the array, the splits are all views of the original string.

import "core:fmt"
import "core:strings"

split_lines_after_n_example :: proc() {
	a := "a\nb\nc\nd\ne"
	b := strings.split_lines_after_n(a, 3)
	fmt.println(b)
}

["a\n", "b\n", "c\nd\ne"]

Splits the input string at every line break \n. Returns the current split string every iteration until the string is consumed.

Inputs:
s: Pointer to the input string, which is modified during the search.

Returns:
line: The resulting substring ok: true if an iteration result was returned, false if the iterator has reached the end

import "core:fmt"
import "core:strings"

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

abcde

Splits the input string at every line break \n for n parts.

Allocates Using Provided Allocator

Inputs:
s: The input string to split. n: The number of parts to split into. allocator: (default is context.allocator)

Returns:
res: The slice (allocated) of the split string (slices into original string) err: An optional allocator error if one occured, nil otherwise

NOTE: Allocation occurs for the array, the splits are all views of the original string.

import "core:fmt"
import "core:strings"

split_lines_n_example :: proc() {
	a := "a\nb\nc\nd\ne"
	b := strings.split_lines_n(a, 3)
	fmt.println(b)
}

["a", "b", "c\nd\ne"]

Splits the input string s by all possible substrs and returns an allocated array of strings

Allocates Using Provided Allocator

Inputs:
s: The input string substrs: An array of substrings used for splitting allocator: (default is context.allocator)

Returns:
res: An array of strings, or nil on empty substring or no matches err: An optional allocator error if one occured, nil otherwise

NOTE: Allocation occurs for the array, the splits are all views of the original string.

import "core:fmt"
import "core:strings"

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

["testing", "this", "out", "nice", "done", "last"]

Splits the input string s by all possible substrs in an iterator fashion. The full string is returned if no match.

Inputs:
it: A pointer to the input string substrs: An array of substrings used for splitting

Returns:
res: The split string ok: true if an iteration result was returned, false if the iterator has reached the end

import "core:fmt"
import "core:strings"

split_multi_iterate_example :: proc() {
	it := "testing,this.out_nice---done~~~last"
	splits := [?]string { "---", "~~~", ".", "_", "," }
	for str in strings.split_multi_iterate(&it, splits[:]) {
		fmt.println(str)
	}
}

testing
this
out
nice
done
last

Splits a string into parts based on a separator. If n < count of seperators, the remainder of the string is returned in the last entry.

Allocates Using Provided Allocator

Inputs:
s: The string to split. sep: The separator string used to split the input string. n: The maximum amount of parts to split the string into. allocator: (default is context.allocator)

Returns:
res: The slice of strings, each representing a part of the split string. err: An optional allocator error if one occured, nil otherwise

NOTE: Allocation occurs for the array, the splits are all views of the original string.

import "core:fmt"
import "core:strings"

split_n_example :: proc() {
	s := "aaa.bbb.ccc.ddd.eee"  // 5 parts present
	ss := strings.split_n(s, ".",3) // total of 3 wanted
	fmt.println(ss)
}

["aaa", "bbb", "ccc.ddd.eee"]

Determines if a string s starts with a given prefix

Inputs:
s: The string to check for the prefix prefix: The prefix to look for

Returns:
result: true if the string s starts with the prefix, otherwise false

import "core:fmt"
import "core:strings"

has_prefix_example :: proc() {
	fmt.println(strings.has_prefix("testing", "test"))
	fmt.println(strings.has_prefix("testing", "te"))
	fmt.println(strings.has_prefix("telephone", "te"))
	fmt.println(strings.has_prefix("testing", "est"))
}

true
true
true
false

Iterates over a string, calling a callback for each rune with the previous, current, and next runes as arguments.

Inputs:
w: An io.Writer to be used by the callback for writing output. s: The input string to be iterated over. callback: A procedure to be called for each rune in the string, with arguments (w: io.Writer, prev, curr, next: rune). The callback can utilize the provided io.Writer to write output during the iteration.

import "core:fmt"
import "core:strings"
import "core:io"

string_case_iterator_example :: proc() {
	my_callback :: proc(w: io.Writer, prev, curr, next: rune) {
		fmt.println("my_callback", curr) // <-- Custom logic here
	}
	s := "hello"
	b: strings.Builder
	strings.builder_init_len(&b, len(s))
	w := strings.to_writer(&b)
	strings.string_case_iterator(w, s, my_callback)
}

my_callback h
my_callback e
my_callback l
my_callback l
my_callback o

Transmutes a raw pointer (null-terminated) into a string. Non-allocating. Searches for a null-byte from 0..<len, otherwise len will be the end size

NOTE: The created string is only valid as long as the pointer and length are valid.

  The string is truncated at the first null-byte encountered.

Inputs:
ptr: A pointer to the start of the null-terminated byte sequence len: The length of the byte sequence

Returns:
res: A string created from the null-terminated byte pointer and length

Transmutes a raw pointer into a string. Non-allocating.

Inputs:
ptr: A pointer to the start of the byte sequence len: The length of the byte sequence

NOTE: The created string is only valid as long as the pointer and length are valid.

Returns:
res: A string created from the byte pointer and length

Returns a substring of s that starts at rune index rune_start and goes up to rune_end.

Think of it as slicing s[rune_start:rune_end] but rune-wise.

Inputs:
s: the string to substring rune_start: the start (inclusive) rune rune_end: the end (exclusive) rune

Returns:
sub: the substring ok: whether the rune indexes where in bounds of the original string

Returns a substring of s that starts at rune index rune_start and goes up to the end of the string.

Think of it as slicing s[rune_start:] but rune-wise.

Inputs:
s: the string to substring rune_start: the start (inclusive) rune

Returns:
sub: the substring ok: whether the rune indexes where in bounds of the original string

Returns a substring of s that goes up to rune index rune_end.

Think of it as slicing s[:rune_end] but rune-wise.

Inputs:
s: the string to substring rune_end: the end (exclusive) rune

Returns:
sub: the substring ok: whether the rune indexes where in bounds of the original string

Converts a string to "Ada_Case"

Allocates Using Provided Allocator

Inputs:
s: The input string to be converted allocator: (default: context.allocator).

Returns:
res: The converted string err: An optional allocator error if one occured, nil otherwise

import "core:fmt"
import "core:strings"

to_ada_case_example :: proc() {
	fmt.println(strings.to_ada_case("HelloWorld"))
}

Hello_World

Converts the input string s to "lowerCamelCase".

Allocates Using Provided Allocator

Inputs:
s: Input string to be converted. allocator: (default: context.allocator).

Returns:
res: The converted string err: An optional allocator error if one occured, nil otherwise

Appends a trailing null byte after the end of the current Builder byte buffer and then casts it to a cstring

Inputs:
b: A pointer to builder

Returns:
res: A cstring of the Builder's buffer upon success err: An optional allocator error if one occured, nil otherwise

Returns a string converted to a delimiter-separated case with configurable casing

Allocates Using Provided Allocator

Inputs:
s: The input string to be converted delimiter: The rune to be used as the delimiter between words all_upper_case: A boolean indicating if the output should be all uppercased (true) or lowercased (false) allocator: (default: context.allocator).

Returns:
res: The converted string err: An optional allocator error if one occured, nil otherwise

import "core:fmt"
import "core:strings"

to_delimiter_case_example :: proc() {
	fmt.println(strings.to_delimiter_case("Hello World", '_', false))
	fmt.println(strings.to_delimiter_case("Hello World", ' ', true))
	fmt.println(strings.to_delimiter_case("aBC", '_', false))
}

hello_world
HELLO WORLD
a_bc

Converts a string to "kebab-case" with all runes lowercased

Allocates Using Provided Allocator

Inputs:
s: The input string to be converted allocator: (default: context.allocator).

Returns:
res: The converted string err: An optional allocator error if one occured, nil otherwise

import "core:fmt"
import "core:strings"

to_kebab_case_example :: proc() {
	fmt.println(strings.to_kebab_case("HelloWorld"))
}

hello-world

Converts the input string s to all lowercase characters.

Allocates Using Provided Allocator

Inputs:
s: Input string to be converted. allocator: (default: context.allocator).

Returns:
res: The new string with all characters converted to lowercase err: An optional allocator error if one occured, nil otherwise

import "core:fmt"
import "core:strings"

to_lower_example :: proc() {
	fmt.println(strings.to_lower("TeST"))
}

test

Converts the input string s to "lowerCamelCase".

Allocates Using Provided Allocator

Inputs:
s: Input string to be converted. allocator: (default: context.allocator).

Returns:
res: The converted string err: An optional allocator error if one occured, nil otherwise

Converts the input string s to "UpperCamelCase" (PascalCase).

Allocates Using Provided Allocator

Inputs:
s: Input string to be converted. allocator: (default: context.allocator).

Returns:
res: The converted string err: An optional allocator error if one occured, nil otherwise

Initializes a string Reader and returns an io.Reader for the given string

Inputs:
r: A pointer to a Reader struct s: The input string to be read

Returns:
res: An io.Reader for the given string

Initializes a string Reader and returns an io.Reader_At for the given string

Inputs:
r: A pointer to a Reader struct s: The input string to be read

Returns:
res: An io.Reader_At for the given string

Converts a string to "SNAKE_CASE" with all runes uppercased

Allocates Using Provided Allocator

Inputs:
s: The input string to be converted allocator: (default: context.allocator).

Returns:
res: The converted string err: An optional allocator error if one occured, nil otherwise

import "core:fmt"
import "core:strings"

to_upper_snake_case_example :: proc() {
	fmt.println(strings.to_upper_snake_case("HelloWorld"))
}

HELLO_WORLD

Converts a string to "snake_case" with all runes lowercased

Allocates Using Provided Allocator

Inputs:
s: The input string to be converted allocator: (default: context.allocator).

Returns:
res: The converted string err: An optional allocator error if one occured, nil otherwise

import "core:fmt"
import "core:strings"

to_snake_case_example :: proc() {
	fmt.println(strings.to_snake_case("HelloWorld"))
	fmt.println(strings.to_snake_case("Hello World"))
}

hello_world
hello_world

Returns an io.Stream from a Builder

Inputs:
b: A pointer to the Builder

Returns:
res: the io.Stream

Casts the Builder byte buffer to a string and returns it

Inputs:
b: A Builder

Returns:
res: The contents of the Builder's buffer, as a string

Converts the input string s to all uppercase characters.

Allocates Using Provided Allocator

Inputs:
s: Input string to be converted. allocator: (default: context.allocator).

Returns:
res: The new string with all characters converted to uppercase err: An optional allocator error if one occured, nil otherwise

import "core:fmt"
import "core:strings"

to_upper_example :: proc() {
	fmt.println(strings.to_upper("Test"))
}

TEST

Converts the input string s to "UpperCamelCase" (PascalCase).

Allocates Using Provided Allocator

Inputs:
s: Input string to be converted. allocator: (default: context.allocator).

Returns:
res: The converted string err: An optional allocator error if one occured, nil otherwise

Converts a string to "KEBAB-CASE" with all runes uppercased

Allocates Using Provided Allocator

Inputs:
s: The input string to be converted allocator: (default: context.allocator).

Returns:
res: The converted string err: An optional allocator error if one occured, nil otherwise

import "core:fmt"
import "core:strings"

to_upper_kebab_case_example :: proc() {
	fmt.println(strings.to_upper_kebab_case("HelloWorld"))
}

HELLO-WORLD

Converts a string to "SNAKE_CASE" with all runes uppercased

Allocates Using Provided Allocator

Inputs:
s: The input string to be converted allocator: (default: context.allocator).

Returns:
res: The converted string err: An optional allocator error if one occured, nil otherwise

import "core:fmt"
import "core:strings"

to_upper_snake_case_example :: proc() {
	fmt.println(strings.to_upper_snake_case("HelloWorld"))
}

HELLO_WORLD

Converts invalid UTF-8 sequences in the input string s to the replacement string.

Allocates Using Provided Allocator

Inputs:
s: Input string that may contain invalid UTF-8 sequences. replacement: String to replace invalid UTF-8 sequences with. allocator: (default: context.allocator).

WARNING: Allocation does not occur when len(s) == 0

Returns:
res: A valid UTF-8 string with invalid sequences replaced by replacement. err: An optional allocator error if one occured, nil otherwise

Returns an io.Writer from a Builder

Inputs:
b: A pointer to the Builder

Returns:
res: The io.Writer

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

Inputs:
s: The input string cutset: The set of characters to be trimmed from both sides of the input string

Returns:
res: The trimmed string as a slice of the original

Trims the cutset string from the s string

Inputs:
s: The input string cutset: The set of characters to be trimmed from the left of the input string

Returns:
res: The trimmed string as a slice of the original

Trims null runes from the left, "\x00\x00testing\x00\x00" -> "testing\x00\x00"

Inputs:
s: The input string

Returns:
res: The trimmed string as a slice of the original

Trims the input string s from the left until the procedure p returns false

Inputs:
s: The input string p: A procedure that takes a rune and returns a boolean

Returns:
res: The trimmed string as a slice of the original

import "core:fmt"
import "core:strings"

trim_left_proc_example :: proc() {
	find :: proc(r: rune) -> bool {
		return r == 'x'
	}
	fmt.println(strings.trim_left_proc("xxxxxxtesting", find))
}

testing

Trims the input string s from the left until the procedure p with state returns false

Inputs:
s: The input string p: A procedure that takes a raw pointer and a rune and returns a boolean state: The raw pointer to be passed to the procedure p

Returns:
res: The trimmed string as a slice of the original

Trims until a valid non-space rune from the left, "\t\txyz\t\t" -> "xyz\t\t"

Inputs:
s: The input string

Returns:
res: The trimmed string as a slice of the original

Trims null runes from both sides, "\x00\x00testing\x00\x00" -> "testing"

Inputs:
s: The input string Returns: res: The trimmed string as a slice of the original

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

Inputs:
s: The input string prefix: The prefix string to be removed

Returns:
res: The trimmed string as a slice of original, or the input string if no prefix was found

import "core:fmt"
import "core:strings"

trim_prefix_example :: proc() {
	fmt.println(strings.trim_prefix("testing", "test"))
	fmt.println(strings.trim_prefix("testing", "abc"))
}

ing
testing

Trims the cutset string from the s string from the right

Inputs:
s: The input string cutset: The set of characters to be trimmed from the right of the input string

Returns:
res: The trimmed string as a slice of the original

Trims null runes from the right, "\x00\x00testing\x00\x00" -> "\x00\x00testing"

Inputs:
s: The input string

Returns:
res: The trimmed string as a slice of the original

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

Inputs:
s: The input string p: A procedure that takes a rune and returns a boolean

Returns:
res: The trimmed string as a slice of the original

import "core:fmt"
import "core:strings"

trim_right_proc_example :: proc() {
	find :: proc(r: rune) -> bool {
		return r != 't'
	}
	fmt.println(strings.trim_right_proc("testing", find))
}

test

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

Inputs:
s: The input string p: A procedure that takes a raw pointer and a rune and returns a boolean state: The raw pointer to be passed to the procedure p

Returns:
res: The trimmed string as a slice of the original, empty when no match

Trims from the right until a valid non-space rune, "\t\txyz\t\t" -> "\t\txyz"

Inputs:
s: The input string

Returns:
res: The trimmed string as a slice of the original

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

Inputs:
s: The input string

Returns:
res: The trimmed string as a slice of the original

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

Inputs:
s: The input string suffix: The suffix string to be removed

Returns:
res: The trimmed string as a slice of original, or the input string if no suffix was found

import "core:fmt"
import "core:strings"

trim_suffix_example :: proc() {
	fmt.println(strings.trim_suffix("todo.txt", ".txt"))
	fmt.println(strings.trim_suffix("todo.doc", ".txt"))
}

todo
todo.doc

Truncates a string str at the first occurrence of char/byte b

Inputs:
str: The input string b: The byte to truncate the string at

NOTE: Failure to find the byte results in returning the entire string.

Returns:
res: The truncated string

Truncates a string str at the first occurrence of rune r as a slice of the original, entire string if not found

Inputs:
str: The input string r: The rune to truncate the string at

Returns:
res: The truncated string

Converts a string str to a cstring

Inputs:
str: The input string

WARNING: This is unsafe because the original string may not contain a null-byte.

Returns:
res: The converted cstring

Appends a trailing null byte after the end of the current Builder byte buffer and then casts it to a cstring

NOTE: This procedure will not check if the backing buffer has enough space to include the extra null byte.

Inputs:
b: A pointer to builder

Returns:
res: A cstring of the Builder's buffer

Appends a byte to the Builder and returns the number of bytes appended

Inputs:
b: A pointer to the Builder x: The byte to be appended

Returns:
n: The number of bytes appended

NOTE: The backing dynamic array may be fixed in capacity or fail to resize, n states the number actually written.

import "core:fmt"
import "core:strings"

write_byte_example :: proc() {
	builder := strings.builder_make()
	strings.write_byte(&builder, 'a')        // 1
	strings.write_byte(&builder, 'b')        // 1
	fmt.println(strings.to_string(builder))  // -> ab
}

ab

Appends a slice of bytes to the Builder and returns the number of bytes appended

Inputs:
b: A pointer to the Builder x: The slice of bytes to be appended

import "core:fmt"
import "core:strings"

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

NOTE: The backing dynamic array may be fixed in capacity or fail to resize, n states the number actually written.

Returns:
n: The number of bytes appended

Appends a rune to the Builder and returns the number of bytes written

Inputs:
b: A pointer to the Builder r: The rune to be appended write_quote: Optional boolean flag to wrap in single-quotes (') (default is true)

Returns:
n: The number of bytes written

NOTE: The backing dynamic array may be fixed in capacity or fail to resize, n states the number actually written.

import "core:fmt"
import "core:strings"

write_encoded_rune_example :: proc() {
	builder := strings.builder_make()
	strings.write_encoded_rune(&builder, 'a', false) // 1
	strings.write_encoded_rune(&builder, '\"', true) // 3
	strings.write_encoded_rune(&builder, 'x', false) // 1
	fmt.println(strings.to_string(builder))
}

a'"'x

Appends an escaped rune to the Builder and returns the number of bytes written

Inputs:
b: A pointer to the Builder r: The rune to be appended quote: The quote character html_safe: Optional boolean flag to encode '<', '>', '&' as digits (default is false)

Usage '\a' will be written as such 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

NOTE: The backing dynamic array may be fixed in capacity or fail to resize, n states the number actually written.

Returns:
n: The number of bytes written

Writes a f16 value to the Builder and returns the number of characters written

Inputs:
b: A pointer to the Builder f: The f16 value to be appended fmt: The format byte always_signed: Optional boolean flag to always include the sign

NOTE: The backing dynamic array may be fixed in capacity or fail to resize, n states the number actually written.

Returns:
n: The number of characters written

Writes a f32 value to the Builder and returns the number of characters written

Inputs:
b: A pointer to the Builder f: The f32 value to be appended fmt: The format byte always_signed: Optional boolean flag to always include the sign

Returns:
n: The number of characters written

NOTE: The backing dynamic array may be fixed in capacity or fail to resize, n states the number actually written.

import "core:fmt"
import "core:strings"

write_f32_example :: proc() {
	builder := strings.builder_make()
	strings.write_f32(&builder, 3.14159, 'f') // 6
	strings.write_string(&builder, " - ")     // 3
	strings.write_f32(&builder, -0.123, 'e')  // 8
	fmt.println(strings.to_string(builder))   // -> 3.14159012 - -1.23000003e-01
}

3.14159012 - -1.23000003e-01

Writes a f64 value to the Builder and returns the number of characters written

Inputs:
b: A pointer to the Builder f: The f64 value to be appended fmt: The format byte always_signed: Optional boolean flag to always include the sign

NOTE: The backing dynamic array may be fixed in capacity or fail to resize, n states the number actually written.

Returns:
n: The number of characters written

Writes a f64 value to the Builder and returns the number of characters written

Inputs:
b: A pointer to the Builder f: The f64 value to be appended fmt: The format byte prec: The precision bit_size: The bit size always_signed: Optional boolean flag to always include the sign (default is false)

NOTE: The backing dynamic array may be fixed in capacity or fail to resize, n states the number actually written.

Returns:
n: The number of characters written

Writes a i64 value to the Builder and returns the number of characters written

Inputs:
b: A pointer to the Builder i: The i64 value to be appended base: The optional base for the numeric representation

NOTE: The backing dynamic array may be fixed in capacity or fail to resize, n states the number actually written.

Returns:
n: The number of characters written

Writes a int value to the Builder and returns the number of characters written

Inputs:
b: A pointer to the Builder i: The int value to be appended base: The optional base for the numeric representation

NOTE: The backing dynamic array may be fixed in capacity or fail to resize, n states the number actually written.

Returns:
n: The number of characters written

Appends a quoted rune to the Builder and returns the number of bytes written

Inputs:
b: A pointer to the Builder r: The rune to be appended

Returns:
n: The number of bytes written

NOTE: The backing dynamic array may be fixed in capacity or fail to resize, n states the number actually written.

import "core:fmt"
import "core:strings"

write_quoted_rune_example :: proc() {
	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
}

abc'ä'abc

Inputs:
b: A pointer to the Builder str: The string to be quoted and appended quote: The optional quote character (default is double quotes)

Returns:
n: The number of bytes written

NOTE: The backing dynamic array may be fixed in capacity or fail to resize, n states the number actually written.

import "core:fmt"
import "core:strings"

write_quoted_string_example :: proc() {
	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 to the Builder and returns the number of bytes written and an io.Error

Inputs:
b: A pointer to the Builder r: The rune to be appended

Returns:
res: The number of bytes written err: An io.Error if one occured, nil otherwise

NOTE: The backing dynamic array may be fixed in capacity or fail to resize, n states the number actually written.

import "core:fmt"
import "core:strings"

write_rune_example :: proc() {
	builder := strings.builder_make()
	strings.write_rune(&builder, 'ä')     // 2 None
	strings.write_rune(&builder, 'b')       // 1 None
	fmt.println(strings.to_string(builder)) // -> äb
}

äb

Appends a string to the Builder and returns the number of bytes written

Inputs:
b: A pointer to the Builder s: The string to be appended

Returns:
n: The number of bytes written

NOTE: The backing dynamic array may be fixed in capacity or fail to resize, n states the number actually written.

import "core:fmt"
import "core:strings"

write_string_example :: proc() {
	builder := strings.builder_make()
	strings.write_string(&builder, "a")     // 1
	strings.write_string(&builder, "bc")    // 2
	fmt.println(strings.to_string(builder)) // -> abc
}

abc

Writes a u64 value to the Builder and returns the number of characters written

Inputs:
b: A pointer to the Builder i: The u64 value to be appended base: The optional base for the numeric representation

NOTE: The backing dynamic array may be fixed in capacity or fail to resize, n states the number actually written.

Returns:
n: The number of characters written

Writes a uint value to the Builder and returns the number of characters written

Inputs:
b: A pointer to the Builder i: The uint value to be appended base: The optional base for the numeric representation

NOTE: The backing dynamic array may be fixed in capacity or fail to resize, n states the number actually written.

Returns:
n: The number of characters written

Overload simple builder_init_* with or without len / ap parameters

Produces a String Builder

Allocates Using Provided Allocator

import "core:fmt"
import "core:strings"
builder_make_example :: proc() {
	sb := strings.builder_make()
	strings.write_byte(&sb, 'a')
	strings.write_string(&sb, " slice of ")
	strings.write_f64(&sb, 3.14,'g',true) // See `fmt.fmt_float` byte codes
	strings.write_string(&sb, " is ")
	strings.write_int(&sb, 180)
	strings.write_rune(&sb,'°')
	the_string :=strings.to_string(sb)
	fmt.println(the_string)
}

a slice of +3.14 is 180°

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