Vector container implementation. More...

Functions
static void *	get_at (qvector_t *vector, int index, bool newmem)

static bool	remove_at (qvector_t *vector, int index)

qvector_t *	qvector (size_t max, size_t objsize, int options)
	Create new qvector_t container.

bool	qvector_addfirst (qvector_t vector, const void data)
	qvector->addfirst(): Insert a element at the beginning of this vector.

bool	qvector_addlast (qvector_t vector, const void data)
	qvector->addlast(): Insert a element at the end of this vector.

void *	qvector_getfirst (qvector_t *vector, bool newmem)
	qvector->addat(): Inserts a element at the specified position in this vector.

void *	qvector_getlast (qvector_t *vector, bool newmem)
	qvector->getlast(): Returns the last element in this vector.

void *	qvector_getat (qvector_t *vector, int index, bool newmem)
	qvector->getat(): Returns the element at the specified position in this vector.

bool	qvector_setfirst (qvector_t vector, const void data)
	qvector->setfirst(): Set the first element with a new value in this vector.

bool	qvector_setlast (qvector_t vector, const void data)
	qvector->setlast(): Set the last element with a new value in this vector.

bool	qvector_setat (qvector_t vector, int index, const void data)
	qvector->setat(): Set new value to the specified position in this vector.

void *	qvector_popfirst (qvector_t *vector)
	qvector->popfirst(): Returns and remove the first element in this vector.

void *	qvector_poplast (qvector_t *vector)
	qvector->poplast(): Returns the last element of this vector.

void *	qvector_popat (qvector_t *vector, int index)
	qvector->popat(): Returns and remove the element at specified position in this vector.

bool	qvector_removefirst (qvector_t *vector)
	qvector->removefirst(): Removes the first element in this vector.

bool	qvector_removelast (qvector_t *vector)
	qvector->removelast(): Removes the last element in this vector.

bool	qvector_removeat (qvector_t *vector, int index)
	qvector->removeat(): Removes the element at the specified position in this vector.

size_t	qvector_size (qvector_t *vector)
	qvector->size(): Get the number of elements in this vector.

void	qvector_lock (qvector_t *vector)
	qvector->lock(): Enters critical section.

void	qvector_unlock (qvector_t *vector)
	qvector->unlock(): Leaves critical section.

void	qvector_clear (qvector_t *vector)
	qvector->clear(): Remove all the elemnts in this vector.

void	qvector_free (qvector_t *vector)
	qvector->free(): Free this vector.

bool	qvector_debug (qvector_t vector, FILE out)
	qvector->debug(): Prints out stored elements for debugging purpose.

bool	qvector_resize (qvector_t *vector, size_t newmax)
	qvector->resize(): Changes the allocated memory space size.

void *	qvector_toarray (qvector_t vector, size_t size)
	qvector->toarray(): Returns an array contains all the elements in this vector.

void	qvector_reverse (qvector_t *vector)
	qvector->reverse(): Reverse the order of element in this vector.

bool	qvector_getnext (qvector_t vector, qvector_obj_t obj, bool newmem)
	qvector->getnext(): Get next element in this vector.

Detailed Description

Vector container implementation.

qvector container is a vector container implementation qvector provides uniformly named methods to add, get, pop and remove an element at the beginning and end of the vector.

 [Conceptional Data Structure Diagram]
 
 DATA             [ C ][ B ][ A ]
 (positive index)   0    1    2
 (negative index)  -3   -2   -1
 
@encode
 
@code
 //create a vector
 qvector_t *vector = qvector(QVECTOR_THREADSAFE, 3, sizeof(int));
 
 //insert elements
 vector->addlast(vector, 100);
 vector->addlast(vector, 101);
 vector->addlast(vector, 102);
 
 //get
 void *e1 = vector->getfirst(vector, true);   //malloced
 void *e3 = vector->getlast(vector, false);   //not malloced
 (...omit...)
 free(e1);
 
 //pop (get and remove)
 void *e2 = vector->popat(vector, 1);    //get malloced copy
 (...omit...)
 free(e2);
 
 //debug output
 vector->debug(vector, stdout, true);
 
 //remove all the elements
 vector->clear(vector);
 
 //free vector object
 vector->free(vector);

Definition in file qvector.c.

Function Documentation

◆ qvector()

qvector_t * qvector	(	size_t	max,
		size_t	objsize,
		int	options
	)

Create new qvector_t container.

Parameters

max	max number of elements
objsize	size of each element
options	combination of initialization options.

Returns: a pointer of malloced qvector_t container, otherwise returns NULL

Return values

errno

will be set in error condition.

ENOMEM : Memory allocation failure.
EINVAL : Invalid argument.

qvector_t *vector = qvector(10, sizeof(int), 0);

Note

Available options:

QVECTOR_THREADSAFE - make it thread-safe.
QVECTOR_RESIZE_DOUBLE - double the size when vector is full
QVECTOR_RESIZE_LINEAR - add the size with initial num when vector is full
QVECTOR_RESIZE_EXACT - add up as much as needed

Definition at line 117 of file qvector.c.

◆ qvector_addfirst()

bool qvector_addfirst	(	qvector_t *	vector,
		const void *	data
	)

qvector->addfirst(): Insert a element at the beginning of this vector.

Parameters

vector	qvector_t container pointer.
data	a pointer which points data memory

Returns: true if successful, otherwise returns false.

Return values

errno will be set in error condition.

EINVAL : Invalid argument.
ENOMEM : Memory allocation failure.

//create a sample object.
struct my_obj obj;
 
//create a vector and add the sample object.
qvector_t *vector = qvector(0, 1, sizeof(struct my_obj));
vector->addfirst(vector, &obj);

Definition at line 233 of file qvector.c.

◆ qvector_addlast()

bool qvector_addlast	(	qvector_t *	vector,
		const void *	data
	)

qvector->addlast(): Insert a element at the end of this vector.

Parameters

vector	qvector_t container pointer.
data	a pointer which points data memory

Returns: true if successful, otherwise returns false.

Return values

errno will be set in error condition.

EINVAL : Invalid argument.
ENOMEM : Memory allocation failure.

//create a sample object.
struct my_obj obj;
 
//create a vector and add the sample object.
qvector_t *vector = qvector(0, 1, sizeof(struct my_obj));
vector->addlast(vector, &obj);

Definition at line 259 of file qvector.c.

◆ qvector_getfirst()

void * qvector_getfirst	(	qvector_t *	vector,
		bool	newmem
	)

qvector->addat(): Inserts a element at the specified position in this vector.

Parameters

vector	qvector_t container pointer
index	index at which the specified element is to be inserted
data	a pointer which points data memory

Returns: true if successful, otherwise returns false.

Return values

errno will be set in errno condition.

ERANGE : Index out of range.
EINVAL : Invalid argument.
ENOMEM : Memory allocation failure.

                       first     last      new
    Array              [ A ][ B ][ C ]?==?[   ]
    (positive index)     0    1    2        3
    (negative index)    -3   -2   -1
  
   @encode
  
   @code
    qvector_t *vector = qvector();
    vector->addat(vector, 0, &data); //same as addfirst().
    vector->addat(vector, 0, &data); //same as addlast().
  
   @encode
  
   @note
    Index starts from 0.
  /
bool qvector_addat(qvector_t *vector, int index, const void *data) {
    //check arguments
    if (data == NULL) {
        errno = EINVAL;
        return false;
    }
 
    //check index
    if (index < 0) {
        index += vector->num;
    }
    if (index > vector->num) {
        errno = ERANGE;
        return false;
    }
 
    vector->lock(vector);
 
    //check whether the vector is full
    if (vector->num >= vector->max) {
        size_t newmax = vector->max + 1;
        if (vector->options & QVECTOR_RESIZE_DOUBLE) {
            newmax = (vector->max + 1) * 2;
        } else if (vector->options & QVECTOR_RESIZE_LINEAR) {
            newmax = vector->max + vector->initnum;
        } else {
            newmax = vector->max + 1;
        }
        bool result = vector->resize(vector, newmax);
        if (result == false)
        {
            vector->unlock(vector);
            errno = ENOMEM;
            return false;
        }
    }
 
    //shift data from index...(num - 1)  to index + 1...num
    int i;
    for (i = vector->num; i > index; i--) {
        void *dst = (unsigned char *)vector->data + vector->objsize * i;
        void *src = (unsigned char *)vector->data + vector->objsize * (i - 1);
 
        memcpy(dst, src, vector->objsize);
    }
 
    void *add = (unsigned char *)vector->data + index * vector->objsize;
    memcpy(add, data, vector->objsize);
    vector->num++;
 
    vector->unlock(vector);
    return true;
}
 
/**
   qvector->getfirst(): Returns the first element in this vector.
  
   @param vector    qvector_t container pointer.
   @param newmem    whether or not to allocate memory for the element.
  
   @return a pointer of element, otherwise returns NULL.
   @retval errno will be set in error condition.
    - ENOENT : Vector is empty.
    - ENOMEM : Memory allocation failure.
  
   @code
    size_t size;
    void *data = vector->getfirst(vector, true);
    if (data != NULL) {
        (...omit...)
        free(data);
    }

Definition at line 371 of file qvector.c.

◆ qvector_getlast()

void * qvector_getlast	(	qvector_t *	vector,
		bool	newmem
	)

qvector->getlast(): Returns the last element in this vector.

Parameters

vector	qvector_t container pointer.
newmem	whether or not to allocate memory for the element.

Returns: a pointer of element, otherwise returns NULL.

Return values

errno

will be set in error condition.

ENOENT : Vector is empty.
ENOMEM : Memory alocation failure.

void *data = vector->getlast(vector, true);
if (data != NULL) {
    (...omit...)
    free(data);
}

Definition at line 395 of file qvector.c.

◆ qvector_getat()

void * qvector_getat	(	qvector_t *	vector,
		int	index,
		bool	newmem
	)

qvector->getat(): Returns the element at the specified position in this vector.

Parameters

vector	qvector_t container pointer.
index	index at which the specified element is to access.
newmem	whether or not to allocate memory for the element.

Returns: a pointer of element, otherwise returns NULL.

Return values

errno

will be set in error condition.

ERANGE : Index out of range.
ENOMEM : Memory allocation failure.

                   first     last
Array              [ A ][ B ][ C ]
(positive index)     0    1    2
(negative index)    -1   -2   -3

Note: Index starts from 0.

Definition at line 423 of file qvector.c.

◆ qvector_setfirst()

bool qvector_setfirst	(	qvector_t *	vector,
		const void *	data
	)

qvector->setfirst(): Set the first element with a new value in this vector.

Parameters

vector	qvector_t container pointer.
data	the pointer of new value.

Returns: true if successful, otherwise returns false.

Return values

errno

will be set in error condition.

ENOENT : Vector is empty.

struct my_obj obj;
//set values to obj;
qvector_t *vector = qvector();
vector->addlast();
vector->setfirst(vector, &obj);

Definition at line 452 of file qvector.c.

◆ qvector_setlast()

bool qvector_setlast	(	qvector_t *	vector,
		const void *	data
	)

qvector->setlast(): Set the last element with a new value in this vector.

Parameters

vector	qvector_t container pointer.
data	the pointer of new value.

Returns: true if successful, otherwise returns false.

Return values

errno

will be set in error condition.

ENOENT : Vector is empty.

struct my_obj obj;
//set values to obj;
qvector_t *vector = qvector();
vector->addlast();
vector->setlast(vector, &obj);

Definition at line 477 of file qvector.c.

◆ qvector_setat()

bool qvector_setat	(	qvector_t *	vector,
		int	index,
		const void *	data
	)

qvector->setat(): Set new value to the specified position in this vector.

Parameters

vector	qvector_t container pointer
index	index at which the specifed element is to set
data	the pointer of new value to be set

Returns: true if successful, otherwise return false.

Return values

errno

will be set in error condition.

ERANGE : Index out of range.

struct my_obj obj;
//set values to obj;
qvector_t *vector = qvector();
vector->addlast();
vector->setat(vector, 0, &obj);

Definition at line 503 of file qvector.c.

◆ qvector_popfirst()

void * qvector_popfirst ( qvector_t * vector )

qvector->popfirst(): Returns and remove the first element in this vector.

Parameters

vector qvector_t container pointer.

Returns: a pointer of malloced element, otherwise returns NULL.

Return values

errno

will be set in error condition.

ENOENT : Vector is empty.
ENOMEM : Memory allocation failure.

Definition at line 525 of file qvector.c.

◆ qvector_poplast()

void * qvector_poplast ( qvector_t * vector )

qvector->poplast(): Returns the last element of this vector.

Parameters

vector qvector_t container pointer.

Returns: a pointer of malloced element, otherwise returns NULL.

Return values

errno

will be set in error condition.

ENOENT : Vector is empty.
ENOMEM : Memeory allocation failure.

Definition at line 539 of file qvector.c.

◆ qvector_popat()

void * qvector_popat	(	qvector_t *	vector,
		int	index
	)

qvector->popat(): Returns and remove the element at specified position in this vector.

Parameters

vector	qvector_t container pointer.
index	index at which the specified element is to be poped.

Returns: a pointer of malloced element, otherwise returns NULL.

Return values

errno

will be set in error condition.

ENOENT : Vector is empty.
ERANGE : Index out of range.
ENOMEM : Mmemory allocation failure.

                    first     last
Array               [ A ][ B ][ C ]
(positive index)      1    2    3
(negative index)     -1   -2   -3

Note: Index starts from 0.

Definition at line 567 of file qvector.c.

◆ qvector_removefirst()

bool qvector_removefirst ( qvector_t * vector )

qvector->removefirst(): Removes the first element in this vector.

Parameters

vector qvector_t container pointer.

Returns: true, otherwise returns false.

Return values

errno

will be set in error condition.

ENOENT : Vector is empty.
ERANGE : Index out of range.

Definition at line 596 of file qvector.c.

◆ qvector_removelast()

bool qvector_removelast ( qvector_t * vector )

qvector->removelast(): Removes the last element in this vector.

Parameters

vector qvector_t container pointer.

Returns: true, otherwise returns false.

Return values

errno

will be set in error condition.

ENOENT : Vector is empty.
ERANGE : Index out of range.

Definition at line 610 of file qvector.c.

◆ qvector_removeat()

bool qvector_removeat	(	qvector_t *	vector,
		int	index
	)

qvector->removeat(): Removes the element at the specified position in this vector.

Parameters

vector	qvector_t container pointer.
index	index at which the specified element is to be removed.

Returns: true, otherwise returns false.

Return values

errno

will be set in error condition.

ENOENT : Vector is empty.
ERANGE : Index out of range.

Definition at line 625 of file qvector.c.

◆ qvector_size()

size_t qvector_size ( qvector_t * vector )

qvector->size(): Get the number of elements in this vector.

Parameters

vector qvector_t container pointer.

Returns: the number of elements in this vector.

Definition at line 644 of file qvector.c.

◆ qvector_lock()

void qvector_lock ( qvector_t * vector )

qvector->lock(): Enters critical section.

Parameters

vector qvector_t container pointer.

Note: From user side, normally locking operation is only needed when traverse all elements using qvector->getnext().

Definition at line 657 of file qvector.c.

◆ qvector_unlock()

void qvector_unlock ( qvector_t * vector )

qvector->unlock(): Leaves critical section.

Parameters

vector qvector_t container pointer.

Definition at line 666 of file qvector.c.

◆ qvector_clear()

void qvector_clear ( qvector_t * vector )

qvector->clear(): Remove all the elemnts in this vector.

Parameters

vector qvector_t container pointer.

Definition at line 675 of file qvector.c.

◆ qvector_free()

void qvector_free ( qvector_t * vector )

qvector->free(): Free this vector.

Parameters

vector qvector_t container pointer.

Definition at line 686 of file qvector.c.

◆ qvector_debug()

bool qvector_debug	(	qvector_t *	vector,
		FILE *	out
	)

qvector->debug(): Prints out stored elements for debugging purpose.

Parameters

vector	qvector_t container pointer.
out	output stream FILE descriptor such like stdout, stderr.

Returns: true if successful, otherwise returns false.

Return values

errno

will be set in error condition.

EIO : Invalid output stream.

Definition at line 707 of file qvector.c.

◆ qvector_resize()

bool qvector_resize	(	qvector_t *	vector,
		size_t	newmax
	)

qvector->resize(): Changes the allocated memory space size.

Parameters

vector	qvector_t container pointer.
newsize	the new max number of elements.

Return values

errno

will be set in error condition.

ENOMEM : Memory allocation failure.

//create a sample object.
struct my_obj obj;
 
//create a vector which allocates 4 * sizeof(obj) memory
qvector_t *vector = qvector(0, 4, sizeof(struct my_obj));
//expand the memory space of vector to 8 * sizeof(obj)
vector->resize(vector, 8);

Definition at line 746 of file qvector.c.

◆ qvector_toarray()

void * qvector_toarray	(	qvector_t *	vector,
		size_t *	size
	)

qvector->toarray(): Returns an array contains all the elements in this vector.

Parameters

vector	qvector_t container pointer.
size	if size is not NULL, the number of elements will be stored.

Returns: a malloced pointer, otherwise return NULL.

Return values

errno

wil be set in error condition.

ENOENT : Vector is empty.
ENOMEM : Memory allocation failure.

Definition at line 787 of file qvector.c.

◆ qvector_reverse()

void qvector_reverse ( qvector_t * vector )

qvector->reverse(): Reverse the order of element in this vector.

Parameters

vector qvector_t container pointer.

Return values

will	be set in error condition. ENOMEM : Memory allocations failure.

Definition at line 823 of file qvector.c.

◆ qvector_getnext()

bool qvector_getnext	(	qvector_t *	vector,
		qvector_obj_t *	obj,
		bool	newmem
	)

qvector->getnext(): Get next element in this vector.

Parameters

vector	qvector_t container pointer.
obj	found data will be stored in this structure.
newmem	whether or not to allocate memory for element.

Returns: true if found, otherwise return fasle.

Return values

errno

will be set in error condition.

ENOENT : No next element.
ENOMEM : Memory allocation failure.

Note: obj should be initialized with 0 by using memset() by the first call. If newmem flag is true, user should de-allocate obj.data resources.

qvector_t *vector = qvector();
(...add data into vector...)
 
qvector_obj_t obj;
memset((void *)&obj, 0, sizeof(obj));
vector->lock(vector);
while(vector->getnext(vector, &obj, false) == true) {
    printf("DATA=%s\n", obj.data);
}
vector->unlock(vector);

Definition at line 881 of file qvector.c.

Functions

Detailed Description

Function Documentation

◆ qvector()

◆ qvector_addfirst()

◆ qvector_addlast()

◆ qvector_getfirst()

◆ qvector_getlast()

◆ qvector_getat()

◆ qvector_setfirst()

◆ qvector_setlast()

◆ qvector_setat()

◆ qvector_popfirst()

◆ qvector_poplast()

◆ qvector_popat()

◆ qvector_removefirst()

◆ qvector_removelast()

◆ qvector_removeat()

◆ qvector_size()

◆ qvector_lock()

◆ qvector_unlock()

◆ qvector_clear()

◆ qvector_free()

◆ qvector_debug()

◆ qvector_resize()

◆ qvector_toarray()

◆ qvector_reverse()

◆ qvector_getnext()