counter(3tcl)

💖 counter — bestie's guide to counting things 💖

okay so you want to count stuff and make little bar charts about it?? say less. this is counter, a package from tcllib, and honestly it's giving statistics girlboss and i'm obsessed. ✨

---

🌸 NAME 🌸

counter — procedures for counters and histograms. that's it. that's the vibe. 💅

---

✨ SYNOPSIS ✨

package require Tcl 8.5 9

package require counter ?2.0.6?

::counter::init tag args

::counter::count tag ?delta? ?instance?

::counter::start tag instance

::counter::stop tag instance

::counter::get tag args

::counter::exists tag

::counter::names

::counter::histHtmlDisplay tag args

::counter::reset tag args

---

🦋 DESCRIPTION 🦋

okay so the counter package literally hands you a whole counter facility, and it can compute statistics and histograms over all the data you collected. it's the main character of data tallying fr fr. 👑

🎀 ::counter::init tag args

this defines a counter with the name tag. the args decides what kind of counter this is gonna be, and here are all your options bestie:

• -group name — keeps a grouped counter, where the name of the histogram bucket gets passed into ::counter::count.
• -hist bucketsize — accumulates the counter into histogram buckets of size bucketsize. for example, if your samples are millisecond time values and bucketsize is 10, then each histogram bucket represents time values of 0 to 10 msec, 10 to 20 msec, 20 to 30 msec, and so on. slay.
• -hist2x bucketsize — accumulates the statistic into histogram buckets. the size of the first bucket is bucketsize, and every other bucket holds values 2 times the size of the previous bucket. so if bucketsize is 10, each histogram bucket represents time values of 0 to 10 msec, 10 to 20 msec, 20 to 40 msec, 40 to 80 msec, and so on. exponential era. 📈
• -hist10x bucketsize — same energy but bigger. the size of the first bucket is bucketsize, and each other bucket holds values 10 times the size of the previous bucket. so with bucketsize of 10, each bucket represents time values of 0 to 10 msec, 10 to 100 msec, 100 to 1000 msec, and so on.
• -lastn N — saves the last N values of the counter so you can maintain a "running average" over the last N values. lowkey so useful. 🫶
• -timehist secsPerMinute — keeps a time-based histogram. the counter gets summed into a histogram bucket based on the current time. there are 60 per-minute buckets with a size determined by secsPerMinute, which is normally 60, but for testing purposes can be less. every "hour" (i.e., 60 "minutes") the contents of the per-minute buckets are summed into the next hourly bucket. every 24 "hours" the contents of the per-hour buckets are summed into the next daily bucket. and here's the tea ☕: the counter package keeps all time-based histograms in sync, so the first secsPerMinute value seen by the package is used for all subsequent time-based histograms. no cap.

🧚 ::counter::count tag ?delta? ?instance?

increments the counter identified by tag. the default increment is 1, but you can increment by any value — integer or real — by specifying delta. ✨

⚠️ bestie you must declare each counter with ::counter::init to define its characteristics before you start using it. no skipping steps.

if the counter type is -group, then the counter identified by instance is the one that gets incremented.

🌈 ::counter::start tag instance

records the starting time of an interval. tag is the name of the counter defined as a -hist value-based histogram. instance distinguishes this interval from any other intervals that might be overlapping this one. so you can have multiple timers running and not get them confused, iconic.

🍓 ::counter::stop tag instance

records the ending time of an interval. the delta time since the corresponding ::counter::start call for instance gets recorded in the histogram identified by tag. boom, timed. ⏱️

💜 ::counter::get tag args

returns statistics about a counter identified by tag. the args decides which value you get back:

• -total — returns the total value of the counter. this is the default if args isn't specified.
• -totalVar — returns the name of the total variable. super handy for specifying with -textvariable in a Tk widget.
• -N — returns the number of samples accumulated into the counter.
• -avg — returns the average of samples accumulated into the counter.
• -avgn — returns the average over the last N samples taken. that N value is set in the ::counter::init call.
• -hist bucket — if bucket is specified, returns the value in that bucket of the histogram. otherwise returns the complete histogram in array get format, sorted by bucket.
• -histVar — returns the name of the histogram array variable.
• -histHour — returns the complete hourly histogram in array get format, sorted by bucket.
• -histHourVar — returns the name of the hourly histogram array variable.
• -histDay — returns the complete daily histogram in array get format, sorted by bucket.
• -histDayVar — returns the name of the daily histogram array variable.
• -resetDate — returns the clock seconds value recorded when the counter was last reset.
• -all — returns an array get of the array used to store the counter. this includes the total, the number of samples (N), and any type-specific information. this does not include the histogram array. note it. 📝

🎀 ::counter::exists tag

returns 1 if the counter is defined. yes/no, that's the whole thing. 💁‍♀️

👑 ::counter::names

returns a list of all counters defined. the full roster, the whole friend group.

🦋 ::counter::histHtmlDisplay tag args

generates HTML to display a histogram for a counter. the args controls the format of the display:

• -title string — label to display above the bar chart.
• -unit unit — specify minutes, hours, or days for the time-base histograms. for value-based histograms, the unit is used in the title.
• -images url — URL of /images directory.
• -gif filename — image for normal histogram bars. the filename is relative to the -images directory.
• -ongif filename — image for the active histogram bar. the filename is relative to the -images directory.
• -max N — maximum number of value-based buckets to display.
• -height N — pixel height of the highest bar.
• -width N — pixel width of each bar.
• -skip N — buckets to skip when labeling value-based histograms.
• -format string — format used to display labels of buckets.
• -text boolean — if 1, a text version of the histogram is dumped; otherwise a graphical one is generated.

💅 ::counter::reset tag args

resets the counter with the name tag to an initial state. the args determine the new characteristics of the counter, and they have the exact same meaning as described for ::counter::init. fresh start energy. 🌱

---

💀 BUGS, IDEAS, FEEDBACK 💀

okay real talk: this document, and the package it describes, will undoubtedly contain bugs and other problems. 😭 not me being honest about it but that's what it says. please report such in the category counter 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. we love feedback bestie. 🫶

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. got it? good. 💖

---

🌸 KEYWORDS 🌸

counting, histogram, statistics, tallying

---

🎀 CATEGORY 🎀

Data structures

---

and that's the whole page bestie!! this was written for tcllib, version 2.0.6, and the page is dated with that same 2.0.6 (yes it's the same number twice, it's giving matching outfits 💅). the manual name is counter(3tcl) in case you forgot. now go count something and slay. 👑✨🦋