vis

a vi-like editor based on Plan 9's structural regular expressions
array.h

(4099B)
      1 #ifndef ARRAY_H
      2 #define ARRAY_H
      3 
      4 #include <stddef.h>
      5 #include <stdbool.h>
      6 
      7 /**
      8  * @file
      9  *
     10  * A dynamically growing array, there exist two typical ways to use it:
     11  *
     12  *  1. To hold pointers to externally allocated memory regions.
     13  *
     14  *     Use `array_init` for initialization, an element has the size of a
     15  *     pointer. Use the functions suffixed with ``_ptr`` to manage your
     16  *     pointers. The cleanup function `array_release_full` must only be
     17  *     used with this type of array.
     18  *
     19  *  2. To hold arbitrary sized objects.
     20  *
     21  *     Use `array_init_sized` to specify the size of a single element.
     22  *     Use the regular (i.e. without the ``_ptr`` suffix) functions to
     23  *     manage your objects. Functions like `array_add` and `array_set`
     24  *     will copy the object into the array, `array_get` will return a
     25  *     pointer to the object stored within the array.
     26  */
     27 /** A dynamically growing array. */
     28 typedef struct {
     29 	char *items;      /** Data pointer, NULL if empty. */
     30 	size_t elem_size; /** Size of one array element. */
     31 	size_t len;       /** Number of currently stored items. */
     32 	size_t count;     /** Maximal capacity of the array. */
     33 } Array;
     34 
     35 /**
     36  * Initialize an Array object to store pointers.
     37  * @rst
     38  * .. note:: Is equivalent to ``array_init_sized(arr, sizeof(void*))``.
     39  * @endrst
     40  */
     41 void array_init(Array*);
     42 /**
     43  * Initialize an Array object to store arbitrarily sized objects.
     44  */
     45 void array_init_sized(Array*, size_t elem_size);
     46 /** Initialize Array by using the same element size as in ``from``. */
     47 void array_init_from(Array*, const Array *from);
     48 /** Release storage space. Reinitializes Array object. */
     49 void array_release(Array*);
     50 /**
     51  * Release storage space and call `free(3)` for each stored pointer.
     52  * @rst
     53  * .. warning:: Assumes array elements to be pointers.
     54  * @endrst
     55  */
     56 void array_release_full(Array*);
     57 /** Empty array, keep allocated memory. */
     58 void array_clear(Array*);
     59 /** Reserve memory to store at least ``count`` elements. */
     60 bool array_reserve(Array*, size_t count);
     61 /**
     62  * Get array element.
     63  * @rst
     64  * .. warning:: Returns a pointer to the allocated array region.
     65  *              Operations which might cause reallocations (e.g. the insertion
     66  *              of new elements) might invalidate the pointer.
     67  * @endrst
     68  */
     69 void *array_get(const Array*, size_t idx);
     70 /**
     71  * Set array element.
     72  * @rst
     73  * .. note:: Copies the ``item`` into the Array. If ``item`` is ``NULL``
     74  *           the corresponding memory region will be cleared.
     75  * @endrst
     76  */
     77 bool array_set(Array*, size_t idx, void *item);
     78 /** Dereference pointer stored in array element. */
     79 void *array_get_ptr(const Array*, size_t idx);
     80 /** Store the address to which ``item`` points to into the array. */
     81 bool array_set_ptr(Array*, size_t idx, void *item);
     82 /** Add element to the end of the array. */
     83 bool array_add(Array*, void *item);
     84 /** Add pointer to the end of the array. */
     85 bool array_add_ptr(Array*, void *item);
     86 /**
     87  * Remove an element by index.
     88  * @rst
     89  * .. note:: Might not shrink underlying memory region.
     90  * @endrst
     91  */
     92 bool array_remove(Array*, size_t idx);
     93 /** Remove all elements with index greater or equal to ``length``, keep allocated memory. */
     94 bool array_truncate(Array*, size_t length);
     95 /**
     96  * Change length.
     97  * @rst
     98  * .. note:: Has to be less or equal than the capacity.
     99  *           Newly accessible elements preserve their previous values.
    100  * @endrst
    101  */
    102 bool array_resize(Array*, size_t length);
    103 /**
    104  * Sort array, the comparision function works as for `qsort(3)`.
    105  */
    106 void array_sort(Array*, int (*compar)(const void*, const void*));
    107 /**
    108  * Push item onto the top of the stack.
    109  * @rst
    110  * .. note:: Is equivalent to ``array_add(arr, item)``.
    111  * @endrst
    112  */
    113 bool array_push(Array*, void *item);
    114 /**
    115  * Get and remove item at the top of the stack.
    116  * @rst
    117  * .. warning:: The same ownership rules as for ``array_get`` apply.
    118  * @endrst
    119  */
    120 void *array_pop(Array*);
    121 /**
    122  * Get item at the top of the stack without removing it.
    123  * @rst
    124  * .. warning:: The same ownership rules as for ``array_get`` apply.
    125  * @endrst
    126  */
    127 void *array_peek(const Array*);
    128 
    129 #endif