You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
93 lines
1.9 KiB
Groff
93 lines
1.9 KiB
Groff
.TH array 3
|
|
.SH NAME
|
|
array \- The array library interface
|
|
.SH SYNTAX
|
|
.B #include <libowfat/array.h>
|
|
|
|
.SH DESCRIPTION
|
|
An \fBallocated\fR array variable keeps track of
|
|
|
|
.sp 1
|
|
.IP \(bu
|
|
a (nonzero) pointer to a dynamically allocated region of memory;
|
|
.IP \(bu
|
|
the number of bytes allocated (always positive); and
|
|
.IP \(bu
|
|
the number of bytes initialized (between 0 and the number of bytes
|
|
allocated).
|
|
.PP
|
|
|
|
There are two other possibilities for the state of an array variable:
|
|
\fBunallocated\fR and \fIfailed\fR. In both cases, there is no
|
|
dynamically allocated region of memory.
|
|
|
|
A new array variable is normally created as a static variable:
|
|
|
|
#include <libowfat/array.h>
|
|
|
|
static array x;
|
|
|
|
At this point it is unallocated. The array library provides various
|
|
allocation and inspection functions.
|
|
|
|
A new array variable can also be created dynamically. It must be
|
|
initialized to all-0, meaning unallocated, before it is given to any of
|
|
the array functions. It must be returned to the unallocated (or failed)
|
|
state, for example with array_reset, before it is destroyed. These rules
|
|
prevent all memory leaks.
|
|
.SH "Expansion and inspection"
|
|
|
|
array x;
|
|
|
|
t* p1 = array_allocate(&x,sizeof(t),pos);
|
|
|
|
t* p2 = array_get(&x,sizeof(t),pos);
|
|
|
|
t* p3 = array_start(&x);
|
|
|
|
int64 len = array_length(&x,sizeof(t));
|
|
|
|
int64 bytes = array_bytes(&x);
|
|
|
|
.SH "Truncation and deallocation"
|
|
|
|
array x;
|
|
|
|
array_truncate(&x,sizeof(t),len);
|
|
|
|
array_trunc(&x);
|
|
|
|
array_reset(&x);
|
|
|
|
array_fail(&x);
|
|
|
|
.SH "Comparison"
|
|
|
|
array x;
|
|
array y;
|
|
|
|
if (array_equal(&x,&y))
|
|
/* arrays are equal... */
|
|
|
|
.SH "Concatenation"
|
|
|
|
array x;
|
|
array y;
|
|
|
|
array_cat(&x,&y);
|
|
|
|
array_catb(&x,"fnord",5);
|
|
|
|
array_cats(&x,"fnord");
|
|
|
|
array_cats0(&x,"fnord"); /* also append the \\0 */
|
|
|
|
array_cat0(&x); /* append \\0 */
|
|
|
|
array_cate(&x,"fnord",1,4); /* append "nor" */
|
|
|
|
.SH "ORIGINAL API DEFINITION"
|
|
http://cr.yp.to/lib/array.html
|
|
.SH "SEE ALSO"
|
|
array_get(3), array_start(3), array_fail(3)
|