This file contains a basic C string handling library. More...

#include "defines.h"
#include "math/math_types.h"

Data Structures
struct	kstring
	A kstring is a managed string for higher-level logic to use. It is safer and, in some cases quicker than a typical cstring because it maintains length/allocation information and doesn't have to use strlen on most of its internal operations. More...

Typedefs
typedef struct kstring	kstring
	A kstring is a managed string for higher-level logic to use. It is safer and, in some cases quicker than a typical cstring because it maintains length/allocation information and doesn't have to use strlen on most of its internal operations. More...

Functions
KAPI u64	string_length (const char *str)
	Gets the length of the given string. More...

KAPI u32	string_utf8_length (const char *str)
	Gets the length of a string in UTF-8 (potentially multibyte) characters. More...

KAPI b8	bytes_to_codepoint (const char bytes, u32 offset, i32 out_codepoint, u8 *out_advance)
	Obtains bytes needed from the byte array to form a UTF-8 codepoint, also providing how many bytes the current character is. More...

KAPI char *	string_duplicate (const char *str)
	Duplicates the provided string. Note that this allocates new memory, which should be freed by the caller. More...

KAPI void	string_free (char *str)
	Frees the memory of the given string. More...

KAPI b8	strings_equal (const char str0, const char str1)
	Case-sensitive string comparison. More...

KAPI b8	strings_equali (const char str0, const char str1)
	Case-insensitive string comparison. More...

KAPI b8	strings_nequal (const char str0, const char str1, u64 length)
	Case-sensitive string comparison for a number of characters. More...

KAPI b8	strings_nequali (const char str0, const char str1, u64 length)
	Case-insensitive string comparison for a number of characters. More...

KAPI i32	string_format (char dest, const char format,...)
	Performs string formatting to dest given format string and parameters. More...

KAPI i32	string_format_v (char dest, const char format, void *va_list)
	Performs variadic string formatting to dest given format string and va_list. More...

KAPI char *	string_empty (char *str)
	Empties the provided string by setting the first character to 0. More...

KAPI char *	string_copy (char dest, const char source)
	Copies the string in source to dest. Does not perform any allocations. More...

KAPI char *	string_ncopy (char dest, const char source, i64 length)
	Copies the string in source to dest up to the given length. Does not perform any allocations. More...

KAPI char *	string_trim (char *str)
	Performs an in-place trim of the provided string. This removes all whitespace from both ends of the string. More...

KAPI void	string_mid (char dest, const char source, i32 start, i32 length)
	Gets a substring of the source string between start and length or to the end of the string. If length is negative, goes to the end of the string. More...

KAPI i32	string_index_of (const char *str, char c)
	Returns the index of the first occurance of c in str; otherwise -1. More...

KAPI i32	string_index_of_str (const char str_0, const char str_1)
	Returns the index of the first occurance of str_1 in str_0; otherwise -1. More...

KAPI b8	string_to_transform (const char str, transform out_transform)
	Attempts to parse a transform from the provided string. If the string contains 10 elements, rotation is parsed as quaternion. If it contains 9 elements, rotation is parsed as euler angles and is converted to quaternion. Anything else is invalid. More...

KAPI b8	string_to_mat4 (const char str, mat4 out_mat)
	Attempts to parse a 4x4 matrix from the provided string. More...

KAPI b8	string_to_vec4 (const char str, vec4 out_vector)
	Attempts to parse a vector from the provided string. More...

KAPI b8	string_to_vec3 (const char str, vec3 out_vector)
	Attempts to parse a vector from the provided string. More...

KAPI b8	string_to_vec2 (const char str, vec2 out_vector)
	Attempts to parse a vector from the provided string. More...

KAPI b8	string_to_f32 (const char str, f32 f)
	Attempts to parse a 32-bit floating-point number from the provided string. More...

KAPI b8	string_to_f64 (const char str, f64 f)
	Attempts to parse a 64-bit floating-point number from the provided string. More...

KAPI b8	string_to_i8 (const char str, i8 i)
	Attempts to parse an 8-bit signed integer from the provided string. More...

KAPI b8	string_to_i16 (const char str, i16 i)
	Attempts to parse a 16-bit signed integer from the provided string. More...

KAPI b8	string_to_i32 (const char str, i32 i)
	Attempts to parse a 32-bit signed integer from the provided string. More...

KAPI b8	string_to_i64 (const char str, i64 i)
	Attempts to parse a 64-bit signed integer from the provided string. More...

KAPI b8	string_to_u8 (const char str, u8 u)
	Attempts to parse an 8-bit unsigned integer from the provided string. More...

KAPI b8	string_to_u16 (const char str, u16 u)
	Attempts to parse a 16-bit unsigned integer from the provided string. More...

KAPI b8	string_to_u32 (const char str, u32 u)
	Attempts to parse a 32-bit unsigned integer from the provided string. More...

KAPI b8	string_to_u64 (const char str, u64 u)
	Attempts to parse a 64-bit unsigned integer from the provided string. More...

KAPI b8	string_to_bool (const char str, b8 b)
	Attempts to parse a boolean from the provided string. "true" or "1" are considered true; anything else is false. More...

KAPI u32	string_split (const char str, char delimiter, char **str_darray, b8 trim_entries, b8 include_empty)
	Splits the given string by the delimiter provided and stores in the provided darray. Optionally trims each entry. NOTE: A string allocation occurs for each entry, and must be freed by the caller. More...

KAPI void	string_cleanup_split_array (char **str_darray)
	Cleans up string allocations in str_darray, but does not free the darray itself. More...

KAPI void	string_append_string (char dest, const char source, const char *append)

KAPI void	string_append_int (char dest, const char source, i64 i)
	Appends the supplied integer to source and outputs to dest. More...

KAPI void	string_append_float (char dest, const char source, f32 f)
	Appends the supplied float to source and outputs to dest. More...

KAPI void	string_append_bool (char dest, const char source, b8 b)
	Appends the supplied boolean (as either "true" or "false") to source and outputs to dest. More...

KAPI void	string_append_char (char dest, const char source, char c)
	Appends the supplied character to source and outputs to dest. More...

KAPI void	string_directory_from_path (char dest, const char path)
	Extracts the directory from a full file path. More...

KAPI void	string_filename_from_path (char dest, const char path)
	Extracts the filename (including file extension) from a full file path. More...

KAPI void	string_filename_no_extension_from_path (char dest, const char path)
	Extracts the filename (excluding file extension) from a full file path. More...

KAPI void	kstring_create (kstring *out_string)

KAPI void	kstring_from_cstring (const char source, kstring out_string)

KAPI void	kstring_destroy (kstring *string)

KAPI u32	kstring_length (const kstring *string)

KAPI u32	kstring_utf8_length (const kstring *string)

KAPI void	kstring_append_str (kstring string, const char s)

KAPI void	kstring_append_kstring (kstring string, const kstring other)

Detailed Description

This file contains a basic C string handling library.

Author: Travis Vroman (travi.nosp@m.s@ko.nosp@m.hieng.nosp@m.ine..nosp@m.com)

Version: 1.0

Date: 2022-01-10

Copyright: Kohi Game Engine is Copyright (c) Travis Vroman 2021-2022

Typedef Documentation

◆ kstring

typedef struct kstring kstring

A kstring is a managed string for higher-level logic to use. It is safer and, in some cases quicker than a typical cstring because it maintains length/allocation information and doesn't have to use strlen on most of its internal operations.

Function Documentation

◆ bytes_to_codepoint()

KAPI b8 bytes_to_codepoint	(	const char *	bytes,
		u32	offset,
		i32 *	out_codepoint,
		u8 *	out_advance
	)

Obtains bytes needed from the byte array to form a UTF-8 codepoint, also providing how many bytes the current character is.

Parameters

bytes	The byte array to choose from.
offset	The offset in bytes to start from.
out_codepoint	A pointer to hold the UTF-8 codepoint.
out_advance	A pointer to hold the advance, or how many bytes the codepoint takes.

Returns: True on success; otherwise false for invalid/unsupported UTF-8.

◆ kstring_append_kstring()

KAPI void kstring_append_kstring	(	kstring *	string,
		const kstring *	other
	)

◆ kstring_append_str()

KAPI void kstring_append_str	(	kstring *	string,
		const char *	s
	)

◆ kstring_create()

KAPI void kstring_create ( kstring * out_string )

◆ kstring_destroy()

KAPI void kstring_destroy ( kstring * string )

◆ kstring_from_cstring()

KAPI void kstring_from_cstring	(	const char *	source,
		kstring *	out_string
	)

◆ kstring_length()

KAPI u32 kstring_length ( const kstring * string )

◆ kstring_utf8_length()

KAPI u32 kstring_utf8_length ( const kstring * string )

◆ string_append_bool()

KAPI void string_append_bool	(	char *	dest,
		const char *	source,
		b8	b
	)

Appends the supplied boolean (as either "true" or "false") to source and outputs to dest.

Parameters

dest	The destination for the string.
source	The string to be appended to.
b	The boolean to be appended.

◆ string_append_char()

KAPI void string_append_char	(	char *	dest,
		const char *	source,
		char	c
	)

Appends the supplied character to source and outputs to dest.

Parameters

dest	The destination for the string.
source	The string to be appended to.
c	The character to be appended.

◆ string_append_float()

KAPI void string_append_float	(	char *	dest,
		const char *	source,
		f32	f
	)

Appends the supplied float to source and outputs to dest.

Parameters

dest	The destination for the string.
source	The string to be appended to.
f	The float to be appended.

◆ string_append_int()

KAPI void string_append_int	(	char *	dest,
		const char *	source,
		i64	i
	)

Appends the supplied integer to source and outputs to dest.

Parameters

dest	The destination for the string.
source	The string to be appended to.
i	The integer to be appended.

◆ string_append_string()

KAPI void string_append_string	(	char *	dest,
		const char *	source,
		const char *	append
	)

Appends append to source and returns a new string.

Parameters

dest	The destination string.
source	The string to be appended to.
append	The string to append to source.

Returns: A new string containing the concatenation of the two strings.

◆ string_cleanup_split_array()

KAPI void string_cleanup_split_array ( char ** str_darray )

Cleans up string allocations in str_darray, but does not free the darray itself.

Parameters

str_darray The darray to be cleaned up.

◆ string_copy()

KAPI char* string_copy	(	char *	dest,
		const char *	source
	)

Copies the string in source to dest. Does not perform any allocations.

Parameters

dest	The destination string.
source	The source string.

Returns: A pointer to the destination string.

◆ string_directory_from_path()

KAPI void string_directory_from_path	(	char *	dest,
		const char *	path
	)

Extracts the directory from a full file path.

Parameters

dest	The destination for the path.
path	The full path to extract from.

◆ string_duplicate()

KAPI char* string_duplicate ( const char * str )

Duplicates the provided string. Note that this allocates new memory, which should be freed by the caller.

Parameters

str	The string to be duplicated.

Returns: A pointer to a newly-created character array (string).

◆ string_empty()

KAPI char* string_empty ( char * str )

Empties the provided string by setting the first character to 0.

Parameters

str	The string to be emptied.

Returns: A pointer to str.

◆ string_filename_from_path()

KAPI void string_filename_from_path	(	char *	dest,
		const char *	path
	)

Extracts the filename (including file extension) from a full file path.

Parameters

dest	The destination for the filename.
path	The full path to extract from.

◆ string_filename_no_extension_from_path()

KAPI void string_filename_no_extension_from_path	(	char *	dest,
		const char *	path
	)

Extracts the filename (excluding file extension) from a full file path.

Parameters

dest	The destination for the filename.
path	The full path to extract from.

◆ string_format()

KAPI i32 string_format	(	char *	dest,
		const char *	format,
			...
	)

Performs string formatting to dest given format string and parameters.

Parameters

dest	The destination for the formatted string.
format	The format string to use for the operation
...	The format arguments.

Returns: The length of the newly-formatted string.

◆ string_format_v()

KAPI i32 string_format_v	(	char *	dest,
		const char *	format,
		void *	va_list
	)

Performs variadic string formatting to dest given format string and va_list.

Parameters

dest	The destination for the formatted string.
format	The string to be formatted.
va_list	The variadic argument list.

Returns: The size of the data written.

◆ string_free()

KAPI void string_free ( char * str )

Frees the memory of the given string.

Parameters

str	The string to be freed.

◆ string_index_of()

KAPI i32 string_index_of	(	const char *	str,
		char	c
	)

Returns the index of the first occurance of c in str; otherwise -1.

Parameters

str	The string to be scanned.
c	The character to search for.

Returns: The index of the first occurance of c; otherwise -1 if not found.

◆ string_index_of_str()

KAPI i32 string_index_of_str	(	const char *	str_0,
		const char *	str_1
	)

Returns the index of the first occurance of str_1 in str_0; otherwise -1.

Parameters

str_0	The string to be scanned.
str_1	The substring to search for.

Returns: The index of the first occurance of str_1; otherwise -1 if not found.

◆ string_length()

KAPI u64 string_length ( const char * str )

Gets the length of the given string.

Parameters

str	The string whose length to obtain.

Returns: The length of the string.

◆ string_mid()

KAPI void string_mid	(	char *	dest,
		const char *	source,
		i32	start,
		i32	length
	)

Gets a substring of the source string between start and length or to the end of the string. If length is negative, goes to the end of the string.

Done by placing zeroes in the string at relevant points.

Parameters

str	The string to be trimmed.

◆ string_ncopy()

KAPI char* string_ncopy	(	char *	dest,
		const char *	source,
		i64	length
	)

Copies the string in source to dest up to the given length. Does not perform any allocations.

Parameters

dest	The destination string.
source	The source string.
length	The maximum length to be copied.

Returns: A pointer to the destination string.

◆ string_split()

KAPI u32 string_split	(	const char *	str,
		char	delimiter,
		char ***	str_darray,
		b8	trim_entries,
		b8	include_empty
	)

Splits the given string by the delimiter provided and stores in the provided darray. Optionally trims each entry. NOTE: A string allocation occurs for each entry, and must be freed by the caller.

Parameters

str	The string to be split.
delimiter	The character to split by.
str_darray	A pointer to a darray of char arrays to hold the entries. NOTE: must be a darray.
trim_entries	Trims each entry if true.
include_empty	Indicates if empty entries should be included.

Returns: The number of entries yielded by the split operation.

◆ string_to_bool()

KAPI b8 string_to_bool	(	const char *	str,
		b8 *	b
	)

Attempts to parse a boolean from the provided string. "true" or "1" are considered true; anything else is false.

Parameters

str	The string to parse from. "true" or "1" are considered true; anything else is false.
b	A pointer to the boolean to write to.

Returns: True if parsed successfully; otherwise false.

◆ string_to_f32()

KAPI b8 string_to_f32	(	const char *	str,
		f32 *	f
	)

Attempts to parse a 32-bit floating-point number from the provided string.

Parameters

str	The string to parse from. Should not be postfixed with 'f'.
f	A pointer to the float to write to.

Returns: True if parsed successfully; otherwise false.

◆ string_to_f64()

KAPI b8 string_to_f64	(	const char *	str,
		f64 *	f
	)

Attempts to parse a 64-bit floating-point number from the provided string.

Parameters

str	The string to parse from.
f	A pointer to the float to write to.

Returns: True if parsed successfully; otherwise false.

◆ string_to_i16()

KAPI b8 string_to_i16	(	const char *	str,
		i16 *	i
	)

Attempts to parse a 16-bit signed integer from the provided string.

Parameters

str	The string to parse from.
i	A pointer to the int to write to.

Returns: True if parsed successfully; otherwise false.

◆ string_to_i32()

KAPI b8 string_to_i32	(	const char *	str,
		i32 *	i
	)

Attempts to parse a 32-bit signed integer from the provided string.

Parameters

str	The string to parse from.
i	A pointer to the int to write to.

Returns: True if parsed successfully; otherwise false.

◆ string_to_i64()

KAPI b8 string_to_i64	(	const char *	str,
		i64 *	i
	)

Attempts to parse a 64-bit signed integer from the provided string.

Parameters

str	The string to parse from.
i	A pointer to the int to write to.

Returns: True if parsed successfully; otherwise false.

◆ string_to_i8()

KAPI b8 string_to_i8	(	const char *	str,
		i8 *	i
	)

Attempts to parse an 8-bit signed integer from the provided string.

Parameters

str	The string to parse from.
i	A pointer to the int to write to.

Returns: True if parsed successfully; otherwise false.

◆ string_to_mat4()

KAPI b8 string_to_mat4	(	const char *	str,
		mat4 *	out_mat
	)

Attempts to parse a 4x4 matrix from the provided string.

Parameters

str	The string to parse from. Should be space delimited. (i.e "1.0 1.0 ... 1.0")
out_mat	A pointer to the matrix to write to.

Returns: True if parsed successfully; otherwise false.

◆ string_to_transform()

KAPI b8 string_to_transform	(	const char *	str,
		transform *	out_transform
	)

Attempts to parse a transform from the provided string. If the string contains 10 elements, rotation is parsed as quaternion. If it contains 9 elements, rotation is parsed as euler angles and is converted to quaternion. Anything else is invalid.

Parameters

str	The string to parse from.
out_transform	A pointer to the transform to write to.

Returns: True if parsed successfully, otherwise false.

◆ string_to_u16()

KAPI b8 string_to_u16	(	const char *	str,
		u16 *	u
	)

Attempts to parse a 16-bit unsigned integer from the provided string.

Parameters

str	The string to parse from.
u	A pointer to the int to write to.

Returns: True if parsed successfully; otherwise false.

◆ string_to_u32()

KAPI b8 string_to_u32	(	const char *	str,
		u32 *	u
	)

Attempts to parse a 32-bit unsigned integer from the provided string.

Parameters

str	The string to parse from.
u	A pointer to the int to write to.

Returns: True if parsed successfully; otherwise false.

◆ string_to_u64()

KAPI b8 string_to_u64	(	const char *	str,
		u64 *	u
	)

Attempts to parse a 64-bit unsigned integer from the provided string.

Parameters

str	The string to parse from.
u	A pointer to the int to write to.

Returns: True if parsed successfully; otherwise false.

◆ string_to_u8()

KAPI b8 string_to_u8	(	const char *	str,
		u8 *	u
	)

Attempts to parse an 8-bit unsigned integer from the provided string.

Parameters

str	The string to parse from.
u	A pointer to the int to write to.

Returns: True if parsed successfully; otherwise false.

◆ string_to_vec2()

KAPI b8 string_to_vec2	(	const char *	str,
		vec2 *	out_vector
	)

Attempts to parse a vector from the provided string.

Parameters

str	The string to parse from. Should be space-delimited. (i.e. "1.0 2.0")
out_vector	A pointer to the vector to write to.

Returns: True if parsed successfully; otherwise false.

◆ string_to_vec3()

KAPI b8 string_to_vec3	(	const char *	str,
		vec3 *	out_vector
	)

Attempts to parse a vector from the provided string.

Parameters

str	The string to parse from. Should be space-delimited. (i.e. "1.0 2.0 3.0")
out_vector	A pointer to the vector to write to.

Returns: True if parsed successfully; otherwise false.

◆ string_to_vec4()

KAPI b8 string_to_vec4	(	const char *	str,
		vec4 *	out_vector
	)

Attempts to parse a vector from the provided string.

Parameters

str	The string to parse from. Should be space-delimited. (i.e. "1.0 2.0 3.0 4.0")
out_vector	A pointer to the vector to write to.

Returns: True if parsed successfully; otherwise false.

◆ string_trim()

KAPI char* string_trim ( char * str )

Performs an in-place trim of the provided string. This removes all whitespace from both ends of the string.

Done by placing zeroes in the string at relevant points.

Parameters

str	The string to be trimmed.

Returns: A pointer to the trimmed string.

◆ string_utf8_length()

KAPI u32 string_utf8_length ( const char * str )

Gets the length of a string in UTF-8 (potentially multibyte) characters.

Parameters

str	The string to examine.

Returns: The UTF-8 length of the string.

◆ strings_equal()

KAPI b8 strings_equal	(	const char *	str0,
		const char *	str1
	)

Case-sensitive string comparison.

Parameters

str0	The first string to be compared.
str1	The second string to be compared.

Returns: True if the same, otherwise false.

◆ strings_equali()

KAPI b8 strings_equali	(	const char *	str0,
		const char *	str1
	)

Case-insensitive string comparison.

Parameters

str0	The first string to be compared.
str1	The second string to be compared.

Returns: True if the same, otherwise false.

◆ strings_nequal()

KAPI b8 strings_nequal	(	const char *	str0,
		const char *	str1,
		u64	length
	)

Case-sensitive string comparison for a number of characters.

Parameters

str0	The first string to be compared.
str1	The second string to be compared.
length	The maximum number of characters to be compared.

Returns: True if the same, otherwise false.

◆ strings_nequali()

KAPI b8 strings_nequali	(	const char *	str0,
		const char *	str1,
		u64	length
	)

Case-insensitive string comparison for a number of characters.

Parameters

str0	The first string to be compared.
str1	The second string to be compared.
length	The maximum number of characters to be compared.

Returns: True if the same, otherwise false.

Data Structures

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ kstring

Function Documentation

◆ bytes_to_codepoint()

◆ kstring_append_kstring()

◆ kstring_append_str()

◆ kstring_create()

◆ kstring_destroy()

◆ kstring_from_cstring()

◆ kstring_length()

◆ kstring_utf8_length()

◆ string_append_bool()

◆ string_append_char()

◆ string_append_float()

◆ string_append_int()

◆ string_append_string()

◆ string_cleanup_split_array()

◆ string_copy()

◆ string_directory_from_path()

◆ string_duplicate()

◆ string_empty()

◆ string_filename_from_path()

◆ string_filename_no_extension_from_path()

◆ string_format()

◆ string_format_v()

◆ string_free()

◆ string_index_of()

◆ string_index_of_str()

◆ string_length()

◆ string_mid()

◆ string_ncopy()

◆ string_split()

◆ string_to_bool()

◆ string_to_f32()

◆ string_to_f64()

◆ string_to_i16()

◆ string_to_i32()

◆ string_to_i64()

◆ string_to_i8()

◆ string_to_mat4()

◆ string_to_transform()

◆ string_to_u16()

◆ string_to_u32()

◆ string_to_u64()

◆ string_to_u8()

◆ string_to_vec2()

◆ string_to_vec3()

◆ string_to_vec4()

◆ string_trim()

◆ string_utf8_length()

◆ strings_equal()

◆ strings_equali()

◆ strings_nequal()

◆ strings_nequali()