struct::queue - Create and manipulate Tcl queue objects, Tcl implementation
Welcome to Struct, a set of packages providing various data structures to Tcl, and additional operations for existing Tcl structures.
This manpage documents the C implementation of the struct::queue package. It provides the same API as the Tcl implementation, although details like the exact wording of error messages may differ.
The ::struct namespace contains a single command with multiple methods for the creation of queue objects. These are:
This class method creates a new queue instance with an associated global Tcl command and returns the fully qualified name of this command. The name is auto-generated.
This class method creates a new queue instance with an associated global Tcl command and returns the fully qualified name of this command. The name is chosen by the user and provided as the argument of the method.
All instances of queues created through the Class API support the following API:
This method returns all elements stored in the queue as a list, without removing them from the queue. The first element of the queue is returned as the first element of the list, while the last element of the queue is matched to the last element of the list.
This method adds the specified item or items at the end of the queue. If more than one item is given, they will be added in the order they are listed.
The method returns the empty string as its result.
The pair of methods put and get manage a queue.
This method returns the segment of count elements starting at the index of the queue, without removing them from the queue. The count defaults to 1.
If more than one element is requested the result will be a list of elements, with the front element of the queue as the first element of the result. If only one element is requested the result is that element.
An error will be thrown if the queue does not hold enough elements to satisfy the request, i.e. at+count reaching beyond the end of the queue.
The first element of the queue is at index 0.
Note that the method accepts for index all syntactical forms supported by the Tcl builtin lindex.
This method removes all elements from the queue.
The method returns the empty string as its result.
This method destroys the queue instance and the associated Tcl command, releasing any associated resurces.
The method returns the empty string as its result.
This method returns the first count elements of the queue, without removing them from the queue. The count defaults to 1.
If more than one element is requested the result will be a list of elements, with the front element of the queue as the first element of the result. If only one element is requested the result is that element.
An error will be thrown if the queue does not hold enough elements to satisfy the request, i.e. less than count elements.
This method behaves like method head, except that it removes the returned element(s) as well.
This method behaves like method tail, except that it removes the returned element(s) as well.
This method behaves like method append, except that it adds the elements at the beginning of the queue.
The pair of methods prepend and pop head manage a stack.
This method returns the number of elements stored in the queue.
This method returns the last count elements of the queue, without removing them from the queue. The count defaults to 1.
If more than one element is requested the result will be a list of elements, with the front element of the queue as the first element of the result. If only one element is requested the result is that element.
An error will be thrown if the queue does not hold enough elements to satisfy the request, i.e. less than count elements.
Version 2 introduces incompatible changes to the API of queue objects, therefore the change to the major version number.
The changes in detail are:
Version 2 requires Tcl 8.5 or higher. Tcl 8.4 or less is not supported anymore.
Instance creation syntax has changed. For comparison, the old syntax is
struct::queue FOO ; # or set foo [struct::queue]
whereas the new is
struct queue create FOO ; # or set foo [struct queue new]
The methods peek, put, unget, and get have been renamed to head, append, prepend, and pop head, respectively.
The methods all, at, tail, and pop tail are new.
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