commit 28603430eb4c5a645887b5aa8cf6c6d0eba8788f
parent 8fbb16200dbc666196a1396e234d8fa8056ab8a3
Author: Ellenor Bjornsdottir <ellenor@umbrellix.net>
Date: Tue, 8 Nov 2022 23:14:18 +0000
Minor corrections i think
Diffstat:
2 files changed, 14 insertions(+), 9 deletions(-)
diff --git a/doc/typealloc/3typealloc/typealloc.3 b/doc/typealloc/3typealloc/typealloc.3
@@ -20,13 +20,15 @@ In source (auto-generate libraries for manipulating your TypeAllocs):
.Fn TypeAlloc_copy ta type field len a base ta_ready ta_copy
.Fn TypeAlloc_free ta type field len a base ta_free
.Sh "Field names and their types"
-A "ta_rplus" field refers to the \fBname\fR of a function comparable to stralloc_readyplus(sa, length);.
+A "ta_rplus" field refers to the \fBname\fR of a function comparable to stralloc_readyplus(sa, length);. This function would check if your typealloc is ready for \fIlength\fR more entries, and allocate memory to do so if not.
-A "ta_ready" field refers to the \fBname\fR of a function comparable to stralloc_ready(sa, length);.
+A "ta_ready" field refers to the \fBname\fR of a function comparable to stralloc_ready(sa, length);. This function would check if your typealloc is ready to contain a total of \fIlength\fR entries, and allocate memory to do so if not.
-A "ta_append" field refers to the \fBname\fR of a function comparable to stralloc_cat(sa, items, length);.
+A "ta_append" field refers to the \fBname\fR of a function comparable to stralloc_cat(sa, items, length);. This function runs ta_rplus, and then appends up to \fIlength\fR items from \fI*items\fR to your typealloc.
-A "ta_free" field refers to the \fBname\fR of a function comparable to stralloc_free(sa);.
+Copy is identical, but it copies to the start of the typealloc, rather than appending.
+
+A "ta_free" field refers to the \fBname\fR of a function comparable to stralloc_free(sa);. This is exactly equivalent to free(sa.s); sa.s = NULL; sa.len = sa.a = 0;.
Other fields:
.Bl -tag -width "-w size "
@@ -41,11 +43,13 @@ is the name of the field that describes the number of items in the array.
.It a
is the name of the field that describes the number of items that can be in the array before it has to be expanded.
.It base
-Unclear, but I've only ever seen it at 10. It is an operand of the use of __builtin_mul_overflow in the typeallocdefs header.
+Unclear, but I've only ever seen it at 10. It is an operand of the use of __builtin_mul_overflow in the typealloclib header. Always set this to 10. You are not intended to understand this.
.El
.Sh Description
-TODO: describe all these \fBmacros\fR.
+TODO: describe all these \fBmacros\fR and the functions they generate.
+.Sh Bugs
+This manpage will not work on Plan 9, although the data structure and functions described herein will. mandoc it -T man on a UNIX machine if you need to install this manpage at /sys/man/2 in Plan 9.
.Sh History
-A GEN_ALLOC facility first appeared in qmail. The typealloc facility, derived from the GEN_ALLOC facility, originated in Nightmare Mail (2022).
+A GEN_ALLOC facility first appeared in qmail and was used to create strallocs (mentioned here in the way of an example). The typealloc facility, derived from the GEN_ALLOC facility, originated in Nightmare Mail (2022).
.Sh Copyright
-Inconsistent with the rest of suitcase, the changes to GEN_ALLOC that make it typealloc are licenced to you under the terms of the Creative Commons Zero licence. To the extent that I, Ellenor et al Bjornsdottir, hold copyright in this work, I grant you full licence to use the parts of this work I hold copyright in as if it had lapsed into the public domain. Where that is not possible, permission to use, copy, modify and redistribute the parts of this work I hold copyright in is granted, free of further hindrance, and also without any warranties express or implied, including that of merchantability, fitness for purpose, or noninfringement of others' copyrights (though I do not believe any are infringed).
+Inconsistent with the rest of suitcase, the changes to GEN_ALLOC that make it typealloc are licenced to you under the following terms: To the extent that I, Ellenor et al Bjornsdottir, hold copyright in this work, I grant you full licence to use the parts of this work I hold copyright in as if it had lapsed into the public domain. Where that is not possible, permission to use, copy, modify and redistribute, or to do some or all of those things at the same time, or in any sequence, the parts of this work I hold copyright in is granted, free of further hindrance, and also without any warranties express or implied, including that of merchantability, fitness for purpose, or noninfringement of others' copyrights (though I do not believe any are infringed). I believe this is substantially identical to the 0-clause BSD licence.
diff --git a/head/ta_stralloc/stralloc.h b/head/ta_stralloc/stralloc.h
@@ -2,8 +2,9 @@
#define STRALLOC_H
#include "typealloc.h"
+#include "typeallocdefs.h"
-GEN_ALLOC_typedef(stralloc,char,s,len,a)
+TypeAlloc_typedef(stralloc,char,s,len,a)
#define STRALLOC_ZERO {0, 0, 0}
extern int stralloc_starts(stralloc *sa, char *s);
