1[manpage_begin struct::stack n 1.5.1] 2[moddesc {Tcl Data Structures}] 3[titledesc {Create and manipulate stack objects}] 4[category {Data structures}] 5[require Tcl 8.4] 6[require struct::stack [opt 1.5.1]] 7[description] 8 9The [namespace ::struct] namespace contains a commands for processing 10finite stacks. 11 12[para] 13 14It exports a single command, [cmd ::struct::stack]. All functionality 15provided here can be reached through a subcommand of this command. 16 17[para] 18 19[emph Note:] As of version 1.3.3 of this package a critcl based C 20implementation is available. This implementation however requires Tcl 218.4 to run. 22 23[para] 24 25The [cmd ::struct::stack] command creates a new stack object with an 26associated global Tcl command whose name is [emph stackName]. This 27command may be used to invoke various operations on the stack. It has 28the following general form: 29 30[list_begin definitions] 31 32[call [arg stackName] [cmd option] [opt [arg "arg arg ..."]]] 33 34[arg Option] and the [arg arg]s determine the exact behavior of the 35command. The following commands are possible for stack objects: 36 37 38[call [arg stackName] [method clear]] 39 40Remove all items from the stack. 41 42 43[call [arg stackName] [method destroy]] 44 45Destroy the stack, including its storage space and associated command. 46 47 48[call [arg stackName] [method get]] 49 50Returns the whole contents of the stack as a list, without removing 51them from the stack. 52 53[call [arg stackName] [method getr]] 54 55A variant of [method get], which returns the contents in reversed order. 56 57[call [arg stackName] [method peek] [opt [arg count]]] 58 59Return the top [arg count] items of the stack, without removing them from 60the stack. If [arg count] is not specified, it defaults to 1. If 61[arg count] is 1, the result is a simple string; otherwise, it is a 62list. If specified, [arg count] must be greater than or equal to 1. 63 64If there are not enoughs items on the stack to fulfull the request, 65this command will throw an error. 66 67[call [arg stackName] [method peekr] [opt [arg count]]] 68 69A variant of [method peek], which returns the items in reversed order. 70 71[call [arg stackName] [method trim] [opt [arg newsize]]] 72 73Shrinks the stack to contain at most [arg newsize] elements and 74returns a list containing the elements which were removed. Nothing is 75done if the stack is already at the specified size, or smaller. In 76that case the result is the empty list. 77 78[call [arg stackName] [method trim*] [opt [arg newsize]]] 79 80A variant of [method trim] which performs the shrinking, but does not 81return the removed elements. 82 83[call [arg stackName] [method pop] [opt [arg count]]] 84 85Return the top [arg count] items of the stack, and remove them 86from the stack. If [arg count] is not specified, it defaults to 1. 87If [arg count] is 1, the result is a simple string; otherwise, it is a 88list. If specified, [arg count] must be greater than or equal to 1. 89 90If there are not enoughs items on the stack to fulfull the request, 91this command will throw an error. 92 93 94[call [arg stackName] [method push] [arg item] [opt [arg item...]]] 95 96Push the [arg item] or items specified onto the stack. If more than 97one [arg item] is given, they will be pushed in the order they are 98listed. 99 100 101[call [arg stackName] [method size]] 102 103Return the number of items on the stack. 104 105[list_end] 106 107[section {BUGS, IDEAS, FEEDBACK}] 108 109This document, and the package it describes, will undoubtedly contain 110bugs and other problems. 111 112Please report such in the category [emph {struct :: stack}] of the 113[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. 114 115Please also report any ideas for enhancements you may have for either 116package and/or documentation. 117 118 119[keywords queue matrix tree graph] 120[manpage_end] 121