typealloc.3 (3762B)
1 .Dd Oct 13, 2022 2 .Dt typealloc 3 3 .Os 4 .Sh NAME 5 .Nm typealloc 6 .Nd a framework for building dynamically-allocated lists of objects represented by data types in C 7 .Sh SYNOPSIS 8 .In typealloc/typealloc.h 9 .Fn TypeAlloc_typedef ta type field len a 10 11 In headers (generate separate headers to save object code duplication): 12 .In typealloc/typeallocdefs.h 13 14 In source (auto-generate libraries for manipulating your TypeAllocs): 15 .In typealloc/typealloclib.h 16 17 .Fn TypeAlloc_readyplus ta type field len a base ta_rplus 18 .Fn TypeAlloc_ready ta type field len a base ta_ready 19 .Fn TypeAlloc_append ta type field len a base ta_rplus ta_append 20 .Fn TypeAlloc_copy ta type field len a base ta_ready ta_copy 21 .Fn TypeAlloc_free ta type field len a base ta_free 22 .Sh "Field names and their types" 23 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. 24 25 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. 26 27 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. 28 29 Copy is identical, but it copies to the start of the typealloc, rather than appending. 30 31 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;. 32 33 Other fields: 34 .Bl -tag -width "-w size " 35 .It ta 36 is the name of a typealloc. 37 .It type 38 is the name of the type that that typealloc stores an array of. 39 .It field 40 is the name of the field of the typealloc that points to the beginning of the array. This can safely be 's' if you'd like. 41 .It len 42 is the name of the field that describes the number of items in the array. 43 .It a 44 is the name of the field that describes the number of items that can be in the array before it has to be expanded. 45 .It base 46 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. 47 .El 48 .Sh Description 49 TODO: describe all these \fBmacros\fR and the functions they generate. 50 .Sh Bugs 51 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. 52 .Sh History 53 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). 54 .Sh Copyright 55 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.