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

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

Name

struct::stack - Create and manipulate Tcl stack objects, C 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::stack 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 stack objects. These are:

::struct stack new

This class method creates a new stack instance with an associated global Tcl command and returns the fully qualified name of this command. The name is auto-generated.

::struct stack create name

This class method creates a new stack 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 stacks created through the Class API support the following API:

stackObj at index

This method returns the requested element stored without removing it from the stack. The topmost element of the stack is addressed by index 0, whereas the bottommost element can be addressed as either size-1, or end. This addressing order matches the order used by method get to return the stack.

An error is thrown if the specified index is not within the boundaries of the stack.

Note that the method accepts for index all syntactical forms supported by the Tcl builtin lindex.

stackObj bottom ?count?

This method returns the bottom count elements of the stack, without removing them from the stack. The count defaults to 1.

If only one element is requested the result is that element. If more than one element is requested the result will be a list of elements, with the bottommost element of the stack returned as the last element of the result. This matches the ordering of method get.

An error will be thrown if the stack does not hold enough elements to satisfy the request, i.e. less than count elements.

stackObj clear

This method removes all elements from the stack.

The method returns the empty string as its result.

stackObj destroy

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

The method returns the empty string as its result.

stackObj get

This method returns all elements stored in the stack as a list, without removing them from the stack. The topmost element of the stack is returned as the first element of the list, while the bottom-most element of the stack is matched to the last element of the list.

In other words, writing the list in left-to-right order the top of the stack will be at the left, and the bottom at the right.

stackObj pop ?count?

This method returns the top count items of the stack, and removes them from the stack. The count defaults to 1.

If only one element is requested the result is that element. If more than one element is requested the result will be a list of elements, with the topmost element of the stack as the first element of the result. This matches the ordering of method get.

An error will be thrown if the stack does not hold enough elements to satisfy the request, i.e. less than count elements.

stackObj push item ?item...?

This method pushes the specified item or items onto the stack. If more than one item is given, they will be pushed in the order they are listed.

The method returns the empty string as its result.

stackObj rotate count steps

This method rotates the top count elements of the stack by the specified number of steps.

Rotating 1 element (i.e. "count == 1") is a no-op. Similarly "steps == 0 mod n" is a no-op as well.

Laying out the contents of the stack as returned by method get, i.e. top at the left, a positive number of steps rotates the elements left, whereas a negative steps rotates to the right.

The result of the method is the empty string.

stackObj size

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

stackObj top ?count?

This method returns the top count elements of the stack, without removing them from the stack. The count defaults to 1.

If only one element is requested the result is that element. If more than one element is requested the result will be a list of elements, with the topmost element of the stack returned as the first element of the result. This matches the ordering of method get.

An error will be thrown if the stack does not hold enough elements to satisfy the request, i.e. less than count elements.

stackObj trim ?newsize?

This method shrinks the stack to contain at most newsize elements and returns a list containing the elements which were removed. Nothing is done if the stack is already at the specified size, or smaller. In that case the result is the empty list.

stackObj trim* ?newsize?

This method is a variant of method trim which does not return the removed elements, and only performs any necessary shrinking.

Changes

Changes for version 2

Version 2 introduces incompatible changes to the API of stack 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::stack FOO       ; # or
    	set foo [struct::stack]
    

    whereas the new is

    	struct stack create FOO ; # or
    	set foo [struct stack new]
    
  3. Method getr has been dropped. Use

    	lreverse [FOO get]	
    

    instead, assuming that FOO is a stack instance.

  4. The methods peek and peekr have been renamed to top and bottom, respectively.

  5. The method at is 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, lifo, stack

Category

Data structures