/*

 * Copyright (c) 2012, 2013, Oracle and/or its affiliates. All rights reserved.

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

 *

 * This code is free software; you can redistribute it and/or modify it

 * under the terms of the GNU General Public License version 2 only, as

 * published by the Free Software Foundation.  Oracle designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Oracle in the LICENSE file that accompanied this code.

 *

 * This code is distributed in the hope that it will be useful, but WITHOUT

 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

 * version 2 for more details (a copy is included in the LICENSE file that

 * accompanied this code).

 *

 * You should have received a copy of the GNU General Public License version

 * 2 along with this work; if not, write to the Free Software Foundation,

 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

 *

 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

 * or visit www.oracle.com if you need additional information or have any

 * questions.

 */

package java.util;

import java.util.function.DoubleConsumer;

import java.util.stream.Collector;

/**

 * A state object for collecting statistics such as count, min, max, sum, and

 * average.

 *

 * <p>This class is designed to work with (though does not require)

 * {@linkplain java.util.stream streams}. For example, you can compute

 * summary statistics on a stream of doubles with:

 * <pre> {@code

 * DoubleSummaryStatistics stats = doubleStream.collect(DoubleSummaryStatistics::new,

 *                                                      DoubleSummaryStatistics::accept,

 *                                                      DoubleSummaryStatistics::combine);

 * }</pre>

 *

 * <p>{@code DoubleSummaryStatistics} can be used as a

 * {@linkplain java.util.stream.Stream#collect(Collector) reduction}

 * target for a {@linkplain java.util.stream.Stream stream}. For example:

 *

 * <pre> {@code

 * DoubleSummaryStatistics stats = people.stream()

 *     .collect(Collectors.summarizingDouble(Person::getWeight));

 *}</pre>

 *

 * This computes, in a single pass, the count of people, as well as the minimum,

 * maximum, sum, and average of their weights.

 *

 * @implNote This implementation is not thread safe. However, it is safe to use

 * {@link java.util.stream.Collectors#summarizingDouble(java.util.function.ToDoubleFunction)

 * Collectors.toDoubleStatistics()} on a parallel stream, because the parallel

 * implementation of {@link java.util.stream.Stream#collect Stream.collect()}

 * provides the necessary partitioning, isolation, and merging of results for

 * safe and efficient parallel execution.

 * @since 1.8

 */

public class DoubleSummaryStatistics implements DoubleConsumer {

    private long count;

    private double sum;

    private double min = Double.POSITIVE_INFINITY;

    private double max = Double.NEGATIVE_INFINITY;

    /**

     * Construct an empty instance with zero count, zero sum,

     * {@code Double.POSITIVE_INFINITY} min, {@code Double.NEGATIVE_INFINITY}

     * max and zero average.

     */

    public DoubleSummaryStatistics() { }

    /**

     * Records another value into the summary information.

     *

     * @param value the input value

     */

    @Override

    public void accept(double value) {

        ++count;

        sum += value;

        min = Math.min(min, value);

        max = Math.max(max, value);

    }

    /**

     * Combines the state of another {@code DoubleSummaryStatistics} into this

     * one.

     *

     * @param other another {@code DoubleSummaryStatistics}

     * @throws NullPointerException if {@code other} is null

     */

    public void combine(DoubleSummaryStatistics other) {

        count += other.count;

        sum += other.sum;

        min = Math.min(min, other.min);

        max = Math.max(max, other.max);

    }

    /**

     * Return the count of values recorded.

     *

     * @return the count of values

     */

    public final long getCount() {

        return count;

    }

    /**

     * Returns the sum of values recorded, or zero if no values have been

     * recorded. The sum returned can vary depending upon the order in which

     * values are recorded. This is due to accumulated rounding error in

     * addition of values of differing magnitudes. Values sorted by increasing

     * absolute magnitude tend to yield more accurate results.  If any recorded

     * value is a {@code NaN} or the sum is at any point a {@code NaN} then the

     * sum will be {@code NaN}.

     *

     * @return the sum of values, or zero if none

     */

    public final double getSum() {

        return sum;

    }

    /**

     * Returns the minimum recorded value, {@code Double.NaN} if any recorded

     * value was NaN or {@code Double.POSITIVE_INFINITY} if no values were

     * recorded. Unlike the numerical comparison operators, this method

     * considers negative zero to be strictly smaller than positive zero.

     *

     * @return the minimum recorded value, {@code Double.NaN} if any recorded

     * value was NaN or {@code Double.POSITIVE_INFINITY} if no values were

     * recorded

     */

    public final double getMin() {

        return min;

    }

    /**

     * Returns the maximum recorded value, {@code Double.NaN} if any recorded

     * value was NaN or {@code Double.NEGATIVE_INFINITY} if no values were

     * recorded. Unlike the numerical comparison operators, this method

     * considers negative zero to be strictly smaller than positive zero.

     *

     * @return the maximum recorded value, {@code Double.NaN} if any recorded

     * value was NaN or {@code Double.NEGATIVE_INFINITY} if no values were

     * recorded

     */

    public final double getMax() {

        return max;

    }

    /**

     * Returns the arithmetic mean of values recorded, or zero if no values have been

     * recorded. The average returned can vary depending upon the order in

     * which values are recorded. This is due to accumulated rounding error in

     * addition of values of differing magnitudes. Values sorted by increasing

     * absolute magnitude tend to yield more accurate results. If any recorded

     * value is a {@code NaN} or the sum is at any point a {@code NaN} then the

     * average will be {@code NaN}.

     *

     * @return the arithmetic mean of values, or zero if none

     */

    public final double getAverage() {

        return getCount() > 0 ? getSum() / getCount() : 0.0d;

    }

    /**

     * {@inheritDoc}

     *

     * Returns a non-empty string representation of this object suitable for

     * debugging. The exact presentation format is unspecified and may vary

     * between implementations and versions.

     */

    @Override

    public String toString() {

        return String.format(

            "%s{count=%d, sum=%f, min=%f, average=%f, max=%f}",

            this.getClass().getSimpleName(),

            getCount(),

            getSum(),

            getMin(),

            getAverage(),

            getMax());

    }

}