temelia/release/include/stack.h

/*!
 Temelia - Stack interface.

 Copyright (C) 2008, 2009 Ceata (http://cod.ceata.org/proiecte/temelia).

 @author Dascalu Laurentiu

 This program is free software; you can redistribute it and
 modify it under the terms of the GNU General Public License
 as published by the Free Software Foundation; either version 3
 of the License, or (at your option) any later version.

 This program is distributed in the hope that it will be useful,
 but WITHOUT ANY WARRANTY; without even the implied warranty of
 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 GNU General Public License for more details.

 You should have received a copy of the GNU General Public License
 along with this program; if not, write to the Free Software
 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
 */

#ifndef STACK_H_
#define STACK_H_

#include "platform.h"

struct _stack_t;
typedef struct _stack_t *stack_t;

/*!
 * @brief Constructor - allocates an empty stack with maximum N keys.
 * Complexity O(1)
 *
 * @param Stack'stack size
 */
DECLSPEC stack_t stack_new(int capacity);

/*!
 * @brief Destructor - frees the memory occuppied by the stack.
 * Complexity O(n)
 *
 * @param Stack
 */
DECLSPEC void stack_delete(stack_t stack);

/*!
 * @brief Returns the current number of keys of the given stack.
 * Complexity O(1)
 *
 * @param Stack
 */
DECLSPEC int stack_get_size(stack_t stack);

/*!
 * @brief Returns the maximum number of keys of the given stack.
 * Complexity O(1)
 *
 * @param Stack
 */
DECLSPEC int stack_get_capacity(stack_t stack);

/*!
 * @brief Returns the current capacity increment, when the stack
 * will be full.
 * Complexity O(1)
 *
 * @param Stack
 */
DECLSPEC int stack_get_capacity_increment(stack_t stack);

/*!
 * @brief Sets the capacity increment step, when the stack gets full.
 * Complexity O(1)
 *
 * @param Stack
 * @param Capacity increment value
 */
DECLSPEC void stack_set_capacity_increment(stack_t stack, int new_capacity_increment);

/*!
 * @brief Returns the internal stack representation; cast it to vector.
 * Complexity O(1)
 *
 * @param Stack
 */
DECLSPEC void *stack_get_internal_representation(stack_t stack);

/*!
 * @brief Returns 1 if the stack is empty and 0 if it isn't.
 * Complexity O(1)
 *
 * @param Stack
 */
DECLSPEC int stack_is_empty(stack_t stack);

/*!
 * @brief Returns 1 if the stack is full and 0 if it isn't.
 * Complexity O(1)
 *
 * @param Stack
 */
DECLSPEC int stack_is_full(stack_t stack);

/*!
 * @brief Pushes key into the stack.
 * Complexity O(1)
 *
 * @param Stack
 * @param Key
 */
DECLSPEC void stack_push(stack_t stack, void *key);

/*!
 * @brief Removes key from stack'stack peek.
 * Complexity O(1)
 *
 * @param Stack
 */
DECLSPEC void stack_pop(stack_t stack);

/*!
 * @brief Returns the key from the peek of the stack.
 * Complexity O(1)
 *
 * @param Stack
 */
DECLSPEC void *stack_top(stack_t stack);

/*!
 * @brief Iterates over the keys of the stack . If order is 1 the functions prints
 * the keys in the natural order (LIFO) , else if order is -1 the functions
 * prints the keys in the same order you introduced them.
 * Complexity O(n)
 *
 * @param Stack
 * @param Pointer to iterating function
 * @param Context
 * @param Order
 */
DECLSPEC void stack_iterate(stack_t stack, void key_handler(void *key, void *context),
		void *context, int order);

#endif /* STACK_H_ */