///////////////////////////////////////////
// functions


/* 
	allocate memory of a new array with the given number of elements,
	fill all its bytes with zero for safety
	
	example-1 : MYARRAYTYPE* MyArray = array_new( sizeof(MYARRAYTYPE), NULL, 10 );							
					
	example-2 : int MyArrayLength = 10;
					MYARRAYTYPE* MyArray = array_new( sizeof(MYARRAYTYPE), NULL, MyArrayLength );							
					
	example-3 : int MyArrayLength = 0;
					MYARRAYTYPE* MyArray = array_new( sizeof(MYARRAYTYPE), &MyArrayLength, 10 );	
					(now MyArrayLength is set to 10)
						
	(initially MyArray should be NULL)
	(arraylength can be NULL)
	
	returns the array, sets arraylength
*/
void*		array_new(int elementsize, int* arraylength, int newelementscount);


/*
	same as array_new() but initializes all bytes to (char)defaultvalue (instead of zero)
	
	example-1 : MyArray = array_new_initbytes( sizeof(MYARRAYTYPE), NULL, 10, 255 );
	
	example-2 : MyArray = array_new_initbytes( sizeof(MYARRAYTYPE), &MyArrayLength, 10, 255 );
	
	returns the array, sets arraylength	
*/
void*		array_new_initbytes(int elementsize, int* arraylength, int newelementscount, int defaultvalue);


/* 
	fill an array with default data given by one locally created element,
	
	example : 	MYARRAYTYPE NewElement = 10;
					array_fill( MyArray, MyArrayLength, &NewElement );	
	
	returns nothing
*/
void		array_fill(char* arrayin, int arraylength, char newelement);										// by loop and =
void		array_fill(short* arrayin, int arraylength, short newelement);
void		array_fill(int* arrayin, int arraylength, int newelement);
void		array_fill(var* arrayin, int arraylength, var newelement);
void		array_fill(VECTOR* arrayin, int arraylength, VECTOR* newelement);									// by loop and memcpy

void		array_fillbytes(char* arrayin, int arraylength, char bytevalue);									// by one memset (fast)
void		array_fillbytes(short* arrayin, int arraylength, char bytevalue);
void		array_fillbytes(int* arrayin, int arraylength, char bytevalue);
void		array_fillbytes(var* arrayin, int arraylength, char bytevalue);
void		array_fillbytes(VECTOR* arrayin, int arraylength, char bytevalue);

void		array_fillbytes2(void* arrayin, int elementsize, int arraylength, char bytevalue);			// name should differs from the other overloaded functions !

/* 
	reallocate memory of an existing array with a given number of new elements,
	without element value initialization, or decrease array length
	
	example : MyArray = array_realloc( MyArray, sizeof(MYARRAYTYPE), &MyArrayLength, 10 );
	
	returns the array, sets arraylength
*/
void*		array_realloc(void* arrayin, int elementsize, int* arraylength, int newelementscount);


/* 
	reallocate memory of an existing array and a given number of new elements,
	and fill it with default value given by one locally created element,
	or decrease array length
	
	example : 	MYARRAYTYPE newarrayelement = MyDefaultValue or MyDefaultStruct;
					MyArray = array_add( MyArray, sizeof(MYARRAYTYPE), &MyArrayLength, 10, &newarrayelement );	
	(where new_arrayelement is a local variable or struct created/allocated and set before calling it,
	if NULL then new elements will be filled with zeros)
	
	returns the array, sets arraylength
*/
void*		array_add(void* arrayin, int elementsize, int* arraylength, int newelementscount, void* newelement);		// WRONG ! -> char/short/int/var* newelement because of memcpy


/*
	free array memory, set it to NULL for future usage, and set length to zero
	
	example : array_destroy( MyArray, &MyArrayLength );	
	(arraylength can be NULL)
	
	returns nothing, sets the array, arraylength
*/
void		array_destroy(void* arrayin);
void		array_destroy(void* arrayin, int* arraylength);


//----------------------
/*
	pseudo 2D array operations
*/

/*
	2D array helpers
*/
int		array_getx(int sizex, int sizey, int abspos);
int		array_gety(int sizex, int sizey, int abspos);
int		array_getabs(int sizex, int sizey, int posx, int posy);

/*
	reposition array elements as it would be rotated as a 2D matrix
	to the given direction (angle/45), assuming currently looking towards 0
	
	example : 	int* MyArray is the existing array to be rotated
					int MyRotateArrayLength = MyArrayLength;
					int MyRotateSizeX = MySizeX;
					int MyRotateSizeY = MySizeY;
					MYARRAYTYPE* MyRotatedArray = array_rotate_...( MyArray, &MyRotateArrayLength, 2, &MyRotateSizeX, &MyRotateSizeY );	
	(direction 2 means rotation by 90 degrees)
	(no diagonal rotation supported i.e. 1,3,5,7)
	
	returns the new array (it can be used to overwrite the old one, without using new variables).
*/
char*		array_rotate(char* arrayin, int* arraylength, int direction, int* sizex, int* sizey);				
short*	array_rotate(short* arrayin, int* arraylength, int direction, int* sizex, int* sizey);
int*		array_rotate(int* arrayin, int* arraylength, int direction, int* sizex, int* sizey);
var*		array_rotate(var* arrayin, int* arraylength, int direction, int* sizex, int* sizey);				

//----------------------
/*
	pseudo 3D array operations
*/

/*
	3D array helpers
*/
int		array_getx_multi(int sizex, int sizey, int sizez, int abspos);
int		array_gety_multi(int sizex, int sizey, int sizez, int abspos);
int		array_getabs_multi(int sizex, int sizey, int posx, int posy, int posz);

/*
	same as array_rotate() but supports 3D arrays organized level by level
*/
char*		array_rotate_multi(char* arrayin, int* arraylength, int direction, int* sizex, int* sizey);
short*	array_rotate_multi(short* arrayin, int* arraylength, int direction, int* sizex, int* sizey);
int*		array_rotate_multi(int* arrayin, int* arraylength, int direction, int* sizex, int* sizey);
var*		array_rotate_multi(var* arrayin, int* arraylength, int direction, int* sizex, int* sizey);