#import "String";
Searching, comparing, splitting, trimming and scanning strings, and working with file paths.
Strings are bytes. Case-insensitive procedures fold only the ASCII letters, and nothing here
decodes UTF-8; use Unicode for that. Procedures that return a part of their input (trim,
the splits, path_filename) return a view into it, not a copy. Procedures that build a new string
(join, replace, to_lower_copy, path_join) allocate it with the context allocator, and the
caller frees it. A search that finds nothing returns -1, or false with an empty or whole string.
assert(trim(" hello ") == "hello");
found, key, value := split_from_left("name=jai", #char "=");
assert(found && key == "name" && value == "jai");Reads the next token from line and removes it, with any spaces before it, from line.
line := " name =value";
token, ok := parse_token(*line);
assert(ok && token == "name" && line == " =value");
token, ok = parse_token(*line);
assert(ok && token == "=" && line == "value");Reads the next token as parse_token does and returns it with whether it is equal to match.
The token is removed from line whether or not it matches.
line := "if (x)";
_, matched := match_token(*line, "if");
assert(matched && line == " (x)");Like match_token, with ASCII letters matched in either case.
line := "IF x";
_, matched := match_token_nocase(*line, "if");
assert(matched);Reads the next token and reads it as true or false, in either case. The second result is false
when the token is anything else or there is none; the token is removed from line anyway.
line := "True rest";
value, ok := parse_bool(*line);
assert(ok && value && line == " rest");Reads the next token and looks it up by name among the values of the enum type T. The second result is
false when no value has that name, and then the value is zero. The name is case sensitive.
Color :: enum { RED; GREEN; }
line := "GREEN;";
value, ok := parse_enum(*line, Color);
assert(ok && value == .GREEN && line == ";");Reads the next token as a whole number of type T (int by default). Only space and tab are skipped
in front of it unless you pass spaces.
Reads the next token as a decimal number. The second result is false when the token is not entirely a
number, or there is none.
line := "2.5 rest";
value, ok := parse_float(*line);
assert(ok && value == 2.5);The last component of path: everything after the last / or \. Both separators count on every
platform. The result points into path.
assert(path_filename("dir/name.ext") == "name.ext");
assert(path_filename("dir/") == "");The directory part of path, including its trailing separator. Empty when path has no separator.
Both / and \ count on every platform.
assert(path_strip_filename("dir/name.ext") == "dir/");
assert(path_strip_filename("name.ext") == "");The extension of the last component of path, without the dot, and whether it has one.
ext, found := path_extension("dir/archive.tar.gz");
assert(found && ext == "gz");
_, hidden := path_extension("dir/.hidden");
assert(!hidden);path without the extension of its last component and the dot before it. A path with no extension is
returned unchanged. The result points into path.
assert(path_strip_extension("dir/name.ext") == "dir/name");
assert(path_strip_extension("dir.d/name") == "dir.d/name");Splits name into its directory (with the trailing separator), its name without the extension, the
extension without the dot, and the name with the extension. All four point into name; a missing
part is empty.
dir, base, ext, file := path_decomp("src/main.jai");
assert(dir == "src/" && base == "main" && ext == "jai" && file == "main.jai");The last component of s without its extension.
Replaces every / and \ in path with separator (the platform's by default), in place. path must
be writable, not a string literal.
path := copy_string("a/b\\c");
defer free(path);
path_overwrite_separators(path, #char "/");
assert(path == "a/b/c");path when its extension is already extension (without the dot); otherwise a new string with
.extension added. Another extension is kept, so a.txt becomes a.txt.png.
same := path_ensure_extension("a.png", "png");
assert(same == "a.png");
longer := path_ensure_extension("a", "png");
defer free(longer);
assert(longer == "a.png");The components one after another with separator between them. A trailing separator on a component
is dropped first, so no separator is doubled. Empty components still add a separator.
Whether path is absolute: it starts with / elsewhere, or with a drive letter, : and a
separator on Windows. Not defined on every platform.
#if OS == .WINDOWS assert(is_absolute_path("C:\\dir"));
else assert(is_absolute_path("/dir") && !is_absolute_path("dir"));Splits name into its directory (with the trailing separator), its name without the extension, the
extension without the dot, and the name with the extension. All four point into name; a missing
part is empty.
dir, base, ext, file := path_decomp("src/main.jai");
assert(dir == "src/" && base == "main" && ext == "jai" && file == "main.jai");The last component of s without its extension.
The part of s that starts at index and holds at most count bytes; empty when index is
past the end. Both must not be negative: a negative one fails an assert.
Orders two strings byte by byte: -1 when a sorts first, 1 when b does, 0 when they are equal.
Like compare, but ASCII letters match in either case. Bytes outside A-Z and a-z compare as they are,
so this does not fold other scripts.
assert(compare_nocase("Hello", "hELLO") == 0);
assert(compare_nocase("a", "B") == -1);Whether the two strings hold the same bytes. The same as a == b.
Whether the two strings are equal when ASCII letters are matched in either case.
assert(equal_nocase("MiXeD", "mixed"));
assert(!equal_nocase("abc", "abcd"));Whether s starts with prefix. An empty prefix always matches.
assert(begins_with("filename.txt", "file"));
assert(!begins_with("file", "filename"));Whether s ends with suffix. An empty suffix always matches.
Like begins_with, with ASCII letters matched in either case.
assert(begins_with_nocase("Content-Length: 5", "content-length"));Like ends_with, with ASCII letters matched in either case.
assert(ends_with_nocase("PHOTO.JPG", ".jpg"));Whether the byte c appears in chars.
The index of the first byte in s at or after start_index, or -1 when there is none.
assert(find_index_from_left("a/b/c", #char "/") == 1);
assert(find_index_from_left("a/b/c", #char "/", 2) == 3);
assert(find_index_from_left("abc", #char "/") == -1);The index of the last byte in s, or -1 when there is none.
assert(find_index_from_right("a/b/c", #char "/") == 3);The index of the first byte of s at or after start_index that is in bytes, or -1 when there is none.
assert(find_index_of_any_from_left("key=value;", "=;") == 3);
assert(find_index_of_any_from_left("key=value;", "=;", 4) == 9);The index of the last byte of s that is in bytes, or -1 when there is none.
assert(find_index_of_any_from_right("dir\\sub/file", "/\\") == 7);The index where substring first appears in s when ASCII letters are matched in either case, and
whether it was found. When it is not found the index is -1. An empty substring, or one longer than s,
is never found.
index, found := index_of_string_nocase("Hello World", "WORLD");
assert(found && index == 6);Whether substring appears in s, and the part of s after its first match. When it does not appear the
remainder is empty. An empty substring is never found. The remainder points into s.
Like contains, with ASCII letters matched in either case.
found, rest := contains_nocase("abcDEFghi", "def");
assert(found && rest == "ghi");Whether any byte of chars appears in s, and the part of s after the first such byte.
found, rest := contains_any_character("a,b;c", ";,");
assert(found && rest == "b;c");Whether any of the substrings appears in s, and the part of s after the earliest match. At one
position the first substring listed wins. Empty substrings are ignored.
found, rest := contains_any_string("say hello world", "world", "hello");
assert(found && rest == " world");Overwrites every byte of s that is in chars with replacement. s is changed in place, so it
must not be a string literal.
text := copy_string("a-b_c");
defer free(text);
replace_chars(text, "-_", #char " ");
assert(text == "a b c");Turns the ASCII capitals of s into lower case, in place. Other bytes are left as they are, so UTF-8
text is not folded. s must be writable, not a string literal.
text := copy_string("MiXeD");
defer free(text);
to_lower_in_place(text);
assert(text == "mixed");Turns the ASCII lower case letters of s into capitals, in place. See to_lower_in_place.
text := copy_string("MiXeD");
defer free(text);
to_upper_in_place(text);
assert(text == "MIXED");A copy of s with ASCII capitals turned into lower case. The copy is allocated with the context
allocator and the caller frees it.
lower := to_lower_copy("Hello");
defer free(lower);
assert(lower == "hello");A copy of s with ASCII lower case letters turned into capitals. The copy is allocated with the
context allocator and the caller frees it.
upper := to_upper_copy("Hello");
defer free(upper);
assert(upper == "HELLO");s without the chars at its start; the result points into s.
s without the chars at its end; the result points into s.
assert(trim_right(" hi ") == " hi");s without the chars at either end; the result points into s.
_s without the spaces, tabs and line breaks at its end. The same as trim_right.
The part of _s before its first space, tab or line break, or all of it when it has none.
assert(eat_until_space("word and more") == "word");
assert(eat_until_space("single") == "single");The part of s before the first byte that is in bytes, or all of s when there is none.
assert(stop_at_any("name=value", "=:") == "name");Removes the carriage return from every \r\n pair in s, in place, and shortens s. A lone \r is
kept. s must be writable.
text := copy_string("a\r\nb\rc");
defer free(text);
normalize_line_endings(*text);
assert(text == "a\nb\rc");Splits s at the first byte. Returns whether it was found, the part before it and the part after it.
found, left, right := split_from_left("key=a=b", #char "=");
assert(found && left == "key" && right == "a=b");
found, left, right = split_from_left("none", #char "=");
assert(!found && left == "none" && right == "");Splits s at the last byte. Returns whether it was found, the part before it and the part after it.
found, left, right := split_from_right("a.b.c", #char ".");
assert(found && left == "a.b" && right == "c");
found, left, right = split_from_right("abc", #char ".");
assert(!found && left == "abc" && right == "");Splits s at the first byte that is in bytes. Returns whether one was found, the part before it and
the part after it. When none is found the result is false, all of s and an empty string.
found, left, right := split_from_left_by_any("a,b;c", ",;");
assert(found && left == "a" && right == "b;c");Splits s at the last byte that is in bytes. Returns whether one was found, the part before it and
the part after it. When none is found the result is false, all of s and an empty string.
found, left, right := split_from_right_by_any("a,b;c", ",;");
assert(found && left == "a,b" && right == "c");The pieces of s between each separator (a string or a byte).
The strings one after another, with separator between them.
A copy of s with every non-overlapping old replaced by new, and how many were replaced.
Whether s starts with prefix. An empty prefix always matches.
assert(begins_with("filename.txt", "file"));
assert(!begins_with("file", "filename"));Whether the whole of s matches the pattern pat.
assert(wildcard_match("main.jai", "*.jai"));
assert(wildcard_match("v2", "v[0-9]"));
assert(!wildcard_match("ab", "a?b"));Reads values from text as format describes. Returns whether the whole text matched, and the values
read, as Anys.
Reads values from text as format describes, storing them through the pointers in args.
Returns whether the whole text matched.
Runs a few checks of the module with asserts. A smoke test; the real tests are in the module's test folder.
The bytes trim, trim_left and trim_right remove by default: space, tab, carriage return and line feed.
The bytes parse_token treats as tokens of their own by default: ;, =, ( and ).
The separator a path joined on this platform uses: \ on Windows and / elsewhere.