/+junk/c_sdl_joypad_ducktape

/* c-basic-offset: 2; tab-width: 2; indent-tabs-mode: nil

 * vi: set shiftwidth=2 tabstop=2 expandtab:

 * :indentSize=2:tabSize=2:noTabs=true:

 */

#ifndef __H_DYNAMIC_ARRAY__

#define __H_DYNAMIC_ARRAY__

#include <stdlib.h>

#include "defs.h"

/*

 * This file, as the rest of the project is under MIT license.

 * see http://opensource.org/licenses/MIT

 *

 * Author Gustav Hartvigsson <gustav.hartvigsson _at_ gmail.com> 2014

 */

/** @file

 * Dynamic Array.

 *

 * This file contains an imlpementation of a "dynamic" array, it is usefule when

 * dealing with lare amounts of data that may change over time, or with an

 * unknowned numebr of items.

 * 

 * Note that accsess time is constant, but write time is not guarenteed to be.

 * 

 * When the size of the array is equal to the number of elements in it, it will

 * re-allocate the array with a larger size.

 */

/**

 * The padding that is added when expanding the array.

 */

#define ARRAY_PADDING 8

/**

 * an opaque data structure that represents the dynamic array.

 */

typedef struct DynamicArray DynamicArray;

#ifndef __H_DEFS__

/**

 * Represents a for each function.

 * 

 * @param self the dynamic array.

 * @param data the data to be passed to the each iteration.

 * @returns data to be put in a new \c DynamicArray, if used with

 *          <tt>dynamic_array_for_each_with_return</tt>.

 */

typedef void * (* ForEachFunc)(DynamicArray * self, void * item, void * data);

/**

 * Represents a function to be used when freeing some item in a dynamic array.

 *

 * @param obj The object to be freed.

 */

typedef void * (* FreeFunc)(void * obj);

#endif /* __H_DEFS__ */

/**

 * Create a new dynamic array.

 *

 * @param len The length of the initial array.

 * @param free_func The function to be used when freeing the items. Can be \c NULL.

 *        If free_func is NULL, it will use the standard library's 

 *       <tt>free()</tt>.

 *        

 *        Normally a function with the signature <tt> (DynamicArray * self,

          void * item, void * data) </tt> should be used but cast to FreeFunc.

 */

DynamicArray * dynamic_array_new (size_t len, FreeFunc free_func);

/**

 * Frees the dynamic array.

 * 

 * after this is run the data will be lost.

 */

void dynamic_array_free (DynamicArray * self);

/**

 * Get an item from the array.

 */

void * dynamic_array_get (DynamicArray * self, size_t index);

/**

 * Get the length of the array.

 */

size_t dynamic_array_len (DynamicArray * self);

/**

 * Get the size of the array, this is not the same as the length of the array.

 * The size is the number of elements that can be allocated without resizing

 * the array.

 * 

 * To get the length of the array use dynamic_array_len ().

 */

size_t dynamic_array_size (DynamicArray * self);

/**

 * Add an item to the array.

 */

void dynamic_array_add (DynamicArray * self, void * item);

/**

 * Dumps a copy of the array. Must be cast.

 * 

 * Is not freed when the dynamic array is freed.

 * 

 * Is null-terminated.

 */

void ** dynamic_array_dump_array (DynamicArray * self);

/**

 * Use a function on the array.

 */

void dynamic_array_for_each (DynamicArray * self, ForEachFunc func,

                             void * data);

/** TODO

 * same as dynamic_array_for_each (), with the difference that it returns a new

 * DynamicArray.

 */

DynamicArray * dynamic_array_for_each_with_return (DynamicArray * self,

                                                   ForEachFunc func,

                                                   void * data);

#endif /* #define __H_DYNAMIC_ARRAY__ */