org.djutils.stats.summarizers.Counter Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of djutils-stats Show documentation
DJUTILS statistical and data storage utilities
The newest version!
package org.djutils.stats.summarizers;

import org.djutils.exceptions.Throw;

/**
 * The Counter class defines a statistics event counter.
 * 
 * Copyright (c) 2002-2024 Delft University of Technology, Jaffalaan 5, 2628 BX Delft, the Netherlands. All rights reserved. See
 * for project information  https://simulation.tudelft.nl. The DSOL
 * project is distributed under a three-clause BSD-style license, which can be found at
 * 
 * https://simulation.tudelft.nl/dsol/3.0/license.html. 

 * @author  Alexander Verbraeck
 * @author Peter Jacobs 
 */
public class Counter implements Statistic
{
    /** */
    private static final long serialVersionUID = 20200228L;

    /** count represents the value of the counter. */
    private long count = 0;

    /** n represents the number of measurements. */
    private long n = 0;

    /** description refers to the title of this counter. */
    private String description;

    /** the semaphore. */
    private Object semaphore = new Object();

    /**
     * Constructs a new Counter.
     * @param description String; the description for this counter
     */
    public Counter(final String description)
    {
        Throw.whenNull(description, "description cannot be null");
        this.description = description;
        initialize();
    }

    /**
     * Returns the current counter value.
     * @return long; the counter value
     */
    public long getCount()
    {
        return this.count;
    }

    /** {@inheritDoc} */
    @Override
    public long getN()
    {
        return this.n;
    }

    /**
     * Process one observed value.
     * @param value long; the value to process
     * @return long; the value
     */
    public long register(final long value)
    {
        synchronized (this.semaphore)
        {
            this.count += value;
            this.n++;
        }
        return value;
    }

    /**
     * Initialize the counter.
     */
    @Override
    public void initialize()
    {
        synchronized (this.semaphore)
        {
            this.n = 0;
            this.count = 0;
        }
    }

    /** {@inheritDoc} */
    @Override
    public String getDescription()
    {
        return this.description;
    }

    /**
     * Return a string representing a header for a textual table with a monospaced font that can contain multiple statistics.
     * @return String; header for the textual table.
     */
    public static String reportHeader()
    {
        return "-".repeat(72) + String.format("%n| %-48.48s | %6.6s | %8.8s |%n", "Counter name", "n", "count")
                + "-".repeat(72);
    }

    /** {@inheritDoc} */
    @Override
    public String reportLine()
    {
        return String.format("| %-48.48s | %6d | %8d |", getDescription(), getN(), getCount());
    }

    /**
     * Return a string representing a footer for a textual table with a monospaced font that can contain multiple statistics.
     * @return String; footer for the textual table
     */
    public static String reportFooter()
    {
        return "-".repeat(72);
    }

    /** {@inheritDoc} */
    @Override
    public String toString()
    {
        return "Counter [description=" + this.description + ", n=" + this.n + ", count=" + this.count + "]";
    }
    
}