MovingSum<T> Class

Definition

Namespace

Bodu.Numerics

Assembly

Bodu.Numerics.dll

Package

Bodu.Numerics 1.0.0

Source

MovingSum{T}.cs

Maintains the sum and mean of the most recent N samples of a stream, updating in amortized O(1) as each new sample displaces the oldest.

public sealed class MovingSum<T> where T : INumber<T>

Type Parameters

T

The numeric type of the samples.

Inheritance

object

MovingSum<T>

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

Extension Methods

ComparableExtensions.AtLeast<T>(T, T, IComparer<T>)

ComparableExtensions.AtMost<T>(T, T, IComparer<T>)

ComparableExtensions.IsEqualTo<T>(T, T, IComparer<T>)

ComparableExtensions.Max<T>(T, T, IComparer<T>)

ComparableExtensions.Min<T>(T, T, IComparer<T>)

Examples

var window = new MovingSum<double>(3);
window.Add(1.0);   // window: {1}          Sum = 1
window.Add(2.0);   // window: {1, 2}       Sum = 3
window.Add(3.0);   // window: {1, 2, 3}    Sum = 6
window.Add(4.0);   // window: {2, 3, 4}    Sum = 9, Mean = 3

Remarks

This is the finance / telemetry "rolling window" idiom: the window holds the last Capacity samples, Sum and Mean always describe exactly those samples, and until the window fills (IsFull) they describe the samples received so far. Samples are accepted as T and the sum is maintained in T - exact for integer, decimal, and BigInteger samples - while Mean is a derived result computed and returned as a finite double. The rolling-sum arithmetic is checked: a fixed-width integer sum that would overflow throws OverflowException from Add(T) rather than silently wrapping, and the window state is left unchanged when that happens. Floating-point sums cannot overflow (they saturate per IEEE 754); a sum that has saturated to infinity surfaces as OverflowException when Mean is read.

For floating-point samples the subtract-on-evict update accumulates rounding drift, so the sum is transparently recomputed from the buffered window after every full window turnover, bounding the drift to one window's worth of rounding. Samples must be finite: NaN and infinite values are rejected by Add(T). For min/max over the same window, pair this type with MovingMinMax<T>; for whole-stream moments use RunningStatistics<T>.

Constructors

MovingSum(int)

Initializes a new instance of the MovingSum<T> class with the given window size.

public MovingSum(int capacity)

Parameters

capacity int

The number of most-recent samples the window covers.

Exceptions

ArgumentOutOfRangeException

capacity ≤ 0.

Properties

Capacity

Gets the number of most-recent samples the window covers once full.

public int Capacity { get; }

Property Value

int

The fixed window size supplied at construction.

Count

Gets the number of samples currently in the window.

public int Count { get; }

Property Value

int

The sample count, at most Capacity.

IsEmpty

Gets a value indicating whether the window contains no samples.

public bool IsEmpty { get; }

Property Value

bool

true when Count is zero; otherwise false.

IsFull

Gets a value indicating whether the window has filled to Capacity and every new sample now evicts the oldest.

public bool IsFull { get; }

Property Value

bool

true when Count equals Capacity.

Mean

Gets the arithmetic mean of the samples currently in the window.

public double Mean { get; }

Property Value

double

The window mean, computed in double.

Exceptions

InvalidOperationException

The window is empty.

OverflowException

The window sum is outside the range representable by double (possible for unbounded integer sample types such as BigInteger, or a floating-point sum that has saturated to infinity).

Sum

Gets the sum of the samples currently in the window.

public T Sum { get; }

Property Value

T

The window sum in T; T.Zero when the window is empty.

Methods

Add(T)

Adds a sample to the window, evicting the oldest sample once the window is full.

public void Add(T value)

Parameters

value T

The sample to add. Must be finite.

Exceptions

ArgumentException

value is NaN or infinite.

OverflowException

The updated rolling sum overflows T (fixed-width integer sample types; the arithmetic is checked). The window state is unchanged when this is thrown. The subtract-then-add update can, in rare magnitude combinations, overflow transiently even when the final sum would fit.

Reset()

Resets the window to the empty state, discarding every buffered sample.

public void Reset()

ToString()

Returns a culture-invariant summary of the window state for diagnostics.

public override string ToString()

Returns

string

A string such as "Capacity = 3, Count = 2, Sum = 7".

Applies to

Product	Versions
.NET	8, 10