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 a new qvector_t container.
bool qvector_addfirst (qvector_t *vector, const void *data)
 qvector->addfirst(): Insert an element at the beginning of this vector.
bool qvector_addlast (qvector_t *vector, const void *data)
 qvector->addlast(): Insert an element at the end of this vector.
bool qvector_addat (qvector_t *vector, int index, const void *data)
 qvector->addat(): Insert an element at the specified position in this vector.
void * qvector_getfirst (qvector_t *vector, bool newmem)
 qvector->getfirst(): Returns the first element 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 removes 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 removes the element at the 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 stored elements for debugging purposes.
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 containing 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); //allocated
void *e3 = vector->getlast(vector, false); //not allocated
(...omit...)
free(e1);
//pop (get and remove)
void *e2 = vector->popat(vector, 1); //get allocated copy
(...omit...)
free(e2);
//debug output
vector->debug(vector, stdout, true);
//remove all the elements
vector->clear(vector);
//free vector object
vector->free(vector);
qvector
qvector_t * qvector(size_t max, size_t objsize, int options)
Create a new qvector_t container.
Definition qvector.c:113

Definition in file qvector.c.

Function Documentation

◆ qvector()

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

Create a new qvector_t container.

Parameters
maxmaximum number of elements
objsizesize of each element
optionscombination of initialization options
Returns
allocated qvector_t pointer on success, or NULL on failure.
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 withinitial num when vector is full
  • QVECTOR_RESIZE_EXACT - add up as much as needed

Definition at line 113 of file qvector.c.

◆ qvector_addfirst()

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

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

Parameters
vectorqvector_t container pointer.
datapointer to the source data
Returns
true on success, otherwise 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 229 of file qvector.c.

◆ qvector_addlast()

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

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

Parameters
vectorqvector_t container pointer.
datapointer to the source data
Returns
true on success, otherwise 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 255 of file qvector.c.

◆ qvector_addat()

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

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

Parameters
vectorqvector_t container pointer
indexindex at which the specified element is to be inserted
datapointer to the source data
Returns
true on success, otherwise false.
Return values
errnowill be set in error 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
qvector_t *vector = qvector();
vector->addat(vector, 0, &data); //same as addfirst().
vector->addat(vector, 0, &data); //same as addlast().
Note
Index starts from 0.

Definition at line 292 of file qvector.c.

◆ qvector_getfirst()

void * qvector_getfirst ( qvector_t * vector,
bool newmem )

qvector->getfirst(): Returns the first element in this vector.

Parameters
vectorqvector_t container pointer.
newmemwhether or not to allocate memory for the element.
Returns
pointer to the element on success, or NULL on failure.
Return values
errnowill be set in error condition.
  • ENOENT : Vector is empty.
  • ENOMEM : Memory allocation failure.
size_t size;
void *data = vector->getfirst(vector, true);
if (data != NULL) {
(...omit...)
free(data);
}

Definition at line 367 of file qvector.c.

◆ qvector_getlast()

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
pointer to the element on success, or NULL on failure.
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 391 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
vectorqvector_t container pointer.
indexindex at which the specified element is to access.
newmemwhether or not to allocate memory for the element.
Returns
pointer to the element on success, or NULL on failure.
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 419 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
vectorqvector_t container pointer.
datapointer to the new value
Returns
true on success, otherwise 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 448 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
vectorqvector_t container pointer.
datapointer to the new value
Returns
true on success, otherwise 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 473 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
vectorqvector_t container pointer
indexindex of the element to update
datapointer to the new value
Returns
true on success, otherwise 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 499 of file qvector.c.

◆ qvector_popfirst()

void * qvector_popfirst ( qvector_t * vector)

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

Parameters
vectorqvector_t container pointer.
Returns
allocated element on success, or NULL on failure.
Return values
errnowill be set in error condition.
  • ENOENT : Vector is empty.
  • ENOMEM : Memory allocation failure.

Definition at line 521 of file qvector.c.

◆ qvector_poplast()

void * qvector_poplast ( qvector_t * vector)

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

Parameters
vectorqvector_t container pointer.
Returns
allocated element on success, or NULL on failure.
Return values
errnowill be set in error condition.
  • ENOENT : Vector is empty.
  • ENOMEM : Memory allocation failure.

Definition at line 535 of file qvector.c.

◆ qvector_popat()

void * qvector_popat ( qvector_t * vector,
int index )

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

Parameters
vectorqvector_t container pointer.
indexindex of the element to pop
Returns
allocated element on success, or NULL on failure.
Return values
errnowill be set in error condition.
  • ENOENT : Vector is empty.
  • ERANGE : Index out of range.
  • ENOMEM : Memory 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 563 of file qvector.c.

◆ qvector_removefirst()

bool qvector_removefirst ( qvector_t * vector)

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

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

Definition at line 592 of file qvector.c.

◆ qvector_removelast()

bool qvector_removelast ( qvector_t * vector)

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

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

Definition at line 606 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
vectorqvector_t container pointer.
indexindex at which the specified element is to be removed.
Returns
true, otherwise false.
Return values
errnowill be set in error condition.
  • ENOENT : Vector is empty.
  • ERANGE : Index out of range.

Definition at line 621 of file qvector.c.

◆ qvector_size()

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 640 of file qvector.c.

◆ qvector_lock()

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 653 of file qvector.c.

◆ qvector_unlock()

void qvector_unlock ( qvector_t * vector)

qvector->unlock(): Leaves critical section.

Parameters
vectorqvector_t container pointer.

Definition at line 662 of file qvector.c.

◆ qvector_clear()

void qvector_clear ( qvector_t * vector)

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

Parameters
vectorqvector_t container pointer.

Definition at line 671 of file qvector.c.

◆ qvector_free()

void qvector_free ( qvector_t * vector)

qvector->free(): Free this vector.

Parameters
vectorqvector_t container pointer.

Definition at line 682 of file qvector.c.

◆ qvector_debug()

bool qvector_debug ( qvector_t * vector,
FILE * out )

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

Parameters
vectorqvector_t container pointer.
outoutput stream such as stdout or stderr.
Returns
true on success, otherwise false.
Return values
errnowill be set in error condition.
  • EIO : Invalid output stream.

Definition at line 703 of file qvector.c.

◆ qvector_resize()

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.

◆ qvector_toarray()

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

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

Parameters
vectorqvector_t container pointer.
sizeif size is not NULL, the number of elements will be stored.
Returns
allocated pointer on success, or NULL on failure.
Return values
errnowill be set in error condition.
  • ENOENT : Vector is empty.
  • ENOMEM : Memory allocation failure.

Definition at line 783 of file qvector.c.

◆ qvector_reverse()

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.

◆ qvector_getnext()

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 free 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.