$string_utils

Work with strings.

16 natives. Read-only natives only look things up; the rest change something. Parameter types use the language's names (Types).

alloc_temp

$string_utils.alloc_temp(size_bytes: int, partition: int) -> string

Allocate a temporary string storage buffer of provided size and return result, or NULL & warn if cannot.

Parameter	Type	Meaning
size_bytes	int	The number of bytes for the string buffer.
partition	int	The string partition to use (or default 0).

Returns string: A temporary empty string with a buffer sized as requested, or NULL

append_temp

$string_utils.append_temp(buffer: string, string: string, buffer_size_bytes: int) -> string

Append string to buffer -in place- up to buffer_size_bytes-1.

Parameter	Type	Meaning
buffer	string	The buffer with some string data maybe.
string	string	The string to append.
buffer_size_bytes	int	The size of the string buffer.

Returns string: Buffer after appending as much of string as fits

compare

read-only

$string_utils.compare(string1: string, string2: string) -> int

Compares two strings alphanumerically

Parameter	Type	Meaning
string1	string	The first string.
string2	string	The second string.

Returns int: 0 if the strings are equal, <0 if the first string is less than the second, and >0 if the first string is greater than the second.

concat_temp

read-only

$string_utils.concat_temp(string1: string, string2: string, partition: int) -> string

Concatenates two strings together in a temporary string storage allocated result.

Parameter	Type	Meaning
string1	string	The first string to concatenate.
string2	string	The second string to concatenate.
partition	int	The string partition to use (or default 0).

Returns string: A temporary string which is the concatenation of the two arguments

contains

read-only

$string_utils.contains(string: string, substring: string) -> bool

Find if string contains substring

Parameter	Type	Meaning
string	string	The string to search in.
substring	string	The substring to search.

Returns bool: True if string contains substring

format_hex_string

read-only

$string_utils.format_hex_string(value: int) -> string

Returns the string representation of a given integer in base 16.

Parameter	Type	Meaning
value	int	The integer value.

Returns string: A temporary string which is the representation of the given integer formatted in hexidecimal (base 16).

format_string_fill

read-only

$string_utils.format_string_fill(length: int, charval: string) -> string

Returns a string of the given length filled with the given character value.

Parameter	Type	Meaning
length	int	The length of the resulting string.
charval	string	The string value to use, assumed to be a single character.

Returns string: A temporary string of the given size filled with the given character value.

format_string_length

$string_utils.format_string_length(string: string, args: list) -> int

Gets the length of a formated string, not including the null terminator.

Parameter	Type	Meaning
string	string	The format string.
args	list	The format string args.

Returns int: Length of the string, not including the null terminator.

format_string_temp

read-only

$string_utils.format_string_temp(string: string, args: list, partition: int) -> string

Returns a formatted string a temporary string storage allocated result.

Parameter	Type	Meaning
string	string	The format string.
args	list	The format string args.
partition	int	The string partition to use (or default 0).

Returns string: The result string.

get_character

read-only

$string_utils.get_character(string: string, index: int) -> int

Gets the index'th character in a string or zero if none.

Parameter	Type	Meaning
string	string	The string.
index	int	The index.

Returns int: Character code or zero if not found.

length

read-only

$string_utils.length(string: string) -> int

Gets the length of a string, not including the null terminator.

Parameter	Type	Meaning
string	string	The string.

Returns int: Length of the string, not including the null terminator.

length_utf8

read-only

$string_utils.length_utf8(string: string) -> int

Gets the number of utf-8 characters in a string.

Parameter	Type	Meaning
string	string	The string.

Returns int: Number of utf-8 characters

set_temp

$string_utils.set_temp(buffer: string, string: string, buffer_size_bytes: int) -> string

Sets the contents of a string buffer to the provided string, up to buffer_size_bytes-1.

Parameter	Type	Meaning
buffer	string	The buffer to set into.
string	string	The string to set.
buffer_size_bytes	int	The size of the string buffer.

Returns string: The string buffer passed in with contents set to string1.

substr_temp

read-only

$string_utils.substr_temp(string: string, start: int, length: int) -> string

Returns the substring of a given string in a temporary string storage allocated result.

Parameter	Type	Meaning
string	string	The input string to perform substring on.
start	int	The starting character position (zero-based index).
length	int	The number of characters to copy from the input string (clamped to the end of the input).

Returns string: A temporary string which is the substring of the input

trim_start

$string_utils.trim_start(string: string, trim: int) -> string

Does the equivalent if 'string + x' in C, effectively trimming x characters from the start of the string, but doesn't alter the original string. The original string must continue to live as long as the returned string is in use.

Parameter	Type	Meaning
string	string	The string to trim.
trim	int	The number of characters to trim.

Returns string: The trimmed string, or NULL if invalid parameters are passed.

trim_start_utf8

$string_utils.trim_start_utf8(string: string, trim: int) -> string

Trimming x utf-8 characters from the start of the string, but doesn't alter the original string. The original string must continue to live as long as the returned string is in use.

Parameter	Type	Meaning
string	string	The string to trim.
trim	int	The number of utf-8 characters to trim.

Returns string: The trimmed string, or NULL if invalid parameters are passed.