Varray

# 20. Varray

The 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 * `membsize`, 64 * `membsize`, 128 * `membsize`, upto 2^21 * `membsize`).

### 20.1. Varray functions

These functions should be used to manage varray objects.

The `varray_init` function
Synopsis

      #include <mba/varray.h>
      int varray_init(struct varray *va, size_t membsize, struct allocator *al);

Description
The `varray_init` function with initialize the `varray` `va` with no initial elements. The size of each element in the array will be `membsize`. The `allocator` `al` will be used to allocate memory to back the array.
Returns
The `varray_init` function returns 0 on success or -1 for failure in which case `errno` will be set to an appropriate value.

The `varray_deinit` function
Synopsis

      #include <mba/varray.h>
      int varray_deinit(struct varray *va);

Description
The `varray_deinit` function deinitializes the `varray` `va` and releases any storage backing the array.
Returns
The `varray_deinit` function returns 0 on success or -1 for failure in which case `errno` will be set to an appropriate value.

The `varray_new` function
Synopsis

      #include <mba/varray.h>
      struct varray *varray_new(size_t membsize, struct allocator *al);

Description
The `varray_new` function allocates storage for a new `varray` object and initializes with the `varray_init` function.
Returns
The `varray_new` function returns the new `varray` object or a null pointer if an error occurred in which case `errno` will be set appropriately.

The `varray_del` function
Synopsis

      #include <mba/varray.h>
      void varray_del(void *va);

Description
The `varray_del` function calls `varray_deinit` on the object `va` and then frees the `va` object itself.

The `varray_get` function
Synopsis

      #include <mba/varray.h>
      void *varray_get(struct varray *va, unsigned int idx);

Description
The `varray_get` function returns a pointer to memory at index `idx`. The memory will be `membsize` bytes in size as specified in the `varray_new` function. The memory is initialized to 0 when the chunk backing it is allocated meaning the memory should initially be 0.
Returns
The `varray_get` function returns a pointer to the memory at index `idx` or a null pointer if an error occured in which case errno will be set appropriately.

The `varray_release` function
Synopsis

      #include <mba/varray.h>
      void varray_release(struct varray *va, unsigned int from);

Description
The `varray_release` function may release all memory chunks storing elements from index `from` and higher. This function will only free memory chunks that constitute elements at the `from` index and above. If the `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.

The `varray_iterate` function
Synopsis

      #include <mba/varray.h>
      void varray_iterate(void *va, iter_t *iter);

Description
The `varray_iterate` and `varray_next` functions will enumerate over every element in the array that has ever been accessed with the `varray_get` function. However, adjacent elements in the same memory chunk will also be returned by `varray_next` even if they those elements have never been accessed with `varray_get`. Similarly, there may be gaps in the full range that are not returned by `varray_next` because no element was accessed in a range necessary for the chunk of memory for that range to be allocated. The `varray_iterate` function initializes the `iter` object to point to the beginning of the array. The `varray_next` function returns each element in the array or `NULL` if all elements have been enumerated.

The `varray_next` function
Synopsis

      #include <mba/varray.h>
      void *varray_next(void *va, iter_t *iter);

Returns
The `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.

Copyright 2003 Michael B. Allen <mba2000 ioplex.com>