/*
 * AverageOverTime.cs
 * 
 * Copyright © 2009
 * Diversified Technical Systems, Inc.
 * All Rights Reserved
 */

using System.Collections.Generic;

namespace DTS.Common.Utilities
{
    /// <summary>
    /// A class to represent the average value of a dynamically specified set over time.  This
    /// class is intended to be used to keep a running average of sets of piecemeal-collected
    /// data, and it is assumed that a subclass will implement the type-specific features of
    /// this task.
    /// </summary>
    /// 
    /// <typeparam name="T">
    /// The type we're talking the average value over time of.
    /// </typeparam>
    /// 
    public abstract class AverageValueOverTime<T> : Exceptional
    {
        /// <summary>
        /// Initialize an instance of the AverageValueOverTime class, assuming that no
        /// averaging has been done yet.
        /// </summary>
        /// 
        /// <param name="initialTime">
        /// The <see cref="double"/> begin time of the average (using the time units specified
        /// by the "TimeUnitSymbol" property.
        /// </param>
        /// 
        /// <param name="sampleRate">
        /// The <see cref="double"/> sample rate of the items being averaged (using the time units
        /// specifed by the "TimeUnitSymbol" property.
        /// </param>
        /// 
        /// <param name="initialAverage">
        /// The "zero" value of our generic data type.
        /// </param>
        /// 
        /// <param name="timeUnitSymbol">
        /// The <see cref="string"/> time unit description for begin/end times and the sample rate.
        /// </param>
        /// 
        protected AverageValueOverTime(double initialTime,
                                     double sampleRate,
                                     T initialAverage,
                                     string timeUnitSymbol)
            : this(initialTime,
                    initialTime,
                    sampleRate,
                    initialAverage,
                    timeUnitSymbol)
        {
        }

        /// <summary>
        /// Initialize an instance of the AverageValueOverTime class.
        /// </summary>
        /// 
        /// <param name="beginTime">
        /// The <see cref="double"/> begin time of the average (using the time units specified
        /// by the "TimeUnitSymbol" property.
        /// </param>
        /// 
        /// <param name="endTime">
        /// The <see cref="double"/> end time of the average (using the time units specified
        /// by the "TimeUnitSymbol" property.
        /// </param>
        /// 
        /// <param name="sampleRate">
        /// The <see cref="double"/> sample rate of the items being averaged (using the time units
        /// specifed by the "TimeUnitSymbol" property.
        /// </param>
        /// 
        /// <param name="initialAverage">
        /// The initial average value to be appended to.
        /// </param>
        /// 
        /// <param name="timeUnitSymbol">
        /// The <see cref="string"/> time unit description for begin/end times and the sample rate.
        /// </param>
        /// 
        protected AverageValueOverTime(double beginTime,
                                     double endTime,
                                     double sampleRate,
                                     T initialAverage,
                                     string timeUnitSymbol)
        {
            try
            {   //
                // Initialize the known knowns.
                //
                BeginTime = beginTime;
                EndTime = endTime;
                SampleRate = sampleRate;
                TimeUnitSymbol = timeUnitSymbol;
                CurrentAverage = initialAverage;
            }

            catch (System.Exception ex)
            {
                throw new Exception("encountered problem constructing " + GetType().FullName, ex);
            }
        }

        //
        // These properties should be useful no matter what we're taking
        // the running average of.
        //
        /// <summary>
        /// Beginning Time
        /// </summary>
        public double BeginTime { get; protected set; }
        /// <summary>
        /// Ending Time
        /// </summary>
        public double EndTime { get; protected set; }
        /// <summary>
        /// The sampling rate
        /// </summary>
        public double SampleRate { get; protected set; }
        /// <summary>
        /// the time unit symbol
        /// </summary>
        public string TimeUnitSymbol { get; protected set; }
        /// <summary>
        /// the current average
        /// </summary>
        public T CurrentAverage { get; protected set; }


        /// <summary>
        /// appends a list of values
        /// </summary>
        /// <param name="values">list of values</param>
        /// <remarks>inheriting clases should know more about the nature of the data type
        /// and averaging them over time.
        /// </remarks>
        public abstract void AppendValues(List<T> values);
        /// <summary>
        /// appends an array of values
        /// </summary>
        /// <param name="values">array of values</param>
        /// <remarks>inheriting clases should know more about the nature of the data type
        /// and averaging them over time.
        /// </remarks>
        public abstract void AppendValues(T[] values);
    }
}