[ Main Table Of Contents | Table Of Contents | Keyword Index ]

c::stack(n) 1 doc "Tcl Data Structures"

Name

c::stack - Create and manipulate C-level stack objects

Table Of Contents

Synopsis

Description

Welcome to Struct, a set of packages providing various data structures to Tcl, and additional operations for existing Tcl structures.

This package provides a basic C API for the creation and use of stacks. It does provide neither Tcl commands nor other items visible at script level.

The package is meant to be used by other C level data structure packages, either internally, or providing a Tcl level API to it. An example of the former is the package c::queue which uses several stacks inside of each queue. An example of the latter is the C implementation of package struct::stack.

To support this the package provides its C API by means of a stubs table which can be imported.

API

CSTACK cstack_create ( CSTACK_CELL_FREE fun, void* clientdata )

This function creates and initializes a new stack object and returns its handle. The client-data is simply stored and available upon request, see function cstack_clientdata_get below.

The free function fun is for the release of memory associated with the cells of the new stack. It may be NULL.

void cstack_destroy ( CSTACK s )

This function destroys the specified stack object, releasing all allocated memory.

The cell release function is called for all cells left in the stack.

long int cstack_size ( CSTACK s )

This function returns the number of cells in the stack.

void cstack_top ( CSTACK s )

This function returns the topmost cell in the stack.

The code asserts that the stack is not empty.

void cstack_bottom ( CSTACK s )

This function returns the bottom-most cell in the stack.

The code asserts that the stack is not empty.

void cstack_at ( CSTACK s long int i)

This function returns the indexed cell in the stack.

The code asserts that the stack is not empty, and that the index is in the proper range.

Index 0 addresses the topmost cell, whereas

index 'cstack_size()-1' addresses the bottommost cell.

void cstack_atr ( CSTACK s long int i)

This function is a variant of function cstack_at above, returning the indexed cell in the stack.

In contrast to the former the indexing is reversed. I.e.:

Index 'cstack_size()-1' addresses the topmost cell, whereas

index 0 addresses the bottommost cell.

CSLICE cstack_get ( CSTACK s, long int at, long int n )

This function returns the n cells starting at index at in the stack as a slice, with the topmost cell of the stack as the last element of the slice (natural internal order).

The indexing is the same as for function cstack_at above.

Index 0 addresses the topmost cell, whereas

index 'cstack_size()-1' addresses the bottommost cell.

CSLICE cstack_getr ( CSTACK s, long int at, long int n )

This function is a variant of function cstack_get above, returning the indexed slice in the stack.

In contrast to the former the indexing is reversed. I.e.:

Index 'cstack_size()-1' addresses the topmost cell, whereas

index 0 addresses the bottommost cell.

Note that this does not affect the ordering in the slice itself, which has the topmost cell of the stack as the last element of the slice (natural internal order).

void cstack_push ( CSTACK s, void* item )

This function pushes the item onto the stack.

void cstack_push_slice ( CSTACK s, CSLICE sl )

This function pushes all items in the slice onto the stack. It is a convenience function reducing the number of calls to cstack_push for bulk operations.

void cstack_pop ( CSTACK s, long int n )

This function removes the n topmost cells from the stack.

The cell release function is called for all removed cells. This is in contrast to function cstack_drop below.

void cstack_clear ( CSTACK s )

This convenience function is a variant cstack_pop which removes all cells from the stack. After the operation s is empty.

void cstack_trim ( CSTACK s, long int n )

This function removes cells until the stack contains only n cells. If the stack had less cells to begin with nothing is done.

The cell release function is called for all removed cells.

void cstack_drop ( CSTACK s, long int n )

This function drops the n topmost cells from the stack.

Note: The cell release function is not called for the removed cells. This is in contrast to function cstack_pop above.

void cstack_drop_all ( CSTACK s )

This convenience function is a variant of cstack_drop which drops all cells from the stack. After the operation s is empty.

void cstack_rol ( CSTACK s, long int n, long int step )

This function rotates the n topmost cells in the stack by step elements.

void cstack_move ( CSTACK s, CSTACK src, long int n )

This function moves the n topmost cells in the stack src to the stack s. This reverses their order. As the cells are not destroyed the release function is not called.

As a basic precaution the release functions of both stacks are compared, and have to match. The code will assert this and panic if the condition is not true.

void cstack_move_all ( CSTACK s, CSTACK src )

This convenience function is a variant of cstack_move which moves all cells of the source to the destination. After the operation src is empty.

void cstack_clientdata_set ( CSTACK s, void* clientdata )

This function sets new client data into the stack.

void* cstack_clientdata_get ( CSTACK s )

This function returns the client data currently stored in the stack.

License

This package, written by Andreas Kupries, is BSD licensed.

Bugs, Ideas, Feedback

This document, and the package it describes, will undoubtedly contain bugs and other problems. Please report such at the Struct Tracker. Please also report any ideas for enhancements you may have for either package and/or documentation.

Keywords

data structures, lifo, stack

Category

Data structures