struct::prioqueue(n)

💖 struct::prioqueue(n) — the Tcl Data Structures manual, but make it a group chat 💖

okay bestie, sit down, hydrate, because we're about to talk about priority queues and honestly? it's giving main character energy. this is the struct::prioqueue page from the Tcl Data Structures manual set, and by the end of it you're gonna be putting items in priority order like it's nothing. no cap. 🎀

---

✨ NAME ✨

struct::prioqueue — create and manipulate prioqueue objects. that's it, that's the name, and it's iconic. 🦋

---

🌸 SYNOPSIS 🌸

package require Tcl 8.5 9

package require struct::prioqueue ?1.5?

::struct::prioqueue ?-ascii|-dictionary|-integer|-real? ?prioqueueName?

prioqueueName option ?arg arg ...?

prioqueueName clear

prioqueueName remove item

prioqueueName destroy

prioqueueName get ?count?

prioqueueName peek ?count?

prioqueueName peekpriority ?count?

prioqueueName put item prio ?item prio ...?

prioqueueName size

like… look at that. every single one of those is a real thing you can do. we're so blessed. 😭💜

---

👑 DESCRIPTION 👑

so this package implements a simple priority queue using nested tcl lists. simple! elegant! lowkey genius! 💅

the command ::struct::prioqueue creates a brand new priority queue, and the default priority key type is -integer. which means, bestie, that the keys you hand over to the put subcommand have to be that type. no exceptions, she's strict. ✨

that same key type also sets your priority ordering, and here's the tea 🍓:

• for key types -ascii and -dictionary, the data is sorted in ascending order (exactly like lsort -increasing)
• for -integer and -real, the data is sorted in descending order (exactly like lsort -decreasing)

prioqueue names are unrestricted, but heads up — they may be recognized as options if no priority type is given. yes, that's a real vibe check moment, watch out for it. 🙈

---

🌈 the commands, one by one, no skips 🌈

• ::struct::prioqueue ?-ascii|-dictionary|-integer|-real? ?prioqueueName? — this creates a new prioqueue object with an associated global Tcl command whose name is prioqueueName. that command is your girl — you use her to invoke all the various operations on the prioqueue. general form below, obviously:

prioqueueName option ?arg arg ...?

• prioqueueName option ?arg arg ...? — here option and the args decide the exact behavior of the command. the possible commands for prioqueue objects are the ones listed right below. periodt. 💅
• prioqueueName clear — removes all items from the prioqueue. clean slate, fresh start, therapy basically. 🧹
• prioqueueName remove item — removes the selected item from this priority queue. just that one. targeted. 🎯
• prioqueueName destroy — destroys the prioqueue, including its storage space and its associated command. like, gone gone. 💀
• prioqueueName get ?count? — returns the front count items of the prioqueue (but not their priorities) and removes them from the prioqueue. 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 are no items, or too few items, in the prioqueue, this command will throw an error. so be normal about it. 😭
• prioqueueName peek ?count? — same energy as get but she doesn't remove anything — returns the front count items (again, not their priorities) and leaves them right where they are. count defaults to 1. count of 1 gives you a simple string; otherwise you get a list. if specified, count must be greater than or equal to 1. no items or too few items? error. peek with your eyes only, bestie. 👀
• prioqueueName peekpriority ?count? — returns the front count items' priority keys, without removing them from the prioqueue. count defaults to 1, and a count of 1 gives a simple string, otherwise a list. if specified, count must be greater than or equal to 1. no items or too few items in the queue → error. yes this is the one that shows you the receipts. 🧾
• prioqueueName put item prio ?item prio ...? — puts the item or items you specify into the prioqueue. prio must be a valid priority key for this type of prioqueue — otherwise an error is thrown and no item is added, so nothing gets half-done, we love a clean fail. items are inserted at their priority ranking, and items with equal priority are added in the order they were added. first come first served among the equals, no cutting the line. 🚶♀️🚶♀️🚶♀️
• prioqueueName size — returns the number of items in the prioqueue. a number. that's the whole thing. still important. 💖

---

🫶 BUGS, IDEAS, FEEDBACK 🫶

ngl, this document, and the package it describes, will undoubtedly contain bugs and other problems. it's not a read, it's a reality. 😭

please report such things in the category struct :: prioqueue of the Tcllib Trackers at [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 want the glow-up ideas. ✨

when proposing code changes, please provide unified diffs, i.e. the output of diff -u.

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

---

⭐ KEYWORDS ⭐

• ordered list
• prioqueue
• priority queue

---

🦋 CATEGORY 🦋

Data structures

---

💜 COPYRIGHT 💜

Copyright (c) 2003 Michael Schlenker <mic42@users.sourceforge.net>

---

and that's the whole page, bestie — brought to you by tcllib, version 1.5, in the struct::prioqueue(n) manual. go forth, put things in priority order, and slay. 💅✨🌸