Differences From
Artifact [7f4b99ca6c]:
55 55
56 56 ## ksbufmk
57 57 `ksbuf* ksbufmk(void* where, kiochan channel, sz run)` initializes a new buffer at the specified address. `run` should be equivalent to the full length of the memory region minus `sizeof(struct ksbuf)` - in other words, the size of the string the `ksbuf` can hold. memory should be allocated by the user, either by creating an array on the stack or with `kmem` allocation functions. `ksbufmk()` returns a pointer to the new structure. the return value will always point to the same point in memory as `where`, but will be of the appropriate type to pass to buffer functions.
58 58
59 59 ## ksbufput
60 60 `kcond ksbufput(ksbuf* b, ksraw str)` copies a string into a buffer with `kscp`. flushing it as necessary.
61 61
62 -# ksbufflush
62 +## ksbufflush
63 63 `kcond ksbufflush(ksbuf* b)` flushes a buffer to its assigned channel, emptying it and readying it for another write cycle. a buffer should almost always be flushed before it goes out of scope or is deallocated.
64 64
65 65 ## kscomp
66 66 `char* kscomp(size_t ct, ksraw struct[], kmbuf* buf)` is a **string composition** function. it serves as an efficient, generalized replacement for functions like `strcat` and `strdup`.
67 67
68 68 to use kscomp, create an array of `kstr` and fill it with the strings you wish to concatenate. for example, to programmatically generate an HTML link tag, you might use the following code.
69 69
................................................................................
76 76 ksref(text),
77 77 Kstr("</a>")
78 78 };
79 79 char* html = kscomp(Kmsz(chain), chain, &buf);
80 80
81 81 kscomp will only calculate the length of individual strings if they are not already known. when it needs to calculate the length of a string, it will store that length in the original array so repeated calls can be made without needing to repeatedly calculate the lengths. this is not always desirable, so the variant `kscompc` exists, which is exactly the same as `kscomp` in every respect except that `chain` is not altered in any way.
82 82
83 -## macros
83 +## ksemit
84 +`ksemit(sz len, ksraw* array, kiochan channel)` takes a `len`-length `array` of `ksraw`s and prints them to a channel. a buffer will be allocated based on the total length of the strings to avoid unnecessary write calls.
85 +
86 +## ksemitc
87 +`ksemitc(const char** array, sz bufsz, kiochan channel)` takes a null-terminated `array` of NUL-terminated strings and buffer-prints them to a channel. `bufsz` controls the size of the buffer used, and should be as close as possible to the size of the strings emitted. the buffer will be kept on the stack, so no memory management or cleanup is necessary.
88 +
89 +# macros
84 90 if `KFclean` is not set when <k/str.h> is included, the following macros are defined.
85 91
86 - * `Kstr(string)` - the compile-time equivalent to `kstr()`. `Kstr` takes a literal string and inserts the text `{ sizeof (string), string }` into the document, suitable for initializing a kstr.
92 + * `Kstr(string)` - the compile-time equivalent to `kstr()`. `Kstr` takes a literal string and inserts the text `{ sizeof (string) - 1, string }` into the document, suitable for initializing a kstr.