SampleAndHold.h

// DSPark - Professional Audio DSP Framework
// Copyright (c) 2026 Cristian Moresi - MIT License
 
#pragma once
 
#include "DspMath.h"
 
#include <algorithm>
#include <cmath>
#include <limits>
 
namespace dspark {
 
template <FloatType T>
class SampleAndHold
{
public:
    enum class Mode
    {
        Counter, 
        Trigger  
    };
 
    void setMode(Mode mode) noexcept { mode_ = mode; }
 
    void setHoldSamples(int numSamples) noexcept
    {
        setHoldPeriod(static_cast<double>(numSamples));
    }
 
    void setHoldPeriod(double samples) noexcept
    {
        constexpr double maxPeriod = static_cast<double>(std::numeric_limits<int>::max());
        holdPeriod_ = (samples >= 1.0) ? std::min(samples, maxPeriod) : 1.0; // NaN -> 1
        // An integer period drops any sub-sample offset left by a fractional
        // one, so it captures on the sample grid (period 1 is transparent).
        if (holdPeriod_ == std::floor(holdPeriod_))
            phase_ = std::floor(phase_);
    }
 
    [[nodiscard]] double getHoldPeriod() const noexcept { return holdPeriod_; }
 
    void setHoldRate(double targetRate, double actualRate) noexcept
    {
        if (!(targetRate > 0.0) || !(actualRate > 0.0))
        {
            setHoldPeriod(1.0);
            return;
        }
        setHoldPeriod(actualRate / targetRate);
    }
 
    [[nodiscard]] T process(T input, bool trigger = false) noexcept
    {
        if (mode_ == Mode::Counter)
            advanceCounter(input);
        else if (trigger) // Mode::Trigger
            heldValue_ = input;
        previous_ = input;
        return heldValue_;
    }
 
    void processBlock(T* data, int numSamples) noexcept
    {
        if (mode_ == Mode::Counter)
        {
            // Branch hoisted out of the hot loop
            for (int i = 0; i < numSamples; ++i)
            {
                const T input = data[i];
                advanceCounter(input);
                previous_ = input;
                data[i] = heldValue_;
            }
        }
        else if (numSamples > 0)
        {
            // In trigger mode with no triggers provided, it holds indefinitely.
            previous_ = data[numSamples - 1];
            for (int i = 0; i < numSamples; ++i)
            {
                data[i] = heldValue_;
            }
        }
    }
 
    void processBlock(T* data, const bool* triggers, int numSamples) noexcept
    {
        if (mode_ == Mode::Trigger && triggers != nullptr)
        {
            // Branch hoisted out of the hot loop
            for (int i = 0; i < numSamples; ++i)
            {
                if (triggers[i])
                {
                    heldValue_ = data[i];
                }
                previous_ = data[i];
                data[i] = heldValue_;
            }
        }
        else
        {
            processBlock(data, numSamples);
        }
    }
 
    [[nodiscard]] T getHeldValue() const noexcept { return heldValue_; }
 
    void reset(T initialValue = T(0)) noexcept
    {
        heldValue_ = initialValue;
        previous_ = initialValue;
        phase_ = 0.0; // Ensures initialValue is output before the next capture
    }
 
private:
    inline void advanceCounter(T input) noexcept
    {
        phase_ += 1.0;
        if (phase_ >= holdPeriod_)
        {
            phase_ -= holdPeriod_;
            // The period shrank below the time already elapsed: capture now.
            if (phase_ >= 1.0) phase_ = 0.0;
            heldValue_ = (phase_ > 0.0) ? input - static_cast<T>(phase_) * (input - previous_)
                                        : input;
        }
    }
 
    Mode mode_ = Mode::Counter;
    double holdPeriod_ = 1.0;
    double phase_ = 0.0;     
    T heldValue_ = T(0);
    T previous_ = T(0);      
};
 
} // namespace dspark