NAME

       array_allocate - make sure array has at least n elements allocated

SYNTAX

       #include <libowfat/array.h>

       void* array_allocate(array* x, uint64 membersize, int64 pos);

         array x;
         int64 pos;
         t* p = array_allocate(&x,sizeof(t),pos);

DESCRIPTION

       array_allocate  makes sure that enough bytes are allocated in x for at least pos+1 objects
       of type t. (The size of t must be positive; otherwise the effects are undefined.)  If  not
       enough  bytes  are  allocated  (or x 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
       pos+1 objects. If not enough bytes are initialized, array_allocate initializes more  bytes
       (setting them to 0), up to exactly the end of the pos+1st object.

       array_allocate then returns a pointer to the pos+1st object; i.e., object number pos, 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 errno appropriately, without
       touching x. In particular, array_allocate returns 0 if

       •      x has failed, or

       •      pos is negative, or

       •      not enough memory is available.

       array_allocate does not change x to have failed; if you want to do that, use array_fail.

PERFORMANCE

       This function can call realloc when the array needs to  be  enlarged.   Under  exceptional
       circumstances,  this  can lead to blocking the current thread.  It will also zero-fill the
       newly enlarged part of the array, leading to all pages being mapped in  by  the  operating
       system.  If a small array is enlarged to a very large array, this can lead to swapping and
       blocking.

SEE ALSO

       array_get(3), array_start(3), array_fail(3)

                                                                                array_allocate(3)