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

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.