1 files changed, 117 insertions, 13 deletions

diff --git a/core/strings/builder.odin b/core/strings/builder.odin
index 6952ba088..d6065cf70 100644
--- a/core/strings/builder.odin
+++ b/core/strings/builder.odin
@@ -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)
 }