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

struct::queue(n) 2 doc "Tcl Data Structures"

Name

struct::queue - Create and manipulate Tcl queue objects, Tcl implementation

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 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.

Class API

The ::struct namespace contains a single command with multiple methods for the creation of queue objects. These are:

::struct queue new

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.

::struct queue create name

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.

Instance API

All instances of queues created through the Class API support the following API:

queueObj all

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.

queueObj append item ?...?

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.

queueObj at index ?count?

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.

queueObj clear

This method removes all elements from the queue.

The method returns the empty string as its result.

queueObj destroy

This method destroys the queue instance and the associated Tcl command, releasing any associated resurces.

The method returns the empty string as its result.

queueObj head ?count?

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.

queueObj pop head ?n?

This method behaves like method head, except that it removes the returned element(s) as well.

queueObj pop tail ?n?

This method behaves like method tail, except that it removes the returned element(s) as well.

queueObj prepend item ?...?

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.

queueObj size

This method returns the number of elements stored in the queue.

queueObj tail ?count?

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.

Changes

Changes for version 2

Version 2 introduces incompatible changes to the API of queue objects, therefore the change to the major version number.

The changes in detail are:

  1. Version 2 requires Tcl 8.5 or higher. Tcl 8.4 or less is not supported anymore.

  2. 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]
    
  3. The methods peek, put, unget, and get have been renamed to head, append, prepend, and pop head, respectively.

  4. The methods all, at, tail, and pop tail are new.

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, fifo, queue

Category

Data structures