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 an integer onto the top of this stack.
void *	qstack_pop (qstack_t *stack, size_t *size)
	qstack->pop(): Removes an element at the top of this stack and returns that element.
char *	qstack_popstr (qstack_t *stack)
	qstack->popstr(): Removes an element at the top of this stack and returns that element.
int64_t	qstack_popint (qstack_t *stack)
	qstack->popint(): Removes an 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 removes 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 a 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(): Prints stored elements for debugging purposes.
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, "Object A", sizeof("Object A"));
stack->push(stack, "Object B", sizeof("Object B"));
stack->push(stack, "Object C", sizeof("Object C"));
 
void *obj = stack->pop(stack, NULL);
printf("pop(): %s\n", (char*)obj);
free(obj);
obj = stack->pop(stack, NULL);
printf("pop(): %s\n", (char*)obj);
free(obj);
obj = 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(): Object C
pop(): Object B
pop(): Object A

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

pointer to allocated qstack_t container on success, or NULL on failure.

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 on success, otherwise 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 on success, otherwise 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 an integer onto the top of this stack.

Parameters

stack	qstack container pointer.
num	integer data.

Returns

true on success, otherwise 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 an 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

pointer to allocated element on success, or NULL on failure.

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 an element at the top of this stack and returns that element.

Parameters

stack

qstack container pointer.

Returns

pointer to allocated string element on success, or NULL on failure.

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 an 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 removes the element at the specified position in this stack.

Parameters

stack	qstack container pointer.
index	index of the element to pop
size	if size is not NULL, element size will be stored.

Returns

pointer to allocated element on success, or NULL on failure.

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 an element from the bottom in this stack. For example, index -1 will always pop an 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

pointer to allocated element on success, or NULL on failure.

Definition at line 337 of file qstack.c.

qstack_getstr()

char * qstack_getstr

(

qstack_t *

stack

)

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

Parameters

stack

qstack container pointer.

Returns

pointer to allocated string element on success, or NULL on failure.

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

pointer to element on success, or NULL on failure.

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 an element from the bottom in this stack. For example, index -1 will always get an 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(): Prints stored elements for debugging purposes.

Parameters

stack	qstack container pointer.
out	output stream such as stdout or stderr.

Returns

true on success, otherwise 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.