c::stack - Create and manipulate C-level stack objects
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.
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.
This function destroys the specified stack object, releasing all allocated memory.
The cell release function is called for all cells left in the stack.
This function returns the number of cells in the stack.
This function returns the topmost cell in the stack.
The code asserts that the stack is not empty.
This function returns the bottom-most cell in the stack.
The code asserts that the stack is not empty.
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.
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.
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.
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).
This function pushes the item onto the stack.
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.
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.
This convenience function is a variant cstack_pop which removes all cells from the stack. After the operation s is empty.
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.
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.
This convenience function is a variant of cstack_drop which drops all cells from the stack. After the operation s is empty.
This function rotates the n topmost cells in the stack by step elements.
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.
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.
This function sets new client data into the stack.
This function returns the client data currently stored in the stack.
This package, written by Andreas Kupries, is BSD licensed.
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.
Data structures