/+junk/c_sdl_joypad : contents of src/DynamicArray.h at revision 20

: (revision 20)

To get this branch, use:

bzr branch
http://gegoxaren.bato24.eu/bzr/%2Bjunk/c_sdl_joypad

#ifndef __H_DYNAMIC_ARRAY__
#define __H_DYNAMIC_ARRAY__
#include <stdlib.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;

/**
 * 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 DynamicArray, if used with
 * dynamic_array_for_each_with_return.
 */
typedef void * (* ForEachFunc)(DynamicArray * self, void * item, void * data);


/**
 * Create a new dynamic array.
 *
 * @param len The length of the initial array.
 * @param item_size The size of the items to be stored.
 */
DynamicArray * dynamic_array_new (size_t len);

/**
 * 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 dymanic_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);

/**
 * 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__ */

16 by Gustav Hartvigsson * made the code compile.	1	#ifndef __H_DYNAMIC_ARRAY__
16 by Gustav Hartvigsson * made the code compile.	2	#define __H_DYNAMIC_ARRAY__
7 by Gustav Hartvigsson * Added licensing information to the files.	3	#include <stdlib.h>
	4
	5	/*
	6	* This file, as the rest of the project is under MIT license.
	7	* see http://opensource.org/licenses/MIT
8 by Gustav Hartvigsson * added and changed little in the files Lincening information.	8	*
	9	* Author Gustav Hartvigsson <gustav.hartvigsson _at_ gmail.com> 2014
7 by Gustav Hartvigsson * Added licensing information to the files.	10	*/
	11
	12	/** @file
	13	* Dynamic Array.
	14	*
	15	* This file contains an imlpementation of a "dynamic" array, it is usefule when
	16	* dealing with lare amounts of data that may change over time, or with an
	17	* unknowned numebr of items.
	18	*
	19	* Note that accsess time is constant, but write time is not guarenteed to be.
	20	*
	21	* When the size of the array is equal to the number of elements in it, it will
	22	* re-allocate the array with a larger size.
	23	*/
	24
	25	/**
	26	* The padding that is added when expanding the array.
	27	*/
	28	#define ARRAY_PADDING 8
	29
	30	/**
16 by Gustav Hartvigsson * made the code compile.	31	* an opaque data structure that represents the dynamic array.
	32	*/
	33	typedef struct _DynamicArray DynamicArray;
	34
	35	/**
7 by Gustav Hartvigsson * Added licensing information to the files.	36	* Represents a for each function.
	37	*
	38	* @param self the dynamic array.
	39	* @param data the data to be passed to the each iteration.
	40	* @returns data to be put in a new DynamicArray, if used with
	41	* dynamic_array_for_each_with_return.
	42	*/
16 by Gustav Hartvigsson * made the code compile.	43	typedef void * (* ForEachFunc)(DynamicArray * self, void * item, void * data);
7 by Gustav Hartvigsson * Added licensing information to the files.	44
	45
	46	/**
	47	* Create a new dynamic array.
	48	*
	49	* @param len The length of the initial array.
	50	* @param item_size The size of the items to be stored.
	51	*/
16 by Gustav Hartvigsson * made the code compile.	52	DynamicArray * dynamic_array_new (size_t len);
7 by Gustav Hartvigsson * Added licensing information to the files.	53
	54	/**
	55	* Frees the dynamic array.
	56	*
	57	* after this is run the data will be lost.
	58	*/
	59	void dynamic_array_free (DynamicArray * self);
	60
	61
	62	/**
	63	* Get an item from the array.
	64	*/
16 by Gustav Hartvigsson * made the code compile.	65	void * dynamic_array_get (DynamicArray * self, size_t index);
7 by Gustav Hartvigsson * Added licensing information to the files.	66
	67	/**
	68	* Get the length of the array.
	69	*/
	70	size_t dymanic_array_len (DynamicArray * self);
	71
	72
	73	/**
19 by Gustav Hatvigsson * Started working on some tests, they do not work... yet.	74	* Get the size of the array, this is not the same as the length of the array.
	75	* The size is the number of elements that can be allocated without resizing
	76	* the array.
	77	*
	78	* To get the length of the array use dynamic_array_len ().
	79	*/
	80	size_t dynamic_array_size (DynamicArray * self);
	81
	82
	83	/**
7 by Gustav Hartvigsson * Added licensing information to the files.	84	* Add an item to the array.
	85	*/
	86	void dynamic_array_add (DynamicArray * self, void * item);
	87
	88	/**
19 by Gustav Hatvigsson * Started working on some tests, they do not work... yet.	89	* Dumps a copy of the array. Must be cast.
7 by Gustav Hartvigsson * Added licensing information to the files.	90	*
	91	* Is not freed when the dynamic array is freed.
	92	*
	93	* Is null-terminated.
	94	*/
	95	void ** dynamic_array_dump_array (DynamicArray * self);
	96
	97	/**
	98	* Use a function on the array.
	99	*/
	100	void dynamic_array_for_each (DynamicArray * self, ForEachFunc func,
	101	void * data);
	102
	103	/**
	104	* same as dynamic_array_for_each (), with the difference that it returns a new
	105	* DynamicArray.
	106	*/
	107	DynamicArray * dynamic_array_for_each_with_return (DynamicArray * self,
	108	ForEachFunc func,
	109	void * data);
	110
16 by Gustav Hartvigsson * made the code compile.	111	#endif /* #define __H_DYNAMIC_ARRAY__ */