qLibc

Functions
qstack.c File Reference

Stack implementation. More...

Go to the source code of this file.

## Functions
qstack_t * | qstack (int options)
| Create a new stack container.
size_t | qstack_setsize (qstack_t *stack, size_t max)
| qstack->setsize(): Sets maximum number of elements allowed in this stack.
bool | qstack_push (qstack_t *stack, const void *data, size_t size)
| qstack->push(): Pushes an element onto the top of this stack.
bool | qstack_pushstr (qstack_t *stack, const char *str)
| qstack->pushstr(): Pushes a string onto the top of this stack.
bool | qstack_pushint (qstack_t *stack, int64_t num)
| qstack->pushint(): Pushes a integer onto the top of this stack.
void * | qstack_pop (qstack_t *stack, size_t *size)
| qstack->pop(): Removes a element at the top of this stack and returns that element.
char * | qstack_popstr (qstack_t *stack)
| qstack->popstr(): Removes a element at the top of this stack and returns that element.
int64_t | qstack_popint (qstack_t *stack)
| qstack->popint(): Removes a integer at the top of this stack and returns that element.
void * | qstack_popat (qstack_t *stack, int index, size_t *size)
| qstack->popat(): Returns and remove the element at the specified position in this stack.
void * | qstack_get (qstack_t *stack, size_t *size, bool newmem)
| qstack->get(): Returns an element at the top of this stack without removing it.
char * | qstack_getstr (qstack_t *stack)
| qstack->getstr(): Returns an string at the top of this stack without removing it.
int64_t | qstack_getint (qstack_t *stack)
| qstack->getint(): Returns an integer at the top of this stack without removing it.
void * | qstack_getat (qstack_t *stack, int index, size_t *size, bool newmem)
| qstack->getat(): Returns an element at the specified position in this stack without removing it.
size_t | qstack_size (qstack_t *stack)
| qstack->size(): Returns the number of elements in this stack.
void | qstack_clear (qstack_t *stack)
| qstack->clear(): Removes all of the elements from this stack.
bool | qstack_debug (qstack_t *stack, FILE *out)
| qstack->debug(): Print out stored elements for debugging purpose.
void | qstack_free (qstack_t *stack)
| qstack->free(): Free qstack_t

## Detailed Description

Stack implementation.

qstack container is a stack implementation. It represents a last-in-first-out(LIFO). It extends qlist container that allow a linked-list to be treated as a stack.

[Conceptional Data Structure Diagram]
top bottom
DATA PUSH/POP <==> [ C ][ B ][ A ]
(positive index) 0 1 2
(negative index) -3 -2 -1
// create stack
qstack_t *stack = qstack(QSTACK_THREADSAFE);
// example: integer stack
stack->pushint(stack, 1);
stack->pushint(stack, 2);
stack->pushint(stack, 3);
printf("popint(): %d\n", stack->popint(stack));
printf("popint(): %d\n", stack->popint(stack));
printf("popint(): %d\n", stack->popint(stack));
// example: string stack
stack->pushstr(stack, "A string");
stack->pushstr(stack, "B string");
stack->pushstr(stack, "C string");
char *str = stack->popstr(stack);
printf("popstr(): %s\n", str);
free(str);
str = stack->popstr(stack);
printf("popstr(): %s\n", str);
free(str);
str = stack->popstr(stack);
printf("popstr(): %s\n", str);
free(str);
// example: object stack
stack->push(stack, "A object", sizeof("A object"));
stack->push(stack, "B object", sizeof("B object"));
stack->push(stack, "C object", sizeof("C object"));
void *obj = stack->pop(stack, NULL);
printf("pop(): %s\n", (char*)obj);
free(obj);
str = stack->pop(stack, NULL);
printf("pop(): %s\n", (char*)obj);
free(obj);
str = stack->pop(stack, NULL);
printf("pop(): %s\n", (char*)obj);
free(obj);
// release
stack->free(stack);
[Output]
popint(): 3
popint(): 2
popint(): 1
popstr(): C string
popstr(): B string
popstr(): A string
pop(): C object
pop(): B object
pop(): A object
qstack
qstack_t * qstack(int options)
Create a new stack container.
Definition qstack.c:129

Definition in file qstack.c.

## Function Documentation

## ◆ qstack()

qstack_t * qstack | ( | int | options | ) |

Create a new stack container.

Parameters

  options | combination of initialization options.

Returns
  a pointer of malloced qstack_t container, otherwise returns NULL.

Return values

  errno | will be set in error condition. ENOMEM : Memory allocation failure.

qstack_t *stack = qstack(QSTACK_THREADSAFE);

Note
  Available options:
  - QSTACK_THREADSAFE - make it thread-safe.

Definition at line 129 of file qstack.c.

## ◆ qstack_setsize()

size_t qstack_setsize | ( | qstack_t * | stack,
|  | size_t | max
| ) |  |

qstack->setsize(): Sets maximum number of elements allowed in this stack.

Parameters

  stack | qstack container pointer.
  max | maximum number of elements. 0 means no limit.

Returns
  previous maximum number.

Definition at line 177 of file qstack.c.

## ◆ qstack_push()

bool qstack_push | ( | qstack_t * | stack,
|  | const void * | data,
|  | size_t | size
| ) |  |

qstack->push(): Pushes an element onto the top of this stack.

Parameters

  stack | qstack container pointer.
  data | a pointer which points data memory.
  size | size of the data.

Returns
  true if successful, otherwise returns false.

Return values

  errno | will be set in error condition. EINVAL : Invalid argument. ENOBUFS : Stack full. Only happens when this stack has set to have limited number of elements) ENOMEM : Memory allocation failure.

Definition at line 195 of file qstack.c.

## ◆ qstack_pushstr()

bool qstack_pushstr | ( | qstack_t * | stack,
|  | const char * | str
| ) |  |

qstack->pushstr(): Pushes a string onto the top of this stack.

Parameters

  stack | qstack container pointer.
  data | a pointer which points data memory.
  size | size of the data.

Returns
  true if successful, otherwise returns false.

Return values

  errno | will be set in error condition. EINVAL : Invalid argument. ENOBUFS : Stack full. Only happens when this stack has set to have limited number of elements. ENOMEM : Memory allocation failure.

Definition at line 213 of file qstack.c.

## ◆ qstack_pushint()

bool qstack_pushint | ( | qstack_t * | stack,
|  | int64_t | num
| ) |  |

qstack->pushint(): Pushes a integer onto the top of this stack.

Parameters

  stack | qstack container pointer.
  num | integer data.

Returns
  true if successful, otherwise returns false.

Return values

  errno | will be set in error condition. ENOBUFS : Stack full. Only happens when this stack has set to have limited number of elements. ENOMEM : Memory allocation failure.

Definition at line 233 of file qstack.c.

## ◆ qstack_pop()

void * qstack_pop | ( | qstack_t * | stack,
|  | size_t * | size
| ) |  |

qstack->pop(): Removes a element at the top of this stack and returns that element.

Parameters

  stack | qstack container pointer.
  size | if size is not NULL, element size will be stored.

Returns
  a pointer of malloced element, otherwise returns NULL.

Return values

  errno | will be set in error condition. ENOENT : Stack is empty. ENOMEM : Memory allocation failure.

Definition at line 249 of file qstack.c.

## ◆ qstack_popstr()

char * qstack_popstr | ( | qstack_t * | stack | ) |

qstack->popstr(): Removes a element at the top of this stack and returns that element.

Parameters

  stack | qstack container pointer.

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

Return values

  errno | will be set in error condition. ENOENT : Stack is empty. ENOMEM : Memory allocation failure.

Note
  The string element should be pushed through pushstr().

Definition at line 267 of file qstack.c.

## ◆ qstack_popint()

int64_t qstack_popint | ( | qstack_t * | stack | ) |

qstack->popint(): Removes a integer at the top of this stack and returns that element.

Parameters

  stack | qstack container pointer.

Returns
  an integer value, otherwise returns 0.

Return values

  errno | will be set in error condition. ENOENT : Stack is empty. ENOMEM : Memory allocation failure.

Note
  The integer element should be pushed through pushint().

Definition at line 291 of file qstack.c.

## ◆ qstack_popat()

void * qstack_popat | ( | qstack_t * | stack,
|  | int | index,
|  | size_t * | size
| ) |  |

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

Parameters

  stack | qstack container pointer.
  index | index at which the specified element is to be inserted
  size | if size is not NULL, element size will be stored.

Returns
  a pointer of malloced element, otherwise returns NULL.

Return values

  errno | will be set in error condition. ERANGE : Index out of range. ENOMEM : Memory allocation failure.

Note
  Negative index can be used for addressing a element from the bottom in this stack. For example, index -1 will always pop a element which is pushed at very first time.

Definition at line 320 of file qstack.c.

## ◆ qstack_get()

void * qstack_get | ( | qstack_t * | stack,
|  | size_t * | size,
|  | bool | newmem
| ) |  |

qstack->get(): Returns an element at the top of this stack without removing it.

Parameters

  stack | qstack container pointer.
  size | if size is not NULL, element size will be stored.
  newmem | whether or not to allocate memory for the element.

Return values

  errno | will be set in error condition. ENOENT : Stack is empty. ENOMEM : Memory allocation failure.

Returns
  a pointer of malloced element, otherwise returns NULL.

Definition at line 337 of file qstack.c.

## ◆ qstack_getstr()

char * qstack_getstr | ( | qstack_t * | stack | ) |

qstack->getstr(): Returns an string at the top of this stack without removing it.

Parameters

  stack | qstack container pointer.

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

Return values

  errno | will be set in error condition. ENOENT : Stack is empty. ENOMEM : Memory allocation failure.

Note
  The string element should be pushed through pushstr().

Definition at line 355 of file qstack.c.

## ◆ qstack_getint()

int64_t qstack_getint | ( | qstack_t * | stack | ) |

qstack->getint(): Returns an integer at the top of this stack without removing it.

Parameters

  stack | qstack container pointer.

Returns
  an integer value, otherwise returns 0.

Return values

  errno | will be set in error condition. ENOENT : Stack is empty. ENOMEM : Memory allocation failure.

Note
  The integer element should be pushed through pushint().

Definition at line 379 of file qstack.c.

## ◆ qstack_getat()

void * qstack_getat | ( | qstack_t * | stack,
|  | int | index,
|  | size_t * | size,
|  | bool | newmem
| ) |  |

qstack->getat(): Returns an element at the specified position in this stack without removing it.

Parameters

  stack | qstack container pointer.
  index | index at which the specified element is to be inserted
  size | if size is not NULL, element size will be stored.
  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.

Note
  Negative index can be used for addressing a element from the bottom in this stack. For example, index -1 will always get a element which is pushed at very first time.

Definition at line 409 of file qstack.c.

## ◆ qstack_size()

size_t qstack_size | ( | qstack_t * | stack | ) |

qstack->size(): Returns the number of elements in this stack.

Parameters

  stack | qstack container pointer.

Returns
  the number of elements in this stack.

Definition at line 420 of file qstack.c.

## ◆ qstack_clear()

void qstack_clear | ( | qstack_t * | stack | ) |

qstack->clear(): Removes all of the elements from this stack.

Parameters

  stack | qstack container pointer.

Definition at line 429 of file qstack.c.

## ◆ qstack_debug()

bool qstack_debug | ( | qstack_t * | stack,
|  | FILE * | out
| ) |  |

qstack->debug(): Print out stored elements for debugging purpose.

Parameters

  stack | qstack container pointer.
  out | output stream FILE descriptor such like stdout, stderr.

Returns
  true if successful, otherwise returns false.

Definition at line 441 of file qstack.c.

## ◆ qstack_free()

void qstack_free | ( | qstack_t * | stack | ) |

qstack->free(): Free qstack_t

Parameters

  stack | qstack container pointer.

Returns
  always returns true.

Definition at line 452 of file qstack.c.