strings

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

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

Internal function to lookup whether the text string exists in the map, returns the entry Sets and allocates the entry if it wasn't set yet

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 looked up or interned
• loc: The caller location for debugging purposes (default: #caller_location)

Returns:

• new_entry: The interned cstring
• err: An allocator error if one occured, nil otherwise

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

Example:

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"
}

Output:

a
ab

Alias to builder_from_bytes

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

Replaces n instances of old in the string in a Builder b with the new string

Allocates Using The Allocator On The Builder

Inputs:

• b: The input Builder
• 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)

Returns:

• replaced: The number of replacements
• err: if any allocation errors occurred

Replaces all instances of old in the string in a Builder b with the new string

Allocates Using The Allocator On The Builder

Inputs:

• b: The input Builder
• old: The substring to be replaced
• new: The replacement string

Returns:

• replaced: The number of replacements
• err: if any allocation errors occurred

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

Alias for centre_justify

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)
• loc: The caller location for debugging purposes (default: #caller_location)

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 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

Returns the common prefix between strings a and b

Inputs:

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

Returns:

• n: The string prefix common between strings a and b

Example:

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

common_prefix_example :: proc() {
	fmt.println(strings.common_prefix("testing", "test"))
	fmt.println(strings.common_prefix("testing", "te"))
	fmt.println(strings.common_prefix("telephone", "te"))
}

Output:

test
te
te

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

Example:

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

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

Output:

abc

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

Example:

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"))
}

Output:

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

Example:

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"))
}

Output:

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

Example:

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", " "))
}

Output:

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

Example:

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"
}

Output:

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)
• loc: The caller location for debugging purposes (default: #caller_location)

Returns:

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

Example:

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"
}

Output:

some
me
example

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)

Example:

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"))
}

Output:

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)
• loc: The caller location for debugging purposes (default: #caller_location)

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

Example:

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

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

Output:

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)
• loc: The caller location for debugging purposes (default: #caller_location)

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)
• loc: The caller location for debugging purposes (default: #caller_location)

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

Example:

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"))
}

Output:

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

Example:

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"))
}

Output:

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.

Example:

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"))
}

Output:

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.

Example:

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"))
}

Output:

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.

Example:

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", 'ä'))
}

Output:

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

Example:

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))
}

Output:

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.

Example:

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'))
}

Output:

-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
• loc: The caller location for debugging purposes (default: #caller_location)

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)
• loc: The caller location for debugging purposes (default: #caller_location)

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

Example:

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[:], "..."))
}

Output:

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

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.

Example:

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"))
}

Output:

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

Example:

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"))
}

Output:

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.

Example:

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", 'ä'))
}

Output:

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)
• loc: The caller location for debugging purposes (default: #caller_location)

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)
• loc: The caller location for debugging purposes (default: #caller_location)

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

Example:

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 == "")
}

Output:

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

Example:

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"))
}

Output:

4
2
2
0

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)
• loc: The caller location for debugging purposes (default: #caller_location)

Returns:

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

Example:

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))
}

Output:

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)
• loc: The caller location for debugging purposes (default: #caller_location)

Returns:

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

Example:

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"))
}

Output:

 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)
• loc: The caller location for debugging purposes (default: #caller_location)

Returns:

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

WARNING: Panics if count < 0

Example:

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

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

Output:

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)
• loc: The caller location for debugging purposes (default: #caller_location)

Returns:

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

Example:

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))
}

Output:

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)
• loc: The caller location for debugging purposes (default: #caller_location)

Returns:

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

Example:

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"))
}

Output:

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)
• loc: The caller location for debugging purposes (default: #caller_location)

Returns:

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

Example:

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

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

Output:

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)
• loc: The caller location for debugging purposes (default: #caller_location)

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

Example:

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
}

Output:

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)
• loc: The caller location for debugging purposes (default: #caller_location)

Returns:

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

Example:

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

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

Output:

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).
• loc: The caller location for debugging purposes (default: #caller_location)

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.

Example:

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

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

Output:

["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).
• loc: The caller location for debugging purposes (default: #caller_location)

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.

Example:

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)
}

Output:

["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

Example:

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)
	}
}

Output:

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)
• loc: The caller location for debugging purposes (default: #caller_location)

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.

Example:

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)
}

Output:

["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

Example:

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
	}
}

Output:

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

Example:

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)
	}
}

Output:

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)
• loc: The caller location for debugging purposes (default: #caller_location)

Returns:

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

Example:

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

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

Output:

["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)
• loc: The caller location for debugging purposes (default: #caller_location)

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.

Example:

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)
}

Output:

["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

Example:

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
	}
}

Output:

a
b
c
d
e