c::queue - Create and manipulate C-level queue 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 queues. 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 latter is the C implementation of package struct::queue.
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 queue object and returns its handle. The client-data is simply stored and available upon request, see function cqueue_clientdata_get below.
The free function fun is for the release of memory associated with the cells of the new queue. It may be NULL.
This function destroys the specified queue object, releasing all allocated memory.
The cell release function is called for all cells left in the queue.
This function returns the number of cells in the queue.
This function returns the first cell in the queue.
The code asserts that the queue is not empty.
This function returns the last cell in the queue.
The code asserts that the queue is not empty.
This function returns the first n cells in the queue as a slice, with the first cell of the queue as the first element of the slice (natural internal order).
This function returns the last n cells in the queue as a slice, with the last cell of the queue as the last element of the slice (natural internal order).
This function returns the n cells starting at index at in the queue as a slice, with the first cell in the queue as the first element of the slice (natural internal order).
The indexing uses the natural internal order:
Index 0 addresses the first cell, whereas
index 'cqueue_size()-1' addresses the last cell.
This function adds the item to the queue, at the end.
This function adds the item to the queue, at the head.
This function adds all items in the slice to the queue, at the end, in slice order (keeping their order in the queue). It is a convenience function reducing the number of calls to cqueue_append for bulk operations.
This function adds all items in the slice to the queue, at the head, in slice order (reversing their order in the queue). It is a convenience function reducing the number of calls to cqueue_prepend for bulk operations.
This function removes the first n cells from the queue.
The cell release function is called for all removed cells. This is in contrast to function cqueue_drop_head below.
This function removes the last n cells from the queue.
The cell release function is called for all removed cells. This is in contrast to function cqueue_drop_tail below.
This convenience function is a variant cqueue_remove_head which removes all cells from the queue. After the operation q is empty.
This function drops the first n cells from the queue.
Note: The cell release function is not called for the removed cells. This is in contrast to function cqueue_remove_head above.
This function drops the last n cells from the queue.
Note: The cell release function is not called for the removed cells. This is in contrast to function cqueue_remove_tail above.
This convenience function is a variant of cqueue_drop_head which drops all cells from the queue. After the operation q is empty.
This function moves the first n cells in the queue src to the queue q, adding them at the end. This keeps their order. As the cells are not destroyed the release function is not called.
As a basic precaution the release functions of both queues 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 cqueue_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 queue.
This function returns the client data currently stored in the queue.
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