mirrors/Odin
1
0
Fork 0
mirror of https://github.com/odin-lang/Odin.git synced 2026-03-02 22:58:20 +00:00
Code Issues Packages Projects Releases Wiki Activity

Small improvements strings documentation

Browse Source 
* 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
This commit is contained in:
Lucas Perlind
2023-04-03 08:33:24 +10:00
parent 6ff0cc0b40
commit 67e6f57192
6 changed files with 484 additions and 401 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
core/strings/ascii_set.odin
View File

@@ -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 {

186
core/strings/builder.odin
View File

@@ -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) {

79
core/strings/conversion.odin
View File

@@ -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

16
core/strings/intern.odin
View File

@@ -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 {

54
core/strings/reader.odin
View File

@@ -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`)
*/

542
core/strings/strings.odin
View File

File diff suppressed because it is too large Load Diff