qLibc

Functions
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.
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);
qvector
qvector_t * qvector(size_t max, size_t objsize, int options)
Create new qvector_t container.
Definition qvector.c:117

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.