.\" 
.\" Copyright 2003 Michael B. Allen <mba2000 ioplex.com>
.\" 
.TH varray 3m "Apr 29, 2005" "libmba-0.9.1" "MBA Library Functions"
.SH NAME
varray \- A variable sized array.
.SH SYNOPSIS
.nf
.B #include <mba/varray.h>
.sp
.BI "int varray_init(struct varray *" va ", size_t " membsize ", struct allocator *" al ");
.br
.BI "int varray_deinit(struct varray *" va ");
.br
.BI "struct varray *varray_new(size_t " membsize ", struct allocator *" al ");
.br
.BI "void varray_del(void *" va ");
.br
.BI "void *varray_get(struct varray *" va ", unsigned int " idx ");
.br
.BI "int varray_index(struct varray *" va ", void *" elem ");
.br
.BI "void varray_release(struct varray *" va ", unsigned int " from ");
.br
.BI "void varray_iterate(void *" va ", iter_t *" iter ");
.br
.BI "void *varray_next(void *" va ", iter_t *" iter ");
.br

.fi
.SH DESCRIPTION
The
.BR "varray" (3m)
module is a variable array that permits quick access to elements by index without allocating all the memory for the array when the array is created. Instead, memory is allocated as necessary in increasingly larger chunks (32 *
.IR "membsize" ,
64 *
.IR "membsize" ,
128 *
.IR "membsize" ,
upto 2^20 *
.IR "membsize" ).
.PP
.TP
.B init
The
.B varray_init
function with initialize the
.B varray
.I va
with no initial elements. The size of each element in the array will be
.IR "membsize" .
The
.B allocator
.I al
will be used to allocate memory to back the array.
.TP
.B deinit
The
.B varray_deinit
function deinitializes the
.B varray
.I va
and releases any storage backing the array.
.TP
.B new
The
.B varray_new
function allocates storage for a new
.B varray
object and initializes with the
.B varray_init
function.
.TP
.B del
The
.B varray_del
function calls
.B varray_deinit
on the object
.I va
and then frees the
.I va
object itself.
.TP
.B get
The
.B varray_get
function returns a pointer to memory at index
.IR "idx" .
The memory will be
.I membsize
bytes in size as specified in the
.B varray_new
function. The memory is initialized to 0 when the chunk backing it is allocated meaning the memory should initially be 0.
.TP
.B index
The
.B varray_index
function returns the index of the element
.IR "elem" .
If the element is not found -1 is returned and
.B errno
is set to
.IR "EFAULT" .
.TP
.B release
The
.B varray_release
function may release all memory chunks storing elements from index
.I from
and higher. This function will only free memory chunks that constitute elements at the
.I from
index and above. If the
.I from
index is the first element of a chunk, that chunk will be freed as well. This function should only be used if it is understood that the range of elements being accessed has been significantly reduced such that memory will not be frequently allocated and freed.
.TP
.B iterate\fR, \fBnext
The
.B varray_iterate
and
.B varray_next
functions will enumerate over every element in the array that has ever been accessed with the
.I varray_get
function. However, adjacent elements in the same memory chunk will also be returned by
.I varray_next
even if they those elements have never been accessed with
.IR "varray_get" .
Similarly, there may be gaps in the full range that are not returned by
.I varray_next
because no element was accessed in a range necessary for the chunk of memory for that range to be allocated. The
.I varray_iterate
function initializes the
.I iter
object to point to the beginning of the array. The
.I varray_next
function returns each element in the array or
.I NULL
if all elements have been enumerated.
.SH RETURNS
.TP
.B init
The
.B varray_init
function returns 0 on success or -1 for failure in which case
.I errno
will be set to an appropriate value.
.TP
.B deinit
The
.B varray_deinit
function returns 0 on success or -1 for failure in which case
.I errno
will be set to an appropriate value.
.TP
.B new
The
.B varray_new
function returns the new
.I varray
object or a null pointer if an error occurred in which case
.I errno
will be set appropriately.
.TP
.B get
The
.B varray_get
function returns a pointer to the memory at index
.I idx
or a null pointer if an error occured in which case errno will be set appropriately.
.TP
.B index
The
.B varray_index
function returns the index of the element or -1 and sets
.B errno
to
.I EFAULT
to indicate the element is not in the array.
.TP
.B next
The
.B varray_next
function returns a pointer to the memory of the next element in the enumeration or a null pointer if there are no more elements to be enumerated.