/*

 *      Dynamic array, to store all your flims in Includes macros required

 *      to create an array of strings but as the primitive type for the

 *      array is void * providing your own duplicate_primitive and

 *      destroy_primitive functions will allow you to use the dynamic_array

 *      API to have a dynamic array containing any primitive

 *

 *      Authors: Horms <horms@vergenet.net>

 *

 *      Released under the terms of the GNU GPL

 *

 */

#ifndef DYNAMIC_ARRAY_FLIM

#define DYNAMIC_ARRAY_FLIM

#include <stdio.h>

#include <stdlib.h>

#include <string.h>

#include <errno.h>

/*

 * Default blocking size for dynamic array

 * can be overriden when array is created

 */

#define DEFAULT_DYNAMIC_ARRAY_BLOCK_SIZE (size_t)7

/* #defines to destroy and dupilcate strings */

#define DESTROY_STR (void (*)(void *s))free

#define DUP_STR (void *(*)(const void *s))strdup

#define DISPLAY_STR (void (*)(char *d, void *s))strcpy

#define LEN_STR (size_t (*)(void *s))strlen

typedef struct {

  void **vector;

  size_t count;

  size_t allocated_size;

  size_t block_size;

} dynamic_array_t;

/**********************************************************************

 * dynamic_array_create

 * Create a dynamic array

 * pre: block_size: blocking size to use.

 *                  DEFAULT_DYNAMIC_ARRAY_BLOCK_SIZE is used if

 *                  block_size is 0

 *                  Block size refers to how many elements are prealocated

 *                  each time the array is grown.

 * return: An empty dynamic array

 *         NULL on error

 **********************************************************************/

extern dynamic_array_t *dynamic_array_create(size_t block_size);

/**********************************************************************

 * dynamic_array_destroy

 * Free an array an all the elements held within

 * pre: a: array to destroy

 *      destroy_element: pointer to funtion to destroy array elements

 *                       Function should take an argument of a pointer

 *                       and free the memory allocated to the structure

 *                       pointed to.

 * post: array is freed and destroy_element is called for all elements

 *       of the array.

 *       Nothing if a is NULL

 **********************************************************************/

void dynamic_array_destroy(dynamic_array_t * a,

			   void (*destroy_element) (void *));

/**********************************************************************

 * dynamic_array_add_element

 * Add an element to a dynamic array

 * pre: a: dynamic array to add element to

 *      e: element to add

 *      destroy_element: pointer to a function to destroy an element

 *                       passed to dynamic_array_destroy on error

 *      duplicate_element: pointer to a function to duplicate an

 *                         element should take a pointer to an element

 *                         to duplicate as the only element and return

 *                         a copy of the element Any memory allocation

 *                         required should be done by this function.

 * post: element in inserted in the first unused position in the array

 *       array size is increased by a->block_size if there is

 *       insufficient room in the array to add the element.

 *       Nothing is done if e is NULL

 * return: a on success

 *         NULL if a is NULL or an error occurs

 **********************************************************************/

dynamic_array_t *dynamic_array_add_element(dynamic_array_t * a,

					   const void *e,

					   void (*destroy_element) (void

								    *s),

					   void

					   *(*duplicate_element) (const

								  void

								  *s));

/**********************************************************************

 * dynamic_array_display

 * Print the contents of a dynamic array to a string

 * pre: a: dynamic array to display

 *      delimiter: character to place between elements of the array

 *      display_element: pointer to a function to display an element

 *      element_length:  pointer to a function to return the

 *                       length of an element

 * post: If a is NULL or there are no elements in a then nothing is done

 *       Else a character buffer is alocated and the contents

 *       of each array element, separated by delimiter is placed

 *       in the '\0' termintated buffer returned. It is up to the

 *       user to free this buffer.

 * return: Allocated buffer as above

 *         NULL on error, NULL a or empty a

 **********************************************************************/

char *dynamic_array_display(dynamic_array_t * a,

			    char delimiter,

			    void (*display_element) (char *, void *),

			    size_t(*element_length) (void *)

    );

/**********************************************************************

 * dynamic_array_get_element

 * Get an element from an array

 * pre: a: array to retrieve element from

 *      elementno: index element in array to retrieve

 * post: no change is made to a

 * return: element requested

 *         NULL if element is beyond the number of elements in the arary

 **********************************************************************/

void *dynamic_array_get_element(dynamic_array_t * a, size_t elementno);

/**********************************************************************

 * dynamic_array_get_count

 * Get the number of elements in the array

 * pre: array to find the number of elements in

 * return: number of elements in the array

 *         -1 if a is NULL

 **********************************************************************/

size_t dynamic_array_get_count(dynamic_array_t * a);

/**********************************************************************

 * dynamic_array_get_vector

 * Get the array contained in the dynamic array

 * pre: array to find the vector of

 * return: vector

 *         NULL if a is NULL

 **********************************************************************/

void *dynamic_array_get_vector(dynamic_array_t * a);

/**********************************************************************

 * dynamic_array_split_str

 * Split a string into substrings on a delimiter

 * pre: str: string to split

 *      delimiter: character to split string on

 * post: string is split.

 *       Note: The string is modified.

 * return: dynamic array containing sub_strings

 *         NULL on error

 *         string being NULL is an error state

 **********************************************************************/

dynamic_array_t *dynamic_array_split_str(char *string,

					 const char delimiter);

#endif