mirror of
https://github.com/Ed94/Odin.git
synced 2026-07-15 07:31:26 -07:00
documentation for the rest of the strings library
This commit is contained in:
Michael Kutowski
GitHub
+117
-13
@@ -7,40 +7,56 @@ import "core:io"
|
||||
|
||||
Builder_Flush_Proc :: #type proc(b: ^Builder) -> (do_reset: bool)
|
||||
|
||||
/*
|
||||
dynamic byte buffer / string builder with helper procedures
|
||||
the dynamic array is wrapped inside the struct to be more opaque
|
||||
you can use `fmt.sbprint*` procedures with a `^strings.Builder` directly
|
||||
*/
|
||||
Builder :: struct {
|
||||
buf: [dynamic]byte,
|
||||
}
|
||||
|
||||
// return a builder, default length 0 / cap 16 are done through make
|
||||
make_builder_none :: proc(allocator := context.allocator) -> Builder {
|
||||
return Builder{buf=make([dynamic]byte, allocator)}
|
||||
}
|
||||
|
||||
// return a builder, with a set length `len` and cap 16 byte buffer
|
||||
make_builder_len :: proc(len: int, allocator := context.allocator) -> Builder {
|
||||
return Builder{buf=make([dynamic]byte, len, allocator)}
|
||||
}
|
||||
|
||||
// return a builder, with a set length `len` byte buffer and a custom `cap`
|
||||
make_builder_len_cap :: proc(len, cap: int, allocator := context.allocator) -> Builder {
|
||||
return Builder{buf=make([dynamic]byte, len, cap, allocator)}
|
||||
}
|
||||
|
||||
// overload simple `make_builder_*` with or without len / cap parameters
|
||||
make_builder :: proc{
|
||||
make_builder_none,
|
||||
make_builder_len,
|
||||
make_builder_len_cap,
|
||||
}
|
||||
|
||||
// initialize a builder, default length 0 / cap 16 are done through make
|
||||
// replaces the existing `buf`
|
||||
init_builder_none :: proc(b: ^Builder, allocator := context.allocator) {
|
||||
b.buf = make([dynamic]byte, allocator)
|
||||
}
|
||||
|
||||
// initialize a builder, with a set length `len` and cap 16 byte buffer
|
||||
// replaces the existing `buf`
|
||||
init_builder_len :: proc(b: ^Builder, len: int, allocator := context.allocator) {
|
||||
b.buf = make([dynamic]byte, len, allocator)
|
||||
}
|
||||
|
||||
// initialize a builder, with a set length `len` byte buffer and a custom `cap`
|
||||
// replaces the existing `buf`
|
||||
init_builder_len_cap :: proc(b: ^Builder, len, cap: int, allocator := context.allocator) {
|
||||
b.buf = make([dynamic]byte, len, cap, allocator)
|
||||
}
|
||||
|
||||
// overload simple `init_builder_*` with or without len / ap parameters
|
||||
init_builder :: proc{
|
||||
init_builder_none,
|
||||
init_builder_len,
|
||||
@@ -76,30 +92,42 @@ _builder_stream_vtable := &io.Stream_VTable{
|
||||
},
|
||||
}
|
||||
|
||||
// return an `io.Stream` from a builder
|
||||
to_stream :: proc(b: ^Builder) -> io.Stream {
|
||||
return io.Stream{stream_vtable=_builder_stream_vtable, stream_data=b}
|
||||
}
|
||||
|
||||
// return an `io.Writer` from a builder
|
||||
to_writer :: proc(b: ^Builder) -> io.Writer {
|
||||
return io.to_writer(to_stream(b))
|
||||
}
|
||||
|
||||
|
||||
|
||||
|
||||
// delete and clear the builder byte buffer content
|
||||
destroy_builder :: proc(b: ^Builder) {
|
||||
delete(b.buf)
|
||||
clear(&b.buf)
|
||||
}
|
||||
|
||||
// reserve the builfer byte buffer to a specific cap, when it's higher than before
|
||||
grow_builder :: proc(b: ^Builder, cap: int) {
|
||||
reserve(&b.buf, cap)
|
||||
}
|
||||
|
||||
// clear the builder byte buffer content
|
||||
reset_builder :: proc(b: ^Builder) {
|
||||
clear(&b.buf)
|
||||
}
|
||||
|
||||
|
||||
/*
|
||||
create an empty builder with the same slice length as its cap
|
||||
uses the `mem.nil_allocator` to avoid allocation and keep a fixed length
|
||||
used in `fmt.bprint*`
|
||||
|
||||
bytes: [8]byte // <-- gets filled
|
||||
builder := strings.builder_from_slice(bytes[:])
|
||||
strings.write_byte(&builder, 'a') -> "a"
|
||||
strings.write_byte(&builder, 'b') -> "ab"
|
||||
*/
|
||||
builder_from_slice :: proc(backing: []byte) -> Builder {
|
||||
s := transmute(mem.Raw_Slice)backing
|
||||
d := mem.Raw_Dynamic_Array{
|
||||
@@ -112,20 +140,36 @@ builder_from_slice :: proc(backing: []byte) -> Builder {
|
||||
buf = transmute([dynamic]byte)d,
|
||||
}
|
||||
}
|
||||
|
||||
// cast the builder byte buffer to a string and return it
|
||||
to_string :: proc(b: Builder) -> string {
|
||||
return string(b.buf[:])
|
||||
}
|
||||
|
||||
// return the length of the builder byte buffer
|
||||
builder_len :: proc(b: Builder) -> int {
|
||||
return len(b.buf)
|
||||
}
|
||||
|
||||
// return the cap of the builder byte buffer
|
||||
builder_cap :: proc(b: Builder) -> int {
|
||||
return cap(b.buf)
|
||||
}
|
||||
|
||||
// returns the space left in the builder byte buffer to use up
|
||||
builder_space :: proc(b: Builder) -> int {
|
||||
return max(cap(b.buf), len(b.buf), 0)
|
||||
return cap(b.buf) - len(b.buf)
|
||||
}
|
||||
|
||||
/*
|
||||
appends a byte to the builder, returns the append diff
|
||||
|
||||
builder := strings.make_builder()
|
||||
strings.write_byte(&builder, 'a') // 1
|
||||
strings.write_byte(&builder, 'b') // 1
|
||||
strings.write_byte(&builder, 'c') // 1
|
||||
fmt.println(strings.to_string(builder)) // -> abc
|
||||
*/
|
||||
write_byte :: proc(b: ^Builder, x: byte) -> (n: int) {
|
||||
n0 := len(b.buf)
|
||||
append(&b.buf, x)
|
||||
@@ -133,6 +177,14 @@ write_byte :: proc(b: ^Builder, x: byte) -> (n: int) {
|
||||
return n1-n0
|
||||
}
|
||||
|
||||
/*
|
||||
appends a slice of bytes to the builder, returns the append diff
|
||||
|
||||
builder := strings.make_builder()
|
||||
bytes := [?]byte { 'a', 'b', 'c' }
|
||||
strings.write_bytes(&builder, bytes[:]) // 3
|
||||
fmt.println(strings.to_string(builder)) // -> abc
|
||||
*/
|
||||
write_bytes :: proc(b: ^Builder, x: []byte) -> (n: int) {
|
||||
n0 := len(b.buf)
|
||||
append(&b.buf, ..x)
|
||||
@@ -140,11 +192,28 @@ write_bytes :: proc(b: ^Builder, x: []byte) -> (n: int) {
|
||||
return n1-n0
|
||||
}
|
||||
|
||||
/*
|
||||
appends a single rune into the builder, returns written rune size and an `io.Error`
|
||||
|
||||
builder := strings.make_builder()
|
||||
strings.write_rune_builder(&builder, 'ä') // 2 None
|
||||
strings.write_rune_builder(&builder, 'b') // 1 None
|
||||
strings.write_rune_builder(&builder, 'c') // 1 None
|
||||
fmt.println(strings.to_string(builder)) // -> äbc
|
||||
*/
|
||||
write_rune_builder :: proc(b: ^Builder, r: rune) -> (int, io.Error) {
|
||||
return io.write_rune(to_writer(b), r)
|
||||
}
|
||||
|
||||
/*
|
||||
appends a quoted rune into the builder, returns written size
|
||||
|
||||
builder := strings.make_builder()
|
||||
strings.write_string(&builder, "abc") // 3
|
||||
strings.write_quoted_rune_builder(&builder, 'ä') // 4
|
||||
strings.write_string(&builder, "abc") // 3
|
||||
fmt.println(strings.to_string(builder)) // -> abc'ä'abc
|
||||
*/
|
||||
write_quoted_rune_builder :: proc(b: ^Builder, r: rune) -> (n: int) {
|
||||
return write_quoted_rune(to_writer(b), r)
|
||||
}
|
||||
@@ -155,7 +224,7 @@ _write_byte :: proc(w: io.Writer, c: byte) -> int {
|
||||
return 1 if err == nil else 0
|
||||
}
|
||||
|
||||
|
||||
// writer append a quoted rune into the byte buffer, return the written size
|
||||
write_quoted_rune :: proc(w: io.Writer, r: rune) -> (n: int) {
|
||||
quote := byte('\'')
|
||||
n += _write_byte(w, quote)
|
||||
@@ -173,50 +242,75 @@ write_quoted_rune :: proc(w: io.Writer, r: rune) -> (n: int) {
|
||||
return
|
||||
}
|
||||
|
||||
|
||||
// overload for `write_string_*` variants
|
||||
write_string :: proc{
|
||||
write_string_builder,
|
||||
write_string_writer,
|
||||
}
|
||||
|
||||
/*
|
||||
appends a string to the builder, return the written byte size
|
||||
|
||||
builder := strings.make_builder()
|
||||
strings.write_string(&builder, "a") // 1
|
||||
strings.write_string(&builder, "bc") // 2
|
||||
strings.write_string(&builder, "xyz") // 3
|
||||
fmt.println(strings.to_string(builder)) // -> abcxyz
|
||||
*/
|
||||
write_string_builder :: proc(b: ^Builder, s: string) -> (n: int) {
|
||||
return write_string_writer(to_writer(b), s)
|
||||
}
|
||||
|
||||
// appends a string to the writer
|
||||
write_string_writer :: proc(w: io.Writer, s: string) -> (n: int) {
|
||||
n, _ = io.write(w, transmute([]byte)s)
|
||||
return
|
||||
}
|
||||
|
||||
|
||||
|
||||
|
||||
// pops and returns the last byte in the builder
|
||||
// returns 0 when the builder is empty
|
||||
pop_byte :: proc(b: ^Builder) -> (r: byte) {
|
||||
if len(b.buf) == 0 {
|
||||
return 0
|
||||
}
|
||||
|
||||
r = b.buf[len(b.buf)-1]
|
||||
d := cast(^mem.Raw_Dynamic_Array)&b.buf
|
||||
d.len = max(d.len-1, 0)
|
||||
return
|
||||
}
|
||||
|
||||
// pops the last rune in the builder and returns the popped rune and its rune width
|
||||
// returns 0, 0 when the builder is empty
|
||||
pop_rune :: proc(b: ^Builder) -> (r: rune, width: int) {
|
||||
if len(b.buf) == 0 {
|
||||
return 0, 0
|
||||
}
|
||||
|
||||
r, width = utf8.decode_last_rune(b.buf[:])
|
||||
d := cast(^mem.Raw_Dynamic_Array)&b.buf
|
||||
d.len = max(d.len-width, 0)
|
||||
return
|
||||
}
|
||||
|
||||
|
||||
@(private)
|
||||
DIGITS_LOWER := "0123456789abcdefx"
|
||||
|
||||
// overload for `write_quoted_string_*` variants
|
||||
write_quoted_string :: proc{
|
||||
write_quoted_string_builder,
|
||||
write_quoted_string_writer,
|
||||
}
|
||||
|
||||
/*
|
||||
append a quoted string into the builder, return the written byte size
|
||||
|
||||
builder := strings.make_builder()
|
||||
strings.write_quoted_string(&builder, "a") // 3
|
||||
strings.write_quoted_string(&builder, "bc", '\'') // 4
|
||||
strings.write_quoted_string(&builder, "xyz") // 5
|
||||
fmt.println(strings.to_string(builder)) // -> "a"'bc'xyz"
|
||||
*/
|
||||
write_quoted_string_builder :: proc(b: ^Builder, str: string, quote: byte = '"') -> (n: int) {
|
||||
n, _ = io.write_quoted_string(to_writer(b), str, quote)
|
||||
return
|
||||
@@ -228,11 +322,13 @@ write_quoted_string_writer :: proc(w: io.Writer, str: string, quote: byte = '"')
|
||||
return
|
||||
}
|
||||
|
||||
// overload for `write_encoded_rune_*`
|
||||
write_encoded_rune :: proc{
|
||||
write_encoded_rune_builder,
|
||||
write_encoded_rune_writer,
|
||||
}
|
||||
|
||||
// appends a rune to the builder, optional `write_quote` boolean tag, returns the written rune size
|
||||
write_encoded_rune_builder :: proc(b: ^Builder, r: rune, write_quote := true) -> (n: int) {
|
||||
n, _ = io.write_encoded_rune(to_writer(b), r, write_quote)
|
||||
return
|
||||
@@ -244,12 +340,15 @@ write_encoded_rune_writer :: proc(w: io.Writer, r: rune, write_quote := true) ->
|
||||
return
|
||||
}
|
||||
|
||||
|
||||
// overload for `write_escaped_rune_*`
|
||||
write_escaped_rune :: proc{
|
||||
write_escaped_rune_builder,
|
||||
write_escaped_rune_writer,
|
||||
}
|
||||
|
||||
// appends a rune to the builder, fully written out in case of escaped runes e.g. '\a' will be written as such
|
||||
// when `r` and `quote` match and `quote` is `\\` - they will be written as two slashes
|
||||
// `html_safe` flag in case the runes '<', '>', '&' should be encoded as digits e.g. `\u0026`
|
||||
write_escaped_rune_builder :: proc(b: ^Builder, r: rune, quote: byte, html_safe := false) -> (n: int) {
|
||||
n, _ = io.write_escaped_rune(to_writer(b), r, quote, html_safe)
|
||||
return
|
||||
@@ -261,21 +360,26 @@ write_escaped_rune_writer :: proc(w: io.Writer, r: rune, quote: byte, html_safe
|
||||
return
|
||||
}
|
||||
|
||||
|
||||
// writes a u64 value `i` in `base` = 10 into the builder, returns the written amount of characters
|
||||
write_u64 :: proc(b: ^Builder, i: u64, base: int = 10) -> (n: int) {
|
||||
buf: [32]byte
|
||||
s := strconv.append_bits(buf[:], i, base, false, 64, strconv.digits, nil)
|
||||
return write_string(b, s)
|
||||
}
|
||||
|
||||
// writes a i64 value `i` in `base` = 10 into the builder, returns the written amount of characters
|
||||
write_i64 :: proc(b: ^Builder, i: i64, base: int = 10) -> (n: int) {
|
||||
buf: [32]byte
|
||||
s := strconv.append_bits(buf[:], u64(i), base, true, 64, strconv.digits, nil)
|
||||
return write_string(b, s)
|
||||
}
|
||||
|
||||
// writes a uint value `i` in `base` = 10 into the builder, returns the written amount of characters
|
||||
write_uint :: proc(b: ^Builder, i: uint, base: int = 10) -> (n: int) {
|
||||
return write_u64(b, u64(i), base)
|
||||
}
|
||||
|
||||
// writes a int value `i` in `base` = 10 into the builder, returns the written amount of characters
|
||||
write_int :: proc(b: ^Builder, i: int, base: int = 10) -> (n: int) {
|
||||
return write_i64(b, i64(i), base)
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user