struct::prioqueue(3tcl)

💖 struct::prioqueue — the manual, but make it cute ✨

ok so bestie, welcome to struct::prioqueue, a page straight out of Tcl Data Structures. grab a boba, we're building priority queues 🌸

---

🎀 NAME 🎀

struct::prioqueue — create and manipulate prioqueue objects. that's it, that's the job 💅

---

✨ 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

---

🌈 DESCRIPTION 🌈

okay so this package implements a simple priority queue using nested tcl lists. no cap, that's the whole storage strategy 🍓

the command ::struct::prioqueue creates a brand new priority queue with the default priority key type -integer. what that means for you: keys you hand over to the put subcommand must have that type. it's giving strict but fair ✨

this is also what sets your priority ordering, so pay attention bestie:

• 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. lowkey a little trap, iykyk 👀

👑 the commands, one by one

• ::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 main character, it's how you invoke all the various operations on the prioqueue. its general form is:

prioqueueName option ?arg arg ...?

• prioqueueName option ?arg arg ...? — option and the args decide the exact behavior of the command. for prioqueue objects, the possible commands are the ones listed below 💅
• prioqueueName clear — remove all items from the prioqueue. total clean slate, so satisfying 🧚
• prioqueueName remove item — remove the selected item from this priority queue. bye bestie 👋
• prioqueueName destroy — destroy the prioqueue, including its storage space and its associated command. it's gone gone 💀
• prioqueueName get ?count? — return the front count items of the prioqueue (but not their priorities) and remove 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 you do specify it, 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 check your size first fr fr.
• prioqueueName peek ?count? — return the front count items of the prioqueue (but not their priorities), without removing them from the prioqueue. look, don't touch 🙈. 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 yeah, if there are no items or too few items in the queue, this command will throw an error.
• prioqueueName peekpriority ?count? — return the front count items' priority keys, without removing them from the prioqueue. same deal: count defaults to 1; count of 1 gives you a simple string, otherwise a list; if specified it must be greater than or equal to 1; and if there are no items or too few items in the queue, this command will throw an error 🌸
• prioqueueName put item prio ?item prio ...? — put 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. items get inserted at their priority ranking, and items with equal priority are added in the order they were added (fifo energy, we love to see it) 🫶
• prioqueueName size — return the number of items in the prioqueue. the receipts 📊

---

🦋 BUGS, IDEAS, FEEDBACK 🦋

ngl bestie, this document and the package it describes will undoubtedly contain bugs and other problems. it's giving humble.

please report such in the category struct :: prioqueue of the Tcllib Trackers at http://core.tcl.tk/tcllib/reportlist. please also report any ideas for enhancements you may have for either the package and/or the documentation 💜

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

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. no cap, that's the whole workflow 🎀

---

🔥 KEYWORDS 🔥

ordered list, prioqueue, priority queue

---

⭐ CATEGORY ⭐

Data structures

---

💜 COPYRIGHT 💜

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

---

okay that's the whole page, and yes, this little icon of a manual comes from tcllib, version 1.5 — the struct::prioqueue(3tcl) era, iconic behavior only 👑 thanks for reading bestie, now go sort something 💅✨