diff options
| author | Lucas Perlind <perlindluca@gmail.com> | 2023-04-03 08:33:24 +1000 |
|---|---|---|
| committer | Lucas Perlind <perlindluca@gmail.com> | 2023-04-03 08:44:14 +1000 |
| commit | 67e6f571925a07d25b5b3bef2ecb22a30afb6508 (patch) | |
| tree | b12a01775f35d2aaec40265092f91b4fbd0430c9 /core/strings | |
| parent | 6ff0cc0b400524232cdce44f5b2a68b399ba4adc (diff) | |
Small improvements strings documentation
* Use new 'Returns:' and 'Inputs:' keywords used by the website generator
* Make order item order resemble website, i.e. 'Returns:' comes before
'Example:'
* Add a few missing input items
* Add a few missing return items
Diffstat (limited to 'core/strings')
| -rw-r--r-- | core/strings/ascii_set.odin | 8 | ||||
| -rw-r--r-- | core/strings/builder.odin | 186 | ||||
| -rw-r--r-- | core/strings/conversion.odin | 79 | ||||
| -rw-r--r-- | core/strings/intern.odin | 16 | ||||
| -rw-r--r-- | core/strings/reader.odin | 54 | ||||
| -rw-r--r-- | core/strings/strings.odin | 542 |
6 files changed, 484 insertions, 401 deletions
diff --git a/core/strings/ascii_set.odin b/core/strings/ascii_set.odin index c9cc6b212..c65ef1c61 100644 --- a/core/strings/ascii_set.odin +++ b/core/strings/ascii_set.odin @@ -12,10 +12,10 @@ Ascii_Set :: distinct [8]u32 /* Creates an Ascii_Set with unique characters from the input string. -**Inputs** +Inputs: - chars: A string containing characters to include in the Ascii_Set. -**Returns** +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. */ @@ -33,11 +33,11 @@ ascii_set_make :: proc(chars: string) -> (as: Ascii_Set, ok: bool) #no_bounds_ch /* Determines if a given char is contained within an Ascii_Set. -**Inputs** +Inputs: - as: The Ascii_Set to search. - c: The char to check for in the Ascii_Set. -**Returns** +Returns: A boolean indicating if the byte is contained in the Ascii_Set (true) or not (false). */ ascii_set_contains :: proc(as: Ascii_Set, c: byte) -> bool #no_bounds_check { diff --git a/core/strings/builder.odin b/core/strings/builder.odin index 4994230a9..32442c21a 100644 --- a/core/strings/builder.odin +++ b/core/strings/builder.odin @@ -7,10 +7,10 @@ import "core:io" /* Type definition for a procedure that flushes a Builder -**Inputs** +Inputs: - b: A pointer to the Builder -**Returns** +Returns: A boolean indicating whether the Builder should be reset */ Builder_Flush_Proc :: #type proc(b: ^Builder) -> (do_reset: bool) @@ -27,10 +27,10 @@ Produces a Builder with a default length of 0 and cap of 16 *Allocates Using Provided Allocator* -**Inputs** +Inputs: - allocator: (default is context.allocator) -**Returns** +Returns: A new Builder */ builder_make_none :: proc(allocator := context.allocator) -> Builder { @@ -41,11 +41,11 @@ Produces a Builder with a specified length and cap of max(16,len) byte buffer *Allocates Using Provided Allocator* -**Inputs** +Inputs: - len: The desired length of the Builder's buffer - allocator: (default is context.allocator) -**Returns** +Returns: A new Builder */ builder_make_len :: proc(len: int, allocator := context.allocator) -> Builder { @@ -56,12 +56,12 @@ Produces a Builder with a specified length and cap *Allocates Using Provided Allocator* -**Inputs** +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** +Returns: A new Builder */ builder_make_len_cap :: proc(len, cap: int, allocator := context.allocator) -> Builder { @@ -79,11 +79,11 @@ It replaces the existing `buf` *Allocates Using Provided Allocator* -**Inputs** +Inputs: - b: A pointer to the Builder - allocator: (default is context.allocator) -**Returns** +Returns: initialized ^Builder */ builder_init_none :: proc(b: ^Builder, allocator := context.allocator) -> ^Builder { @@ -96,12 +96,12 @@ It replaces the existing `buf` *Allocates Using Provided Allocator* -**Inputs** +Inputs: - b: A pointer to the Builder - len: The desired length of the Builder's buffer - allocator: (default is context.allocator) -**Returns** +Returns: Initialized ^Builder */ builder_init_len :: proc(b: ^Builder, len: int, allocator := context.allocator) -> ^Builder { @@ -112,13 +112,13 @@ builder_init_len :: proc(b: ^Builder, len: int, allocator := context.allocator) Initializes a Builder with a specified length and cap It replaces the existing `buf` -**Inputs** +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** +Returns: A pointer to the initialized Builder */ builder_init_len_cap :: proc(b: ^Builder, len, cap: int, allocator := context.allocator) -> ^Builder { @@ -165,10 +165,10 @@ _builder_stream_vtable := &_builder_stream_vtable_obj /* Returns an io.Stream from a Builder -**Inputs** +Inputs: - b: A pointer to the Builder -**Returns** +Returns: An io.Stream */ to_stream :: proc(b: ^Builder) -> io.Stream { @@ -177,10 +177,10 @@ to_stream :: proc(b: ^Builder) -> io.Stream { /* Returns an io.Writer from a Builder -**Inputs** +Inputs: - b: A pointer to the Builder -**Returns** +Returns: An io.Writer */ to_writer :: proc(b: ^Builder) -> io.Writer { @@ -189,7 +189,7 @@ to_writer :: proc(b: ^Builder) -> io.Writer { /* Deletes the Builder byte buffer content -**Inputs** +Inputs: - b: A pointer to the Builder */ builder_destroy :: proc(b: ^Builder) { @@ -199,7 +199,7 @@ builder_destroy :: proc(b: ^Builder) { /* Reserves the Builder byte buffer to a specific capacity, when it's higher than before -**Inputs** +Inputs: - b: A pointer to the Builder - cap: The desired capacity for the Builder's buffer */ @@ -209,7 +209,7 @@ builder_grow :: proc(b: ^Builder, cap: int) { /* Clears the Builder byte buffer content (sets len to zero) -**Inputs** +Inputs: - b: A pointer to the Builder */ builder_reset :: proc(b: ^Builder) { @@ -220,9 +220,12 @@ Creates a Builder from a slice of bytes with the same slice length as its capaci *Uses Nil Allocator - Does NOT allocate* -**Inputs** +Inputs: - backing: A slice of bytes to be used as the backing buffer +Returns: +A new Builder + Example: import "core:fmt" @@ -241,8 +244,6 @@ Output: a ab -**Returns** -A new Builder */ builder_from_bytes :: proc(backing: []byte) -> Builder { s := transmute(runtime.Raw_Slice)backing @@ -261,10 +262,10 @@ builder_from_slice :: builder_from_bytes /* Casts the Builder byte buffer to a string and returns it -**Inputs** +Inputs: - b: A Builder -**Returns** +Returns: The contents of the Builder's buffer, as a string */ to_string :: proc(b: Builder) -> string { @@ -273,10 +274,10 @@ to_string :: proc(b: Builder) -> string { /* Returns the length of the Builder's buffer, in bytes -**Inputs** +Inputs: - b: A Builder -**Returns** +Returns: The length of the Builder's buffer */ builder_len :: proc(b: Builder) -> int { @@ -285,10 +286,10 @@ builder_len :: proc(b: Builder) -> int { /* Returns the capacity of the Builder's buffer, in bytes -**Inputs** +Inputs: - b: A Builder -**Returns** +Returns: The capacity of the Builder's buffer */ builder_cap :: proc(b: Builder) -> int { @@ -297,10 +298,10 @@ builder_cap :: proc(b: Builder) -> int { /* The free space left in the Builder's buffer, in bytes -**Inputs** +Inputs: - b: A Builder -**Returns** +Returns: The available space left in the Builder's buffer */ builder_space :: proc(b: Builder) -> int { @@ -309,10 +310,15 @@ builder_space :: proc(b: Builder) -> int { /* Appends a byte to the Builder and returns the number of bytes appended -**Inputs** +Inputs: - b: A pointer to the Builder - x: The byte to be appended +Returns: +The number of bytes appended + +NOTE: The backing dynamic array may be fixed in capacity or fail to resize, `n` states the number actually written. + Example: import "core:fmt" @@ -329,10 +335,6 @@ Output: ab -NOTE: The backing dynamic array may be fixed in capacity or fail to resize, `n` states the number actually written. - -**Returns** -The number of bytes appended */ write_byte :: proc(b: ^Builder, x: byte) -> (n: int) { n0 := len(b.buf) @@ -343,7 +345,7 @@ write_byte :: proc(b: ^Builder, x: byte) -> (n: int) { /* Appends a slice of bytes to the Builder and returns the number of bytes appended -**Inputs** +Inputs: - b: A pointer to the Builder - x: The slice of bytes to be appended @@ -361,7 +363,7 @@ Example: NOTE: The backing dynamic array may be fixed in capacity or fail to resize, `n` states the number actually written. -**Returns** +Returns: The number of bytes appended */ write_bytes :: proc(b: ^Builder, x: []byte) -> (n: int) { @@ -373,10 +375,15 @@ write_bytes :: proc(b: ^Builder, x: []byte) -> (n: int) { /* Appends a single rune to the Builder and returns the number of bytes written and an `io.Error` -**Inputs** +Inputs: - b: A pointer to the Builder - r: The rune to be appended +Returns: +The number of bytes written and an io.Error (if any) + +NOTE: The backing dynamic array may be fixed in capacity or fail to resize, `n` states the number actually written. + Example: import "core:fmt" @@ -393,10 +400,6 @@ Output: äb -NOTE: The backing dynamic array may be fixed in capacity or fail to resize, `n` states the number actually written. - -**Returns** -The number of bytes written and an io.Error (if any) */ write_rune :: proc(b: ^Builder, r: rune) -> (int, io.Error) { return io.write_rune(to_writer(b), r) @@ -404,10 +407,15 @@ write_rune :: proc(b: ^Builder, r: rune) -> (int, io.Error) { /* Appends a quoted rune to the Builder and returns the number of bytes written -**Inputs** +Inputs: - b: A pointer to the Builder - r: The rune to be appended +Returns: +The number of bytes written + +NOTE: The backing dynamic array may be fixed in capacity or fail to resize, `n` states the number actually written. + Example: import "core:fmt" @@ -425,10 +433,6 @@ Output: abc'ä'abc -NOTE: The backing dynamic array may be fixed in capacity or fail to resize, `n` states the number actually written. - -**Returns** -The number of bytes written */ write_quoted_rune :: proc(b: ^Builder, r: rune) -> (n: int) { return io.write_quoted_rune(to_writer(b), r) @@ -436,10 +440,15 @@ write_quoted_rune :: proc(b: ^Builder, r: rune) -> (n: int) { /* Appends a string to the Builder and returns the number of bytes written -**Inputs** +Inputs: - b: A pointer to the Builder - s: The string to be appended +Returns: +The number of bytes written + +NOTE: The backing dynamic array may be fixed in capacity or fail to resize, `n` states the number actually written. + Example: import "core:fmt" @@ -456,10 +465,6 @@ Output: abc -NOTE: The backing dynamic array may be fixed in capacity or fail to resize, `n` states the number actually written. - -**Returns** -The number of bytes written */ write_string :: proc(b: ^Builder, s: string) -> (n: int) { n0 := len(b.buf) @@ -470,10 +475,10 @@ write_string :: proc(b: ^Builder, s: string) -> (n: int) { /* Pops and returns the last byte in the Builder or 0 when the Builder is empty -**Inputs** +Inputs: - b: A pointer to the Builder -**Returns** +Returns: The last byte in the Builder or 0 if empty */ pop_byte :: proc(b: ^Builder) -> (r: byte) { @@ -489,10 +494,10 @@ pop_byte :: proc(b: ^Builder) -> (r: byte) { /* Pops the last rune in the Builder and returns the popped rune and its rune width or (0, 0) if empty -**Inputs** +Inputs: - b: A pointer to the Builder -**Returns** +Returns: The popped rune and its rune width or (0, 0) if empty */ pop_rune :: proc(b: ^Builder) -> (r: rune, width: int) { @@ -508,11 +513,16 @@ pop_rune :: proc(b: ^Builder) -> (r: rune, width: int) { @(private) DIGITS_LOWER := "0123456789abcdefx" /* -**Inputs** +Inputs: - b: A pointer to the Builder - str: The string to be quoted and appended - quote: The optional quote character (default is double quotes) +Returns: +The number of bytes written + +NOTE: The backing dynamic array may be fixed in capacity or fail to resize, `n` states the number actually written. + Example: import "core:fmt" @@ -530,10 +540,6 @@ Output: "a"'bc'"xyz" -NOTE: The backing dynamic array may be fixed in capacity or fail to resize, `n` states the number actually written. - -**Returns** -The number of bytes written */ write_quoted_string :: proc(b: ^Builder, str: string, quote: byte = '"') -> (n: int) { n, _ = io.write_quoted_string(to_writer(b), str, quote) @@ -542,11 +548,16 @@ write_quoted_string :: proc(b: ^Builder, str: string, quote: byte = '"') -> (n: /* Appends a rune to the Builder and returns the number of bytes written -**Inputs** +Inputs: - b: A pointer to the Builder - r: The rune to be appended - write_quote: Optional boolean flag to wrap in single-quotes (') (default is true) +Returns: +The number of bytes written + +NOTE: The backing dynamic array may be fixed in capacity or fail to resize, `n` states the number actually written. + Example: import "core:fmt" @@ -564,10 +575,6 @@ Output: a'"'x -NOTE: The backing dynamic array may be fixed in capacity or fail to resize, `n` states the number actually written. - -**Returns** -The number of bytes written */ write_encoded_rune :: proc(b: ^Builder, r: rune, write_quote := true) -> (n: int) { n, _ = io.write_encoded_rune(to_writer(b), r, write_quote) @@ -577,7 +584,7 @@ write_encoded_rune :: proc(b: ^Builder, r: rune, write_quote := true) -> (n: int /* Appends an escaped rune to the Builder and returns the number of bytes written -**Inputs** +Inputs: - b: A pointer to the Builder - r: The rune to be appended - quote: The quote character @@ -590,7 +597,7 @@ Appends an escaped rune to the Builder and returns the number of bytes written NOTE: The backing dynamic array may be fixed in capacity or fail to resize, `n` states the number actually written. -**Returns** +Returns: The number of bytes written */ write_escaped_rune :: proc(b: ^Builder, r: rune, quote: byte, html_safe := false) -> (n: int) { @@ -600,7 +607,7 @@ write_escaped_rune :: proc(b: ^Builder, r: rune, quote: byte, html_safe := false /* Writes a f64 value to the Builder and returns the number of characters written -**Inputs** +Inputs: - b: A pointer to the Builder - f: The f64 value to be appended - fmt: The format byte @@ -610,7 +617,7 @@ Writes a f64 value to the Builder and returns the number of characters written NOTE: The backing dynamic array may be fixed in capacity or fail to resize, `n` states the number actually written. -**Returns** +Returns: The number of characters written */ write_float :: proc(b: ^Builder, f: f64, fmt: byte, prec, bit_size: int, always_signed := false) -> (n: int) { @@ -626,7 +633,7 @@ write_float :: proc(b: ^Builder, f: f64, fmt: byte, prec, bit_size: int, always_ /* Writes a f16 value to the Builder and returns the number of characters written -**Inputs** +Inputs: - b: A pointer to the Builder - f: The f16 value to be appended - fmt: The format byte @@ -634,7 +641,7 @@ Writes a f16 value to the Builder and returns the number of characters written NOTE: The backing dynamic array may be fixed in capacity or fail to resize, `n` states the number actually written. -**Returns** +Returns: The number of characters written */ write_f16 :: proc(b: ^Builder, f: f16, fmt: byte, always_signed := false) -> (n: int) { @@ -648,12 +655,17 @@ write_f16 :: proc(b: ^Builder, f: f16, fmt: byte, always_signed := false) -> (n: /* Writes a f32 value to the Builder and returns the number of characters written -**Inputs** +Inputs: - b: A pointer to the Builder - f: The f32 value to be appended - fmt: The format byte - always_signed: Optional boolean flag to always include the sign +Returns: +The number of characters written + +NOTE: The backing dynamic array may be fixed in capacity or fail to resize, `n` states the number actually written. + Example: import "core:fmt" @@ -671,10 +683,6 @@ Output: 3.14159012 - -1.23000003e-01 -NOTE: The backing dynamic array may be fixed in capacity or fail to resize, `n` states the number actually written. - -**Returns** -The number of characters written */ write_f32 :: proc(b: ^Builder, f: f32, fmt: byte, always_signed := false) -> (n: int) { buf: [384]byte @@ -687,7 +695,7 @@ write_f32 :: proc(b: ^Builder, f: f32, fmt: byte, always_signed := false) -> (n: /* Writes a f32 value to the Builder and returns the number of characters written -**Inputs** +Inputs: - b: A pointer to the Builder - f: The f32 value to be appended - fmt: The format byte @@ -695,7 +703,7 @@ Writes a f32 value to the Builder and returns the number of characters written NOTE: The backing dynamic array may be fixed in capacity or fail to resize, `n` states the number actually written. -**Returns** +Returns: The number of characters written */ write_f64 :: proc(b: ^Builder, f: f64, fmt: byte, always_signed := false) -> (n: int) { @@ -709,14 +717,14 @@ write_f64 :: proc(b: ^Builder, f: f64, fmt: byte, always_signed := false) -> (n: /* Writes a u64 value to the Builder and returns the number of characters written -**Inputs** +Inputs: - b: A pointer to the Builder - i: The u64 value to be appended - base: The optional base for the numeric representation NOTE: The backing dynamic array may be fixed in capacity or fail to resize, `n` states the number actually written. -**Returns** +Returns: The number of characters written */ write_u64 :: proc(b: ^Builder, i: u64, base: int = 10) -> (n: int) { @@ -727,14 +735,14 @@ write_u64 :: proc(b: ^Builder, i: u64, base: int = 10) -> (n: int) { /* Writes a i64 value to the Builder and returns the number of characters written -**Inputs** +Inputs: - b: A pointer to the Builder - i: The i64 value to be appended - base: The optional base for the numeric representation NOTE: The backing dynamic array may be fixed in capacity or fail to resize, `n` states the number actually written. -**Returns** +Returns: The number of characters written */ write_i64 :: proc(b: ^Builder, i: i64, base: int = 10) -> (n: int) { @@ -745,14 +753,14 @@ write_i64 :: proc(b: ^Builder, i: i64, base: int = 10) -> (n: int) { /* Writes a uint value to the Builder and returns the number of characters written -**Inputs** +Inputs: - b: A pointer to the Builder - i: The uint value to be appended - base: The optional base for the numeric representation NOTE: The backing dynamic array may be fixed in capacity or fail to resize, `n` states the number actually written. -**Returns** +Returns: The number of characters written */ write_uint :: proc(b: ^Builder, i: uint, base: int = 10) -> (n: int) { @@ -761,14 +769,14 @@ write_uint :: proc(b: ^Builder, i: uint, base: int = 10) -> (n: int) { /* Writes a int value to the Builder and returns the number of characters written -**Inputs** +Inputs: - b: A pointer to the Builder - i: The int value to be appended - base: The optional base for the numeric representation NOTE: The backing dynamic array may be fixed in capacity or fail to resize, `n` states the number actually written. -**Returns** +Returns: The number of characters written */ write_int :: proc(b: ^Builder, i: int, base: int = 10) -> (n: int) { diff --git a/core/strings/conversion.odin b/core/strings/conversion.odin index dc41a02dc..0160c8a60 100644 --- a/core/strings/conversion.odin +++ b/core/strings/conversion.odin @@ -9,14 +9,14 @@ Converts invalid UTF-8 sequences in the input string `s` to the `replacement` st *Allocates Using Provided Allocator* -**Inputs** +Inputs: - s: Input string that may contain invalid UTF-8 sequences. - replacement: String to replace invalid UTF-8 sequences with. - allocator: (default: context.allocator). WARNING: Allocation does not occur when len(s) == 0 -**Returns** +Returns: A valid UTF-8 string with invalid sequences replaced by `replacement`. */ to_valid_utf8 :: proc(s, replacement: string, allocator := context.allocator) -> string { @@ -77,10 +77,13 @@ Converts the input string `s` to all lowercase characters. *Allocates Using Provided Allocator* -**Inputs** +Inputs: - s: Input string to be converted. - allocator: (default: context.allocator). +Returns: +A new string with all characters converted to lowercase. + Example: import "core:fmt" @@ -94,8 +97,6 @@ Output: test -**Returns** -A new string with all characters converted to lowercase. */ to_lower :: proc(s: string, allocator := context.allocator) -> string { b: Builder @@ -110,10 +111,13 @@ Converts the input string `s` to all uppercase characters. *Allocates Using Provided Allocator* -**Inputs** +Inputs: - s: Input string to be converted. - allocator: (default: context.allocator). +Returns: +A new string with all characters converted to uppercase. + Example: import "core:fmt" @@ -127,8 +131,6 @@ Output: TEST -**Returns** -A new string with all characters converted to uppercase. */ to_upper :: proc(s: string, allocator := context.allocator) -> string { b: Builder @@ -141,10 +143,10 @@ to_upper :: proc(s: string, allocator := context.allocator) -> string { /* Checks if the rune `r` is a delimiter (' ', '-', or '_'). -**Inputs** +Inputs: - r: Rune to check for delimiter status. -**Returns** +Returns: True if `r` is a delimiter, false otherwise. */ is_delimiter :: proc(r: rune) -> bool { @@ -153,10 +155,10 @@ is_delimiter :: proc(r: rune) -> bool { /* Checks if the rune `r` is a non-alphanumeric or space character. -**Inputs** +Inputs: - r: Rune to check for separator status. -**Returns** +Returns: True if `r` is a non-alpha or `unicode.is_space` rune. */ is_separator :: proc(r: rune) -> bool { @@ -184,7 +186,7 @@ is_separator :: proc(r: rune) -> bool { /* Iterates over a string, calling a callback for each rune with the previous, current, and next runes as arguments. -**Inputs** +Inputs: - w: An io.Writer to be used by the callback for writing output. - s: The input string to be iterated over. - callback: A procedure to be called for each rune in the string, with arguments (w: io.Writer, prev, curr, next: rune). @@ -246,11 +248,11 @@ Converts the input string `s` to "lowerCamelCase". *Allocates Using Provided Allocator* -**Inputs** +Inputs: - s: Input string to be converted. - allocator: (default: context.allocator). -**Returns** +Returns: A "lowerCamelCase" formatted string. */ to_camel_case :: proc(s: string, allocator := context.allocator) -> string { @@ -281,11 +283,11 @@ Converts the input string `s` to "UpperCamelCase" (PascalCase). *Allocates Using Provided Allocator* -**Inputs** +Inputs: - s: Input string to be converted. - allocator: (default: context.allocator). -**Returns** +Returns: A "PascalCase" formatted string. */ to_pascal_case :: proc(s: string, allocator := context.allocator) -> string { @@ -314,12 +316,15 @@ Returns a string converted to a delimiter-separated case with configurable casin *Allocates Using Provided Allocator* -**Inputs** +Inputs: - s: The input string to be converted - delimiter: The rune to be used as the delimiter between words - all_upper_case: A boolean indicating if the output should be all uppercased (true) or lowercased (false) - allocator: (default: context.allocator). +Returns: +The converted string + Example: import "core:fmt" @@ -337,8 +342,6 @@ Output: HELLO WORLD a_bc -**Returns** -The converted string */ to_delimiter_case :: proc( s: string, @@ -388,10 +391,13 @@ Converts a string to "snake_case" with all runes lowercased *Allocates Using Provided Allocator* -**Inputs** +Inputs: - s: The input string to be converted - allocator: (default: context.allocator). +Returns: +The converted string + Example: import "core:fmt" @@ -407,9 +413,6 @@ Output: hello_world hello_world -``` -**Returns** -The converted string */ to_snake_case :: proc(s: string, allocator := context.allocator) -> string { return to_delimiter_case(s, '_', false, allocator) @@ -421,10 +424,13 @@ Converts a string to "SNAKE_CASE" with all runes uppercased *Allocates Using Provided Allocator* -**Inputs** +Inputs: - s: The input string to be converted - allocator: (default: context.allocator). +Returns: +The converted string + Example: import "core:fmt" @@ -438,8 +444,6 @@ Output: HELLO_WORLD -**Returns** -The converted string */ to_upper_snake_case :: proc(s: string, allocator := context.allocator) -> string { return to_delimiter_case(s, '_', true, allocator) @@ -449,10 +453,13 @@ Converts a string to "kebab-case" with all runes lowercased *Allocates Using Provided Allocator* -**Inputs** +Inputs: - s: The input string to be converted - allocator: (default: context.allocator). +Returns: +The converted string + Example: import "core:fmt" @@ -466,8 +473,6 @@ Output: hello-world -**Returns** -The converted string */ to_kebab_case :: proc(s: string, allocator := context.allocator) -> string { return to_delimiter_case(s, '-', false, allocator) @@ -477,10 +482,13 @@ Converts a string to "KEBAB-CASE" with all runes uppercased *Allocates Using Provided Allocator* -**Inputs** +Inputs: - s: The input string to be converted - allocator: (default: context.allocator). +Returns: +The converted string + Example: import "core:fmt" @@ -494,8 +502,6 @@ Output: HELLO-WORLD -**Returns** -The converted string */ to_upper_kebab_case :: proc(s: string, allocator := context.allocator) -> string { return to_delimiter_case(s, '-', true, allocator) @@ -505,10 +511,13 @@ Converts a string to "Ada_Case" *Allocates Using Provided Allocator* -**Inputs** +Inputs: - s: The input string to be converted - allocator: (default: context.allocator). +Returns: +The converted string + Example: import "core:fmt" @@ -522,8 +531,6 @@ Output: Hello_World -**Returns** -The converted string */ to_ada_case :: proc(s: string, allocator := context.allocator) -> string { s := s diff --git a/core/strings/intern.odin b/core/strings/intern.odin index e73b33f07..463abeb1e 100644 --- a/core/strings/intern.odin +++ b/core/strings/intern.odin @@ -25,7 +25,7 @@ Initializes the entries map and sets the allocator for the string entries *Allocates Using Provided Allocators* -**Inputs** +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) @@ -37,7 +37,7 @@ intern_init :: proc(m: ^Intern, allocator := context.allocator, map_allocator := /* Frees the map and all its content allocated using the `.allocator`. -**Inputs** +Inputs: - m: A pointer to the Intern struct to be destroyed */ intern_destroy :: proc(m: ^Intern) { @@ -51,13 +51,13 @@ Returns an interned copy of the given text, adding it to the map if not already *Allocate using the Intern's Allocator (First time string is seen only)* -**Inputs** +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** +Returns: The interned string and an allocator error if any */ intern_get :: proc(m: ^Intern, text: string) -> (str: string, err: runtime.Allocator_Error) { @@ -69,13 +69,13 @@ Returns an interned copy of the given text as a cstring, adding it to the map if *Allocate using the Intern's Allocator (First time string is seen only)* -**Inputs** +Inputs: - m: A pointer to the Intern struct - text: The string to be interned NOTE: The returned cstring lives as long as the map entry lives -**Returns** +Returns: The interned cstring and an allocator error if any */ intern_get_cstring :: proc(m: ^Intern, text: string) -> (str: cstring, err: runtime.Allocator_Error) { @@ -88,11 +88,11 @@ Sets and allocates the entry if it wasn't set yet *Allocate using the Intern's Allocator (First time string is seen only)* -**Inputs** +Inputs: - m: A pointer to the Intern struct - text: The string to be looked up or interned -**Returns** +Returns: The new or existing interned entry and an allocator error if any */ _intern_get_entry :: proc(m: ^Intern, text: string) -> (new_entry: ^Intern_Entry, err: runtime.Allocator_Error) #no_bounds_check { diff --git a/core/strings/reader.odin b/core/strings/reader.odin index 917092ad6..715e57ada 100644 --- a/core/strings/reader.odin +++ b/core/strings/reader.odin @@ -16,7 +16,7 @@ Reader :: struct { /* Initializes a string Reader with the provided string -**Inputs** +Inputs: - r: A pointer to a Reader struct - s: The input string to be read */ @@ -28,10 +28,10 @@ reader_init :: proc(r: ^Reader, s: string) { /* Converts a Reader into an `io.Stream` -**Inputs** +Inputs: - r: A pointer to a Reader struct -**Returns** +Returns: An io.Stream for the given Reader */ reader_to_stream :: proc(r: ^Reader) -> (s: io.Stream) { @@ -42,11 +42,11 @@ reader_to_stream :: proc(r: ^Reader) -> (s: io.Stream) { /* Initializes a string Reader and returns an `io.Reader` for the given string -**Inputs** +Inputs: - r: A pointer to a Reader struct - s: The input string to be read -**Returns** +Returns: An io.Reader for the given string */ to_reader :: proc(r: ^Reader, s: string) -> io.Reader { @@ -57,11 +57,11 @@ to_reader :: proc(r: ^Reader, s: string) -> io.Reader { /* Initializes a string Reader and returns an `io.Reader_At` for the given string -**Inputs** +Inputs: - r: A pointer to a Reader struct - s: The input string to be read -**Returns** +Returns: An `io.Reader_At` for the given string */ to_reader_at :: proc(r: ^Reader, s: string) -> io.Reader_At { @@ -72,10 +72,10 @@ to_reader_at :: proc(r: ^Reader, s: string) -> io.Reader_At { /* Returns the remaining length of the Reader -**Inputs** +Inputs: - r: A pointer to a Reader struct -**Returns** +Returns: The remaining length of the Reader */ reader_length :: proc(r: ^Reader) -> int { @@ -87,10 +87,10 @@ reader_length :: proc(r: ^Reader) -> int { /* Returns the length of the string stored in the Reader -**Inputs** +Inputs: - r: A pointer to a Reader struct -**Returns** +Returns: The length of the string stored in the Reader */ reader_size :: proc(r: ^Reader) -> i64 { @@ -99,11 +99,11 @@ reader_size :: proc(r: ^Reader) -> i64 { /* Reads len(p) bytes from the Reader's string and copies into the provided slice. -**Inputs** +Inputs: - r: A pointer to a Reader struct - p: A byte slice to copy data into -**Returns** +Returns: - n: The number of bytes read - err: An `io.Error` if an error occurs while reading, including `.EOF`, otherwise `nil` denotes success. */ @@ -119,12 +119,12 @@ reader_read :: proc(r: ^Reader, p: []byte) -> (n: int, err: io.Error) { /* Reads len(p) bytes from the Reader's string and copies into the provided slice, at the specified offset from the current index. -**Inputs** +Inputs: - r: A pointer to a Reader struct - p: A byte slice to copy data into - off: The offset from which to read -**Returns** +Returns: - n: The number of bytes read - err: An `io.Error` if an error occurs while reading, including `.EOF`, otherwise `nil` denotes success. */ @@ -144,10 +144,10 @@ reader_read_at :: proc(r: ^Reader, p: []byte, off: i64) -> (n: int, err: io.Erro /* Reads and returns a single byte from the Reader's string -**Inputs** +Inputs: - r: A pointer to a Reader struct -**Returns** +Returns: - The byte read from the Reader - err: An `io.Error` if an error occurs while reading, including `.EOF`, otherwise `nil` denotes success. */ @@ -163,10 +163,10 @@ reader_read_byte :: proc(r: ^Reader) -> (byte, io.Error) { /* Decrements the Reader's index (i) by 1 -**Inputs** +Inputs: - r: A pointer to a Reader struct -**Returns** +Returns: An `io.Error` if `r.i <= 0` (`.Invalid_Unread`), otherwise `nil` denotes success. */ reader_unread_byte :: proc(r: ^Reader) -> io.Error { @@ -180,10 +180,10 @@ reader_unread_byte :: proc(r: ^Reader) -> io.Error { /* Reads and returns a single rune and its `size` from the Reader's string -**Inputs** +Inputs: - r: A pointer to a Reader struct -**Returns** +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 @@ -205,12 +205,12 @@ reader_read_rune :: proc(r: ^Reader) -> (rr: rune, size: int, err: io.Error) { /* Decrements the Reader's index (i) by the size of the last read rune -**Inputs** +Inputs: - r: A pointer to a Reader struct WARNING: May only be used once and after a valid `read_rune` call -**Returns** +Returns: An `io.Error` if an error occurs while unreading (`.Invalid_Unread`), else `nil` denotes success. */ reader_unread_rune :: proc(r: ^Reader) -> io.Error { @@ -227,12 +227,12 @@ reader_unread_rune :: proc(r: ^Reader) -> io.Error { /* Seeks the Reader's index to a new position -**Inputs** +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** +Returns: - The absolute offset after seeking - err: An `io.Error` if an error occurs while seeking (`.Invalid_Whence`, `.Invalid_Offset`) */ @@ -259,13 +259,13 @@ reader_seek :: proc(r: ^Reader, offset: i64, whence: io.Seek_From) -> (i64, io.E /* Writes the remaining content of the Reader's string into the provided `io.Writer` -**Inputs** +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** +Returns: - n: The number of bytes written - err: An io.Error if an error occurs while writing (`.Short_Write`) */ diff --git a/core/strings/strings.odin b/core/strings/strings.odin index 8cb046bd6..3c55374b7 100644 --- a/core/strings/strings.odin +++ b/core/strings/strings.odin @@ -11,12 +11,12 @@ Clones a string *Allocates Using Provided Allocator* -**Inputs** +Inputs: - s: The string to be cloned - allocator: (default: context.allocator) - loc: The caller location for debugging purposes (default: #caller_location) -**Returns** +Returns: A cloned string */ clone :: proc(s: string, allocator := context.allocator, loc := #caller_location) -> string { @@ -29,12 +29,12 @@ Clones a string safely (returns early with an allocation error on failure) *Allocates Using Provided Allocator* -**Inputs** +Inputs: - s: The string to be cloned - allocator: (default: context.allocator) - loc: The caller location for debugging purposes (default: #caller_location) -**Returns** +Returns: - str: A cloned string - err: A mem.Allocator_Error if an error occurs during allocation */ @@ -48,12 +48,12 @@ Clones a string and appends a null-byte to make it a cstring *Allocates Using Provided Allocator* -**Inputs** +Inputs: - s: The string to be cloned - allocator: (default: context.allocator) - loc: The caller location for debugging purposes (default: #caller_location) -**Returns** +Returns: A cloned cstring with an appended null-byte */ clone_to_cstring :: proc(s: string, allocator := context.allocator, loc := #caller_location) -> cstring { @@ -65,29 +65,29 @@ clone_to_cstring :: proc(s: string, allocator := context.allocator, loc := #call /* Transmutes a raw pointer into a string. Non-allocating. -**Inputs** +Inputs: - ptr: A pointer to the start of the byte sequence - len: The length of the byte sequence NOTE: The created string is only valid as long as the pointer and length are valid. -**Returns** +Returns: A string created from the byte pointer and length */ string_from_ptr :: proc(ptr: ^byte, len: int) -> string { return transmute(string)mem.Raw_String{ptr, len} } /* -Transmutes a raw pointer (null-terminated) into a string. Non-allocating. Searches for a null-byte from `0..<len`, otherwhise `len` will be the end size +Transmutes a raw pointer (null-terminated) into a string. Non-allocating. Searches for a null-byte from `0..<len`, otherwise `len` will be the end size NOTE: The created string is only valid as long as the pointer and length are valid. The string is truncated at the first null-byte encountered. -**Inputs** +Inputs: - ptr: A pointer to the start of the null-terminated byte sequence - len: The length of the byte sequence -**Returns** +Returns: A string created from the null-terminated byte pointer and length */ string_from_null_terminated_ptr :: proc(ptr: ^byte, len: int) -> string { @@ -98,10 +98,10 @@ string_from_null_terminated_ptr :: proc(ptr: ^byte, len: int) -> string { /* Gets the raw byte pointer for the start of a string `str` -**Inputs** +Inputs: - str: The input string -**Returns** +Returns: A pointer to the start of the string's bytes */ ptr_from_string :: proc(str: string) -> ^byte { @@ -111,12 +111,12 @@ ptr_from_string :: proc(str: string) -> ^byte { /* Converts a string `str` to a cstring -**Inputs** +Inputs: - str: The input string WARNING: This is unsafe because the original string may not contain a null-byte. -**Returns** +Returns: The converted cstring */ unsafe_string_to_cstring :: proc(str: string) -> cstring { @@ -126,13 +126,13 @@ unsafe_string_to_cstring :: proc(str: string) -> cstring { /* Truncates a string `str` at the first occurrence of char/byte `b` -**Inputs** +Inputs: - str: The input string - b: The byte to truncate the string at NOTE: Failure to find the byte results in returning the entire string. -**Returns** +Returns: The truncated string */ truncate_to_byte :: proc(str: string, b: byte) -> string { @@ -145,11 +145,11 @@ truncate_to_byte :: proc(str: string, b: byte) -> string { /* Truncates a string `str` at the first occurrence of rune `r` as a slice of the original, entire string if not found -**Inputs** +Inputs: - str: The input string - r: The rune to truncate the string at -**Returns** +Returns: The truncated string */ truncate_to_rune :: proc(str: string, r: rune) -> string { @@ -164,12 +164,12 @@ Clones a byte array `s` and appends a null-byte *Allocates Using Provided Allocator* -**Inputs** +Inputs: - s: The byte array to be cloned - allocator: (default: context.allocator) - loc: The caller location for debugging purposes (default: `#caller_location`) -**Returns** +Returns: A cloned string from the byte array with a null-byte */ clone_from_bytes :: proc(s: []byte, allocator := context.allocator, loc := #caller_location) -> string { @@ -183,12 +183,12 @@ Clones a cstring `s` as a string *Allocates Using Provided Allocator* -**Inputs** +Inputs: - s: The cstring to be cloned - allocator: (default: context.allocator) - loc: The caller location for debugging purposes (default: `#caller_location`) -**Returns** +Returns: A cloned string from the cstring */ clone_from_cstring :: proc(s: cstring, allocator := context.allocator, loc := #caller_location) -> string { @@ -199,7 +199,7 @@ Clones a string from a byte pointer `ptr` and a byte length `len` *Allocates Using Provided Allocator* -**Inputs** +Inputs: - ptr: A pointer to the start of the byte sequence - len: The length of the byte sequence - allocator: (default: context.allocator) @@ -207,7 +207,7 @@ Clones a string from a byte pointer `ptr` and a byte length `len` NOTE: Same as `string_from_ptr`, but perform an additional `clone` operation -**Returns** +Returns: A cloned string from the byte pointer and length */ clone_from_ptr :: proc(ptr: ^byte, len: int, allocator := context.allocator, loc := #caller_location) -> string { @@ -226,7 +226,7 @@ Clones a string from a null-terminated cstring `ptr` and a byte length `len` *Allocates Using Provided Allocator* -**Inputs** +Inputs: - ptr: A pointer to the start of the null-terminated cstring - len: The byte length of the cstring - allocator: (default: context.allocator) @@ -234,7 +234,7 @@ Clones a string from a null-terminated cstring `ptr` and a byte length `len` NOTE: Truncates at the first null-byte encountered or the byte length. -**Returns** +Returns: A cloned string from the null-terminated cstring and byte length */ clone_from_cstring_bounded :: proc(ptr: cstring, len: int, allocator := context.allocator, loc := #caller_location) -> string { @@ -246,11 +246,11 @@ clone_from_cstring_bounded :: proc(ptr: cstring, len: int, allocator := context. 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** +Inputs: - lhs: First string for comparison - rhs: Second string for comparison -**Returns** +Returns: -1 if `lhs` comes first, 1 if `rhs` comes first, or 0 if they are equal */ compare :: proc(lhs, rhs: string) -> int { @@ -259,11 +259,11 @@ compare :: proc(lhs, rhs: string) -> int { /* Returns the byte offset of the rune `r` in the string `s`, -1 when not found -**Inputs** +Inputs: - s: The input string - r: The rune to search for -**Returns** +Returns: The byte offset of the rune `r` in the string `s`, or -1 if not found */ contains_rune :: proc(s: string, r: rune) -> int { @@ -277,10 +277,13 @@ contains_rune :: proc(s: string, r: rune) -> int { /* Returns true when the string `substr` is contained inside the string `s` -**Inputs** +Inputs: - s: The input string - substr: The substring to search for +Returns: +`true` if `substr` is contained inside the string `s`, `false` otherwise + Example: import "core:fmt" @@ -298,8 +301,6 @@ Output: true false -**Returns** -`true` if `substr` is contained inside the string `s`, `false` otherwise */ contains :: proc(s, substr: string) -> bool { return index(s, substr) >= 0 @@ -307,10 +308,13 @@ contains :: proc(s, substr: string) -> bool { /* Returns `true` when the string `s` contains any of the characters inside the string `chars` -**Inputs** +Inputs: - s: The input string - chars: The characters to search for +Returns: +`true` if the string `s` contains any of the characters in `chars`, `false` otherwise + Example: import "core:fmt" @@ -330,8 +334,6 @@ Output: true false -**Returns** -`true` if the string `s` contains any of the characters in `chars`, `false` otherwise */ contains_any :: proc(s, chars: string) -> bool { return index_any(s, chars) >= 0 @@ -339,9 +341,12 @@ contains_any :: proc(s, chars: string) -> bool { /* Returns the UTF-8 rune count of the string `s` -**Inputs** +Inputs: - s: The input string +Returns: +The UTF-8 rune count of the string `s` + Example: import "core:fmt" @@ -357,8 +362,6 @@ Output: 4 5 -**Returns** -The UTF-8 rune count of the string `s` */ rune_count :: proc(s: string) -> int { return utf8.rune_count_in_string(s) @@ -367,10 +370,13 @@ rune_count :: proc(s: string) -> int { Returns whether the strings `u` and `v` are the same alpha characters, ignoring different casings Works with UTF-8 string content -**Inputs** +Inputs: - u: The first string for comparison - v: The second string for comparison +Returns: +`true` if the strings `u` and `v` are the same alpha characters (ignoring case) + Example: import "core:fmt" @@ -390,8 +396,6 @@ Output: true false -**Returns** -`true` if the strings `u` and `v` are the same alpha characters (ignoring case) */ equal_fold :: proc(u, v: string) -> bool { s, t := u, v @@ -438,10 +442,13 @@ equal_fold :: proc(u, v: string) -> bool { /* Returns the prefix length common between strings `a` and `b` -**Inputs** +Inputs: - a: The first input string - b: The second input string +Returns: +The prefix length common between strings `a` and `b` + Example: import "core:fmt" @@ -461,8 +468,6 @@ Output: 2 0 -**Returns** -The prefix length common between strings `a` and `b` */ prefix_length :: proc(a, b: string) -> (n: int) { _len := min(len(a), len(b)) @@ -490,10 +495,13 @@ prefix_length :: proc(a, b: string) -> (n: int) { /* Determines if a string `s` starts with a given `prefix` -**Inputs** +Inputs: - s: The string to check for the `prefix` - prefix: The prefix to look for +Returns: +`true` if the string `s` starts with the `prefix`, otherwise `false` + Example: import "core:fmt" @@ -513,8 +521,6 @@ Output: true false -**Returns** -`true` if the string `s` starts with the `prefix`, otherwise `false` */ has_prefix :: proc(s, prefix: string) -> bool { return len(s) >= len(prefix) && s[0:len(prefix)] == prefix @@ -522,6 +528,13 @@ has_prefix :: proc(s, prefix: string) -> bool { /* 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: +`true` if the string `s` ends with the `suffix`, otherwise `false` + Example: import "core:fmt" @@ -539,12 +552,6 @@ Output: false true -**Inputs** -- s: The string to check for the `suffix` -- suffix: The suffix to look for - -**Returns** -`true` if the string `s` ends with the `suffix`, otherwise `false` */ has_suffix :: proc(s, suffix: string) -> bool { return len(s) >= len(suffix) && s[len(s)-len(suffix):] == suffix @@ -554,6 +561,14 @@ 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: +A combined string from the slice of strings `a` separated with the `sep` string + Example: import "core:fmt" @@ -572,13 +587,6 @@ Output: a-b-c a...b...c -**Inputs** -- a: A slice of strings to join -- sep: The separator string -- allocator: (default is context.allocator) - -**Returns** -A combined string from the slice of strings `a` separated with the `sep` string */ join :: proc(a: []string, sep: string, allocator := context.allocator) -> string { if len(a) == 0 { @@ -603,12 +611,12 @@ Joins a slice of strings `a` with a `sep` string, returns an error on allocation *Allocates Using Provided Allocator* -**Inputs** +Inputs: - a: A slice of strings to join - sep: The separator string - allocator: (default is context.allocator) -**Returns** +Returns: - str: A combined string from the slice of strings `a` separated with the `sep` string - err: An error if allocation failed, otherwise `nil` */ @@ -635,10 +643,13 @@ Returns a combined string from the slice of strings `a` without a separator *Allocates Using Provided Allocator* -**Inputs** +Inputs: - a: A slice of strings to concatenate - allocator: (default is context.allocator) +Returns: +The concatenated string + Example: import "core:fmt" @@ -653,8 +664,6 @@ Output: abc -**Returns** -The concatenated string */ concatenate :: proc(a: []string, allocator := context.allocator) -> string { if len(a) == 0 { @@ -677,11 +686,11 @@ Returns a combined string from the slice of strings `a` without a separator, or *Allocates Using Provided Allocator* -**Inputs** +Inputs: - a: A slice of strings to concatenate - allocator: (default is context.allocator) -**Returns** +Returns: The concatenated string, and an error if allocation fails */ concatenate_safe :: proc(a: []string, allocator := context.allocator) -> (res: string, err: mem.Allocator_Error) { @@ -705,12 +714,15 @@ Returns a substring of the input string `s` with the specified rune offset and l *Allocates Using Provided Allocator* -**Inputs** +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) +Returns: +The substring + Example: import "core:fmt" @@ -728,8 +740,6 @@ Output: me example -**Returns** -The substring */ cut :: proc(s: string, rune_offset := int(0), rune_length := int(0), allocator := context.allocator) -> (res: string) { s := s; rune_length := rune_length @@ -789,7 +799,7 @@ Splits the input string `s` into a slice of substrings separated by the specifie *Used Internally - Private Function* -**Inputs** +Inputs: - s: The input string to split - sep: The separator string - sep_save: A flag determining if the separator should be saved in the resulting substrings @@ -798,7 +808,7 @@ Splits the input string `s` into a slice of substrings separated by the specifie NOTE: Allocation occurs for the array, the splits are all views of the original string. -**Returns** +Returns: A slice of substrings */ @private @@ -853,11 +863,15 @@ Splits a string into parts based on a separator. *Allocates Using Provided Allocator* -**Inputs** +Inputs: - s: The string to split. - sep: The separator string used to split the input string. - allocator: (default is context.allocator). +Returns: A slice of strings, each representing a part of the split string. + +NOTE: Allocation occurs for the array, the splits are all views of the original string. + Example: import "core:fmt" @@ -873,9 +887,6 @@ Output: ["aaa", "bbb", "ccc", "ddd", "eee"] -NOTE: Allocation occurs for the array, the splits are all views of the original string. - -**Returns** A slice of strings, each representing a part of the split string. */ split :: proc(s, sep: string, allocator := context.allocator) -> []string { return _split(s, sep, 0, -1, allocator) @@ -885,11 +896,15 @@ Splits a string into parts based on a separator. If n < count of seperators, the *Allocates Using Provided Allocator* -**Inputs** +Inputs: - s: The string to split. - sep: The separator string used to split the input string. - allocator: (default is context.allocator) +Returns: A slice of strings, each representing a part of the split string. + +NOTE: Allocation occurs for the array, the splits are all views of the original string. + Example: import "core:fmt" @@ -905,9 +920,6 @@ Output: ["aaa", "bbb", "ccc.ddd.eee"] -NOTE: Allocation occurs for the array, the splits are all views of the original string. - -**Returns** A slice of strings, each representing a part of the split string. */ split_n :: proc(s, sep: string, n: int, allocator := context.allocator) -> []string { return _split(s, sep, 0, n, allocator) @@ -917,11 +929,16 @@ Splits a string into parts after the separator, retaining it in the substrings. *Allocates Using Provided Allocator* -**Inputs** +Inputs: - s: The string to split. - sep: The separator string used to split the input string. - allocator: (default is context.allocator). +Returns: +A slice of strings, each representing a part of the split string after the separator. + +NOTE: Allocation occurs for the array, the splits are all views of the original string. + Example: import "core:fmt" @@ -937,10 +954,6 @@ Output: ["aaa.", "bbb.", "ccc.", "ddd.", "eee"] -NOTE: Allocation occurs for the array, the splits are all views of the original string. - -**Returns** -A slice of strings, each representing a part of the split string after the separator. */ split_after :: proc(s, sep: string, allocator := context.allocator) -> []string { return _split(s, sep, len(sep), -1, allocator) @@ -950,12 +963,17 @@ Splits a string into a total of `n` parts after the separator. *Allocates Using Provided Allocator* -**Inputs** +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) +Returns: +A slice of strings with `n` parts or fewer if there weren't + +NOTE: Allocation occurs for the array, the splits are all views of the original string. + Example: import "core:fmt" @@ -971,10 +989,6 @@ Output: ["aaa.", "bbb.", "ccc.ddd.eee"] -NOTE: Allocation occurs for the array, the splits are all views of the original string. - -**Returns** -A slice of strings with `n` parts or fewer if there weren't */ split_after_n :: proc(s, sep: string, n: int, allocator := context.allocator) -> []string { return _split(s, sep, len(sep), n, allocator) @@ -985,12 +999,12 @@ up to (but not including) the separator, as well as a boolean indicating success *Used Internally - Private Function* -**Inputs** +Inputs: - s: Pointer to the input string, which is modified during the search. - sep: The separator string to search for. - sep_save: Number of characters from the separator to include in the result. -**Returns** +Returns: A tuple containing the resulting substring and a boolean indicating success. */ @private @@ -1023,10 +1037,13 @@ _split_iterator :: proc(s: ^string, sep: string, sep_save: int) -> (res: string, /* Splits the input string by the byte separator in an iterator fashion. -**Inputs** +Inputs: - s: Pointer to the input string, which is modified during the search. - sep: The byte separator to search for. +Returns: +A tuple containing the resulting substring and a boolean indicating success. + Example: import "core:fmt" @@ -1047,8 +1064,6 @@ Output: d e -**Returns** -A tuple containing the resulting substring and a boolean indicating success. */ split_by_byte_iterator :: proc(s: ^string, sep: u8) -> (res: string, ok: bool) { m := index_byte(s^, sep) @@ -1068,10 +1083,13 @@ split_by_byte_iterator :: proc(s: ^string, sep: u8) -> (res: string, ok: bool) { Splits the input string by the separator string in an iterator fashion. Destructively consumes the original string until the end. -**Inputs** +Inputs: - s: Pointer to the input string, which is modified during the search. - sep: The separator string to search for. +Returns: +A tuple containing the resulting substring and a boolean indicating success. + Example: import "core:fmt" @@ -1092,8 +1110,6 @@ Output: d e -**Returns** -A tuple containing the resulting substring and a boolean indicating success. */ split_iterator :: proc(s: ^string, sep: string) -> (string, bool) { return _split_iterator(s, sep, 0) @@ -1102,10 +1118,13 @@ split_iterator :: proc(s: ^string, sep: string) -> (string, bool) { Splits the input string after every separator string in an iterator fashion. Destructively consumes the original string until the end. -**Inputs** +Inputs: - s: Pointer to the input string, which is modified during the search. - sep: The separator string to search for. +Returns: +A tuple containing the resulting substring and a boolean indicating success. + Example: import "core:fmt" @@ -1126,8 +1145,6 @@ Output: d. e -**Returns** -A tuple containing the resulting substring and a boolean indicating success. */ split_after_iterator :: proc(s: ^string, sep: string) -> (string, bool) { return _split_iterator(s, sep, len(sep)) @@ -1137,10 +1154,10 @@ Trims the carriage return character from the end of the input string. *Used Internally - Private Function* -**Inputs** +Inputs: - s: The input string to trim. -**Returns** +Returns: The trimmed string as a slice of the original. */ @(private) @@ -1158,10 +1175,13 @@ Splits the input string at every line break `\n`. *Allocates Using Provided Allocator* -**Inputs** +Inputs: - s: The input string to split. - allocator: (default is context.allocator) +Returns: +A slice (allocated) of the split string (slices into original string) + Example: import "core:fmt" @@ -1177,8 +1197,6 @@ Output: ["a", "b", "c", "d", "e"] -**Returns** -A slice (allocated) of the split string (slices into original string) */ split_lines :: proc(s: string, allocator := context.allocator) -> []string { sep :: "\n" @@ -1193,11 +1211,16 @@ Splits the input string at every line break `\n` for `n` parts. *Allocates Using Provided Allocator* -**Inputs** +Inputs: - s: The input string to split. - n: The number of parts to split into. - allocator: (default is context.allocator) +Returns: +A slice (allocated) of the split string (slices into original string) + +NOTE: Allocation occurs for the array, the splits are all views of the original string. + Example: import "core:fmt" @@ -1213,10 +1236,6 @@ Output: ["a", "b", "c\nd\ne"] -NOTE: Allocation occurs for the array, the splits are all views of the original string. - -**Returns** -A slice (allocated) of the split string (slices into original string) */ split_lines_n :: proc(s: string, n: int, allocator := context.allocator) -> []string { sep :: "\n" @@ -1231,10 +1250,15 @@ Splits the input string at every line break `\n` leaving the `\n` in the resulti *Allocates Using Provided Allocator* -**Inputs** +Inputs: - s: The input string to split. - allocator: (default is context.allocator) +Returns: +A slice (allocated) of the split string (slices into original string), with `\n` included. + +NOTE: Allocation occurs for the array, the splits are all views of the original string. + Example: import "core:fmt" @@ -1250,10 +1274,6 @@ Output: ["a\n", "b\n", "c\n", "d\n", "e"] -NOTE: Allocation occurs for the array, the splits are all views of the original string. - -**Returns** -A slice (allocated) of the split string (slices into original string), with `\n` included. */ split_lines_after :: proc(s: string, allocator := context.allocator) -> []string { sep :: "\n" @@ -1269,11 +1289,16 @@ Only runs for n parts. *Allocates Using Provided Allocator* -**Inputs** +Inputs: - s: The input string to split. - n: The number of parts to split into. - allocator: (default is context.allocator) +Returns: +A slice (allocated) of the split string (slices into original string), with `\n` included. + +NOTE: Allocation occurs for the array, the splits are all views of the original string. + Example: import "core:fmt" @@ -1289,10 +1314,6 @@ Output: ["a\n", "b\n", "c\nd\ne"] -NOTE: Allocation occurs for the array, the splits are all views of the original string. - -**Returns** -A slice (allocated) of the split string (slices into original string), with `\n` included. */ split_lines_after_n :: proc(s: string, n: int, allocator := context.allocator) -> []string { sep :: "\n" @@ -1306,9 +1327,12 @@ split_lines_after_n :: proc(s: string, n: int, allocator := context.allocator) - Splits the input string at every line break `\n`. Returns the current split string every iteration until the string is consumed. -**Inputs** +Inputs: - s: Pointer to the input string, which is modified during the search. +Returns: +A tuple containing the resulting substring and a boolean indicating success. + Example: import "core:fmt" @@ -1326,8 +1350,6 @@ Output: abcde -**Returns** -A tuple containing the resulting substring and a boolean indicating success. */ split_lines_iterator :: proc(s: ^string) -> (line: string, ok: bool) { sep :: "\n" @@ -1338,9 +1360,12 @@ split_lines_iterator :: proc(s: ^string) -> (line: string, ok: bool) { 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** +Inputs: - s: Pointer to the input string, which is modified during the search. +Returns: +A tuple containing the resulting substring with line breaks included and a boolean indicating success. + Example: import "core:fmt" @@ -1361,8 +1386,6 @@ Output: d e -**Returns** -A tuple containing the resulting substring with line breaks included and a boolean indicating success. */ split_lines_after_iterator :: proc(s: ^string) -> (line: string, ok: bool) { sep :: "\n" @@ -1373,10 +1396,13 @@ split_lines_after_iterator :: proc(s: ^string) -> (line: string, ok: bool) { 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** +Inputs: - s: The input string to search in. - c: The byte to search for. +Returns: +The byte offset of the first occurrence of `c` in `s`, or -1 if not found. + Example: import "core:fmt" @@ -1396,8 +1422,6 @@ Output: -1 -1 -**Returns** -The byte offset of the first occurrence of `c` in `s`, or -1 if not found. */ index_byte :: proc(s: string, c: byte) -> int { for i := 0; i < len(s); i += 1 { @@ -1409,6 +1433,14 @@ index_byte :: proc(s: string, c: byte) -> int { } /* 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: +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: @@ -1430,8 +1462,6 @@ Output: -1 -1 -**Returns** -The byte offset of the last occurrence of `c` in `s`, or -1 if not found. */ last_index_byte :: proc(s: string, c: byte) -> int { for i := len(s)-1; i >= 0; i -= 1 { @@ -1445,6 +1475,13 @@ last_index_byte :: proc(s: string, c: byte) -> int { 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: +The byte offset of the first occurrence of `r` in `s`, or -1 if not found. + Example: import "core:fmt" @@ -1472,8 +1509,6 @@ Output: 6 7 -**Returns** -The byte offset of the first occurrence of `r` in `s`, or -1 if not found. */ index_rune :: proc(s: string, r: rune) -> int { switch { @@ -1500,6 +1535,13 @@ index_rune :: proc(s: string, r: rune) -> int { /* 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: +The byte offset of the first occurrence of `substr` in `s`, or -1 if not found. + Example: import "core:fmt" @@ -1519,8 +1561,6 @@ Output: 2 -1 -**Returns** -The byte offset of the first occurrence of `substr` in `s`, or -1 if not found. */ index :: proc(s, substr: string) -> int { hash_str_rabin_karp :: proc(s: string) -> (hash: u32 = 0, pow: u32 = 1) { @@ -1574,6 +1614,13 @@ index :: proc(s, substr: string) -> int { /* 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: +The byte offset of the last occurrence of `substr` in `s`, or -1 if not found. + Example: import "core:fmt" @@ -1593,8 +1640,6 @@ Output: 2 -1 -**Returns** -The byte offset of the last occurrence of `substr` in `s`, or -1 if not found. */ last_index :: proc(s, substr: string) -> int { hash_str_rabin_karp_reverse :: proc(s: string) -> (hash: u32 = 0, pow: u32 = 1) { @@ -1646,6 +1691,13 @@ last_index :: proc(s, substr: string) -> int { /* 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: +The index of the first character of `chars` found in `s`, or -1 if not found. + Example: import "core:fmt" @@ -1667,8 +1719,6 @@ Output: 0 -1 -**Returns** -The index of the first character of `chars` found in `s`, or -1 if not found. */ index_any :: proc(s, chars: string) -> int { if chars == "" { @@ -1704,10 +1754,13 @@ index_any :: proc(s, chars: string) -> int { /* Finds the last occurrence of any character in `chars` within `s`. Iterates in reverse. -**Inputs** +Inputs: - s: The string to search in - chars: The characters to look for +Returns: +The index of the last matching character, or -1 if not found + Example: import "core:fmt" @@ -1729,8 +1782,6 @@ Output: 3 -1 -**Returns** -The index of the last matching character, or -1 if not found */ last_index_any :: proc(s, chars: string) -> int { if chars == "" { @@ -1783,11 +1834,11 @@ last_index_any :: proc(s, chars: string) -> int { /* Finds the first occurrence of any substring in `substrs` within `s` -**Inputs** +Inputs: - s: The string to search in - substrs: The substrings to look for -**Returns** +Returns: A tuple containing the index of the first matching substring, and its length (width) */ index_multi :: proc(s: string, substrs: []string) -> (idx: int, width: int) { @@ -1822,10 +1873,13 @@ index_multi :: proc(s: string, substrs: []string) -> (idx: int, width: int) { /* Counts the number of non-overlapping occurrences of `substr` in `s` -**Inputs** +Inputs: - s: The string to search in - substr: The substring to count +Returns: +The number of occurrences of `substr` in `s`, returns the rune_count + 1 of the string `s` on empty `substr` + Example: import "core:fmt" @@ -1847,8 +1901,6 @@ Output: 1 0 -**Returns** -The number of occurrences of `substr` in `s`, returns the rune_count + 1 of the string `s` on empty `substr` */ count :: proc(s, substr: string) -> int { if len(substr) == 0 { // special case @@ -1889,11 +1941,14 @@ Repeats the string `s` `count` times, concatenating the result *Allocates Using Provided Allocator* -**Inputs** +Inputs: - s: The string to repeat - count: The number of times to repeat `s` - allocator: (default is context.allocator) +Returns: +The concatenated repeated string + WARNING: Panics if count < 0 Example: @@ -1909,8 +1964,6 @@ Output: abcabc -**Returns** -The concatenated repeated string */ repeat :: proc(s: string, count: int, allocator := context.allocator) -> string { if count < 0 { @@ -1932,12 +1985,15 @@ Replaces all occurrences of `old` in `s` with `new` *Allocates Using Provided Allocator* -**Inputs** +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) +Returns: +A tuple containing the modified string and a boolean indicating if an allocation occurred during the replacement + Example: import "core:fmt" @@ -1955,8 +2011,6 @@ Output: xyzxyz false zzzz true -**Returns** -A tuple containing the modified string and a boolean indicating if an allocation occurred during the replacement */ replace_all :: proc(s, old, new: string, allocator := context.allocator) -> (output: string, was_allocation: bool) { return replace(s, old, new, -1, allocator) @@ -1966,13 +2020,16 @@ Replaces n instances of old in the string s with the new string *Allocates Using Provided Allocator* -**Inputs** +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) +Returns: +A tuple containing the modified string and a boolean indicating if an allocation occurred during the replacement + Example: import "core:fmt" @@ -1992,8 +2049,6 @@ Output: xyzxyz false zzzz true -**Returns** -A tuple containing the modified string and a boolean indicating if an allocation occurred during the replacement */ replace :: proc(s, old, new: string, n: int, allocator := context.allocator) -> (output: string, was_allocation: bool) { if old == new || n == 0 { @@ -2039,12 +2094,15 @@ Removes the key string `n` times from the `s` string *Allocates Using Provided Allocator* -**Inputs** +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) +Returns: +A tuple containing the modified string and a boolean indicating if an allocation occurred during the removal + Example: import "core:fmt" @@ -2064,8 +2122,6 @@ Output: bcbc true abcabc false -**Returns** -A tuple containing the modified string and a boolean indicating if an allocation occurred during the removal */ remove :: proc(s, key: string, n: int, allocator := context.allocator) -> (output: string, was_allocation: bool) { return replace(s, key, "", n, allocator) @@ -2075,11 +2131,14 @@ Removes all the `key` string instances from the `s` string *Allocates Using Provided Allocator* -**Inputs** +Inputs: - s: The input string - key: The substring to be removed - allocator: (default: context.allocator) +Returns: +A tuple containing the modified string and a boolean indicating if an allocation occurred during the removal + Example: import "core:fmt" @@ -2097,8 +2156,6 @@ Output: bcbc true abcabc false -**Returns** -A tuple containing the modified string and a boolean indicating if an allocation occurred during the removal */ remove_all :: proc(s, key: string, allocator := context.allocator) -> (output: string, was_allocation: bool) { return remove(s, key, -1, allocator) @@ -2138,11 +2195,14 @@ is_null :: proc(r: rune) -> bool { /* 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** +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: +The index of the first matching rune, or -1 if no match was found + Example: import "core:fmt" @@ -2167,8 +2227,6 @@ Output: 1 -1 -**Returns** -The index of the first matching rune, or -1 if no match was found */ index_proc :: proc(s: string, p: proc(rune) -> bool, truth := true) -> int { for r, i in s { @@ -2214,10 +2272,13 @@ last_index_proc_with_state :: proc(s: string, p: proc(rawptr, rune) -> bool, sta /* Trims the input string `s` from the left until the procedure `p` returns false -**Inputs** +Inputs: - s: The input string - p: A procedure that takes a rune and returns a boolean +Returns: +The trimmed string as a slice of the original + Example: import "core:fmt" @@ -2234,8 +2295,6 @@ Output: testing -**Returns** -The trimmed string as a slice of the original */ trim_left_proc :: proc(s: string, p: proc(rune) -> bool) -> string { i := index_proc(s, p, false) @@ -2247,12 +2306,12 @@ trim_left_proc :: proc(s: string, p: proc(rune) -> bool) -> string { /* Trims the input string `s` from the left until the procedure `p` with state returns false -**Inputs** +Inputs: - s: The input string - p: A procedure that takes a raw pointer and a rune and returns a boolean - state: The raw pointer to be passed to the procedure `p` -**Returns** +Returns: The trimmed string as a slice of the original */ trim_left_proc_with_state :: proc(s: string, p: proc(rawptr, rune) -> bool, state: rawptr) -> string { @@ -2265,10 +2324,13 @@ trim_left_proc_with_state :: proc(s: string, p: proc(rawptr, rune) -> bool, stat /* Trims the input string `s` from the right until the procedure `p` returns `false` -**Inputs** +Inputs: - s: The input string - p: A procedure that takes a rune and returns a boolean +Returns: +The trimmed string as a slice of the original + Example: import "core:fmt" @@ -2285,8 +2347,6 @@ Output: test -**Returns** -The trimmed string as a slice of the original */ trim_right_proc :: proc(s: string, p: proc(rune) -> bool) -> string { i := last_index_proc(s, p, false) @@ -2301,12 +2361,12 @@ trim_right_proc :: proc(s: string, p: proc(rune) -> bool) -> string { /* Trims the input string `s` from the right until the procedure `p` with state returns `false` -**Inputs** +Inputs: - s: The input string - p: A procedure that takes a raw pointer and a rune and returns a boolean - state: The raw pointer to be passed to the procedure `p` -**Returns** +Returns: The trimmed string as a slice of the original, empty when no match */ trim_right_proc_with_state :: proc(s: string, p: proc(rawptr, rune) -> bool, state: rawptr) -> string { @@ -2335,11 +2395,11 @@ is_in_cutset :: proc(state: rawptr, r: rune) -> bool { /* Trims the cutset string from the `s` string -**Inputs** +Inputs: - s: The input string - cutset: The set of characters to be trimmed from the left of the input string -**Returns** +Returns: The trimmed string as a slice of the original */ trim_left :: proc(s: string, cutset: string) -> string { @@ -2352,11 +2412,11 @@ trim_left :: proc(s: string, cutset: string) -> string { /* Trims the cutset string from the `s` string from the right -**Inputs** +Inputs: - s: The input string - cutset: The set of characters to be trimmed from the right of the input string -**Returns** +Returns: The trimmed string as a slice of the original */ trim_right :: proc(s: string, cutset: string) -> string { @@ -2369,11 +2429,11 @@ trim_right :: proc(s: string, cutset: string) -> string { /* Trims the cutset string from the `s` string, both from left and right -**Inputs** +Inputs: - s: The input string - cutset: The set of characters to be trimmed from both sides of the input string -**Returns** +Returns: The trimmed string as a slice of the original */ trim :: proc(s: string, cutset: string) -> string { @@ -2382,10 +2442,10 @@ trim :: proc(s: string, cutset: string) -> string { /* Trims until a valid non-space rune from the left, "\t\txyz\t\t" -> "xyz\t\t" -**Inputs** +Inputs: - s: The input string -**Returns** +Returns: The trimmed string as a slice of the original */ trim_left_space :: proc(s: string) -> string { @@ -2394,10 +2454,10 @@ trim_left_space :: proc(s: string) -> string { /* Trims from the right until a valid non-space rune, "\t\txyz\t\t" -> "\t\txyz" -**Inputs** +Inputs: - s: The input string -**Returns** +Returns: The trimmed string as a slice of the original */ trim_right_space :: proc(s: string) -> string { @@ -2406,10 +2466,10 @@ trim_right_space :: proc(s: string) -> string { /* Trims from both sides until a valid non-space rune, "\t\txyz\t\t" -> "xyz" -**Inputs** +Inputs: - s: The input string -**Returns** +Returns: The trimmed string as a slice of the original */ trim_space :: proc(s: string) -> string { @@ -2418,10 +2478,10 @@ trim_space :: proc(s: string) -> string { /* Trims null runes from the left, "\x00\x00testing\x00\x00" -> "testing\x00\x00" -**Inputs** +Inputs: - s: The input string -**Returns** +Returns: The trimmed string as a slice of the original */ trim_left_null :: proc(s: string) -> string { @@ -2430,10 +2490,10 @@ trim_left_null :: proc(s: string) -> string { /* Trims null runes from the right, "\x00\x00testing\x00\x00" -> "\x00\x00testing" -**Inputs** +Inputs: - s: The input string -**Returns** +Returns: The trimmed string as a slice of the original */ trim_right_null :: proc(s: string) -> string { @@ -2442,9 +2502,9 @@ trim_right_null :: proc(s: string) -> string { /* Trims null runes from both sides, "\x00\x00testing\x00\x00" -> "testing" -**Inputs** +Inputs: - s: The input string -**Returns** +Returns: The trimmed string as a slice of the original */ trim_null :: proc(s: string) -> string { @@ -2453,10 +2513,13 @@ trim_null :: proc(s: string) -> string { /* Trims a `prefix` string from the start of the `s` string and returns the trimmed string -**Inputs** +Inputs: - s: The input string - prefix: The prefix string to be removed +Returns: +The trimmed string as a slice of original, or the input string if no prefix was found + Example: import "core:fmt" @@ -2472,8 +2535,6 @@ Output: ing testing -**Returns** -The trimmed string as a slice of original, or the input string if no prefix was found */ trim_prefix :: proc(s, prefix: string) -> string { if has_prefix(s, prefix) { @@ -2484,10 +2545,13 @@ trim_prefix :: proc(s, prefix: string) -> string { /* Trims a `suffix` string from the end of the `s` string and returns the trimmed string -**Inputs** +Inputs: - s: The input string - suffix: The suffix string to be removed +Returns: +The trimmed string as a slice of original, or the input string if no suffix was found + Example: import "core:fmt" @@ -2503,8 +2567,6 @@ Output: todo todo.doc -**Returns** -The trimmed string as a slice of original, or the input string if no suffix was found */ trim_suffix :: proc(s, suffix: string) -> string { if has_suffix(s, suffix) { @@ -2517,11 +2579,14 @@ Splits the input string `s` by all possible `substrs` and returns an allocated a *Allocates Using Provided Allocator* -**Inputs** +Inputs: - s: The input string - substrs: An array of substrings used for splitting - allocator: (default is context.allocator) +Returns: +An array of strings, or nil on empty substring or no matches + NOTE: Allocation occurs for the array, the splits are all views of the original string. Example: @@ -2539,8 +2604,6 @@ Output: ["testing", "this", "out", "nice", "done", "last"] -**Returns** -An array of strings, or nil on empty substring or no matches */ split_multi :: proc(s: string, substrs: []string, allocator := context.allocator) -> []string #no_bounds_check { if s == "" || len(substrs) <= 0 { @@ -2585,10 +2648,13 @@ split_multi :: proc(s: string, substrs: []string, allocator := context.allocator /* Splits the input string `s` by all possible `substrs` in an iterator fashion. The full string is returned if no match. -**Inputs** +Inputs: - it: A pointer to the input string - substrs: An array of substrings used for splitting +Returns: +A tuple containing the split string and a boolean indicating success or failure + Example: import "core:fmt" @@ -2611,8 +2677,6 @@ Output: done last -**Returns** -A tuple containing the split string and a boolean indicating success or failure */ split_multi_iterate :: proc(it: ^string, substrs: []string) -> (res: string, ok: bool) #no_bounds_check { if it == nil || len(it) == 0 || len(substrs) <= 0 { @@ -2644,11 +2708,14 @@ Replaces invalid UTF-8 characters in the input string with a specified replaceme *Allocates Using Provided Allocator* -**Inputs** +Inputs: - s: The input string - replacement: The string used to replace invalid UTF-8 characters - allocator: (default is context.allocator) +Returns: +A new string with invalid UTF-8 characters replaced + Example: import "core:fmt" @@ -2663,8 +2730,6 @@ Output: Hello? -**Returns** -A new string with invalid UTF-8 characters replaced */ scrub :: proc(s: string, replacement: string, allocator := context.allocator) -> string { str := s @@ -2702,10 +2767,13 @@ Reverses the input string `s` *Allocates Using Provided Allocator* -**Inputs** +Inputs: - s: The input string - allocator: (default is context.allocator) +Returns: +A reversed version of the input string + Example: import "core:fmt" @@ -2721,8 +2789,6 @@ Output: abcxyz zyxcba -**Returns** -A reversed version of the input string */ reverse :: proc(s: string, allocator := context.allocator) -> string { str := s @@ -2743,11 +2809,16 @@ Expands the input string by replacing tab characters with spaces to align to a s *Allocates Using Provided Allocator* -**Inputs** +Inputs: - s: The input string - tab_size: The number of spaces to use for each tab character - allocator: (default is context.allocator) +Returns: +A new string with tab characters expanded to the specified tab size + +WARNING: Panics if tab_size <= 0 + Example: import "core:fmt" @@ -2762,10 +2833,6 @@ Output: abc1 abc2 abc3 -WARNING: Panics if tab_size <= 0 - -**Returns** -A new string with tab characters expanded to the specified tab size */ expand_tabs :: proc(s: string, tab_size: int, allocator := context.allocator) -> string { if tab_size <= 0 { @@ -2811,10 +2878,13 @@ expand_tabs :: proc(s: string, tab_size: int, allocator := context.allocator) -> /* Splits the input string `str` by the separator `sep` string and returns 3 parts. The values are slices of the original string. -**Inputs** +Inputs: - str: The input string - sep: The separator string +Returns: +A tuple with `head` (before the split), `match` (the separator), and `tail` (the end of the split) strings + Example: import "core:fmt" @@ -2840,8 +2910,6 @@ Output: true true -**Returns** -A tuple with `head` (before the split), `match` (the separator), and `tail` (the end of the split) strings */ partition :: proc(str, sep: string) -> (head, match, tail: string) { i := index(str, sep) @@ -2862,13 +2930,13 @@ Centers the input string within a field of specified length by adding pad string *Allocates Using Provided Allocator* -**Inputs** +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) -**Returns** +Returns: A new string centered within a field of the specified length */ centre_justify :: proc(str: string, length: int, pad: string, allocator := context.allocator) -> string { @@ -2897,13 +2965,13 @@ Left-justifies the input string within a field of specified length by adding pad *Allocates Using Provided Allocator* -**Inputs** +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) -**Returns** +Returns: A new string left-justified within a field of the specified length */ left_justify :: proc(str: string, length: int, pad: string, allocator := context.allocator) -> string { @@ -2931,13 +2999,13 @@ Right-justifies the input string within a field of specified length by adding pa *Allocates Using Provided Allocator* -**Inputs** +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) -**Returns** +Returns: A new string right-justified within a field of the specified length */ right_justify :: proc(str: string, length: int, pad: string, allocator := context.allocator) -> string { @@ -2963,7 +3031,7 @@ right_justify :: proc(str: string, length: int, pad: string, allocator := contex /* Writes a given pad string a specified number of times to an `io.Writer` -**Inputs** +Inputs: - w: The io.Writer to write the pad string to - pad: The pad string to be written - pad_len: The length of the pad string, in runes @@ -2991,11 +3059,11 @@ Splits a string into a slice of substrings at each instance of one or more conse *Allocates Using Provided Allocator* -**Inputs** +Inputs: - s: The input string - allocator: (default is context.allocator) -**Returns** +Returns: A slice of substrings of the input string, or an empty slice if the input string only contains white space */ fields :: proc(s: string, allocator := context.allocator) -> []string #no_bounds_check { @@ -3051,14 +3119,14 @@ Splits a string into a slice of substrings at each run of unicode code points `r *Allocates Using Provided Allocator* -**Inputs** +Inputs: - s: The input string - f: A predicate function to determine the split points - allocator: (default is context.allocator) 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** +Returns: 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 */ fields_proc :: proc(s: string, f: proc(rune) -> bool, allocator := context.allocator) -> []string #no_bounds_check { @@ -3090,10 +3158,10 @@ fields_proc :: proc(s: string, f: proc(rune) -> bool, allocator := context.alloc /* 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** +Inputs: - s: A mutable string reference to be iterated -**Returns** +Returns: - field: The first non-space substring found - ok: A boolean indicating if a non-space substring was found */ @@ -3132,11 +3200,11 @@ Computes the Levenshtein edit distance between two strings NOTE: Does not perform internal allocation if length of string `b`, in runes, is smaller than 64 -**Inputs** +Inputs: - a, b: The two strings to compare - allocator: (default is context.allocator) -**Returns** +Returns: The Levenshtein edit distance between the two strings NOTE: This implementation is a single-row-version of the Wagner–Fischer algorithm, based on C code by Martin Ettl. |