---
name: "counter"
section: "3tcl"
platform: "linux"
package: "tcllib"
version: "2.0+dfsg-4"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/counter"
---

# counter(3tcl)

Procedures for counters and histograms

```

```

## NAME

counter - Procedures for counters and histograms

## 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.

- **::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**.

  - **-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.

  - **-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.

  - **-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.

  - **-lastn** *N*

    Save the last *N* values of the counter to maintain a "running average" over the last *N* values.

  - **-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.

- **::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.

- **::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.

- **::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*.

- **::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.

  - **-totalVar**

    Return the name of the total variable.  Useful for specifying with -textvariable in a Tk widget.

  - **-N**

    Return the number of samples accumulated into the counter.

  - **-avg**

    Return the average of samples accumulated into the counter.

  - **-avgn**

    Return the average over the last *N* samples taken.  The *N* value is set in the **::counter::init** call.

  - **-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.

  - **-histVar**

    Return the name of the histogram array variable.

  - **-histHour**

    Return the complete hourly histogram in array get format sorted by bucket.

  - **-histHourVar**

    Return the name of the hourly histogram array variable.

  - **-histDay**

    Return the complete daily histogram in array get format sorted by bucket.

  - **-histDayVar**

    Return the name of the daily histogram array variable.

  - **-resetDate**

    Return the clock seconds value recorded when the counter was last reset.

  - **-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.

- **::counter::exists** *tag*

  Returns 1 if the counter is defined.

- **::counter::names**

  Returns a list of all counters defined.

- **::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

  - **-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. They have the same meaning as described for **::counter::init**.

## 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.

## KEYWORDS

counting, histogram, statistics, tallying

## CATEGORY

Data structures