From e0d9092df840b14410b709e383b196ed2ac9b9e0 Mon Sep 17 00:00:00 2001 From: Lucas Perlind Date: Fri, 7 Apr 2023 17:35:21 +1000 Subject: [PATCH] Document return values of strings and add allocator errors where possible --- core/encoding/csv/writer.odin | 2 +- core/strings/ascii_set.odin | 4 +- core/strings/builder.odin | 130 ++-- core/strings/conversion.odin | 94 +-- core/strings/intern.odin | 18 +- core/strings/reader.odin | 30 +- core/strings/strings.odin | 611 ++++++++++-------- tests/core/strings/test_core_strings.odin | 38 +- tests/documentation/documentation_tester.odin | 2 +- 9 files changed, 504 insertions(+), 425 deletions(-) diff --git a/core/encoding/csv/writer.odin b/core/encoding/csv/writer.odin index 3a0038916..d519104f2 100644 --- a/core/encoding/csv/writer.odin +++ b/core/encoding/csv/writer.odin @@ -42,7 +42,7 @@ write :: proc(w: ^Writer, record: []string) -> io.Error { } } case: - if strings.contains_rune(field, w.comma) >= 0 { + if strings.contains_rune(field, w.comma) { return true } if strings.contains_any(field, CHAR_SET) { diff --git a/core/strings/ascii_set.odin b/core/strings/ascii_set.odin index c65ef1c61..247b38527 100644 --- a/core/strings/ascii_set.odin +++ b/core/strings/ascii_set.odin @@ -38,8 +38,8 @@ Inputs: - c: The char to check for in the Ascii_Set. Returns: -A boolean indicating if the byte is contained in the Ascii_Set (true) or not (false). +- res: 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 { +ascii_set_contains :: proc(as: Ascii_Set, c: byte) -> (res: bool) #no_bounds_check { return as[c>>5] & (1<<(c&31)) != 0 } diff --git a/core/strings/builder.odin b/core/strings/builder.odin index 32442c21a..90cc4ebdc 100644 --- a/core/strings/builder.odin +++ b/core/strings/builder.odin @@ -3,6 +3,7 @@ package strings import "core:runtime" import "core:unicode/utf8" import "core:strconv" +import "core:mem" import "core:io" /* Type definition for a procedure that flushes a Builder @@ -31,10 +32,11 @@ Inputs: - allocator: (default is context.allocator) Returns: -A new Builder +- res: The new Builder +- err: An optional allocator error if one occured, `nil` otherwise */ -builder_make_none :: proc(allocator := context.allocator) -> Builder { - return Builder{buf=make([dynamic]byte, allocator)} +builder_make_none :: proc(allocator := context.allocator) -> (res: Builder, err: mem.Allocator_Error) #optional_allocator_error { + return Builder{buf=make([dynamic]byte, allocator) or_return }, nil } /* Produces a Builder with a specified length and cap of max(16,len) byte buffer @@ -46,10 +48,11 @@ Inputs: - allocator: (default is context.allocator) Returns: -A new Builder +- res: The new Builder +- err: An optional allocator error if one occured, `nil` otherwise */ -builder_make_len :: proc(len: int, allocator := context.allocator) -> Builder { - return Builder{buf=make([dynamic]byte, len, allocator)} +builder_make_len :: proc(len: int, allocator := context.allocator) -> (res: Builder, err: mem.Allocator_Error) #optional_allocator_error { + return Builder{buf=make([dynamic]byte, len, allocator) or_return }, nil } /* Produces a Builder with a specified length and cap @@ -62,10 +65,11 @@ Inputs: - allocator: (default is context.allocator) Returns: -A new Builder +- res: The new Builder +- err: An optional allocator error if one occured, `nil` otherwise */ -builder_make_len_cap :: proc(len, cap: int, allocator := context.allocator) -> Builder { - return Builder{buf=make([dynamic]byte, len, cap, allocator)} +builder_make_len_cap :: proc(len, cap: int, allocator := context.allocator) -> (res: Builder, err: mem.Allocator_Error) #optional_allocator_error { + return Builder{buf=make([dynamic]byte, len, cap, allocator) or_return }, nil } // overload simple `builder_make_*` with or without len / cap parameters builder_make :: proc{ @@ -84,11 +88,12 @@ Inputs: - allocator: (default is context.allocator) Returns: -initialized ^Builder +- res: A pointer to the initialized Builder +- err: An optional allocator error if one occured, `nil` otherwise */ -builder_init_none :: proc(b: ^Builder, allocator := context.allocator) -> ^Builder { - b.buf = make([dynamic]byte, allocator) - return b +builder_init_none :: proc(b: ^Builder, allocator := context.allocator) -> (res: ^Builder, err: mem.Allocator_Error) #optional_allocator_error { + b.buf = make([dynamic]byte, allocator) or_return + return b, nil } /* Initializes a Builder with a specified length and cap, which is max(len,16) @@ -102,11 +107,12 @@ Inputs: - allocator: (default is context.allocator) Returns: -Initialized ^Builder +- res: A pointer to the initialized Builder +- err: An optional allocator error if one occured, `nil` otherwise */ -builder_init_len :: proc(b: ^Builder, len: int, allocator := context.allocator) -> ^Builder { - b.buf = make([dynamic]byte, len, allocator) - return b +builder_init_len :: proc(b: ^Builder, len: int, allocator := context.allocator) -> (res: ^Builder, err: mem.Allocator_Error) #optional_allocator_error { + b.buf = make([dynamic]byte, len, allocator) or_return + return b, nil } /* Initializes a Builder with a specified length and cap @@ -119,11 +125,12 @@ Inputs: - allocator: (default is context.allocator) Returns: -A pointer to the initialized Builder +- res: A pointer to the initialized Builder +- err: An optional allocator error if one occured, `nil` otherwise */ -builder_init_len_cap :: proc(b: ^Builder, len, cap: int, allocator := context.allocator) -> ^Builder { - b.buf = make([dynamic]byte, len, cap, allocator) - return b +builder_init_len_cap :: proc(b: ^Builder, len, cap: int, allocator := context.allocator) -> (res: ^Builder, err: mem.Allocator_Error) #optional_allocator_error { + b.buf = make([dynamic]byte, len, cap, allocator) or_return + return b, nil } // Overload simple `builder_init_*` with or without len / ap parameters builder_init :: proc{ @@ -169,9 +176,9 @@ Inputs: - b: A pointer to the Builder Returns: -An io.Stream +- res: the io.Stream */ -to_stream :: proc(b: ^Builder) -> io.Stream { +to_stream :: proc(b: ^Builder) -> (res: io.Stream) { return io.Stream{stream_vtable=_builder_stream_vtable, stream_data=b} } /* @@ -180,10 +187,10 @@ Returns an io.Writer from a Builder Inputs: - b: A pointer to the Builder -Returns: -An io.Writer +Returns: +- res: The io.Writer */ -to_writer :: proc(b: ^Builder) -> io.Writer { +to_writer :: proc(b: ^Builder) -> (res: io.Writer) { return io.to_writer(to_stream(b)) } /* @@ -224,7 +231,7 @@ Inputs: - backing: A slice of bytes to be used as the backing buffer Returns: -A new Builder +- res: The new Builder Example: @@ -245,17 +252,8 @@ Output: ab */ -builder_from_bytes :: proc(backing: []byte) -> Builder { - s := transmute(runtime.Raw_Slice)backing - d := runtime.Raw_Dynamic_Array{ - data = s.data, - len = 0, - cap = s.len, - allocator = runtime.nil_allocator(), - } - return Builder{ - buf = transmute([dynamic]byte)d, - } +builder_from_bytes :: proc(backing: []byte) -> (res: Builder) { + return Builder{ buf = mem.buffer_from_slice(backing) } } // Alias to `builder_from_bytes` builder_from_slice :: builder_from_bytes @@ -266,9 +264,9 @@ Inputs: - b: A Builder Returns: -The contents of the Builder's buffer, as a string +- res: The contents of the Builder's buffer, as a string */ -to_string :: proc(b: Builder) -> string { +to_string :: proc(b: Builder) -> (res: string) { return string(b.buf[:]) } /* @@ -278,9 +276,9 @@ Inputs: - b: A Builder Returns: -The length of the Builder's buffer +- res: The length of the Builder's buffer */ -builder_len :: proc(b: Builder) -> int { +builder_len :: proc(b: Builder) -> (res: int) { return len(b.buf) } /* @@ -290,9 +288,9 @@ Inputs: - b: A Builder Returns: -The capacity of the Builder's buffer +- res: The capacity of the Builder's buffer */ -builder_cap :: proc(b: Builder) -> int { +builder_cap :: proc(b: Builder) -> (res: int) { return cap(b.buf) } /* @@ -302,9 +300,9 @@ Inputs: - b: A Builder Returns: -The available space left in the Builder's buffer +- res: The available space left in the Builder's buffer */ -builder_space :: proc(b: Builder) -> int { +builder_space :: proc(b: Builder) -> (res: int) { return cap(b.buf) - len(b.buf) } /* @@ -315,7 +313,7 @@ Inputs: - x: The byte to be appended Returns: -The number of bytes appended +- n: 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. @@ -364,7 +362,7 @@ Example: 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 +- n: The number of bytes appended */ write_bytes :: proc(b: ^Builder, x: []byte) -> (n: int) { n0 := len(b.buf) @@ -380,7 +378,8 @@ Inputs: - r: The rune to be appended Returns: -The number of bytes written and an io.Error (if any) +- res: The number of bytes written +- err: An io.Error if one occured, `nil` otherwise NOTE: The backing dynamic array may be fixed in capacity or fail to resize, `n` states the number actually written. @@ -401,7 +400,7 @@ Output: äb */ -write_rune :: proc(b: ^Builder, r: rune) -> (int, io.Error) { +write_rune :: proc(b: ^Builder, r: rune) -> (res: int, err: io.Error) { return io.write_rune(to_writer(b), r) } /* @@ -412,7 +411,7 @@ Inputs: - r: The rune to be appended Returns: -The number of bytes written +- n: 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. @@ -445,7 +444,7 @@ Inputs: - s: The string to be appended Returns: -The number of bytes written +- n: 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. @@ -479,7 +478,7 @@ Inputs: - b: A pointer to the Builder Returns: -The last byte in the Builder or 0 if empty +- r: The last byte in the Builder or 0 if empty */ pop_byte :: proc(b: ^Builder) -> (r: byte) { if len(b.buf) == 0 { @@ -498,7 +497,8 @@ Inputs: - b: A pointer to the Builder Returns: -The popped rune and its rune width or (0, 0) if empty +- r: The popped rune +- width: The rune width or 0 if the builder was empty */ pop_rune :: proc(b: ^Builder) -> (r: rune, width: int) { if len(b.buf) == 0 { @@ -519,7 +519,7 @@ Inputs: - quote: The optional quote character (default is double quotes) Returns: -The number of bytes written +- n: 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. @@ -554,7 +554,7 @@ Inputs: - write_quote: Optional boolean flag to wrap in single-quotes (') (default is true) Returns: -The number of bytes written +- n: 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. @@ -598,7 +598,7 @@ Inputs: 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 +- n: The number of bytes written */ write_escaped_rune :: proc(b: ^Builder, r: rune, quote: byte, html_safe := false) -> (n: int) { n, _ = io.write_escaped_rune(to_writer(b), r, quote, html_safe) @@ -618,7 +618,7 @@ Inputs: 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 +- n: The number of characters written */ write_float :: proc(b: ^Builder, f: f64, fmt: byte, prec, bit_size: int, always_signed := false) -> (n: int) { buf: [384]byte @@ -642,7 +642,7 @@ Inputs: 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 +- n: The number of characters written */ write_f16 :: proc(b: ^Builder, f: f16, fmt: byte, always_signed := false) -> (n: int) { buf: [384]byte @@ -662,7 +662,7 @@ Inputs: - always_signed: Optional boolean flag to always include the sign Returns: -The number of characters written +- n: 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. @@ -704,7 +704,7 @@ Inputs: 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 +- n: The number of characters written */ write_f64 :: proc(b: ^Builder, f: f64, fmt: byte, always_signed := false) -> (n: int) { buf: [384]byte @@ -725,7 +725,7 @@ Inputs: 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 +- n: The number of characters written */ write_u64 :: proc(b: ^Builder, i: u64, base: int = 10) -> (n: int) { buf: [32]byte @@ -743,7 +743,7 @@ Inputs: 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 +- n: The number of characters written */ write_i64 :: proc(b: ^Builder, i: i64, base: int = 10) -> (n: int) { buf: [32]byte @@ -761,7 +761,7 @@ Inputs: 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 +- n: The number of characters written */ write_uint :: proc(b: ^Builder, i: uint, base: int = 10) -> (n: int) { return write_u64(b, u64(i), base) @@ -777,7 +777,7 @@ Inputs: 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 +- n: The number of characters written */ write_int :: proc(b: ^Builder, i: int, base: int = 10) -> (n: int) { return write_i64(b, i64(i), base) diff --git a/core/strings/conversion.odin b/core/strings/conversion.odin index 0160c8a60..2e82fff58 100644 --- a/core/strings/conversion.odin +++ b/core/strings/conversion.odin @@ -1,6 +1,7 @@ package strings import "core:io" +import "core:mem" import "core:unicode" import "core:unicode/utf8" @@ -17,15 +18,16 @@ Inputs: WARNING: Allocation does not occur when len(s) == 0 Returns: -A valid UTF-8 string with invalid sequences replaced by `replacement`. +- res: A valid UTF-8 string with invalid sequences replaced by `replacement`. +- err: An optional allocator error if one occured, `nil` otherwise */ -to_valid_utf8 :: proc(s, replacement: string, allocator := context.allocator) -> string { +to_valid_utf8 :: proc(s, replacement: string, allocator := context.allocator) -> (res: string, err: mem.Allocator_Error) #optional_allocator_error { if len(s) == 0 { - return "" + return "", nil } b: Builder - builder_init(&b, 0, 0, allocator) + builder_init(&b, 0, 0, allocator) or_return s := s for c, i in s { @@ -70,7 +72,7 @@ to_valid_utf8 :: proc(s, replacement: string, allocator := context.allocator) -> write_string(&b, s[i:][:w]) i += w } - return to_string(b) + return to_string(b), nil } /* Converts the input string `s` to all lowercase characters. @@ -82,7 +84,8 @@ Inputs: - allocator: (default: context.allocator). Returns: -A new string with all characters converted to lowercase. +- res: The new string with all characters converted to lowercase +- err: An optional allocator error if one occured, `nil` otherwise Example: @@ -98,13 +101,13 @@ Output: test */ -to_lower :: proc(s: string, allocator := context.allocator) -> string { +to_lower :: proc(s: string, allocator := context.allocator) -> (res: string, err: mem.Allocator_Error) #optional_allocator_error { b: Builder - builder_init(&b, 0, len(s), allocator) + builder_init(&b, 0, len(s), allocator) or_return for r in s { write_rune(&b, unicode.to_lower(r)) } - return to_string(b) + return to_string(b), nil } /* Converts the input string `s` to all uppercase characters. @@ -116,7 +119,8 @@ Inputs: - allocator: (default: context.allocator). Returns: -A new string with all characters converted to uppercase. +- res: The new string with all characters converted to uppercase +- err: An optional allocator error if one occured, `nil` otherwise Example: @@ -132,13 +136,13 @@ Output: TEST */ -to_upper :: proc(s: string, allocator := context.allocator) -> string { +to_upper :: proc(s: string, allocator := context.allocator) -> (res: string, err: mem.Allocator_Error) #optional_allocator_error { b: Builder - builder_init(&b, 0, len(s), allocator) + builder_init(&b, 0, len(s), allocator) or_return for r in s { write_rune(&b, unicode.to_upper(r)) } - return to_string(b) + return to_string(b), nil } /* Checks if the rune `r` is a delimiter (' ', '-', or '_'). @@ -147,9 +151,9 @@ Inputs: - r: Rune to check for delimiter status. Returns: -True if `r` is a delimiter, false otherwise. +- res: True if `r` is a delimiter, false otherwise. */ -is_delimiter :: proc(r: rune) -> bool { +is_delimiter :: proc(r: rune) -> (res: bool) { return r == '-' || r == '_' || is_space(r) } /* @@ -159,9 +163,9 @@ Inputs: - r: Rune to check for separator status. Returns: -True if `r` is a non-alpha or `unicode.is_space` rune. +- res: True if `r` is a non-alpha or `unicode.is_space` rune. */ -is_separator :: proc(r: rune) -> bool { +is_separator :: proc(r: rune) -> (res: bool) { if r <= 0x7f { switch r { case '0' ..= '9': @@ -253,13 +257,14 @@ Inputs: - allocator: (default: context.allocator). Returns: -A "lowerCamelCase" formatted string. +- res: The converted string +- err: An optional allocator error if one occured, `nil` otherwise */ -to_camel_case :: proc(s: string, allocator := context.allocator) -> string { +to_camel_case :: proc(s: string, allocator := context.allocator) -> (res: string, err: mem.Allocator_Error) #optional_allocator_error { s := s s = trim_space(s) b: Builder - builder_init(&b, 0, len(s), allocator) + builder_init(&b, 0, len(s), allocator) or_return w := to_writer(&b) string_case_iterator(w, s, proc(w: io.Writer, prev, curr, next: rune) { @@ -274,7 +279,7 @@ to_camel_case :: proc(s: string, allocator := context.allocator) -> string { } }) - return to_string(b) + return to_string(b), nil } // Alias to `to_pascal_case` to_upper_camel_case :: to_pascal_case @@ -288,13 +293,14 @@ Inputs: - allocator: (default: context.allocator). Returns: -A "PascalCase" formatted string. +- res: The converted string +- err: An optional allocator error if one occured, `nil` otherwise */ -to_pascal_case :: proc(s: string, allocator := context.allocator) -> string { +to_pascal_case :: proc(s: string, allocator := context.allocator) -> (res: string, err: mem.Allocator_Error) #optional_allocator_error { s := s s = trim_space(s) b: Builder - builder_init(&b, 0, len(s), allocator) + builder_init(&b, 0, len(s), allocator) or_return w := to_writer(&b) string_case_iterator(w, s, proc(w: io.Writer, prev, curr, next: rune) { @@ -309,7 +315,7 @@ to_pascal_case :: proc(s: string, allocator := context.allocator) -> string { } }) - return to_string(b) + return to_string(b), nil } /* Returns a string converted to a delimiter-separated case with configurable casing @@ -323,7 +329,8 @@ Inputs: - allocator: (default: context.allocator). Returns: -The converted string +- res: The converted string +- err: An optional allocator error if one occured, `nil` otherwise Example: @@ -348,11 +355,11 @@ to_delimiter_case :: proc( delimiter: rune, all_upper_case: bool, allocator := context.allocator, -) -> string { +) -> (res: string, err: mem.Allocator_Error) #optional_allocator_error { s := s s = trim_space(s) b: Builder - builder_init(&b, 0, len(s), allocator) + builder_init(&b, 0, len(s), allocator) or_return w := to_writer(&b) adjust_case := unicode.to_upper if all_upper_case else unicode.to_lower @@ -384,7 +391,7 @@ to_delimiter_case :: proc( io.write_rune(w, adjust_case(curr)) } - return to_string(b) + return to_string(b), nil } /* Converts a string to "snake_case" with all runes lowercased @@ -396,7 +403,8 @@ Inputs: - allocator: (default: context.allocator). Returns: -The converted string +- res: The converted string +- err: An optional allocator error if one occured, `nil` otherwise Example: @@ -414,7 +422,7 @@ Output: hello_world */ -to_snake_case :: proc(s: string, allocator := context.allocator) -> string { +to_snake_case :: proc(s: string, allocator := context.allocator) -> (res: string, err: mem.Allocator_Error) #optional_allocator_error { return to_delimiter_case(s, '_', false, allocator) } // Alias for `to_upper_snake_case` @@ -429,7 +437,8 @@ Inputs: - allocator: (default: context.allocator). Returns: -The converted string +- res: The converted string +- err: An optional allocator error if one occured, `nil` otherwise Example: @@ -445,7 +454,7 @@ Output: HELLO_WORLD */ -to_upper_snake_case :: proc(s: string, allocator := context.allocator) -> string { +to_upper_snake_case :: proc(s: string, allocator := context.allocator) -> (res: string, err: mem.Allocator_Error) #optional_allocator_error { return to_delimiter_case(s, '_', true, allocator) } /* @@ -458,7 +467,8 @@ Inputs: - allocator: (default: context.allocator). Returns: -The converted string +- res: The converted string +- err: An optional allocator error if one occured, `nil` otherwise Example: @@ -474,7 +484,7 @@ Output: hello-world */ -to_kebab_case :: proc(s: string, allocator := context.allocator) -> string { +to_kebab_case :: proc(s: string, allocator := context.allocator) -> (res: string, err: mem.Allocator_Error) #optional_allocator_error { return to_delimiter_case(s, '-', false, allocator) } /* @@ -487,7 +497,8 @@ Inputs: - allocator: (default: context.allocator). Returns: -The converted string +- res: The converted string +- err: An optional allocator error if one occured, `nil` otherwise Example: @@ -503,7 +514,7 @@ Output: HELLO-WORLD */ -to_upper_kebab_case :: proc(s: string, allocator := context.allocator) -> string { +to_upper_kebab_case :: proc(s: string, allocator := context.allocator) -> (res: string, err: mem.Allocator_Error) #optional_allocator_error { return to_delimiter_case(s, '-', true, allocator) } /* @@ -516,7 +527,8 @@ Inputs: - allocator: (default: context.allocator). Returns: -The converted string +- res: The converted string +- err: An optional allocator error if one occured, `nil` otherwise Example: @@ -532,11 +544,11 @@ Output: Hello_World */ -to_ada_case :: proc(s: string, allocator := context.allocator) -> string { +to_ada_case :: proc(s: string, allocator := context.allocator) -> (res: string, err: mem.Allocator_Error) #optional_allocator_error { s := s s = trim_space(s) b: Builder - builder_init(&b, 0, len(s), allocator) + builder_init(&b, 0, len(s), allocator) or_return w := to_writer(&b) string_case_iterator(w, s, proc(w: io.Writer, prev, curr, next: rune) { @@ -552,5 +564,5 @@ to_ada_case :: proc(s: string, allocator := context.allocator) -> string { } }) - return to_string(b) + return to_string(b), nil } diff --git a/core/strings/intern.odin b/core/strings/intern.odin index 463abeb1e..73f91d4d4 100644 --- a/core/strings/intern.odin +++ b/core/strings/intern.odin @@ -1,6 +1,7 @@ package strings import "core:runtime" +import "core:mem" // Custom string entry struct Intern_Entry :: struct { @@ -29,10 +30,14 @@ 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) + +Returns: +- err: An allocator error if one occured, `nil` otherwise */ -intern_init :: proc(m: ^Intern, allocator := context.allocator, map_allocator := context.allocator) { +intern_init :: proc(m: ^Intern, allocator := context.allocator, map_allocator := context.allocator) -> (err: mem.Allocator_Error) { m.allocator = allocator - m.entries = make(map[string]^Intern_Entry, 16, map_allocator) + m.entries = make(map[string]^Intern_Entry, 16, map_allocator) or_return + return nil } /* Frees the map and all its content allocated using the `.allocator`. @@ -58,7 +63,8 @@ Inputs: NOTE: The returned string lives as long as the map entry lives. Returns: -The interned string and an allocator error if any +- str: The interned string +- err: An allocator error if one occured, `nil` otherwise */ intern_get :: proc(m: ^Intern, text: string) -> (str: string, err: runtime.Allocator_Error) { entry := _intern_get_entry(m, text) or_return @@ -76,7 +82,8 @@ Inputs: NOTE: The returned cstring lives as long as the map entry lives Returns: -The interned cstring and an allocator error if any +- str: The interned cstring +- err: An allocator error if one occured, `nil` otherwise */ intern_get_cstring :: proc(m: ^Intern, text: string) -> (str: cstring, err: runtime.Allocator_Error) { entry := _intern_get_entry(m, text) or_return @@ -93,7 +100,8 @@ Inputs: - text: The string to be looked up or interned Returns: -The new or existing interned entry and an allocator error if any +- new_entry: The interned cstring +- err: An allocator error if one occured, `nil` otherwise */ _intern_get_entry :: proc(m: ^Intern, text: string) -> (new_entry: ^Intern_Entry, err: runtime.Allocator_Error) #no_bounds_check { if prev, ok := m.entries[text]; ok { diff --git a/core/strings/reader.odin b/core/strings/reader.odin index 715e57ada..081e59b4b 100644 --- a/core/strings/reader.odin +++ b/core/strings/reader.odin @@ -32,7 +32,7 @@ Inputs: - r: A pointer to a Reader struct Returns: -An io.Stream for the given Reader +- s: An io.Stream for the given Reader */ reader_to_stream :: proc(r: ^Reader) -> (s: io.Stream) { s.stream_data = r @@ -47,9 +47,9 @@ Inputs: - s: The input string to be read Returns: -An io.Reader for the given string +- res: An io.Reader for the given string */ -to_reader :: proc(r: ^Reader, s: string) -> io.Reader { +to_reader :: proc(r: ^Reader, s: string) -> (res: io.Reader) { reader_init(r, s) rr, _ := io.to_reader(reader_to_stream(r)) return rr @@ -62,9 +62,9 @@ Inputs: - s: The input string to be read Returns: -An `io.Reader_At` for the given string +- res: An `io.Reader_At` for the given string */ -to_reader_at :: proc(r: ^Reader, s: string) -> io.Reader_At { +to_reader_at :: proc(r: ^Reader, s: string) -> (res: io.Reader_At) { reader_init(r, s) rr, _ := io.to_reader_at(reader_to_stream(r)) return rr @@ -76,9 +76,9 @@ Inputs: - r: A pointer to a Reader struct Returns: -The remaining length of the Reader +- res: The remaining length of the Reader */ -reader_length :: proc(r: ^Reader) -> int { +reader_length :: proc(r: ^Reader) -> (res: int) { if r.i >= i64(len(r.s)) { return 0 } @@ -91,9 +91,9 @@ Inputs: - r: A pointer to a Reader struct Returns: -The length of the string stored in the Reader +- res: The length of the string stored in the Reader */ -reader_size :: proc(r: ^Reader) -> i64 { +reader_size :: proc(r: ^Reader) -> (res: i64) { return i64(len(r.s)) } /* @@ -151,7 +151,7 @@ Returns: - The byte read from the Reader - err: An `io.Error` if an error occurs while reading, including `.EOF`, otherwise `nil` denotes success. */ -reader_read_byte :: proc(r: ^Reader) -> (byte, io.Error) { +reader_read_byte :: proc(r: ^Reader) -> (res: byte, err: io.Error) { r.prev_rune = -1 if r.i >= i64(len(r.s)) { return 0, .EOF @@ -167,9 +167,9 @@ Inputs: - r: A pointer to a Reader struct Returns: -An `io.Error` if `r.i <= 0` (`.Invalid_Unread`), otherwise `nil` denotes success. +- err: An `io.Error` if `r.i <= 0` (`.Invalid_Unread`), otherwise `nil` denotes success. */ -reader_unread_byte :: proc(r: ^Reader) -> io.Error { +reader_unread_byte :: proc(r: ^Reader) -> (err: io.Error) { if r.i <= 0 { return .Invalid_Unread } @@ -211,9 +211,9 @@ Inputs: WARNING: May only be used once and after a valid `read_rune` call Returns: -An `io.Error` if an error occurs while unreading (`.Invalid_Unread`), else `nil` denotes success. +- err: An `io.Error` if an error occurs while unreading (`.Invalid_Unread`), else `nil` denotes success. */ -reader_unread_rune :: proc(r: ^Reader) -> io.Error { +reader_unread_rune :: proc(r: ^Reader) -> (err: io.Error) { if r.i <= 0 { return .Invalid_Unread } @@ -236,7 +236,7 @@ Returns: - The absolute offset after seeking - err: An `io.Error` if an error occurs while seeking (`.Invalid_Whence`, `.Invalid_Offset`) */ -reader_seek :: proc(r: ^Reader, offset: i64, whence: io.Seek_From) -> (i64, io.Error) { +reader_seek :: proc(r: ^Reader, offset: i64, whence: io.Seek_From) -> (res: i64, err: io.Error) { r.prev_rune = -1 abs: i64 switch whence { diff --git a/core/strings/strings.odin b/core/strings/strings.odin index dff68982d..39cbe3654 100644 --- a/core/strings/strings.odin +++ b/core/strings/strings.odin @@ -17,12 +17,13 @@ Inputs: - loc: The caller location for debugging purposes (default: #caller_location) Returns: -A cloned string +- res: The cloned string +- err: An optional allocator error if one occured, `nil` otherwise */ -clone :: proc(s: string, allocator := context.allocator, loc := #caller_location) -> string { - c := make([]byte, len(s), allocator, loc) +clone :: proc(s: string, allocator := context.allocator, loc := #caller_location) -> (res: string, err: mem.Allocator_Error) #optional_allocator_error { + c := make([]byte, len(s), allocator, loc) or_return copy(c, s) - return string(c[:len(s)]) + return string(c[:len(s)]), nil } /* Clones a string safely (returns early with an allocation error on failure) @@ -35,13 +36,12 @@ Inputs: - loc: The caller location for debugging purposes (default: #caller_location) Returns: -- str: A cloned string -- err: A mem.Allocator_Error if an error occurs during allocation +- res: The cloned string +- err: An allocator error if one occured, `nil` otherwise */ -clone_safe :: proc(s: string, allocator := context.allocator, loc := #caller_location) -> (str: string, err: mem.Allocator_Error) { - c := make([]byte, len(s), allocator, loc) or_return - copy(c, s) - return string(c[:len(s)]), nil +@(deprecated="Prefer clone. It now returns an optional allocator error") +clone_safe :: proc(s: string, allocator := context.allocator, loc := #caller_location) -> (res: string, err: mem.Allocator_Error) { + return clone(s, allocator, loc) } /* Clones a string and appends a null-byte to make it a cstring @@ -54,13 +54,14 @@ Inputs: - loc: The caller location for debugging purposes (default: #caller_location) Returns: -A cloned cstring with an appended null-byte +- res: A cloned cstring with an appended null-byte +- err: An optional allocator error if one occured, `nil` otherwise */ -clone_to_cstring :: proc(s: string, allocator := context.allocator, loc := #caller_location) -> cstring { - c := make([]byte, len(s)+1, allocator, loc) +clone_to_cstring :: proc(s: string, allocator := context.allocator, loc := #caller_location) -> (res: cstring, err: mem.Allocator_Error) #optional_allocator_error { + c := make([]byte, len(s)+1, allocator, loc) or_return copy(c, s) c[len(s)] = 0 - return cstring(&c[0]) + return cstring(&c[0]), nil } /* Transmutes a raw pointer into a string. Non-allocating. @@ -72,9 +73,9 @@ Inputs: NOTE: The created string is only valid as long as the pointer and length are valid. Returns: -A string created from the byte pointer and length +- res: A string created from the byte pointer and length */ -string_from_ptr :: proc(ptr: ^byte, len: int) -> string { +string_from_ptr :: proc(ptr: ^byte, len: int) -> (res: string) { return transmute(string)mem.Raw_String{ptr, len} } /* @@ -88,9 +89,9 @@ Inputs: - len: The length of the byte sequence Returns: -A string created from the null-terminated byte pointer and length +- res: A string created from the null-terminated byte pointer and length */ -string_from_null_terminated_ptr :: proc(ptr: ^byte, len: int) -> string { +string_from_null_terminated_ptr :: proc(ptr: ^byte, len: int) -> (res: string) { s := transmute(string)mem.Raw_String{ptr, len} s = truncate_to_byte(s, 0) return s @@ -102,9 +103,10 @@ Inputs: - str: The input string Returns: -A pointer to the start of the string's bytes +- res: A pointer to the start of the string's bytes */ -ptr_from_string :: proc(str: string) -> ^byte { +@(deprecated="Prefer the builtin raw_data.") +ptr_from_string :: proc(str: string) -> (res: ^byte) { d := transmute(mem.Raw_String)str return d.data } @@ -117,9 +119,9 @@ Inputs: WARNING: This is unsafe because the original string may not contain a null-byte. Returns: -The converted cstring +- res: The converted cstring */ -unsafe_string_to_cstring :: proc(str: string) -> cstring { +unsafe_string_to_cstring :: proc(str: string) -> (res: cstring) { d := transmute(mem.Raw_String)str return cstring(d.data) } @@ -133,9 +135,9 @@ Inputs: NOTE: Failure to find the byte results in returning the entire string. Returns: -The truncated string +- res: The truncated string */ -truncate_to_byte :: proc(str: string, b: byte) -> string { +truncate_to_byte :: proc(str: string, b: byte) -> (res: string) { n := index_byte(str, b) if n < 0 { n = len(str) @@ -150,9 +152,9 @@ Inputs: - r: The rune to truncate the string at Returns: -The truncated string +- res: The truncated string */ -truncate_to_rune :: proc(str: string, r: rune) -> string { +truncate_to_rune :: proc(str: string, r: rune) -> (res: string) { n := index_rune(str, r) if n < 0 { n = len(str) @@ -170,13 +172,14 @@ Inputs: - loc: The caller location for debugging purposes (default: `#caller_location`) Returns: -A cloned string from the byte array with a null-byte +- res: The cloned string from the byte array with a null-byte +- err: An optional allocator error if one occured, `nil` otherwise */ -clone_from_bytes :: proc(s: []byte, allocator := context.allocator, loc := #caller_location) -> string { - c := make([]byte, len(s)+1, allocator, loc) +clone_from_bytes :: proc(s: []byte, allocator := context.allocator, loc := #caller_location) -> (res: string, err: mem.Allocator_Error) #optional_allocator_error { + c := make([]byte, len(s)+1, allocator, loc) or_return copy(c, s) c[len(s)] = 0 - return string(c[:len(s)]) + return string(c[:len(s)]), nil } /* Clones a cstring `s` as a string @@ -189,9 +192,10 @@ Inputs: - loc: The caller location for debugging purposes (default: `#caller_location`) Returns: -A cloned string from the cstring +- res: The cloned string from the cstring +- err: An optional allocator error if one occured, `nil` otherwise */ -clone_from_cstring :: proc(s: cstring, allocator := context.allocator, loc := #caller_location) -> string { +clone_from_cstring :: proc(s: cstring, allocator := context.allocator, loc := #caller_location) -> (res: string, err: mem.Allocator_Error) #optional_allocator_error { return clone(string(s), allocator, loc) } /* @@ -208,13 +212,14 @@ Inputs: NOTE: Same as `string_from_ptr`, but perform an additional `clone` operation Returns: -A cloned string from the byte pointer and length +- res: The cloned string from the byte pointer and length +- err: An optional allocator error if one occured, `nil` otherwise */ -clone_from_ptr :: proc(ptr: ^byte, len: int, allocator := context.allocator, loc := #caller_location) -> string { +clone_from_ptr :: proc(ptr: ^byte, len: int, allocator := context.allocator, loc := #caller_location) -> (res: string, err: mem.Allocator_Error) #optional_allocator_error { s := string_from_ptr(ptr, len) return clone(s, allocator, loc) } -// Overloaded procedure to clone from a string, `[]byte`, `cstring` or a `^byte` + length +// Overloaded procedure to clone from a string, `[]byte`, `cstring` or a `^byte` + length clone_from :: proc{ clone, clone_from_bytes, @@ -235,9 +240,10 @@ Inputs: NOTE: Truncates at the first null-byte encountered or the byte length. Returns: -A cloned string from the null-terminated cstring and byte length +- res: The cloned string from the null-terminated cstring and byte length +- err: An optional allocator error if one occured, `nil` otherwise */ -clone_from_cstring_bounded :: proc(ptr: cstring, len: int, allocator := context.allocator, loc := #caller_location) -> string { +clone_from_cstring_bounded :: proc(ptr: cstring, len: int, allocator := context.allocator, loc := #caller_location) -> (res: string, err: mem.Allocator_Error) #optional_allocator_error { s := string_from_ptr((^u8)(ptr), len) s = truncate_to_byte(s, 0) return clone(s, allocator, loc) @@ -251,9 +257,9 @@ Inputs: - rhs: Second string for comparison Returns: --1 if `lhs` comes first, 1 if `rhs` comes first, or 0 if they are equal +- result: `-1` if `lhs` comes first, `1` if `rhs` comes first, or `0` if they are equal */ -compare :: proc(lhs, rhs: string) -> int { +compare :: proc(lhs, rhs: string) -> (result: int) { return mem.compare(transmute([]byte)lhs, transmute([]byte)rhs) } /* @@ -264,15 +270,15 @@ Inputs: - r: The rune to search for Returns: -The byte offset of the rune `r` in the string `s`, or -1 if not found +- result: `true` if the rune `r` in the string `s`, `false` otherwise */ -contains_rune :: proc(s: string, r: rune) -> int { - for c, offset in s { +contains_rune :: proc(s: string, r: rune) -> (result: bool) { + for c in s { if c == r { - return offset + return true } } - return -1 + return false } /* Returns true when the string `substr` is contained inside the string `s` @@ -282,7 +288,7 @@ Inputs: - substr: The substring to search for Returns: -`true` if `substr` is contained inside the string `s`, `false` otherwise +- res: `true` if `substr` is contained inside the string `s`, `false` otherwise Example: @@ -302,7 +308,7 @@ Output: false */ -contains :: proc(s, substr: string) -> bool { +contains :: proc(s, substr: string) -> (res: bool) { return index(s, substr) >= 0 } /* @@ -313,7 +319,7 @@ Inputs: - chars: The characters to search for Returns: -`true` if the string `s` contains any of the characters in `chars`, `false` otherwise +- res: `true` if the string `s` contains any of the characters in `chars`, `false` otherwise Example: @@ -335,7 +341,7 @@ Output: false */ -contains_any :: proc(s, chars: string) -> bool { +contains_any :: proc(s, chars: string) -> (res: bool) { return index_any(s, chars) >= 0 } /* @@ -345,7 +351,7 @@ Inputs: - s: The input string Returns: -The UTF-8 rune count of the string `s` +- res: The UTF-8 rune count of the string `s` Example: @@ -363,7 +369,7 @@ Output: 5 */ -rune_count :: proc(s: string) -> int { +rune_count :: proc(s: string) -> (res: int) { return utf8.rune_count_in_string(s) } /* @@ -375,7 +381,7 @@ Inputs: - v: The second string for comparison Returns: -`true` if the strings `u` and `v` are the same alpha characters (ignoring case) +- res: `true` if the strings `u` and `v` are the same alpha characters (ignoring case) Example: @@ -397,7 +403,7 @@ Output: false */ -equal_fold :: proc(u, v: string) -> bool { +equal_fold :: proc(u, v: string) -> (res: bool) { s, t := u, v loop: for s != "" && t != "" { sr, tr: rune @@ -447,7 +453,7 @@ Inputs: - b: The second input string Returns: -The prefix length common between strings `a` and `b` +- n: The prefix length common between strings `a` and `b` Example: @@ -500,7 +506,7 @@ Inputs: - prefix: The prefix to look for Returns: -`true` if the string `s` starts with the `prefix`, otherwise `false` +- result: `true` if the string `s` starts with the `prefix`, otherwise `false` Example: @@ -522,7 +528,7 @@ Output: false */ -has_prefix :: proc(s, prefix: string) -> bool { +has_prefix :: proc(s, prefix: string) -> (result: bool) { return len(s) >= len(prefix) && s[0:len(prefix)] == prefix } /* @@ -533,7 +539,7 @@ Inputs: - suffix: The suffix to look for Returns: -`true` if the string `s` ends with the `suffix`, otherwise `false` +- result: `true` if the string `s` ends with the `suffix`, otherwise `false` Example: @@ -553,7 +559,7 @@ Output: true */ -has_suffix :: proc(s, suffix: string) -> bool { +has_suffix :: proc(s, suffix: string) -> (result: bool) { return len(s) >= len(suffix) && s[len(s)-len(suffix):] == suffix } /* @@ -567,7 +573,8 @@ Inputs: - allocator: (default is context.allocator) Returns: -A combined string from the slice of strings `a` separated with the `sep` string +- res: A combined string from the slice of strings `a` separated with the `sep` string +- err: An optional allocator error if one occured, `nil` otherwise Example: @@ -588,39 +595,7 @@ Output: a...b...c */ -join :: proc(a: []string, sep: string, allocator := context.allocator) -> string { - if len(a) == 0 { - return "" - } - - n := len(sep) * (len(a) - 1) - for s in a { - n += len(s) - } - - b := make([]byte, n, allocator) - i := copy(b, a[0]) - for s in a[1:] { - i += copy(b[i:], sep) - i += copy(b[i:], s) - } - return string(b) -} -/* -Joins a slice of strings `a` with a `sep` string, returns an error on allocation failure - -*Allocates Using Provided Allocator* - -Inputs: -- a: A slice of strings to join -- sep: The separator string -- allocator: (default is context.allocator) - -Returns: -- str: A combined string from the slice of strings `a` separated with the `sep` string -- err: An error if allocation failed, otherwise `nil` -*/ -join_safe :: proc(a: []string, sep: string, allocator := context.allocator) -> (str: string, err: mem.Allocator_Error) { +join :: proc(a: []string, sep: string, allocator := context.allocator) -> (res: string, err: mem.Allocator_Error) #optional_allocator_error { if len(a) == 0 { return "", nil } @@ -639,6 +614,24 @@ join_safe :: proc(a: []string, sep: string, allocator := context.allocator) -> ( return string(b), nil } /* +Joins a slice of strings `a` with a `sep` string, returns an error on allocation failure + +*Allocates Using Provided Allocator* + +Inputs: +- a: A slice of strings to join +- sep: The separator string +- allocator: (default is context.allocator) + +Returns: +- str: A combined string from the slice of strings `a` separated with the `sep` string +- err: An allocator error if one occured, `nil` otherwise +*/ +@(deprecated="Prefer join. It now returns an optional allocator error") +join_safe :: proc(a: []string, sep: string, allocator := context.allocator) -> (res: string, err: mem.Allocator_Error) { + return join(a, sep, allocator) +} +/* Returns a combined string from the slice of strings `a` without a separator *Allocates Using Provided Allocator* @@ -648,7 +641,8 @@ Inputs: - allocator: (default is context.allocator) Returns: -The concatenated string +- res: The concatenated string +- err: An optional allocator error if one occured, `nil` otherwise Example: @@ -665,35 +659,7 @@ Output: abc */ -concatenate :: proc(a: []string, allocator := context.allocator) -> string { - if len(a) == 0 { - return "" - } - - n := 0 - for s in a { - n += len(s) - } - b := make([]byte, n, allocator) - i := 0 - for s in a { - i += copy(b[i:], s) - } - return string(b) -} -/* -Returns a combined string from the slice of strings `a` without a separator, or an error if allocation fails - -*Allocates Using Provided Allocator* - -Inputs: -- a: A slice of strings to concatenate -- allocator: (default is context.allocator) - -Returns: -The concatenated string, and an error if allocation fails -*/ -concatenate_safe :: proc(a: []string, allocator := context.allocator) -> (res: string, err: mem.Allocator_Error) { +concatenate :: proc(a: []string, allocator := context.allocator) -> (res: string, err: mem.Allocator_Error) #optional_allocator_error { if len(a) == 0 { return "", nil } @@ -710,6 +676,22 @@ concatenate_safe :: proc(a: []string, allocator := context.allocator) -> (res: s return string(b), nil } /* +Returns a combined string from the slice of strings `a` without a separator, or an error if allocation fails + +*Allocates Using Provided Allocator* + +Inputs: +- a: A slice of strings to concatenate +- allocator: (default is context.allocator) + +Returns: +The concatenated string, and an error if allocation fails +*/ +@(deprecated="Prefer concatenate. It now returns an optional allocator error") +concatenate_safe :: proc(a: []string, allocator := context.allocator) -> (res: string, err: mem.Allocator_Error) { + return concatenate(a, allocator) +} +/* Returns a substring of the input string `s` with the specified rune offset and length *Allocates Using Provided Allocator* @@ -721,7 +703,8 @@ Inputs: - allocator: (default is context.allocator) Returns: -The substring +- res: The substring +- err: An optional allocator error if one occured, `nil` otherwise Example: @@ -741,7 +724,7 @@ Output: example */ -cut :: proc(s: string, rune_offset := int(0), rune_length := int(0), allocator := context.allocator) -> (res: string) { +cut :: proc(s: string, rune_offset := int(0), rune_length := int(0), allocator := context.allocator) -> (res: string, err: mem.Allocator_Error) #optional_allocator_error { s := s; rune_length := rune_length context.allocator = allocator @@ -757,7 +740,7 @@ cut :: proc(s: string, rune_offset := int(0), rune_length := int(0), allocator : // We're asking for a substring starting after the end of the input string. // That's just an empty string. if rune_offset >= rune_count { - return "" + return "", nil } // If we don't specify the length of the substring, use the remainder. @@ -769,7 +752,7 @@ cut :: proc(s: string, rune_offset := int(0), rune_length := int(0), allocator : // But we do know it's bounded by the number of runes * 4 bytes, // and can be no more than the size of the input string. bytes_needed := min(rune_length * 4, len(s)) - buf := make([]u8, bytes_needed) + buf := make([]u8, bytes_needed) or_return byte_offset := 0 for i := 0; i < rune_count; i += 1 { @@ -790,7 +773,7 @@ cut :: proc(s: string, rune_offset := int(0), rune_length := int(0), allocator : } s = s[w:] } - return string(buf[:byte_offset]) + return string(buf[:byte_offset]), nil } /* Splits the input string `s` into a slice of substrings separated by the specified `sep` string @@ -809,14 +792,15 @@ Inputs: NOTE: Allocation occurs for the array, the splits are all views of the original string. Returns: -A slice of substrings +- res: The slice of substrings +- err: An optional allocator error if one occured, `nil` otherwise */ @private -_split :: proc(s_, sep: string, sep_save, n_: int, allocator := context.allocator) -> []string { +_split :: proc(s_, sep: string, sep_save, n_: int, allocator := context.allocator) -> (res: []string, err: mem.Allocator_Error) { s, n := s_, n_ if n == 0 { - return nil + return nil, nil } if sep == "" { @@ -825,7 +809,7 @@ _split :: proc(s_, sep: string, sep_save, n_: int, allocator := context.allocato n = l } - res := make([dynamic]string, n, allocator) + res := make([]string, n, allocator) or_return for i := 0; i < n-1; i += 1 { _, w := utf8.decode_rune_in_string(s) res[i] = s[:w] @@ -834,14 +818,14 @@ _split :: proc(s_, sep: string, sep_save, n_: int, allocator := context.allocato if n > 0 { res[n-1] = s } - return res[:] + return res[:], nil } if n < 0 { n = count(s, sep) + 1 } - res := make([dynamic]string, n, allocator) + res = make([]string, n, allocator) or_return n -= 1 @@ -856,7 +840,7 @@ _split :: proc(s_, sep: string, sep_save, n_: int, allocator := context.allocato } res[i] = s - return res[:i+1] + return res[:i+1], nil } /* Splits a string into parts based on a separator. @@ -868,7 +852,9 @@ Inputs: - 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. +Returns: +- res: The slice of strings, each representing a part of the split string. +- err: An optional allocator error if one occured, `nil` otherwise NOTE: Allocation occurs for the array, the splits are all views of the original string. @@ -888,7 +874,7 @@ Output: ["aaa", "bbb", "ccc", "ddd", "eee"] */ -split :: proc(s, sep: string, allocator := context.allocator) -> []string { +split :: proc(s, sep: string, allocator := context.allocator) -> (res: []string, err: mem.Allocator_Error) #optional_allocator_error { return _split(s, sep, 0, -1, allocator) } /* @@ -901,7 +887,9 @@ Inputs: - 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. +Returns: +- res: The slice of strings, each representing a part of the split string. +- err: An optional allocator error if one occured, `nil` otherwise NOTE: Allocation occurs for the array, the splits are all views of the original string. @@ -921,7 +909,7 @@ Output: ["aaa", "bbb", "ccc.ddd.eee"] */ -split_n :: proc(s, sep: string, n: int, allocator := context.allocator) -> []string { +split_n :: proc(s, sep: string, n: int, allocator := context.allocator) -> (res: []string, err: mem.Allocator_Error) #optional_allocator_error { return _split(s, sep, 0, n, allocator) } /* @@ -935,7 +923,8 @@ Inputs: - allocator: (default is context.allocator). Returns: -A slice of strings, each representing a part of the split string after the separator. +- res: The slice of strings, each representing a part of the split string after the separator +- err: An optional allocator error if one occured, `nil` otherwise NOTE: Allocation occurs for the array, the splits are all views of the original string. @@ -955,7 +944,7 @@ Output: ["aaa.", "bbb.", "ccc.", "ddd.", "eee"] */ -split_after :: proc(s, sep: string, allocator := context.allocator) -> []string { +split_after :: proc(s, sep: string, allocator := context.allocator) -> (res: []string, err: mem.Allocator_Error) #optional_allocator_error { return _split(s, sep, len(sep), -1, allocator) } /* @@ -970,7 +959,8 @@ Inputs: - allocator: (default is context.allocator) Returns: -A slice of strings with `n` parts or fewer if there weren't +- res: The slice of strings with `n` parts or fewer if there weren't +- err: An optional allocator error if one occured, `nil` otherwise NOTE: Allocation occurs for the array, the splits are all views of the original string. @@ -990,7 +980,7 @@ Output: ["aaa.", "bbb.", "ccc.ddd.eee"] */ -split_after_n :: proc(s, sep: string, n: int, allocator := context.allocator) -> []string { +split_after_n :: proc(s, sep: string, n: int, allocator := context.allocator) -> (res: []string, err: mem.Allocator_Error) #optional_allocator_error { return _split(s, sep, len(sep), n, allocator) } /* @@ -1005,7 +995,8 @@ Inputs: - sep_save: Number of characters from the separator to include in the result. Returns: -A tuple containing the resulting substring and a boolean indicating success. +- res: The resulting substring +- ok: `true` if an iteration result was returned, `false` if the iterator has reached the end */ @private _split_iterator :: proc(s: ^string, sep: string, sep_save: int) -> (res: string, ok: bool) { @@ -1042,7 +1033,8 @@ Inputs: - sep: The byte separator to search for. Returns: -A tuple containing the resulting substring and a boolean indicating success. +- res: The resulting substring +- ok: `true` if an iteration result was returned, `false` if the iterator has reached the end Example: @@ -1087,7 +1079,8 @@ Inputs: - sep: The separator string to search for. Returns: -A tuple containing the resulting substring and a boolean indicating success. +- res: The resulting substring +- ok: `true` if an iteration result was returned, `false` if the iterator has reached the end Example: @@ -1110,7 +1103,7 @@ Output: e */ -split_iterator :: proc(s: ^string, sep: string) -> (string, bool) { +split_iterator :: proc(s: ^string, sep: string) -> (res: string, ok: bool) { return _split_iterator(s, sep, 0) } /* @@ -1121,7 +1114,8 @@ Inputs: - sep: The separator string to search for. Returns: -A tuple containing the resulting substring and a boolean indicating success. +- res: The resulting substring +- ok: `true` if an iteration result was returned, `false` if the iterator has reached the end Example: @@ -1144,7 +1138,7 @@ Output: e */ -split_after_iterator :: proc(s: ^string, sep: string) -> (string, bool) { +split_after_iterator :: proc(s: ^string, sep: string) -> (res: string, ok: bool) { return _split_iterator(s, sep, len(sep)) } /* @@ -1156,10 +1150,10 @@ Inputs: - s: The input string to trim. Returns: -The trimmed string as a slice of the original. +- res: The trimmed string as a slice of the original. */ @(private) -_trim_cr :: proc(s: string) -> string { +_trim_cr :: proc(s: string) -> (res: string) { n := len(s) if n > 0 { if s[n-1] == '\r' { @@ -1178,7 +1172,8 @@ Inputs: - allocator: (default is context.allocator) Returns: -A slice (allocated) of the split string (slices into original string) +- res: The slice (allocated) of the split string (slices into original string) +- err: An optional allocator error if one occured, `nil` otherwise Example: @@ -1196,13 +1191,13 @@ Output: ["a", "b", "c", "d", "e"] */ -split_lines :: proc(s: string, allocator := context.allocator) -> []string { +split_lines :: proc(s: string, allocator := context.allocator) -> (res: []string, err: mem.Allocator_Error) #optional_allocator_error { sep :: "\n" - lines := _split(s, sep, 0, -1, allocator) + lines := _split(s, sep, 0, -1, allocator) or_return for line in &lines { line = _trim_cr(line) } - return lines + return lines, nil } /* Splits the input string at every line break `\n` for `n` parts. @@ -1215,7 +1210,8 @@ Inputs: - allocator: (default is context.allocator) Returns: -A slice (allocated) of the split string (slices into original string) +- res: The slice (allocated) of the split string (slices into original string) +- err: An optional allocator error if one occured, `nil` otherwise NOTE: Allocation occurs for the array, the splits are all views of the original string. @@ -1235,13 +1231,13 @@ Output: ["a", "b", "c\nd\ne"] */ -split_lines_n :: proc(s: string, n: int, allocator := context.allocator) -> []string { +split_lines_n :: proc(s: string, n: int, allocator := context.allocator) -> (res: []string, err: mem.Allocator_Error) #optional_allocator_error { sep :: "\n" - lines := _split(s, sep, 0, n, allocator) + lines := _split(s, sep, 0, n, allocator) or_return for line in &lines { line = _trim_cr(line) } - return lines + return lines, nil } /* Splits the input string at every line break `\n` leaving the `\n` in the resulting strings. @@ -1253,7 +1249,8 @@ Inputs: - allocator: (default is context.allocator) Returns: -A slice (allocated) of the split string (slices into original string), with `\n` included. +- res: The slice (allocated) of the split string (slices into original string), with `\n` included +- err: An optional allocator error if one occured, `nil` otherwise NOTE: Allocation occurs for the array, the splits are all views of the original string. @@ -1273,13 +1270,13 @@ Output: ["a\n", "b\n", "c\n", "d\n", "e"] */ -split_lines_after :: proc(s: string, allocator := context.allocator) -> []string { +split_lines_after :: proc(s: string, allocator := context.allocator) -> (res: []string, err: mem.Allocator_Error) #optional_allocator_error { sep :: "\n" - lines := _split(s, sep, len(sep), -1, allocator) + lines := _split(s, sep, len(sep), -1, allocator) or_return for line in &lines { line = _trim_cr(line) } - return lines + return lines, nil } /* Splits the input string at every line break `\n` leaving the `\n` in the resulting strings. @@ -1293,7 +1290,8 @@ Inputs: - allocator: (default is context.allocator) Returns: -A slice (allocated) of the split string (slices into original string), with `\n` included. +- res: The slice (allocated) of the split string (slices into original string), with `\n` included +- err: An optional allocator error if one occured, `nil` otherwise NOTE: Allocation occurs for the array, the splits are all views of the original string. @@ -1313,13 +1311,13 @@ Output: ["a\n", "b\n", "c\nd\ne"] */ -split_lines_after_n :: proc(s: string, n: int, allocator := context.allocator) -> []string { +split_lines_after_n :: proc(s: string, n: int, allocator := context.allocator) -> (res: []string, err: mem.Allocator_Error) #optional_allocator_error { sep :: "\n" - lines := _split(s, sep, len(sep), n, allocator) + lines := _split(s, sep, len(sep), n, allocator) or_return for line in &lines { line = _trim_cr(line) } - return lines + return lines, nil } /* Splits the input string at every line break `\n`. @@ -1329,7 +1327,8 @@ 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. +- line: The resulting substring +- ok: `true` if an iteration result was returned, `false` if the iterator has reached the end Example: @@ -1362,7 +1361,8 @@ 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. +- line: The resulting substring with line breaks included +- ok: `true` if an iteration result was returned, `false` if the iterator has reached the end Example: @@ -1399,7 +1399,7 @@ Inputs: - c: The byte to search for. Returns: -The byte offset of the first occurrence of `c` in `s`, or -1 if not found. +- res: The byte offset of the first occurrence of `c` in `s`, or -1 if not found. Example: @@ -1421,7 +1421,7 @@ Output: -1 */ -index_byte :: proc(s: string, c: byte) -> int { +index_byte :: proc(s: string, c: byte) -> (res: int) { for i := 0; i < len(s); i += 1 { if s[i] == c { return i @@ -1437,7 +1437,7 @@ Inputs: - c: The byte to search for. Returns: -The byte offset of the last occurrence of `c` in `s`, or -1 if not found. +- res: The byte offset of the last occurrence of `c` in `s`, or -1 if not found. NOTE: Can't find UTF-8 based runes. @@ -1461,7 +1461,7 @@ Output: -1 */ -last_index_byte :: proc(s: string, c: byte) -> int { +last_index_byte :: proc(s: string, c: byte) -> (res: int) { for i := len(s)-1; i >= 0; i -= 1 { if s[i] == c { return i @@ -1478,7 +1478,7 @@ Inputs: - r: The rune to search for. Returns: -The byte offset of the first occurrence of `r` in `s`, or -1 if not found. +- res: The byte offset of the first occurrence of `r` in `s`, or -1 if not found. Example: @@ -1508,7 +1508,7 @@ Output: 7 */ -index_rune :: proc(s: string, r: rune) -> int { +index_rune :: proc(s: string, r: rune) -> (res: int) { switch { case u32(r) < utf8.RUNE_SELF: return index_byte(s, byte(r)) @@ -1538,7 +1538,7 @@ Inputs: - substr: The substring to search for. Returns: -The byte offset of the first occurrence of `substr` in `s`, or -1 if not found. +- res: The byte offset of the first occurrence of `substr` in `s`, or -1 if not found. Example: @@ -1560,7 +1560,7 @@ Output: -1 */ -index :: proc(s, substr: string) -> int { +index :: proc(s, substr: string) -> (res: int) { hash_str_rabin_karp :: proc(s: string) -> (hash: u32 = 0, pow: u32 = 1) { for i := 0; i < len(s); i += 1 { hash = hash*PRIME_RABIN_KARP + u32(s[i]) @@ -1617,7 +1617,7 @@ Inputs: - substr: The substring to search for. Returns: -The byte offset of the last occurrence of `substr` in `s`, or -1 if not found. +- res: The byte offset of the last occurrence of `substr` in `s`, or -1 if not found. Example: @@ -1639,7 +1639,7 @@ Output: -1 */ -last_index :: proc(s, substr: string) -> int { +last_index :: proc(s, substr: string) -> (res: int) { hash_str_rabin_karp_reverse :: proc(s: string) -> (hash: u32 = 0, pow: u32 = 1) { for i := len(s) - 1; i >= 0; i -= 1 { hash = hash*PRIME_RABIN_KARP + u32(s[i]) @@ -1694,7 +1694,7 @@ Inputs: - chars: The characters to look for Returns: -The index of the first character of `chars` found in `s`, or -1 if not found. +- res: The index of the first character of `chars` found in `s`, or -1 if not found. Example: @@ -1718,7 +1718,7 @@ Output: -1 */ -index_any :: proc(s, chars: string) -> int { +index_any :: proc(s, chars: string) -> (res: int) { if chars == "" { return -1 } @@ -1757,7 +1757,7 @@ Inputs: - chars: The characters to look for Returns: -The index of the last matching character, or -1 if not found +- res: The index of the last matching character, or -1 if not found Example: @@ -1781,7 +1781,7 @@ Output: -1 */ -last_index_any :: proc(s, chars: string) -> int { +last_index_any :: proc(s, chars: string) -> (res: int) { if chars == "" { return -1 } @@ -1837,7 +1837,8 @@ Inputs: - substrs: The substrings to look for Returns: -A tuple containing the index of the first matching substring, and its length (width) +- idx: the index of the first matching substring +- width: the length of the found substring */ index_multi :: proc(s: string, substrs: []string) -> (idx: int, width: int) { idx = -1 @@ -1876,7 +1877,7 @@ Inputs: - 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` +- res: The number of occurrences of `substr` in `s`, returns the rune_count + 1 of the string `s` on empty `substr` Example: @@ -1900,7 +1901,7 @@ Output: 0 */ -count :: proc(s, substr: string) -> int { +count :: proc(s, substr: string) -> (res: int) { if len(substr) == 0 { // special case return rune_count(s) + 1 } @@ -1945,7 +1946,8 @@ Inputs: - allocator: (default is context.allocator) Returns: -The concatenated repeated string +- res: The concatenated repeated string +- err: An optional allocator error if one occured, `nil` otherwise WARNING: Panics if count < 0 @@ -1963,20 +1965,20 @@ Output: abcabc */ -repeat :: proc(s: string, count: int, allocator := context.allocator) -> string { +repeat :: proc(s: string, count: int, allocator := context.allocator) -> (res: string, err: mem.Allocator_Error) #optional_allocator_error { if count < 0 { panic("strings: negative repeat count") } else if count > 0 && (len(s)*count)/count != len(s) { panic("strings: repeat count will cause an overflow") } - b := make([]byte, len(s)*count, allocator) + b := make([]byte, len(s)*count, allocator) or_return i := copy(b, s) for i < len(b) { // 2^N trick to reduce the need to copy copy(b[i:], b[:i]) i *= 2 } - return string(b) + return string(b), nil } /* Replaces all occurrences of `old` in `s` with `new` @@ -1990,7 +1992,8 @@ Inputs: - 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 +- output: The modified string +- was_allocation: `true` if an allocation occurred during the replacement, `false` otherwise Example: @@ -2026,7 +2029,8 @@ Inputs: - allocator: (default: context.allocator) Returns: -A tuple containing the modified string and a boolean indicating if an allocation occurred during the replacement +- output: The modified string +- was_allocation: `true` if an allocation occurred during the replacement, `false` otherwise Example: @@ -2099,7 +2103,8 @@ Inputs: - allocator: (default: context.allocator) Returns: -A tuple containing the modified string and a boolean indicating if an allocation occurred during the removal +- output: The modified string +- was_allocation: `true` if an allocation occurred during the replacement, `false` otherwise Example: @@ -2135,7 +2140,8 @@ Inputs: - allocator: (default: context.allocator) Returns: -A tuple containing the modified string and a boolean indicating if an allocation occurred during the removal +- output: The modified string +- was_allocation: `true` if an allocation occurred during the replacement, `false` otherwise Example: @@ -2161,15 +2167,32 @@ remove_all :: proc(s, key: string, allocator := context.allocator) -> (output: s // Returns true if is an ASCII space character ('\t', '\n', '\v', '\f', '\r', ' ') @(private) _ascii_space := [256]bool{'\t' = true, '\n' = true, '\v' = true, '\f' = true, '\r' = true, ' ' = true} -// Returns true when the `r` rune is '\t', '\n', '\v', '\f', '\r' or ' ' -is_ascii_space :: proc(r: rune) -> bool { +/* +Returns true when the `r` rune is an ASCII whitespace character. + +Inputs: +- r: the rune to test + +Returns: +-res: `true` if `r` is a whitespace character, `false` if otherwise +*/ +is_ascii_space :: proc(r: rune) -> (res: bool) { if r < utf8.RUNE_SELF { return _ascii_space[u8(r)] } return false } -// Returns true if the `r` rune is any ASCII or UTF-8 based whitespace character -is_space :: proc(r: rune) -> bool { + +/* +Returns true when the `r` rune is an ASCII or UTF-8 whitespace character. + +Inputs: +- r: the rune to test + +Returns: +-res: `true` if `r` is a whitespace character, `false` if otherwise +*/ +is_space :: proc(r: rune) -> (res: bool) { if r < 0x2000 { switch r { case '\t', '\n', '\v', '\f', '\r', ' ', 0x85, 0xa0, 0x1680: @@ -2186,10 +2209,20 @@ is_space :: proc(r: rune) -> bool { } return false } -// Returns true if the `r` rune is a null-byte (`0x0`) -is_null :: proc(r: rune) -> bool { + +/* +Returns true when the `r` rune is `0x0` + +Inputs: +- r: the rune to test + +Returns: +-res: `true` if `r` is `0x0`, `false` if otherwise +*/ +is_null :: proc(r: rune) -> (res: bool) { return r == 0x0000 } + /* 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. @@ -2199,7 +2232,7 @@ Inputs: - truth: The boolean value to be matched (default: `true`) Returns: -The index of the first matching rune, or -1 if no match was found +- res: The index of the first matching rune, or -1 if no match was found Example: @@ -2226,7 +2259,7 @@ Output: -1 */ -index_proc :: proc(s: string, p: proc(rune) -> bool, truth := true) -> int { +index_proc :: proc(s: string, p: proc(rune) -> bool, truth := true) -> (res: int) { for r, i in s { if p(r) == truth { return i @@ -2235,7 +2268,7 @@ index_proc :: proc(s: string, p: proc(rune) -> bool, truth := true) -> int { return -1 } // Same as `index_proc`, but the procedure p takes a raw pointer for state -index_proc_with_state :: proc(s: string, p: proc(rawptr, rune) -> bool, state: rawptr, truth := true) -> int { +index_proc_with_state :: proc(s: string, p: proc(rawptr, rune) -> bool, state: rawptr, truth := true) -> (res: int) { for r, i in s { if p(state, r) == truth { return i @@ -2244,7 +2277,7 @@ index_proc_with_state :: proc(s: string, p: proc(rawptr, rune) -> bool, state: r return -1 } // Finds the index of the *last* rune in the string s for which the procedure p returns the same value as truth -last_index_proc :: proc(s: string, p: proc(rune) -> bool, truth := true) -> int { +last_index_proc :: proc(s: string, p: proc(rune) -> bool, truth := true) -> (res: int) { // TODO(bill): Probably use Rabin-Karp Search for i := len(s); i > 0; { r, size := utf8.decode_last_rune_in_string(s[:i]) @@ -2256,7 +2289,7 @@ last_index_proc :: proc(s: string, p: proc(rune) -> bool, truth := true) -> int return -1 } // Same as `index_proc_with_state`, runs through the string in reverse -last_index_proc_with_state :: proc(s: string, p: proc(rawptr, rune) -> bool, state: rawptr, truth := true) -> int { +last_index_proc_with_state :: proc(s: string, p: proc(rawptr, rune) -> bool, state: rawptr, truth := true) -> (res: int) { // TODO(bill): Probably use Rabin-Karp Search for i := len(s); i > 0; { r, size := utf8.decode_last_rune_in_string(s[:i]) @@ -2275,7 +2308,7 @@ Inputs: - p: A procedure that takes a rune and returns a boolean Returns: -The trimmed string as a slice of the original +- res: The trimmed string as a slice of the original Example: @@ -2294,7 +2327,7 @@ Output: testing */ -trim_left_proc :: proc(s: string, p: proc(rune) -> bool) -> string { +trim_left_proc :: proc(s: string, p: proc(rune) -> bool) -> (res: string) { i := index_proc(s, p, false) if i == -1 { return "" @@ -2310,9 +2343,9 @@ Inputs: - state: The raw pointer to be passed to the procedure `p` Returns: -The trimmed string as a slice of the original +- res: 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 { +trim_left_proc_with_state :: proc(s: string, p: proc(rawptr, rune) -> bool, state: rawptr) -> (res: string) { i := index_proc_with_state(s, p, state, false) if i == -1 { return "" @@ -2327,7 +2360,7 @@ Inputs: - p: A procedure that takes a rune and returns a boolean Returns: -The trimmed string as a slice of the original +- res: The trimmed string as a slice of the original Example: @@ -2346,7 +2379,7 @@ Output: test */ -trim_right_proc :: proc(s: string, p: proc(rune) -> bool) -> string { +trim_right_proc :: proc(s: string, p: proc(rune) -> bool) -> (res: string) { i := last_index_proc(s, p, false) if i >= 0 && s[i] >= utf8.RUNE_SELF { _, w := utf8.decode_rune_in_string(s[i:]) @@ -2365,9 +2398,9 @@ Inputs: - state: The raw pointer to be passed to the procedure `p` Returns: -The trimmed string as a slice of the original, empty when no match +- res: 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 { +trim_right_proc_with_state :: proc(s: string, p: proc(rawptr, rune) -> bool, state: rawptr) -> (res: string) { i := last_index_proc_with_state(s, p, state, false) if i >= 0 && s[i] >= utf8.RUNE_SELF { _, w := utf8.decode_rune_in_string(s[i:]) @@ -2378,7 +2411,7 @@ trim_right_proc_with_state :: proc(s: string, p: proc(rawptr, rune) -> bool, sta return s[0:i] } // Procedure for `trim_*_proc` variants, which has a string rawptr cast + rune comparison -is_in_cutset :: proc(state: rawptr, r: rune) -> bool { +is_in_cutset :: proc(state: rawptr, r: rune) -> (res: bool) { if state == nil { return false } @@ -2398,9 +2431,9 @@ Inputs: - cutset: The set of characters to be trimmed from the left of the input string Returns: -The trimmed string as a slice of the original +- res: The trimmed string as a slice of the original */ -trim_left :: proc(s: string, cutset: string) -> string { +trim_left :: proc(s: string, cutset: string) -> (res: string) { if s == "" || cutset == "" { return s } @@ -2415,9 +2448,9 @@ Inputs: - cutset: The set of characters to be trimmed from the right of the input string Returns: -The trimmed string as a slice of the original +- res: The trimmed string as a slice of the original */ -trim_right :: proc(s: string, cutset: string) -> string { +trim_right :: proc(s: string, cutset: string) -> (res: string) { if s == "" || cutset == "" { return s } @@ -2432,9 +2465,9 @@ Inputs: - cutset: The set of characters to be trimmed from both sides of the input string Returns: -The trimmed string as a slice of the original +- res: The trimmed string as a slice of the original */ -trim :: proc(s: string, cutset: string) -> string { +trim :: proc(s: string, cutset: string) -> (res: string) { return trim_right(trim_left(s, cutset), cutset) } /* @@ -2444,9 +2477,9 @@ Inputs: - s: The input string Returns: -The trimmed string as a slice of the original +- res: The trimmed string as a slice of the original */ -trim_left_space :: proc(s: string) -> string { +trim_left_space :: proc(s: string) -> (res: string) { return trim_left_proc(s, is_space) } /* @@ -2456,9 +2489,9 @@ Inputs: - s: The input string Returns: -The trimmed string as a slice of the original +- res: The trimmed string as a slice of the original */ -trim_right_space :: proc(s: string) -> string { +trim_right_space :: proc(s: string) -> (res: string) { return trim_right_proc(s, is_space) } /* @@ -2468,9 +2501,9 @@ Inputs: - s: The input string Returns: -The trimmed string as a slice of the original +- res: The trimmed string as a slice of the original */ -trim_space :: proc(s: string) -> string { +trim_space :: proc(s: string) -> (res: string) { return trim_right_space(trim_left_space(s)) } /* @@ -2480,9 +2513,9 @@ Inputs: - s: The input string Returns: -The trimmed string as a slice of the original +- res: The trimmed string as a slice of the original */ -trim_left_null :: proc(s: string) -> string { +trim_left_null :: proc(s: string) -> (res: string) { return trim_left_proc(s, is_null) } /* @@ -2492,9 +2525,9 @@ Inputs: - s: The input string Returns: -The trimmed string as a slice of the original +- res: The trimmed string as a slice of the original */ -trim_right_null :: proc(s: string) -> string { +trim_right_null :: proc(s: string) -> (res: string) { return trim_right_proc(s, is_null) } /* @@ -2503,9 +2536,9 @@ Trims null runes from both sides, "\x00\x00testing\x00\x00" -> "testing" Inputs: - s: The input string Returns: -The trimmed string as a slice of the original +- res: The trimmed string as a slice of the original */ -trim_null :: proc(s: string) -> string { +trim_null :: proc(s: string) -> (res: string) { return trim_right_null(trim_left_null(s)) } /* @@ -2516,7 +2549,7 @@ Inputs: - 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 +- res: The trimmed string as a slice of original, or the input string if no prefix was found Example: @@ -2534,7 +2567,7 @@ Output: testing */ -trim_prefix :: proc(s, prefix: string) -> string { +trim_prefix :: proc(s, prefix: string) -> (res: string) { if has_prefix(s, prefix) { return s[len(prefix):] } @@ -2548,7 +2581,7 @@ Inputs: - 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 +- res: The trimmed string as a slice of original, or the input string if no suffix was found Example: @@ -2566,7 +2599,7 @@ Output: todo.doc */ -trim_suffix :: proc(s, suffix: string) -> string { +trim_suffix :: proc(s, suffix: string) -> (res: string) { if has_suffix(s, suffix) { return s[:len(s)-len(suffix)] } @@ -2583,7 +2616,8 @@ Inputs: - allocator: (default is context.allocator) Returns: -An array of strings, or nil on empty substring or no matches +- res: An array of strings, or nil on empty substring or no matches +- err: An optional allocator error if one occured, `nil` otherwise NOTE: Allocation occurs for the array, the splits are all views of the original string. @@ -2603,15 +2637,15 @@ Output: ["testing", "this", "out", "nice", "done", "last"] */ -split_multi :: proc(s: string, substrs: []string, allocator := context.allocator) -> []string #no_bounds_check { +split_multi :: proc(s: string, substrs: []string, allocator := context.allocator) -> (res: []string, err: mem.Allocator_Error) #optional_allocator_error #no_bounds_check { if s == "" || len(substrs) <= 0 { - return nil + return nil, nil } // disallow "" substr for substr in substrs { if len(substr) == 0 { - return nil + return nil, nil } } @@ -2626,7 +2660,7 @@ split_multi :: proc(s: string, substrs: []string, allocator := context.allocator it = it[i+w:] } - results := make([dynamic]string, 0, n, allocator) + results := make([dynamic]string, 0, n, allocator) or_return { it := s for len(it) > 0 { @@ -2641,7 +2675,7 @@ split_multi :: proc(s: string, substrs: []string, allocator := context.allocator append(&results, it) } assert(len(results) == n) - return results[:] + return results[:], nil } /* Splits the input string `s` by all possible `substrs` in an iterator fashion. The full string is returned if no match. @@ -2651,7 +2685,8 @@ Inputs: - substrs: An array of substrings used for splitting Returns: -A tuple containing the split string and a boolean indicating success or failure +- res: The split string +- ok: `true` if an iteration result was returned, `false` if the iterator has reached the end Example: @@ -2712,7 +2747,8 @@ Inputs: - allocator: (default is context.allocator) Returns: -A new string with invalid UTF-8 characters replaced +- res: A new string with invalid UTF-8 characters replaced +- err: An optional allocator error if one occured, `nil` otherwise Example: @@ -2729,10 +2765,10 @@ Output: Hello? */ -scrub :: proc(s: string, replacement: string, allocator := context.allocator) -> string { +scrub :: proc(s: string, replacement: string, allocator := context.allocator) -> (res: string, err: mem.Allocator_Error) #optional_allocator_error { str := s b: Builder - builder_init(&b, 0, len(s), allocator) + builder_init(&b, 0, len(s), allocator) or_return has_error := false cursor := 0 @@ -2758,7 +2794,7 @@ scrub :: proc(s: string, replacement: string, allocator := context.allocator) -> str = str[w:] } - return to_string(b) + return to_string(b), nil } /* Reverses the input string `s` @@ -2770,7 +2806,8 @@ Inputs: - allocator: (default is context.allocator) Returns: -A reversed version of the input string +- res: A reversed version of the input string +- err: An optional allocator error if one occured, `nil` otherwise Example: @@ -2788,10 +2825,10 @@ Output: abcxyz zyxcba */ -reverse :: proc(s: string, allocator := context.allocator) -> string { +reverse :: proc(s: string, allocator := context.allocator) -> (res: string, err: mem.Allocator_Error) #optional_allocator_error { str := s n := len(str) - buf := make([]byte, n) + buf := make([]byte, n) or_return i := n for len(str) > 0 { @@ -2800,7 +2837,7 @@ reverse :: proc(s: string, allocator := context.allocator) -> string { copy(buf[i:], str[:w]) str = str[w:] } - return string(buf) + return string(buf), nil } /* Expands the input string by replacing tab characters with spaces to align to a specified tab size @@ -2813,7 +2850,8 @@ Inputs: - allocator: (default is context.allocator) Returns: -A new string with tab characters expanded to the specified tab size +- res: A new string with tab characters expanded to the specified tab size +- err: An optional allocator error if one occured, `nil` otherwise WARNING: Panics if tab_size <= 0 @@ -2832,17 +2870,17 @@ Output: abc1 abc2 abc3 */ -expand_tabs :: proc(s: string, tab_size: int, allocator := context.allocator) -> string { +expand_tabs :: proc(s: string, tab_size: int, allocator := context.allocator) -> (res: string, err: mem.Allocator_Error) #optional_allocator_error { if tab_size <= 0 { panic("tab size must be positive") } if s == "" { - return "" + return "", nil } b: Builder - builder_init(&b, allocator) + builder_init(&b, allocator) or_return writer := to_writer(&b) str := s column: int @@ -2871,7 +2909,7 @@ expand_tabs :: proc(s: string, tab_size: int, allocator := context.allocator) -> str = str[w:] } - return to_string(b) + return to_string(b), nil } /* Splits the input string `str` by the separator `sep` string and returns 3 parts. The values are slices of the original string. @@ -2881,7 +2919,9 @@ Inputs: - sep: The separator string Returns: -A tuple with `head` (before the split), `match` (the separator), and `tail` (the end of the split) strings +- head: the string before the split +- match: the seperator string +- tail: the string after the split Example: @@ -2935,9 +2975,10 @@ Inputs: - allocator: (default is context.allocator) Returns: -A new string centered within a field of the specified length +- res: A new string centered within a field of the specified length +- err: An optional allocator error if one occured, `nil` otherwise */ -centre_justify :: proc(str: string, length: int, pad: string, allocator := context.allocator) -> string { +centre_justify :: proc(str: string, length: int, pad: string, allocator := context.allocator) -> (res: string, err: mem.Allocator_Error) #optional_allocator_error { n := rune_count(str) if n >= length || pad == "" { return clone(str, allocator) @@ -2947,8 +2988,7 @@ centre_justify :: proc(str: string, length: int, pad: string, allocator := conte pad_len := rune_count(pad) b: Builder - builder_init(&b, allocator) - builder_grow(&b, len(str) + (remains/pad_len + 1)*len(pad)) + builder_init(&b, 0, len(str) + (remains/pad_len + 1)*len(pad), allocator) or_return w := to_writer(&b) @@ -2956,7 +2996,7 @@ centre_justify :: proc(str: string, length: int, pad: string, allocator := conte io.write_string(w, str) write_pad_string(w, pad, pad_len, (remains+1)/2) - return to_string(b) + return to_string(b), nil } /* Left-justifies the input string within a field of specified length by adding pad string on the right side, if its length is less than the target length. @@ -2970,9 +3010,10 @@ Inputs: - allocator: (default is context.allocator) Returns: -A new string left-justified within a field of the specified length +- res: A new string left-justified within a field of the specified length +- err: An optional allocator error if one occured, `nil` otherwise */ -left_justify :: proc(str: string, length: int, pad: string, allocator := context.allocator) -> string { +left_justify :: proc(str: string, length: int, pad: string, allocator := context.allocator) -> (res: string, err: mem.Allocator_Error) #optional_allocator_error { n := rune_count(str) if n >= length || pad == "" { return clone(str, allocator) @@ -2983,14 +3024,14 @@ left_justify :: proc(str: string, length: int, pad: string, allocator := context b: Builder builder_init(&b, allocator) - builder_grow(&b, len(str) + (remains/pad_len + 1)*len(pad)) + builder_init(&b, 0, len(str) + (remains/pad_len + 1)*len(pad), allocator) or_return w := to_writer(&b) io.write_string(w, str) write_pad_string(w, pad, pad_len, remains) - return to_string(b) + return to_string(b), nil } /* Right-justifies the input string within a field of specified length by adding pad string on the left side, if its length is less than the target length. @@ -3004,9 +3045,10 @@ Inputs: - allocator: (default is context.allocator) Returns: -A new string right-justified within a field of the specified length +- res: A new string right-justified within a field of the specified length +- err: An optional allocator error if one occured, `nil` otherwise */ -right_justify :: proc(str: string, length: int, pad: string, allocator := context.allocator) -> string { +right_justify :: proc(str: string, length: int, pad: string, allocator := context.allocator) -> (res: string, err: mem.Allocator_Error) #optional_allocator_error { n := rune_count(str) if n >= length || pad == "" { return clone(str, allocator) @@ -3017,14 +3059,14 @@ right_justify :: proc(str: string, length: int, pad: string, allocator := contex b: Builder builder_init(&b, allocator) - builder_grow(&b, len(str) + (remains/pad_len + 1)*len(pad)) + builder_init(&b, 0, len(str) + (remains/pad_len + 1)*len(pad), allocator) or_return w := to_writer(&b) write_pad_string(w, pad, pad_len, remains) io.write_string(w, str) - return to_string(b) + return to_string(b), nil } /* Writes a given pad string a specified number of times to an `io.Writer` @@ -3062,9 +3104,10 @@ Inputs: - allocator: (default is context.allocator) Returns: -A slice of substrings of the input string, or an empty slice if the input string only contains white space +- res: A slice of substrings of the input string, or an empty slice if the input string only contains white space +- err: An optional allocator error if one occured, `nil` otherwise */ -fields :: proc(s: string, allocator := context.allocator) -> []string #no_bounds_check { +fields :: proc(s: string, allocator := context.allocator) -> (res: []string, err: mem.Allocator_Error) #optional_allocator_error #no_bounds_check { n := 0 was_space := 1 set_bits := u8(0) @@ -3083,10 +3126,10 @@ fields :: proc(s: string, allocator := context.allocator) -> []string #no_bounds } if n == 0 { - return nil + return nil, nil } - a := make([]string, n, allocator) + a := make([]string, n, allocator) or_return na := 0 field_start := 0 i := 0 @@ -3110,7 +3153,7 @@ fields :: proc(s: string, allocator := context.allocator) -> []string #no_bounds if field_start < len(s) { a[na] = s[field_start:] } - return a + return a, nil } /* Splits a string into a slice of substrings at each run of unicode code points `r` satisfying the predicate `f(r)` @@ -3125,10 +3168,11 @@ Inputs: 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: -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 +- res: 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 +- err: An optional allocator error if one occured, `nil` otherwise */ -fields_proc :: proc(s: string, f: proc(rune) -> bool, allocator := context.allocator) -> []string #no_bounds_check { - substrings := make([dynamic]string, 0, 32, allocator) +fields_proc :: proc(s: string, f: proc(rune) -> bool, allocator := context.allocator) -> (res: []string, err: mem.Allocator_Error) #optional_allocator_error #no_bounds_check { + substrings := make([dynamic]string, 0, 32, allocator) or_return start, end := -1, -1 for r, offset in s { @@ -3151,7 +3195,7 @@ fields_proc :: proc(s: string, f: proc(rune) -> bool, allocator := context.alloc append(&substrings, s[start : len(s)]) } - return substrings[:] + return substrings[:], nil } /* 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 @@ -3203,11 +3247,12 @@ Inputs: - allocator: (default is context.allocator) Returns: -The Levenshtein edit distance between the two strings +- res: The Levenshtein edit distance between the two strings +- err: An optional allocator error if one occured, `nil` otherwise NOTE: This implementation is a single-row-version of the Wagner–Fischer algorithm, based on C code by Martin Ettl. */ -levenshtein_distance :: proc(a, b: string, allocator := context.allocator) -> int { +levenshtein_distance :: proc(a, b: string, allocator := context.allocator) -> (res: int, err: mem.Allocator_Error) #optional_allocator_error { LEVENSHTEIN_DEFAULT_COSTS: []int : { 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, @@ -3221,16 +3266,16 @@ levenshtein_distance :: proc(a, b: string, allocator := context.allocator) -> in m, n := utf8.rune_count_in_string(a), utf8.rune_count_in_string(b) if m == 0 { - return n + return n, nil } if n == 0 { - return m + return m, nil } costs: []int if n + 1 > len(LEVENSHTEIN_DEFAULT_COSTS) { - costs = make([]int, n + 1, allocator) + costs = make([]int, n + 1, allocator) or_return for k in 0..=n { costs[k] = k } @@ -3263,5 +3308,5 @@ levenshtein_distance :: proc(a, b: string, allocator := context.allocator) -> in i += 1 } - return costs[n] + return costs[n], nil } diff --git a/tests/core/strings/test_core_strings.odin b/tests/core/strings/test_core_strings.odin index 00e53647f..fdaf3af28 100644 --- a/tests/core/strings/test_core_strings.odin +++ b/tests/core/strings/test_core_strings.odin @@ -5,6 +5,7 @@ import "core:testing" import "core:fmt" import "core:os" import "core:runtime" +import "core:mem" TEST_count := 0 TEST_fail := 0 @@ -105,33 +106,46 @@ Case_Kind :: enum { Ada_Case, } -test_cases := [Case_Kind]struct{s: string, p: proc(r: string, allocator: runtime.Allocator) -> string}{ +Case_Proc :: proc(r: string, allocator: runtime.Allocator) -> (string, mem.Allocator_Error) + +test_cases := [Case_Kind]struct{s: string, p: Case_Proc}{ .Lower_Space_Case = {"hellope world", to_lower_space_case}, .Upper_Space_Case = {"HELLOPE WORLD", to_upper_space_case}, - .Lower_Snake_Case = {"hellope_world", strings.to_snake_case}, - .Upper_Snake_Case = {"HELLOPE_WORLD", strings.to_upper_snake_case}, - .Lower_Kebab_Case = {"hellope-world", strings.to_kebab_case}, - .Upper_Kebab_Case = {"HELLOPE-WORLD", strings.to_upper_kebab_case}, - .Camel_Case = {"hellopeWorld", strings.to_camel_case}, - .Pascal_Case = {"HellopeWorld", strings.to_pascal_case}, - .Ada_Case = {"Hellope_World", strings.to_ada_case}, + .Lower_Snake_Case = {"hellope_world", to_snake_case}, + .Upper_Snake_Case = {"HELLOPE_WORLD", to_upper_snake_case}, + .Lower_Kebab_Case = {"hellope-world", to_kebab_case}, + .Upper_Kebab_Case = {"HELLOPE-WORLD", to_upper_kebab_case}, + .Camel_Case = {"hellopeWorld", to_camel_case}, + .Pascal_Case = {"HellopeWorld", to_pascal_case}, + .Ada_Case = {"Hellope_World", to_ada_case}, } -to_lower_space_case :: proc(r: string, allocator: runtime.Allocator) -> string { +to_lower_space_case :: proc(r: string, allocator: runtime.Allocator) -> (string, mem.Allocator_Error) { return strings.to_delimiter_case(r, ' ', false, allocator) } -to_upper_space_case :: proc(r: string, allocator: runtime.Allocator) -> string { +to_upper_space_case :: proc(r: string, allocator: runtime.Allocator) -> (string, mem.Allocator_Error) { return strings.to_delimiter_case(r, ' ', true, allocator) } +// NOTE: we have these wrappers as having #optional_allocator_error changes the type to not be equivalent +to_snake_case :: proc(r: string, allocator: runtime.Allocator) -> (string, mem.Allocator_Error) { return strings.to_snake_case(r, allocator) } +to_upper_snake_case :: proc(r: string, allocator: runtime.Allocator) -> (string, mem.Allocator_Error) { return strings.to_upper_snake_case(r, allocator) } +to_kebab_case :: proc(r: string, allocator: runtime.Allocator) -> (string, mem.Allocator_Error) { return strings.to_kebab_case(r, allocator) } +to_upper_kebab_case :: proc(r: string, allocator: runtime.Allocator) -> (string, mem.Allocator_Error) { return strings.to_upper_kebab_case(r, allocator) } +to_camel_case :: proc(r: string, allocator: runtime.Allocator) -> (string, mem.Allocator_Error) { return strings.to_camel_case(r, allocator) } +to_pascal_case :: proc(r: string, allocator: runtime.Allocator) -> (string, mem.Allocator_Error) { return strings.to_pascal_case(r, allocator) } +to_ada_case :: proc(r: string, allocator: runtime.Allocator) -> (string, mem.Allocator_Error) { return strings.to_ada_case(r, allocator) } + @test test_case_conversion :: proc(t: ^testing.T) { for entry in test_cases { for test_case, case_kind in test_cases { - result := entry.p(test_case.s, context.allocator) + result, err := entry.p(test_case.s, context.allocator) + msg := fmt.tprintf("ERROR: We got the allocation error '{}'\n", err) + expect(t, err == nil, msg) defer delete(result) - msg := fmt.tprintf("ERROR: Input `{}` to converter {} does not match `{}`, got `{}`.\n", test_case.s, case_kind, entry.s, result) + msg = fmt.tprintf("ERROR: Input `{}` to converter {} does not match `{}`, got `{}`.\n", test_case.s, case_kind, entry.s, result) expect(t, result == entry.s, msg) } } diff --git a/tests/documentation/documentation_tester.odin b/tests/documentation/documentation_tester.odin index c50a18ce2..efba63f88 100644 --- a/tests/documentation/documentation_tester.odin +++ b/tests/documentation/documentation_tester.odin @@ -411,7 +411,7 @@ main :: proc() { // NOTE: this will escape the multiline string. Even with a backslash it still escapes due to the semantics of ` // I don't think any examples would really need this specific character so let's just make it forbidden and change // in the future if we really need to - if strings.contains_rune(line, '`') >= 0 { + if strings.contains_rune(line, '`') { fmt.eprintf("The line %q in the output for \"%s.%s\" contains a ` which is not allowed\n", line, test.package_name, test.entity_name) g_bad_doc = true had_line_error = true