counter(n)

✨ NAME ✨

counter — Procedures for counters and histograms. Also known as counter(n), the Counters and Histograms page. No cap, this is the whole 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 💖

The counter package provides a counter facility and can compute statistics and histograms over the collected data. Periodt. ✨

::counter::init tag args

This defines a counter with the name tag. The args determines the characteristics of the counter. The args are:

• -group name — Keep a grouped counter where the name of the histogram bucket is passed into ::counter::count. It's giving group chat energy. 🫶
• -hist bucketsize — Accumulate the counter into histogram buckets of size bucketsize. For example, if the 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. Lowkey obsessed with this bucketing. 📊
• -hist2x bucketsize — Accumulate the statistic into histogram buckets. The size of the first bucket is bucketsize, each other bucket holds values 2 times the size of the previous bucket. For example, if bucketsize is 10, then 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. The way it doubles? Iconic. 🔥
• -hist10x bucketsize — Accumulate the statistic into histogram buckets. The size of the first bucket is bucketsize, each other bucket holds values 10 times the size of the previous bucket. For example, if bucketsize is 10, then each histogram bucket represents time values of 0 to 10 msec, 10 to 100 msec, 100 to 1000 msec, and so on. Ten times? Slay. 💅
• -lastn N — Save the last N values of the counter to maintain a "running average" over the last N values. Bestie, this is your running average era. 📈
• -timehist secsPerMinute — Keep a time-based histogram. The counter is summed into a histogram bucket based on the current time. There are 60 per-minute buckets that have 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. 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. The way it syncs? Main character energy. ⏰

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

Increment the counter identified by tag. The default increment is 1, although you can increment by any value, integer or real, by specifying delta. You must declare each counter with ::counter::init to define the characteristics of counter before you start to use it. If the counter type is -group, then the counter identified by instance is incremented. Not me forgetting to ::counter::init first, couldn't be me. 🙈

::counter::start tag instance

Record the starting time of an interval. The tag is the name of the counter defined as a -hist value-based histogram. The instance is used to distinguish this interval from any other intervals that might be overlapping this one. It's giving overlapping intervals? We love a distinguished instance. 🦋

::counter::stop tag instance

Record the ending time of an interval. The delta time since the corresponding ::counter::start call for instance is recorded in the histogram identified by tag. And that's on periodt. ⏱️

::counter::get tag args

Return statistics about a counter identified by tag. The args determine what value to return:

• -total — Return the total value of the counter. This is the default if args is not specified. The default? We love a default. 👑
• -totalVar — Return the name of the total variable. Useful for specifying with -textvariable in a Tk widget. Tk widget besties, this one's for you. 🎀
• -N — Return the number of samples accumulated into the counter. Capital N energy. 🔢
• -avg — Return the average of samples accumulated into the counter. The average? Mid? No, average is valid. 📊
• -avgn — Return the average over the last N samples taken. The N value is set in the ::counter::init call. Last N? Lowkey specific. 💅
• -hist bucket — If bucket is specified, then the value in that bucket of the histogram is returned. Otherwise the complete histogram is returned in array get format sorted by bucket. Array get format? Iykyk. 🧚
• -histVar — Return the name of the histogram array variable. Var? We stan a variable name. 💜
• -histHour — Return the complete hourly histogram in array get format sorted by bucket. Hourly? The tea is piping hot. ☕
• -histHourVar — Return the name of the hourly histogram array variable. Hourly var? Okay. 🌈
• -histDay — Return the complete daily histogram in array get format sorted by bucket. Daily? The drama continues. 📅
• -histDayVar — Return the name of the daily histogram array variable. Daily var? Slay. ⭐
• -resetDate — Return the clock seconds value recorded when the counter was last reset. Clock seconds? Time is a construct. ⏳
• -all — Return 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. All but not the histogram? Noted. 💀

::counter::exists tag

Returns 1 if the counter is defined. Existence is a vibe. ✨

::counter::names

Returns a list of all counters defined. A whole list? We love a list. 📝

::counter::histHtmlDisplay tag args

Generate HTML to display a histogram for a counter. The args control the format of the display. They are:

• -title string — Label to display above bar chart. Title? Main character energy. 👑
• -unit unit — Specify minutes, hours, or days for the time-base histograms. For value-based histograms, the unit is used in the title. Unit? We love a unit. 📏
• -images url — URL of /images directory. URL? Bestie, link it. 🔗
• -gif filename — Image for normal histogram bars. The filename is relative to the -images directory. GIF? We love a GIF. 🎞️
• -ongif filename — Image for the active histogram bar. The filename is relative to the -images directory. Ongif? Active bar? Hot. 🔥
• -max N — Maximum number of value-based buckets to display. Max? Cap it. 🧢
• -height N — Pixel height of the highest bar. Height? Pixels? Okay. 📐
• -width N — Pixel width of each bar. Width? Also pixels. 📐
• -skip N — Buckets to skip when labeling value-based histograms. Skip? We love a skip. ⏭️
• -format string — Format used to display labels of buckets. Format? String? Iconic. 💅
• -text boolean — If 1, a text version of the histogram is dumped, otherwise a graphical one is generated. Boolean? 1? Say less. 1️⃣

::counter::reset tag args

Resets the counter with the name tag to an initial state. The args determine the new characteristics of the counter. They have the same meaning as described for ::counter::init. Reset? We love a fresh start. 🔄

---

😭 BUGS, IDEAS, FEEDBACK 😭

This document, and the package it describes, will undoubtedly contain bugs and other problems. Please report such in the category counter of the Tcllib Trackers (http://core.tcl.tk/tcllib/reportlist). Please also report any ideas for enhancements you may have for either package and/or documentation.

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.

bestie, don't be shy, report those bugs. The Tcllib Trackers are waiting. 💖

---

🔑 KEYWORDS 🔑

counting, histogram, statistics, tallying

---

🗂️ CATEGORY 🗂️

Data structures

---

this page is from tcllib, version 2.0.6, and it's the counter(n) manual. bye bestie 💖✨