Browse Source

add man pages for array API

master
Felix von Leitner 18 years ago
parent
commit
58bf3e91a3
  1. 1
      CHANGES
  2. 51
      array/array_allocate.3
  3. 19
      array/array_bytes.3
  4. 26
      array/array_cat.3
  5. 18
      array/array_cat0.3
  6. 20
      array/array_catb.3
  7. 22
      array/array_cate.3
  8. 20
      array/array_cats.3
  9. 19
      array/array_cats0.3
  10. 32
      array/array_equal.3
  11. 21
      array/array_fail.3
  12. 20
      array/array_get.3
  13. 20
      array/array_length.3
  14. 23
      array/array_reset.3
  15. 16
      array/array_start.3
  16. 16
      array/array_trunc.3
  17. 24
      array/array_truncate.3

1
CHANGES

@ -2,6 +2,7 @@
add buffer_fromsa (make buffer from stralloc)
add API for integer multiply with overflow detection
change length counters from int to long for 64-bit platforms
add array API from http://cr.yp.to/lib/array.html
0.15:
man page update (document stralloc return values)

51
array/array_allocate.3

@ -0,0 +1,51 @@
.TH array_allocate 3
.SH NAME
array_allocate \- make sure array has at least n elements allocated
.SH SYNTAX
.B #include <array.h>
void* \fBarray_allocate\fP(array* \fIx\fR, uint64 \fImembersize\fR, int64 \fIpos\fR);
array \fIx\fR;
int64 \fIpos\fR;
\fIt\fR* p = array_allocate(&\fIx\fR,sizeof(\fIt\fR),\fIpos\fR);
.SH DESCRIPTION
array_allocate makes sure that enough bytes are allocated in \fIx\fR for
at least \fIpos\fR+1 objects of type \fIt\fR. (The size of \fIt\fR must
be positive; otherwise the effects are undefined.) If not enough bytes
are allocated (or \fIx\fR is unallocated), array_allocate allocates more
bytes, moving the dynamically allocated region if necessary.
array_allocate often allocates somewhat more bytes than necessary, to
save time later.
array_allocate then makes sure that the number of bytes initialized
covers at least those \fIpos\fR+1 objects. If not enough bytes are
initialized, array_allocate initializes more bytes (setting them to 0),
up to exactly the end of the \fIpos\fR+1st object.
array_allocate then returns a pointer to the \fIpos\fR+1st object; i.e.,
object number \fIpos\fR, with objects numbered starting at 0. This
pointer can be used to change or inspect the object. The pointer can
continue to be used through subsequent calls to array_get, array_start,
array_length, and array_bytes, but it must not be used after any other
operations on this array.
If something goes wrong, array_allocate returns 0, setting \fBerrno\fR
appropriately, without touching \fIx\fR. In particular, array_allocate
returns 0 if
.sp 1
.IP \(bu
\fIx\fR has failed, or
.IP \(bu
\fIpos\fR is negative, or
.IP \(bu
not enough memory is available.
.PP
array_allocate does \fInot\fR change \fIx\fR to have failed; if you want
to do that, use array_fail.
.SH "SEE ALSO"
array_get(3), array_start(3), array_fail(3)

19
array/array_bytes.3

@ -0,0 +1,19 @@
.TH array_bytes 3
.SH NAME
array_bytes \- get number of allocated members in array
.SH SYNTAX
.B #include <array.h>
int64 \fBarray_bytes\fP(array* \fIx\fR);
array \fIx\fR;
int64 bytes = array_bytes(&\fIx\fR);
.SH DESCRIPTION
array_bytes returns the number of initialized bytes in \fIx\fR, without
regard to \fIt\fR.
If \fIx\fR is unallocated, array_length and array_bytes return 0.
.SH "SEE ALSO"
array_allocate(3), array_get(3), array_fail(3), array_length(3)

26
array/array_cat.3

@ -0,0 +1,26 @@
.TH array_cat 3
.SH NAME
array_cat \- append one array to another
.SH SYNTAX
.B #include <array.h>
void \fBarray_cat\fP(array* \fIx\fR,array* \fIy\fR);
array \fIx\fR;
array \fIy\fR;
array_cat(&\fIx\fR,&\fIy\fR);
.SH DESCRIPTION
array_cat appends \fIy\fR to \fIx\fR; i.e., it changes \fIx\fR,
allocating more space if necessary, so that the initialized bytes in
\fIx\fR are the previously initialized bytes in \fIx\fR followed by a
copy of the initialized bytes in \fIy\fR.
If \fIx\fR has failed, array_cat has no effect.
If \fIy\fR has failed, array_cat switches \fIx\fR to have failed.
If not enough memory is available, array_cat switches \fIx\fR to have failed.
.SH "SEE ALSO"
array_allocate(3), array_get(3), array_fail(3), array_reset(3),
array_catb(3), array_cats(3), array_cats0(3), array_cate(3)

18
array/array_cat0.3

@ -0,0 +1,18 @@
.TH array_cat0 3
.SH NAME
array_cat0 \- append 0 byte to an array
.SH SYNTAX
.B #include <array.h>
void \fBarray_cat0\fP(array* \fIx\fR);
array \fIx\fR;
array_cat0(&\fIx\fR);
.SH DESCRIPTION
array_cat0 appends a 0-byte to the array \fIx\fR.
array_cat0 handles failure in the same way as array_cat.
.SH "SEE ALSO"
array_allocate(3), array_get(3), array_fail(3), array_reset(3),
array_cat(3), array_catb(3), array_cats(3), array_cats0(3), array_cate(3)

20
array/array_catb.3

@ -0,0 +1,20 @@
.TH array_catb 3
.SH NAME
array_catb \- append bytes to an array
.SH SYNTAX
.B #include <array.h>
void \fBarray_catb\fP(array* \fIx\fR,const char* \fIy\fR,int64 \fIlen\fR);
array \fIx\fR;
const char* \fIy\fR;
int64 \fIlen\fR;
array_catb(&\fIx\fR,\fIy\fR,\fIlen\fR);
.SH DESCRIPTION
array_catb appends the bytes \fIy\fR[0], \fIy\fR[1], ...,
\fIy\fR[\fIlen\fR-1] to the array \fIx\fR. It handles failure in the
same way as array_cat.
.SH "SEE ALSO"
array_allocate(3), array_get(3), array_fail(3), array_reset(3),
array_cat(3), array_cats(3), array_cats0(3), array_cate(3)

22
array/array_cate.3

@ -0,0 +1,22 @@
.TH array_cate 3
.SH NAME
array_cate \- append subset of one array to another array
.SH SYNTAX
.B #include <array.h>
void \fBarray_cate\fP(array* \fIx\fR,array* \fIy\fR, int64 \fIpos\fR,int64 \fIstop\fR);
array \fIx\fR;
array \fIy\fR;
int64 \fIpos\fR;
int64 \fIstop\fR;
array_cate(&\fIx\fR,\fIy\fR,\fIpos\fR,\fIstop\fR);
.SH DESCRIPTION
array_cate is like array_cat, but uses only byte positions \fIpos\fR
through \fIstop\fR-1 in \fIy\fR. It fails if \fIpos\fR negative, or if
\fIstop\fR is smaller than \fIpos\fR, or if the number of initialized
bytes in \fIy\fR is smaller than \fIstop\fR.
.SH "SEE ALSO"
array_allocate(3), array_get(3), array_fail(3), array_reset(3),
array_cat(3), array_cats(3), array_cats0(3), array_cate(3)

20
array/array_cats.3

@ -0,0 +1,20 @@
.TH array_cats 3
.SH NAME
array_cats \- append C string to an array
.SH SYNTAX
.B #include <array.h>
void \fBarray_cats\fP(array* \fIx\fR,const char* \fIy\fR);
array \fIx\fR;
array_cats(&\fIx\fR,"fnord");
.SH DESCRIPTION
array_cats appends the contents of the 0-terminated string \fIy\fR, not
including the terminating 0 byte, to the array \fIx\fR.
array_cats handles failure in the same way as array_cat.
.SH "SEE ALSO"
array_allocate(3), array_get(3), array_fail(3), array_reset(3),
array_cat(3), array_catb(3), array_cats0(3), array_cate(3),
array_cat0(3)

19
array/array_cats0.3

@ -0,0 +1,19 @@
.TH array_cats0 3
.SH NAME
array_cats0 \- append C string to an array
.SH SYNTAX
.B #include <array.h>
void \fBarray_cats0\fP(array* \fIx\fR,const char* \fIy\fR);
array \fIx\fR;
array_cats0(&\fIx\fR,"fnord");
.SH DESCRIPTION
array_cats0 appends the contents of the 0-terminated string \fIy\fR,
including the terminating 0 byte, to the array \fIx\fR.
array_cats0 handles failure in the same way as array_cat.
.SH "SEE ALSO"
array_allocate(3), array_get(3), array_fail(3), array_reset(3),
array_cat(3), array_catb(3), array_cats(3), array_cate(3)

32
array/array_equal.3

@ -0,0 +1,32 @@
.TH array_equal 3
.SH NAME
array_equal \- compare two arrays for equality
.SH SYNTAX
.B #include <array.h>
int \fBarray_equal\fP(array* \fIx\fR,array* \fIy\fR);
array \fIx\fR;
array \fIy\fR;
array_equal(&\fIx\fR,&\fIy\fR);
.SH DESCRIPTION
array_equal returns nonzero if x and y have the same contents: i.e.,
.sp 1
.IP \(bu
\fIx\fR and \fIy\fR are both unallocated; or
.IP \(bu
\fIx\fR is unallocated, \fIy\fR is allocated, and \fIy\fR has no
initialized bytes; or
.IP \(bu
\fIx\fR is allocated, \fIy\fR is unallocated, and \fIx\fR has no
initialized bytes; or
.IP \(bu
\fIx\fR and \fIy\fR are both allocated and have the same sequence of
initialized bytes.
.PP
Otherwise it returns 0.
.SH "SEE ALSO"
array_allocate(3), array_get(3), array_fail(3), array_reset(3)

21
array/array_fail.3

@ -0,0 +1,21 @@
.TH array_fail 3
.SH NAME
array_fail \- switch array to have failed
.SH SYNTAX
.B #include <array.h>
void \fBarray_fail\fP(array* \fIx\fR);
array \fIx\fR;
array_fail(&\fIx\fR);
.SH DESCRIPTION
If \fIx\fR is allocated, array_fail frees the region that \fIx\fR points
to, and switches \fIx\fR to have failed.
If \fIx\fR is unallocated, array_fail simply switches \fIx\fR to have
failed.
If \fIx\fR has already failed, array_fail has no effect.
.SH "SEE ALSO"
array_allocate(3), array_reset(3)

20
array/array_get.3

@ -0,0 +1,20 @@
.TH array_get 3
.SH NAME
array_get \- get pointer to nth element in array
.SH SYNTAX
.B #include <array.h>
void* \fBarray_get\fP(array* \fIx\fR, uint64 \fImembersize\fR, int64 \fIpos\fR);
array \fIx\fR;
int64 \fIpos\fR;
\fIt\fR* p = array_get(&\fIx\fR,sizeof(\fIt\fR),\fIpos\fR);
.SH DESCRIPTION
array_get is similar to array_allocate, but it does not allocate any
extra bytes, and it does not initialize any extra bytes. It returns 0
if \fIx\fR is unallocated, for example, or if fewer than
(\fIpos\fR+1)*sizeof(\fIt\fR) bytes are initialized.
.SH "SEE ALSO"
array_allocate(3), array_fail(3), array_start(3)

20
array/array_length.3

@ -0,0 +1,20 @@
.TH array_length 3
.SH NAME
array_length \- get number of allocated members in array
.SH SYNTAX
.B #include <array.h>
int64 \fBarray_length\fP(array* \fIx\fR,uint64 \fImembersize\fR);
array \fIx\fR;
int64 members = array_length(&\fIx\fR,sizeof(\fIt\fR));
.SH DESCRIPTION
array_length returns the number of initialized bytes in \fIx\fR, divided
by the size of \fIt\fR. In other words, array_get will succeed for
positions 0 through array_length-1; it will fail for position
array_length.
If \fIx\fR is unallocated, array_length and array_bytes return 0.
.SH "SEE ALSO"
array_allocate(3), array_get(3), array_fail(3), array_bytes(3)

23
array/array_reset.3

@ -0,0 +1,23 @@
.TH array_reset 3
.SH NAME
array_reset \- deallocate array
.SH SYNTAX
.B #include <array.h>
void \fBarray_reset\fP(array* \fIx\fR);
array \fIx\fR;
array_reset(&\fIx\fR);
.SH DESCRIPTION
If \fIx\fR is allocated, array_reset frees the region that \fIx\fR
points to, and switches \fIx\fR to being unallocated.
If \fIx\fR x has failed, array_reset simply switches \fIx\fR to being
unallocated.
If \fIx\fR x is unallocated, array_reset has no effect.
.SH "SEE ALSO"
array_allocate(3), array_get(3), array_fail(3), array_trunc(3),
array_truncate(3)

16
array/array_start.3

@ -0,0 +1,16 @@
.TH array_start 3
.SH NAME
array_start \- get pointer to first element in array
.SH SYNTAX
.B #include <array.h>
void* \fBarray_start\fP(array* \fIx\fR);
array \fIx\fR;
\fIt\fR* \fIp\fR = array_start(&\fIx\fR);
.SH DESCRIPTION
array_start is the same as array_get with \fIpos\fR equal to 0.
.SH "SEE ALSO"
array_allocate(3), array_get(3), array_fail(3)

16
array/array_trunc.3

@ -0,0 +1,16 @@
.TH array_trunc 3
.SH NAME
array_trunc \- reduce number of initialized bytes
.SH SYNTAX
.B #include <array.h>
void \fBarray_trunc\fP(array* \fIx\fR);
array \fIx\fR;
array_trunc(&\fIx\fR);
.SH DESCRIPTION
array_trunc is the same as array_truncate with \fIlen\fR equal to 0.
.SH "SEE ALSO"
array_allocate(3), array_get(3), array_fail(3), array_truncate(3),
array_reset(3)

24
array/array_truncate.3

@ -0,0 +1,24 @@
.TH array_truncate 3
.SH NAME
array_truncate \- reduce number of initialized bytes
.SH SYNTAX
.B #include <array.h>
void \fBarray_truncate\fP(array* \fIx\fR, uint64 \fImembersize\fR, int64 \fIlen\fR);
array_truncate(&\fIx\fR,sizeof(\fIt\fR),\fIlen\fR);
.SH DESCRIPTION
array_truncate reduces the number of initialized bytes in \fIx\fR to
exactly \fIlen\fR*sizeof(\fIt\fR). If the number of initialized bytes
was already this small (or smaller), array_truncate has no effect. If
\fIlen\fR is negative, array_truncate has no effect. If \fIx\fR is
unallocated, array_truncate has no effect. If \fIx\fR has failed,
array_truncate has no effect.
array_truncate does not change the allocation in \fIx\fR. If you want to free
the memory used by \fIx\fR, use array_reset.
.SH "SEE ALSO"
array_allocate(3), array_get(3), array_fail(3), array_trunc(3),
array_reset(3)
Loading…
Cancel
Save