qLibc
qvector.c File Reference

Vector container implementation. More...

Go to the source code of this file.

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. More...
 
bool qvector_addfirst (qvector_t *vector, const void *data)
 qvector->addfirst(): Insert a element at the beginning of this vector. More...
 
bool qvector_addlast (qvector_t *vector, const void *data)
 qvector->addlast(): Insert a element at the end of this vector. More...
 
void * qvector_getfirst (qvector_t *vector, bool newmem)
 qvector->addat(): Inserts a element at the specified position in this vector. More...
 
void * qvector_getlast (qvector_t *vector, bool newmem)
 qvector->getlast(): Returns the last element in this vector. More...
 
void * qvector_getat (qvector_t *vector, int index, bool newmem)
 qvector->getat(): Returns the element at the specified position in this vector. More...
 
bool qvector_setfirst (qvector_t *vector, const void *data)
 qvector->setfirst(): Set the first element with a new value in this vector. More...
 
bool qvector_setlast (qvector_t *vector, const void *data)
 qvector->setlast(): Set the last element with a new value in this vector. More...
 
bool qvector_setat (qvector_t *vector, int index, const void *data)
 qvector->setat(): Set new value to the specified position in this vector. More...
 
void * qvector_popfirst (qvector_t *vector)
 qvector->popfirst(): Returns and remove the first element in this vector. More...
 
void * qvector_poplast (qvector_t *vector)
 qvector->poplast(): Returns the last element of this vector. More...
 
void * qvector_popat (qvector_t *vector, int index)
 qvector->popat(): Returns and remove the element at specified position in this vector. More...
 
bool qvector_removefirst (qvector_t *vector)
 qvector->removefirst(): Removes the first element in this vector. More...
 
bool qvector_removelast (qvector_t *vector)
 qvector->removelast(): Removes the last element in this vector. More...
 
bool qvector_removeat (qvector_t *vector, int index)
 qvector->removeat(): Removes the element at the specified position in this vector. More...
 
size_t qvector_size (qvector_t *vector)
 qvector->size(): Get the number of elements in this vector. More...
 
void qvector_lock (qvector_t *vector)
 qvector->lock(): Enters critical section. More...
 
void qvector_unlock (qvector_t *vector)
 qvector->unlock(): Leaves critical section. More...
 
void qvector_clear (qvector_t *vector)
 qvector->clear(): Remove all the elemnts in this vector. More...
 
void qvector_free (qvector_t *vector)
 qvector->free(): Free this vector. More...
 
bool qvector_debug (qvector_t *vector, FILE *out)
 qvector->debug(): Prints out stored elements for debugging purpose. More...
 
bool qvector_resize (qvector_t *vector, size_t newmax)
 qvector->resize(): Changes the allocated memory space size. More...
 
void * qvector_toarray (qvector_t *vector, size_t *size)
 qvector->toarray(): Returns an array contains all the elements in this vector. More...
 
void qvector_reverse (qvector_t *vector)
 qvector->reverse(): Reverse the order of element in this vector. More...
 
bool qvector_getnext (qvector_t *vector, qvector_obj_t *obj, bool newmem)
 qvector->getnext(): Get next element in this vector. More...
 

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_t* qvector ( size_t  max,
size_t  objsize,
int  options 
)

Create new qvector_t container.

Parameters
maxmax number of elements
objsizesize of each element
optionscombination of initialization options.
Returns
a pointer of malloced qvector_t container, otherwise returns NULL
Return values
errnowill 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.

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

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

Parameters
vectorqvector_t container pointer.
dataa pointer which points data memory
Returns
true if successful, otherwise returns false.
Return values
errnowill 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.

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

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

Parameters
vectorqvector_t container pointer.
dataa pointer which points data memory
Returns
true if successful, otherwise returns false.
Return values
errnowill 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.

void* qvector_getfirst ( qvector_t *  vector,
bool  newmem 
)

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

Parameters
vectorqvector_t container pointer
indexindex at which the specified element is to be inserted
dataa pointer which points data memory
Returns
true if successful, otherwise returns false.
Return values
errnowill 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.

void* qvector_getlast ( qvector_t *  vector,
bool  newmem 
)

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

Parameters
vectorqvector_t container pointer.
newmemwhether or not to allocate memory for the element.
Returns
a pointer of element, otherwise returns NULL.
Return values
errnowill 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.

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

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

Parameters
vectorqvector_t container pointer.
indexindex at which the specified element is to access.
newmemwhether or not to allocate memory for the element.
Returns
a pointer of element, otherwise returns NULL.
Return values
errnowill 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.

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

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

Parameters
vectorqvector_t container pointer.
datathe pointer of new value.
Returns
true if successful, otherwise returns false.
Return values
errnowill 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.

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

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

Parameters
vectorqvector_t container pointer.
datathe pointer of new value.
Returns
true if successful, otherwise returns false.
Return values
errnowill 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.

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

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

Parameters
vectorqvector_t container pointer
indexindex at which the specifed element is to set
datathe pointer of new value to be set
Returns
true if successful, otherwise return false.
Return values
errnowill 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.

void* qvector_popfirst ( qvector_t *  vector)

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

Parameters
vectorqvector_t container pointer.
Returns
a pointer of malloced element, otherwise returns NULL.
Return values
errnowill be set in error condition.
  • ENOENT : Vector is empty.
  • ENOMEM : Memory allocation failure.

Definition at line 525 of file qvector.c.

void* qvector_poplast ( qvector_t *  vector)

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

Parameters
vectorqvector_t container pointer.
Returns
a pointer of malloced element, otherwise returns NULL.
Return values
errnowill be set in error condition.
  • ENOENT : Vector is empty.
  • ENOMEM : Memeory allocation failure.

Definition at line 539 of file qvector.c.

void* qvector_popat ( qvector_t *  vector,
int  index 
)

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

Parameters
vectorqvector_t container pointer.
indexindex at which the specified element is to be poped.
Returns
a pointer of malloced element, otherwise returns NULL.
Return values
errnowill 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.

bool qvector_removefirst ( qvector_t *  vector)

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

Parameters
vectorqvector_t container pointer.
Returns
true, otherwise returns false.
Return values
errnowill be set in error condition.
  • ENOENT : Vector is empty.
  • ERANGE : Index out of range.

Definition at line 596 of file qvector.c.

bool qvector_removelast ( qvector_t *  vector)

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

Parameters
vectorqvector_t container pointer.
Returns
true, otherwise returns false.
Return values
errnowill be set in error condition.
  • ENOENT : Vector is empty.
  • ERANGE : Index out of range.

Definition at line 610 of file qvector.c.

bool qvector_removeat ( qvector_t *  vector,
int  index 
)

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

Parameters
vectorqvector_t container pointer.
indexindex at which the specified element is to be removed.
Returns
true, otherwise returns false.
Return values
errnowill be set in error condition.
  • ENOENT : Vector is empty.
  • ERANGE : Index out of range.

Definition at line 625 of file qvector.c.

size_t qvector_size ( qvector_t *  vector)

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

Parameters
vectorqvector_t container pointer.
Returns
the number of elements in this vector.

Definition at line 644 of file qvector.c.

void qvector_lock ( qvector_t *  vector)

qvector->lock(): Enters critical section.

Parameters
vectorqvector_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.

void qvector_unlock ( qvector_t *  vector)

qvector->unlock(): Leaves critical section.

Parameters
vectorqvector_t container pointer.

Definition at line 666 of file qvector.c.

void qvector_clear ( qvector_t *  vector)

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

Parameters
vectorqvector_t container pointer.

Definition at line 675 of file qvector.c.

void qvector_free ( qvector_t *  vector)

qvector->free(): Free this vector.

Parameters
vectorqvector_t container pointer.

Definition at line 686 of file qvector.c.

bool qvector_debug ( qvector_t *  vector,
FILE *  out 
)

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

Parameters
vectorqvector_t container pointer.
outoutput stream FILE descriptor such like stdout, stderr.
Returns
true if successful, otherwise returns false.
Return values
errnowill be set in error condition.
  • EIO : Invalid output stream.

Definition at line 703 of file qvector.c.

bool qvector_resize ( qvector_t *  vector,
size_t  newmax 
)

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

Parameters
vectorqvector_t container pointer.
newsizethe new max number of elements.
Return values
errnowill 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 742 of file qvector.c.

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

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

Parameters
vectorqvector_t container pointer.
sizeif size is not NULL, the number of elements will be stored.
Returns
a malloced pointer, otherwise return NULL.
Return values
errnowil be set in error condition.
  • ENOENT : Vector is empty.
  • ENOMEM : Memory allocation failure.

Definition at line 783 of file qvector.c.

void qvector_reverse ( qvector_t *  vector)

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

Parameters
vectorqvector_t container pointer.
Return values
willbe set in error condition.
  • ENOMEM : Memory allocations failure.

Definition at line 819 of file qvector.c.

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

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

Parameters
vectorqvector_t container pointer.
objfound data will be stored in this structure.
newmemwhether or not to allocate memory for element.
Returns
true if found, otherwise return fasle.
Return values
errnowill 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 877 of file qvector.c.