§4.3.1: char_is_slash
fstr_bool char_is_slash(
char c
)
Description
This call returns non-zero if c is \ or /.
§4.3.2: char_to_upper
char char_to_upper(
char c
)
Description
If c is a lowercase letter this call returns the uppercase equivalent, otherwise it returns c.
§4.3.3: char_to_lower
char char_to_lower(
char c
)
Description
If c is an uppercase letter this call returns the lowercase equivalent, otherwise it returns c.
§4.3.4: char_is_whitespace
fstr_bool char_is_whitespace(
char c
)
Description
This call returns non-zero if c is whitespace.
§4.3.5: char_is_alpha_numeric
fstr_bool char_is_alpha_numeric(
char c
)
Description
This call returns non-zero if c is any alphanumeric character including underscore.
§4.3.6: char_is_alpha_numeric_true
fstr_bool char_is_alpha_numeric_true(
char c
)
Description
This call returns non-zero if c is any alphanumeric character no including underscore.
§4.3.7: char_is_alpha
fstr_bool char_is_alpha(
char c
)
Description
This call returns non-zero if c is any alphabetic character including underscore.
§4.3.8: char_is_alpha_true
fstr_bool char_is_alpha_true(
char c
)
Description
This call returns non-zero if c is any alphabetic character.
§4.3.9: char_is_hex
fstr_bool char_is_hex(
char c
)
Description
This call returns non-zero if c is any valid hexadecimal digit.
§4.3.10: char_is_numeric
fstr_bool char_is_numeric(
char c
)
Description
This call returns non-zero if c is any valid decimal digit.
§4.3.11: string_zero
String string_zero(
void
)
Description
This call returns a String struct of zeroed members.
§4.3.12: make_string_cap
String make_string_cap(
void *str,
int32_t size,
int32_t mem_size
)
Parameters
str
The str parameter provides the of memory with which the string shall operate.
size
The size parameter expresses the initial size of the string.
If the memory does not already contain a useful string this should be zero.
mem_size
The mem_size parameter expresses the full size of the memory provided by str.
Description
This call returns the String created from the parameters.
§4.3.13: make_string
String make_string(
void *str,
int32_t size
)
Parameters
str
The str parameter provides the of memory with which the string shall operate.
size
The size parameter expresses the initial size of the string.
If the memory does not already contain a useful string this should be zero. Since this version
does not specify the size of the memory it is also assumed that this size is the maximum size
of the memory.
Description
This call returns the String created from the parameters.
§4.3.14: make_lit_string
#define make_lit_string(s)
Description
This macro takes a literal string in quotes and uses it to create a String
with the correct size and memory size. Strings created this way should usually not be mutated.
§4.3.15: make_fixed_width_string
#define make_fixed_width_string(s)
Description
This macro takes a local char array with a fixed width and uses it to create
an empty String with the correct size and memory size to operate on the array.
§4.3.16: expand_str
#define expand_str(s)
Description
This macro is a helper for any calls that take a char*,int pair to specify a
string. This macro expands to both of those parameters from one String struct.
§4.3.17: str_size
int32_t str_size(
char *str
)
Description
This call returns the number of bytes before a null terminator starting at str.
§4.3.18: make_string_slowly
String make_string_slowly(
void *str
)
Description
This call makes a string by counting the number of bytes before a null terminator and
treating that as the size and memory size of the string.
§4.3.19: substr_tail
String substr_tail(
String str,
int32_t start
)
Description
This call creates a substring of str that starts with an offset from str's base.
The new string uses the same underlying memory so both strings will see changes.
Usually strings created this way should only go through immutable calls.
§4.3.20: substr
String substr(
String str,
int32_t start,
int32_t size
)
Description
This call creates a substring of str that starts with an offset from str's base,
and has a fixed size. The new string uses the same underlying memory so both strings
will see changes. Usually strings created this way should only go through immutable calls.
§4.3.21: skip_whitespace
String skip_whitespace(
String str
)
Description
This call creates a substring that starts with the first non-whitespace character of str.
Like other substr calls, the new string uses the underlying memory and so should usually be
considered immutable.
See Also
§4.3.22: chop_whitespace
String chop_whitespace(
String str
)
Description
This call creates a substring that ends with the last non-whitespace character of str.
Like other substr calls, the new string uses the underlying memory and so should usually be
considered immutable.
See Also
§4.3.23: skip_chop_whitespace
String skip_chop_whitespace(
String str
)
Description
This call is equivalent to calling skip_whitespace and chop_whitespace together.
See Also
§4.3.24: tailstr
String tailstr(
String str
)
Description
This call returns an empty String with underlying memory taken from
the portion of str's memory that is not used.
§4.3.25: match_cc
fstr_bool match_cc(
char *a,
char *b
)
Description
This call returns non-zero if a and b are equivalent.
§4.3.26: match_sc
fstr_bool match_sc(
String a,
char *b
)
Description
This call returns non-zero if a and b are equivalent.
§4.3.27: match_cs
fstr_bool match_cs(
char *a,
String b
)
Description
This call returns non-zero if a and b are equivalent.
§4.3.28: match_ss
fstr_bool match_ss(
String a,
String b
)
Description
This call returns non-zero if a and b are equivalent.
§4.3.29: match_part_ccl
fstr_bool match_part_ccl(
char *a,
char *b,
int32_t *len
)
Parameters
len
If this call returns non-zero this parameter is used to output the length of b.
Description
This call is similar to a match call, except that it is permitted for a to be longer than b.
In other words this call returns non-zero if b is a prefix of a.
§4.3.30: match_part_scl
fstr_bool match_part_scl(
String a,
char *b,
int32_t *len
)
Parameters
len
If this call returns non-zero this parameter is used to output the length of b.
Description
This call is similar to a match call, except that it is permitted for a to be longer than b.
In other words this call returns non-zero if b is a prefix of a.
§4.3.31: match_part_cc
fstr_bool match_part_cc(
char *a,
char *b
)
Parameters
len
If this call returns non-zero this parameter is used to output the length of b.
Description
This call is similar to a match call, except that it is permitted for a to be longer than b.
In other words this call returns non-zero if b is a prefix of a.
§4.3.32: match_part_sc
fstr_bool match_part_sc(
String a,
char *b
)
Description
This call is similar to a match call, except that it is permitted for a to be longer than b.
In other words this call returns non-zero if b is a prefix of a.
§4.3.33: match_part_cs
fstr_bool match_part_cs(
char *a,
String b
)
Description
This call is similar to a match call, except that it is permitted for a to be longer than b.
In other words this call returns non-zero if b is a prefix of a.
§4.3.34: match_part_ss
fstr_bool match_part_ss(
String a,
String b
)
Description
This call is similar to a match call, except that it is permitted for a to be longer than b.
In other words this call returns non-zero if b is a prefix of a.
§4.3.35: match_insensitive_cc
fstr_bool match_insensitive_cc(
char *a,
char *b
)
Description
This call returns non-zero if a and b are equivalent under case insensitive comparison.
§4.3.36: match_insensitive_sc
fstr_bool match_insensitive_sc(
String a,
char *b
)
Description
This call returns non-zero if a and b are equivalent under case insensitive comparison.
§4.3.37: match_insensitive_cs
fstr_bool match_insensitive_cs(
char *a,
String b
)
Description
This call returns non-zero if a and b are equivalent under case insensitive comparison.
§4.3.38: match_insensitive_ss
fstr_bool match_insensitive_ss(
String a,
String b
)
Description
This call returns non-zero if a and b are equivalent under case insensitive comparison.
§4.3.39: match_part_insensitive_ccl
fstr_bool match_part_insensitive_ccl(
char *a,
char *b,
int32_t *len
)
Parameters
len
If this call returns non-zero this parameter is used to output the length of b.
Description
This call performs the same partial matching rule as match_part under case insensitive comparison.
See Also
§4.3.40: match_part_insensitive_scl
fstr_bool match_part_insensitive_scl(
String a,
char *b,
int32_t *len
)
Parameters
len
If this call returns non-zero this parameter is used to output the length of b.
Description
This call performs the same partial matching rule as match_part under case insensitive comparison.
See Also
§4.3.41: match_part_insensitive_cc
fstr_bool match_part_insensitive_cc(
char *a,
char *b
)
Description
This call performs the same partial matching rule as match_part under case insensitive comparison.
See Also
§4.3.42: match_part_insensitive_sc
fstr_bool match_part_insensitive_sc(
String a,
char *b
)
Description
This call performs the same partial matching rule as match_part under case insensitive comparison.
See Also
§4.3.43: match_part_insensitive_cs
fstr_bool match_part_insensitive_cs(
char *a,
String b
)
Description
This call performs the same partial matching rule as match_part under case insensitive comparison.
See Also
§4.3.44: match_part_insensitive_ss
fstr_bool match_part_insensitive_ss(
String a,
String b
)
Description
This call performs the same partial matching rule as match_part under case insensitive comparison.
See Also
§4.3.45: compare_cc
int32_t compare_cc(
char *a,
char *b
)
Description
This call returns zero if a and b are equivalent,
it returns negative if a sorts before b alphabetically,
and positive if a sorts after b alphabetically.
§4.3.46: compare_sc
int32_t compare_sc(
String a,
char *b
)
Description
This call returns zero if a and b are equivalent,
it returns negative if a sorts before b alphabetically,
and positive if a sorts after b alphabetically.
§4.3.47: compare_cs
int32_t compare_cs(
char *a,
String b
)
Description
This call returns zero if a and b are equivalent,
it returns negative if a sorts before b alphabetically,
and positive if a sorts after b alphabetically.
§4.3.48: compare_ss
int32_t compare_ss(
String a,
String b
)
Description
This call returns zero if a and b are equivalent,
it returns negative if a sorts before b alphabetically,
and positive if a sorts after b alphabetically.
§4.3.49: find_c_char
int32_t find_c_char(
char *str,
int32_t start,
char character
)
Parameters
str
The str parameter provides a null terminated string to search.
start
The start parameter provides the index of the first character in str to search.
character
The character parameter provides the character for which to search.
Description
This call returns the index of the first occurance of character, or the size of the string
if the character is not found.
§4.3.50: find_s_char
int32_t find_s_char(
String str,
int32_t start,
char character
)
Parameters
str
The str parameter provides a string to search.
start
The start parameter provides the index of the first character in str to search.
character
The character parameter provides the character for which to search.
Description
This call returns the index of the first occurance of character, or the size of the string
if the character is not found.
§4.3.51: find_c_chars
int32_t find_c_chars(
char *str,
int32_t start,
char *characters
)
Parameters
str
The str parameter provides a null terminated string to search.
start
The start parameter provides the index of the first character in str to search.
character
The characters parameter provides a null terminated array of characters for which to search.
Description
This call returns the index of the first occurance of a character in the characters array,
or the size of the string if no such character is not found.
§4.3.52: find_s_chars
int32_t find_s_chars(
String str,
int32_t start,
char *characters
)
Parameters
str
The str parameter provides a string to search.
start
The start parameter provides the index of the first character in str to search.
character
The characters parameter provides a null terminated array of characters for which to search.
Description
This call returns the index of the first occurance of a character in the characters array,
or the size of the string if no such character is not found.
§4.3.53: find_substr_c
int32_t find_substr_c(
char *str,
int32_t start,
String seek
)
Parameters
str
The str parameter provides a null terminated string to search.
start
The start parameter provides the index of the first character in str to search.
seek
The seek parameter provides a string to find in str.
Description
This call returns the index of the first occurance of the seek substring in str or the
size of str if no such substring in str is found.
§4.3.54: find_substr_s
int32_t find_substr_s(
String str,
int32_t start,
String seek
)
Parameters
str
The str parameter provides a string to search.
start
The start parameter provides the index of the first character in str to search.
seek
The seek parameter provides a string to find in str.
Description
This call returns the index of the first occurance of the seek substring in str or the
size of str if no such substring in str is found.
§4.3.55: rfind_substr_s
int32_t rfind_substr_s(
String str,
int32_t start,
String seek
)
Parameters
str
The str parameter provides a string to search.
start
The start parameter provides the index of the first character in str to search.
seek
The seek parameter provides a string to find in str.
Description
This call returns the index of the last occurance of the seek substring in str
or -1 if no such substring in str is found.
§4.3.56: find_substr_insensitive_c
int32_t find_substr_insensitive_c(
char *str,
int32_t start,
String seek
)
Parameters
str
The str parameter provides a null terminated string to search.
start
The start parameter provides the index of the first character in str to search.
seek
The seek parameter provides a string to find in str.
Description
This call acts as find_substr under case insensitive comparison.
See Also
§4.3.57: find_substr_insensitive_s
int32_t find_substr_insensitive_s(
String str,
int32_t start,
String seek
)
Parameters
str
The str parameter provides a string to search.
start
The start parameter provides the index of the first character in str to search.
seek
The seek parameter provides a string to find in str.
Description
This call acts as find_substr under case insensitive comparison.
See Also
§4.3.58: has_substr_c
fstr_bool has_substr_c(
char *s,
String seek
)
Description
This call returns non-zero if the string s contains a substring equivalent to seek.
§4.3.59: has_substr_s
fstr_bool has_substr_s(
String s,
String seek
)
Description
This call returns non-zero if the string s contains a substring equivalent to seek.
§4.3.60: has_substr_insensitive_c
fstr_bool has_substr_insensitive_c(
char *s,
String seek
)
Description
This call returns non-zero if the string s contains a substring equivalent to seek
under case insensitive comparison.
§4.3.61: has_substr_insensitive_s
fstr_bool has_substr_insensitive_s(
String s,
String seek
)
Description
This call returns non-zero if the string s contains a substring equivalent to seek
under case insensitive comparison.
§4.3.62: copy_fast_unsafe_cc
int32_t copy_fast_unsafe_cc(
char *dest,
char *src
)
Description
This call performs a copy from the src buffer to the dest buffer.
The copy does not stop until a null terminator is found in src. There
is no safety against overrun so dest must be large enough to contain src.
The null terminator is not written to dest. This call returns the number
of bytes coppied to dest.
§4.3.63: copy_fast_unsafe_cs
int32_t copy_fast_unsafe_cs(
char *dest,
String src
)
Description
This call performs a copy from the src string to the dest buffer.
The copy does not stop until src.size characters are coppied. There
is no safety against overrun so dest must be large enough to contain src.
The null terminator is not written to dest. This call returns the number
of bytes coppied to dest.
§4.3.64: copy_checked_ss
fstr_bool copy_checked_ss(
String *dest,
String src
)
Description
This call performs a copy from the src string to the dest string.
The memory_size of dest is checked before any coppying is done.
This call returns non-zero on a successful copy.
§4.3.65: copy_partial_sc
fstr_bool copy_partial_sc(
String *dest,
char *src
)
Description
This call performs a copy from the src buffer to the dest string.
The memory_size of dest is checked if the entire copy cannot be performed,
as many bytes as possible are coppied to dest. This call returns non-zero
if the entire string is coppied to dest.
§4.3.66: copy_partial_ss
fstr_bool copy_partial_ss(
String *dest,
String src
)
Description
This call performs a copy from the src string to the dest string.
The memory_size of dest is checked if the entire copy cannot be performed,
as many bytes as possible are coppied to dest. This call returns non-zero
if the entire string is coppied to dest.
§4.3.67: copy_cc
int32_t copy_cc(
char *dest,
char *src
)
Description
This call performs a copy from src to dest equivalent to copy_fast_unsafe.
See Also
§4.3.68: copy_ss
void copy_ss(
String *dest,
String src
)
Description
This call performs a copy from src to dest equivalent to copy_checked.
See Also
§4.3.69: copy_sc
void copy_sc(
String *dest,
char *src
)
Description
This call performs a copy from src to dest equivalent to copy_partial.
See Also
§4.3.70: append_checked_ss
fstr_bool append_checked_ss(
String *dest,
String src
)
Description
This call checks if there is enough space in dest's underlying memory
to append src onto dest. If there is src is appended and the call returns non-zero.
§4.3.71: append_partial_sc
fstr_bool append_partial_sc(
String *dest,
char *src
)
Description
This call attemps to append as much of src into the space in dest's underlying memory
as possible. If the entire string is appended the call returns non-zero.
§4.3.72: append_partial_ss
fstr_bool append_partial_ss(
String *dest,
String src
)
Description
This call attemps to append as much of src into the space in dest's underlying memory
as possible. If the entire string is appended the call returns non-zero.
§4.3.73: append_s_char
fstr_bool append_s_char(
String *dest,
char c
)
Description
This call attemps to append c onto dest. If there is space left in dest's underlying
memory the character is appended and the call returns non-zero.
§4.3.74: append_ss
fstr_bool append_ss(
String *dest,
String src
)
Description
This call is equivalent to append_partial.
See Also
§4.3.75: append_sc
fstr_bool append_sc(
String *dest,
char *src
)
Description
This call is equivalent to append_partial.
See Also
§4.3.76: terminate_with_null
fstr_bool terminate_with_null(
String *str
)
Description
This call attemps to append a null terminator onto str without effecting the
size of str. This is usually called when the time comes to pass the the string to an
API that requires a null terminator. This call returns non-zero if there was a spare
byte in the strings underlying memory.
§4.3.77: append_padding
fstr_bool append_padding(
String *dest,
char c,
int32_t target_size
)
Description
This call pads out dest so that it has a size of target_size by appending
the padding character c until the target size is achieved. This call returns
non-zero if dest does not run out of space in the underlying memory.
§4.3.78: replace_char
void replace_char(
String *str,
char replace,
char with
)
Parameters
str
The str parameter provides the string in which replacement shall be performed.
replace
The replace character specifies which character should be replaced.
with
The with character specifies what to write into the positions where replacement occurs.
Description
This call replaces all occurances of character in str with another character.
§4.3.79: int_to_str_size
int32_t int_to_str_size(
int32_t x
)
Description
This call returns the number of bytes required to represent x as a string.
§4.3.80: int_to_str
fstr_bool int_to_str(
String *dest,
int32_t x
)
Description
This call writes a string representation of x into dest. If there is enough
space in dest this call returns non-zero.
§4.3.81: append_int_to_str
fstr_bool append_int_to_str(
String *dest,
int32_t x
)
Description
This call appends a string representation of x onto dest. If there is enough
space in dest this call returns non-zero.
§4.3.82: u64_to_str_size
int32_t u64_to_str_size(
uint64_t x
)
Description
This call returns the number of bytes required to represent x as a string.
§4.3.83: u64_to_str
fstr_bool u64_to_str(
String *dest,
uint64_t x
)
Description
This call writes a string representation of x into dest. If there is enough
space in dest this call returns non-zero.
§4.3.84: append_u64_to_str
fstr_bool append_u64_to_str(
String *dest,
uint64_t x
)
Description
This call appends a string representation of x onto dest. If there is enough
space in dest this call returns non-zero.
§4.3.85: float_to_str_size
int32_t float_to_str_size(
float x
)
Description
This call returns the number of bytes required to represent x as a string.
§4.3.86: append_float_to_str
fstr_bool append_float_to_str(
String *dest,
float x
)
Description
This call writes a string representation of x into dest. If there is enough
space in dest this call returns non-zero.
§4.3.87: float_to_str
fstr_bool float_to_str(
String *dest,
float x
)
Description
This call appends a string representation of x onto dest. If there is enough
space in dest this call returns non-zero.
§4.3.88: str_is_int_c
int32_t str_is_int_c(
char *str
)
Description
If str is a valid string representation of an integer, this call returns non-zero
§4.3.89: str_is_int_s
fstr_bool str_is_int_s(
String str
)
Description
If str is a valid string representation of an integer, this call returns non-zero.
§4.3.90: str_to_int_c
int32_t str_to_int_c(
char *str
)
Description
If str is a valid string representation of an integer, this call will return
the integer represented by the string. Otherwise this call returns zero.
§4.3.91: str_to_int_s
int32_t str_to_int_s(
String str
)
Description
If str represents a valid string representation of an integer, this call will return
the integer represented by the string. Otherwise this call returns zero.
§4.3.92: hexchar_to_int
int32_t hexchar_to_int(
char c
)
Description
If c is a valid hexadecimal digit [0-9a-fA-F] this call returns the value of
the integer value of the digit. Otherwise the return is some nonsense value.
§4.3.93: int_to_hexchar
char int_to_hexchar(
int32_t x
)
Description
If x is in the range [0,15] this call returns the equivalent lowercase hexadecimal digit.
Otherwise the return is some nonsense value.
§4.3.94: hexstr_to_int
uint32_t hexstr_to_int(
String str
)
Description
This call interprets str has a hexadecimal representation of an integer and returns
the represented integer value.
§4.3.95: color_to_hexstr
fstr_bool color_to_hexstr(
String *s,
uint32_t color
)
Description
This call fills s with the hexadecimal representation of the color.
If there is enough memory in s to represent the color this call returns non-zero.
§4.3.96: hexstr_to_color
fstr_bool hexstr_to_color(
String s,
uint32_t *out
)
Description
This call interprets s as a color and writes the 32-bit integer representation into out.
§4.3.97: reverse_seek_slash_pos
int32_t reverse_seek_slash_pos(
String str,
int32_t pos
)
Description
This call searches for a slash in str by starting pos bytes from the end and going backwards.
§4.3.98: reverse_seek_slash
int32_t reverse_seek_slash(
String str
)
Description
This call searches for a slash in str by starting at the end and going backwards.
§4.3.99: front_of_directory
String front_of_directory(
String dir
)
Description
This call returns a substring of dir containing only the file name or
folder name furthest to the right in the directory.
See Also
§4.3.100: path_of_directory
String path_of_directory(
String dir
)
Description
This call returns a substring of dir containing the whole path except
for the final file or folder name.
See Also
§4.3.101: set_last_folder_sc
fstr_bool set_last_folder_sc(
String *dir,
char *folder_name,
char slash
)
Parameters
dir
The dir parameter is the directory string in which to set the last folder in the directory.
folder_name
The folder_name parameter is a null terminated string specifying the name to set
at the end of the directory.
slash
The slash parameter specifies what slash to use between names in the directory.
Description
This call deletes the last file name or folder name in the dir string and appends the new provided one.
If there is enough memory in dir this call returns non-zero.
§4.3.102: set_last_folder_ss
fstr_bool set_last_folder_ss(
String *dir,
String folder_name,
char slash
)
Parameters
dir
The dir parameter is the directory string in which to set the last folder in the directory.
folder_name
The folder_name parameter is a string specifying the name to set at the end of the directory.
slash
The slash parameter specifies what slash to use between names in the directory.
Description
This call deletes the last file name or folder name in the dir string and appends the new provided one.
If there is enough memory in dir this call returns non-zero.
§4.3.103: file_extension
String file_extension(
String str
)
Description
This call returns a substring containing only the file extension of the provided filename.
See Also
§4.3.104: remove_last_folder
fstr_bool remove_last_folder(
String *str
)
Description
This call attemps to delete a folder or filename off the end of a path string.
This call returns non-zero on success.
§4.3.105: string_set_match
fstr_bool string_set_match(
String *str_set,
int32_t count,
String str,
int32_t *match_index
)
Parameters
str_set
The str_set parameter is an array of String structs specifying matchable strings.
count
The count parameter specifies the number of String structs in the str_set array.
str
The str parameter specifies the string to match against the str_set.
match_index
If this call succeeds match_index is filled with the index into str_set where the match occurred.
Description
This call tries to see if str matches any of the strings in str_set. If there is a match the call
succeeds and returns non-zero. The matching rule is equivalent to the matching rule for match.
See Also