Expand and Shrink Array

Introduction

Files
file	ub_esarray.h
	Allocated memory array which is expanded or shrinked automatically.

Functions
ub_esarray_cstd_t *	ub_esarray_init (int esunit, int elesize, int maxeles)
	initialize ub_esarray object. More...
void	ub_esarray_close (ub_esarray_cstd_t *eah)
	close ub_esarray More...
int	ub_esarray_add_ele (ub_esarray_cstd_t *eah, ub_esarray_element_t *ed)
	add one element More...
int	ub_esarray_pop_ele (ub_esarray_cstd_t *eah, ub_esarray_element_t *ed)
	pop in fifo mode(get from index=0, and delete index=0) More...
int	ub_esarray_pop_last_ele (ub_esarray_cstd_t *eah, ub_esarray_element_t *ed)
	pop in stack mode(get from the last index, and delete it) More...
int	ub_esarray_del_ele (ub_esarray_cstd_t *eah, ub_esarray_element_t *ed)
	delete one element *ed More...
int	ub_esarray_data_lock (ub_esarray_cstd_t *eah)
	lock data to preserve checked out data by ub_esarray_get_newele or ub_esarray_get_ele More...
int	ub_esarray_data_unlock (ub_esarray_cstd_t *eah)
	unlock data to return to the default status More...
int	ub_esarray_ele_nums (ub_esarray_cstd_t *eah)
	returns the number of elements More...
ub_esarray_element_t *	ub_esarray_get_newele (ub_esarray_cstd_t *eah)
	get a new element from the ub_esarray_array More...
ub_esarray_element_t *	ub_esarray_get_ele (ub_esarray_cstd_t *eah, int index)
	get the indexed element from the ub_esarray_array More...
int	ub_esarray_del_pointer (ub_esarray_cstd_t *eah, ub_esarray_element_t *ed)
	delete one element with element pointer More...
int	ub_esarray_del_index (ub_esarray_cstd_t *eah, int index)
	delete one element with index More...

Typedefs
typedef struct ub_esarray_cstd	ub_esarray_cstd_t
	the data handle of ub_esarray object, the inside of it is private More...
typedef void	ub_esarray_element_t
	data type of the element More...

Typedef Documentation

ub_esarray_cstd_t

typedef struct ub_esarray_cstd ub_esarray_cstd_t

the data handle of ub_esarray object, the inside of it is private

ub_esarray_element_t

typedef void ub_esarray_element_t

data type of the element

Note

for actual element type, the caller needs to cast ub_esarray_element_t type value.

Function Documentation

ub_esarray_init()

ub_esarray_cstd_t* ub_esarray_init	(	int	esunit,
		int	elesize,
		int	maxeles
	)

initialize ub_esarray object.

Returns

the data handle of ub_esarray_array object

Parameters

esunit	expand and shrink unit
elesize	element size
maxeles	max number of elements

ub_esarray_close()

void ub_esarray_close

(

ub_esarray_cstd_t *

eah

)

close ub_esarray

Parameters

eah	the data handle of ub_esarray object

ub_esarray_add_ele()

int ub_esarray_add_ele	(	ub_esarray_cstd_t *	eah,
		ub_esarray_element_t *	ed
	)

add one element

Returns

0 on success, -1 on error

Parameters

eah	the data handle of ub_esarray_array object
ed	a new element to add

Note

thread safe, data is copied, 'ed' can be freed after this call.

ub_esarray_pop_ele()

int ub_esarray_pop_ele	(	ub_esarray_cstd_t *	eah,
		ub_esarray_element_t *	ed
	)

pop in fifo mode(get from index=0, and delete index=0)

Returns

0 on success, -1 on error

Parameters

eah	the data handle of ub_esarray_array object
ed	popped element; the data is copied to ed, which must have elesize space

Note

thread safe, data is copied, 'ed' must be allocated by the caller.

ub_esarray_pop_last_ele()

int ub_esarray_pop_last_ele	(	ub_esarray_cstd_t *	eah,
		ub_esarray_element_t *	ed
	)

pop in stack mode(get from the last index, and delete it)

Returns

0 on success, -1 on error

Parameters

eah	the data handle of ub_esarray_array object
ed	poped element; the data is copied to ed, which must have elesize space

Note

thread safe, data is copied, 'ed' must be allocated by the caller.

ub_esarray_del_ele()

int ub_esarray_del_ele	(	ub_esarray_cstd_t *	eah,
		ub_esarray_element_t *	ed
	)

delete one element *ed

Returns

0 on success, -1 if no such elemet exists

Parameters

eah	the data handle of ub_esarray_array object
ed	the element which has the same contents as 'ed' should be deleted

Note

thread safe, the caller needs to bring 'ed' with the contents

ub_esarray_data_lock()

int ub_esarray_data_lock

(

ub_esarray_cstd_t *

eah

)

lock data to preserve checked out data by ub_esarray_get_newele or ub_esarray_get_ele

Note

using the data pointers or the data index number is not thread safe, to be thread safe, call 'ub_esarray_data_lock' before the work, and call 'ub_esarray_data_unlock' after the work.

ub_esarray_data_unlock()

int ub_esarray_data_unlock

(

ub_esarray_cstd_t *

eah

)

unlock data to return to the default status

ub_esarray_ele_nums()

int ub_esarray_ele_nums

(

ub_esarray_cstd_t *

eah

)

returns the number of elements

Returns

the number of elements

ub_esarray_get_newele()

ub_esarray_element_t* ub_esarray_get_newele

(

ub_esarray_cstd_t *

eah

)

get a new element from the ub_esarray_array

Returns

a new element which has area of elesize bytes

Parameters

eah	the data handle of ub_esarray_array object

Note

the contentes of the return is NOT THREAD-SAFE. the caller needs to make sure that no delete happens during the time to use the result pointer. the internal data is locked after this call.

ub_esarray_get_ele()

ub_esarray_element_t* ub_esarray_get_ele	(	ub_esarray_cstd_t *	eah,
		int	index
	)

get the indexed element from the ub_esarray_array

Returns

the indexed element which has area of elesize bytes

Parameters

eah	the data handle of ub_esarray_array object
index	index in the current ub_esarray_array

Note

the contentes of the return is NOT THREAD-SAFE. the caller needs to make sure that no delete happens during the time to use the result pointer. the internal data is locked after this call.

ub_esarray_del_pointer()

int ub_esarray_del_pointer	(	ub_esarray_cstd_t *	eah,
		ub_esarray_element_t *	ed
	)

delete one element with element pointer

Returns

0 on success, -1 if no such element exists

Parameters

eah	the data handle of ub_esarray_array object
ed	the element pointer which should be deleted

Note

NOT THREAD-SAFE; between ub_esarray_get_ele and ub_esarray_del_pointer, no other delete can happen.

ub_esarray_del_index()

int ub_esarray_del_index	(	ub_esarray_cstd_t *	eah,
		int	index
	)

delete one element with index

Returns

0 on success, -1 if index >= number of elements

Parameters

eah	the data handle of ub_esarray_array object
index	the index of the current ub_esarray_array, which should be deleted

Note

NOT THREAD-SAFE; index may not be right number, if other delete happens after getting index.