struct::stack(3tcl)

💖 struct::stack — the Tcl Data Structures manual, but make it cute 💖

okay bestie, sit down, hydrate, because we're learning about struct::stack from the Tcl Data Structures manual and it's genuinely so much fun. this is the struct::stack(3tcl) page and yes it's giving "finite stacks, but make it iconic" ✨

---

🎀 NAME 🎀

struct::stack — create and manipulate stack objects. that's it, that's the whole vibe. 🫶

---

✨ SYNOPSIS ✨

no cap, here's the whole shape of it:

package require Tcl 8.5 9

package require struct::stack ?1.5.4?

stackName option ?arg arg ...?

stackName clear

stackName destroy

stackName get

stackName getr

stackName peek ?count?

stackName peekr ?count?

stackName trim ?newsize?

stackName trim* ?newsize?

stackName pop ?count?

stackName push item ?item...?

stackName size

look at all those little commands. they're like a friend group fr fr 💅

---

🌸 DESCRIPTION 🌸

so, the ::struct namespace is where all the commands for processing finite stacks live. it exports exactly one command — ::struct::stack — and literally every bit of functionality here is reachable through a subcommand of that one command. one queen, many talents. 👑

💡 note, bestie: as of version 1.3.3 of this package, there's a critcl based C implementation available. but — and this is important — that implementation requires Tcl 8.4 to run. iykyk.

the ::struct::stack command creates a brand new stack object with an associated global Tcl command whose name is stackName. you use that command to invoke all the various operations on the stack. its general form is:

stackName option ?arg arg ...?

option and the args determine the exact behavior of the command. and these are the commands possible for stack objects — buckle up, there's a lot and we love that for us:

• stackName clear — remove all items from the stack. like, gone. bye. 🧹
• stackName destroy — destroy the stack, including its storage space and its associated command. it's not just leaving the party, it's deleting the group chat. 😭
• stackName get — returns the whole contents of the stack as a list, and does not remove them from the stack. look, don't touch. 🙈
• stackName getr — a variant of get, but it returns the contents in reversed order. ✨
• stackName peek ?count? — return the top count items of the stack, without removing them from the stack. if count isn't specified, it defaults to 1. if count is 1, the result is a simple string; otherwise it's a list. if specified, count must be greater than or equal to 1. and if there aren't enough items on the stack to fulfil the request, this command will throw an error. 😤
• stackName peekr ?count? — a variant of peek, which returns the items in reversed order. 🔄
• stackName trim ?newsize? — shrinks the stack to contain at most newsize elements, and returns a list containing the elements which were removed. if the stack is already at the specified size, or smaller, nothing is done — and in that case the result is the empty list. lowkey polite of it. 🎀
• stackName trim* ?newsize? — a variant of trim which performs the shrinking, but does not return the removed elements. silent, mysterious, main character energy. 💅
• stackName pop ?count? — return the top count items of the stack, and remove them from the stack. if count isn't specified, it defaults to 1. if count is 1, the result is a simple string; otherwise it's a list. if specified, count must be greater than or equal to 1. and if there aren't enough items on the stack to fulfil the request, this command will throw an error. same energy as peek, but it actually takes the items with it. 🫣
• stackName push item ?item...? — push the item, or items, specified onto the stack. if more than one item is given, they will be pushed in the order they are listed. order matters, bestie, always has. 🍓
• stackName size — return the number of items on the stack. the headcount. the attendance list. 👑

---

💀 BUGS, IDEAS, FEEDBACK 💀

ngl, this document — and the package it describes — will undoubtedly contain bugs and other problems. it's giving "we're all human." so please report them in the category struct :: stack of the Tcllib Trackers:

http://core.tcl.tk/tcllib/reportlist

and please also report any ideas for enhancements you may have for either the package and/or the documentation. we love a glow-up suggestion. 🌈

when proposing code changes, please provide unified diffs, i.e. the output of diff -u. that's the standard, no substitutions. ✨

⚠️ note further that attachments are strongly preferred over inlined patches. attachments can be made by going to the Edit form of the ticket immediately after its creation, and then using the left-most button in the secondary navigation bar. do it that way, fr fr. 🫶

---

🔥 KEYWORDS 🔥

• graph
• matrix
• queue
• tree

(not me noticing stack isn't in its own keyword list — iconic behavior honestly 💀)

---

🌟 CATEGORY 🌟

Data structures

---

and that's the whole page, bestie!! 💜 you now know every single option, argument, default, error case and caveat, and you did it with style. slay. 🦋

this was tcllib version 1.5.4, dated struct::stack(3tcl) — mwah, go push something onto a stack and feel powerful. 💅✨