dspx 0.1.1-alpha.0

package/src/native/utils/SlidingWindowFilter.cc

@@ -0,0 +1,239 @@
+#include "SlidingWindowFilter.h"
+#include "../core/Policies.h"
+
+using namespace dsp::utils;
+
+// -----------------------------------------------------------------------------
+// Constructor
+// Constructs a new sliding window filter with the specified window size
+// @ param window_size - The number of samples in the sliding window
+// @ param policy - An instance of the policy (default-constructed if not provided)
+// @ return void
+// -----------------------------------------------------------------------------
+template <typename T, typename Policy>
+SlidingWindowFilter<T, Policy>::SlidingWindowFilter(size_t window_size, Policy policy)
+    : m_buffer(window_size), m_policy(std::move(policy))
+{
+}
+
+// -----------------------------------------------------------------------------
+// Constructor (Time-Aware)
+// Constructs a new time-aware sliding window filter
+// @ param window_size - The number of samples in the sliding window
+// @ param window_duration_ms - The maximum age of samples in milliseconds
+// @ param policy - An instance of the policy (default-constructed if not provided)
+// @ return void
+// -----------------------------------------------------------------------------
+template <typename T, typename Policy>
+SlidingWindowFilter<T, Policy>::SlidingWindowFilter(size_t window_size, double window_duration_ms, Policy policy)
+    : m_buffer(window_size, window_duration_ms), m_policy(std::move(policy))
+{
+}
+
+// -----------------------------------------------------------------------------
+// addSample
+// Adds a new sample to the sliding window
+// If buffer is full, removes oldest sample (delegates to policy.onRemove)
+// Then adds new sample (delegates to policy.onAdd)
+// @ param newValue - The new sample to add
+// @ return T - The computed result from the policy
+// -----------------------------------------------------------------------------
+template <typename T, typename Policy>
+T SlidingWindowFilter<T, Policy>::addSample(T newValue)
+{
+    if (m_buffer.isFull())
+    {
+        T oldestValue = m_buffer.peek();
+        m_policy.onRemove(oldestValue);
+    }
+
+    m_buffer.pushOverwrite(newValue);
+    m_policy.onAdd(newValue);
+
+    return m_policy.getResult(m_buffer.getCount());
+}
+
+// -----------------------------------------------------------------------------
+// addSampleWithTimestamp
+// Adds a new sample with timestamp (time-aware mode)
+// Expires old samples first, then adds the new sample
+// @ param newValue - The new sample to add
+// @ param timestamp - The timestamp in milliseconds
+// @ return T - The computed result from the policy
+// -----------------------------------------------------------------------------
+template <typename T, typename Policy>
+T SlidingWindowFilter<T, Policy>::addSampleWithTimestamp(T newValue, double timestamp)
+{
+    if (!m_buffer.isTimeAware())
+    {
+        throw std::runtime_error("addSampleWithTimestamp requires time-aware mode");
+    }
+
+    // First, expire old samples and update policy
+    while (m_buffer.getCount() > 0)
+    {
+        size_t initial_count = m_buffer.getCount();
+        m_buffer.expireOld(timestamp);
+        size_t expired_count = initial_count - m_buffer.getCount();
+
+        // We need to reconstruct the policy state from remaining samples
+        // This is inefficient but correct. Better approach: track what was removed
+        if (expired_count > 0)
+        {
+            // Rebuild policy from scratch using remaining samples
+            m_policy.clear();
+            auto remaining = m_buffer.toVector();
+            for (const auto &value : remaining)
+            {
+                m_policy.onAdd(value);
+            }
+        }
+        break; // expireOld already removed all expired samples
+    }
+
+    // Check if buffer is full (by sample count)
+    if (m_buffer.isFull())
+    {
+        T oldestValue = m_buffer.peek();
+        m_policy.onRemove(oldestValue);
+    }
+
+    // Add the new sample
+    m_buffer.pushOverwriteWithTimestamp(newValue, timestamp);
+    m_policy.onAdd(newValue);
+
+    return m_policy.getResult(m_buffer.getCount());
+}
+
+// -----------------------------------------------------------------------------
+// clear
+// Clears all samples from the filter
+// Resets both the circular buffer and the policy state
+// @ return void
+// -----------------------------------------------------------------------------
+template <typename T, typename Policy>
+void SlidingWindowFilter<T, Policy>::clear()
+{
+    m_buffer.clear();
+    m_policy.clear();
+}
+
+// -----------------------------------------------------------------------------
+// isFull
+// Checks if the buffer is full
+// @ return bool - true if buffer contains window_size samples
+// -----------------------------------------------------------------------------
+template <typename T, typename Policy>
+bool SlidingWindowFilter<T, Policy>::isFull() const noexcept
+{
+    return m_buffer.isFull();
+}
+
+// -----------------------------------------------------------------------------
+// getCount
+// Gets the current number of samples in the buffer
+// @ return size_t - The number of samples
+// -----------------------------------------------------------------------------
+template <typename T, typename Policy>
+size_t SlidingWindowFilter<T, Policy>::getCount() const noexcept
+{
+    return m_buffer.getCount();
+}
+
+// -----------------------------------------------------------------------------
+// getWindowSize
+// Gets the window size
+// @ return size_t - The maximum number of samples in the window
+// -----------------------------------------------------------------------------
+template <typename T, typename Policy>
+size_t SlidingWindowFilter<T, Policy>::getWindowSize() const noexcept
+{
+    return m_buffer.getCapacity();
+}
+
+// -----------------------------------------------------------------------------
+// getBufferContents
+// Exports the buffer contents
+// @ return std::vector<T> - A vector containing all samples in the buffer
+// -----------------------------------------------------------------------------
+template <typename T, typename Policy>
+std::vector<T> SlidingWindowFilter<T, Policy>::getBufferContents() const
+{
+    return m_buffer.toVector();
+}
+
+// -----------------------------------------------------------------------------
+// setBufferContents
+// Restores the buffer contents
+// @ param bufferData - The samples to restore to the buffer
+// @ return void
+// -----------------------------------------------------------------------------
+template <typename T, typename Policy>
+void SlidingWindowFilter<T, Policy>::setBufferContents(const std::vector<T> &bufferData)
+{
+    m_buffer.fromVector(bufferData);
+}
+
+// -----------------------------------------------------------------------------
+// getPolicy
+// Access to the policy for state serialization
+// @ return Policy& - Reference to the internal policy object
+// -----------------------------------------------------------------------------
+template <typename T, typename Policy>
+Policy &SlidingWindowFilter<T, Policy>::getPolicy()
+{
+    return m_policy;
+}
+
+// -----------------------------------------------------------------------------
+// getPolicy (const)
+// Const access to the policy
+// @ return const Policy& - Const reference to the internal policy object
+// -----------------------------------------------------------------------------
+template <typename T, typename Policy>
+const Policy &SlidingWindowFilter<T, Policy>::getPolicy() const
+{
+    return m_policy;
+}
+
+// Note: getState() and setState() are template methods defined in the header
+// They use decltype and are auto-deduced, so they must remain in the header
+
+// -----------------------------------------------------------------------------
+// Explicit template instantiations
+// Instantiate all Policy combinations we use
+// -----------------------------------------------------------------------------
+namespace dsp::utils
+{
+    using namespace dsp::core;
+
+    // MeanPolicy instantiations
+    template class SlidingWindowFilter<int, MeanPolicy<int>>;
+    template class SlidingWindowFilter<float, MeanPolicy<float>>;
+    template class SlidingWindowFilter<double, MeanPolicy<double>>;
+
+    // RmsPolicy instantiations
+    template class SlidingWindowFilter<int, RmsPolicy<int>>;
+    template class SlidingWindowFilter<float, RmsPolicy<float>>;
+    template class SlidingWindowFilter<double, RmsPolicy<double>>;
+
+    // MeanAbsoluteValuePolicy instantiations
+    template class SlidingWindowFilter<float, MeanAbsoluteValuePolicy<float>>;
+    template class SlidingWindowFilter<double, MeanAbsoluteValuePolicy<double>>;
+
+    // VariancePolicy instantiations
+    template class SlidingWindowFilter<int, VariancePolicy<int>>;
+    template class SlidingWindowFilter<float, VariancePolicy<float>>;
+    template class SlidingWindowFilter<double, VariancePolicy<double>>;
+
+    // Note: ZScorePolicy is NOT instantiated here because it has a different interface
+    // (getResult takes 2 parameters: currentValue and count, not just count)
+    // MovingZScoreFilter doesn't use SlidingWindowFilter template
+
+    // WaveformLengthFilter instantiations
+    template class dsp::utils::SlidingWindowFilter<float, SumPolicy<float>>;
+    template class dsp::utils::SlidingWindowFilter<double, SumPolicy<double>>;
+
+    // WAMP,SSC instantiations
+    template class dsp::utils::SlidingWindowFilter<bool, CounterPolicy>;
+}

package/src/native/utils/SlidingWindowFilter.h

@@ -0,0 +1,159 @@
+#pragma once
+#include "CircularBufferArray.h"
+#include <utility>
+#include <vector>
+
+namespace dsp::utils
+{
+    /**
+     * @brief A generic, policy-based sliding window filter engine.
+     *
+     * This class implements the sliding window logic (circular buffer management)
+     * while delegating the statistical computation to a Policy class.
+     *
+     * This is a zero-cost abstraction: the compiler inlines all policy methods,
+     * resulting in performance identical to hand-written specialized filters.
+     *
+     * @tparam T The numeric type (e.g., float, double).
+     * @tparam Policy The struct that defines the state and math operations.
+     *               Must implement: onAdd(T), onRemove(T), clear(), getResult(size_t)
+     */
+    template <typename T, typename Policy>
+    class SlidingWindowFilter
+    {
+    public:
+        /**
+         * @brief Constructs a new sliding window filter.
+         * @param window_size The number of samples in the sliding window.
+         * @param policy An instance of the policy (default-constructed if not provided).
+         */
+        explicit SlidingWindowFilter(size_t window_size, Policy policy = Policy());
+
+        /**
+         * @brief Constructs a new time-aware sliding window filter.
+         * @param window_size The number of samples in the sliding window.
+         * @param window_duration_ms The maximum age of samples in milliseconds.
+         * @param policy An instance of the policy (default-constructed if not provided).
+         */
+        explicit SlidingWindowFilter(size_t window_size, double window_duration_ms, Policy policy = Policy());
+
+        // Delete copy constructor and copy assignment
+        SlidingWindowFilter(const SlidingWindowFilter &) = delete;
+        SlidingWindowFilter &operator=(const SlidingWindowFilter &) = delete;
+
+        // Enable move semantics
+        SlidingWindowFilter(SlidingWindowFilter &&) noexcept = default;
+        SlidingWindowFilter &operator=(SlidingWindowFilter &&) noexcept = default;
+
+        /**
+         * @brief Adds a new sample to the sliding window.
+         *
+         * If the buffer is full, removes the oldest sample (delegates to policy.onRemove),
+         * then adds the new sample (delegates to policy.onAdd).
+         *
+         * @param newValue The new sample to add.
+         * @return T The computed result from the policy.
+         */
+        T addSample(T newValue);
+
+        /**
+         * @brief Adds a new sample with timestamp (time-aware mode).
+         *
+         * Expires old samples first, then adds the new sample.
+         *
+         * @param newValue The new sample to add.
+         * @param timestamp The timestamp in milliseconds.
+         * @return T The computed result from the policy.
+         */
+        T addSampleWithTimestamp(T newValue, double timestamp);
+
+        /**
+         * @brief Clears all samples from the filter.
+         *
+         * Resets both the circular buffer and the policy state.
+         */
+        void clear();
+
+        /**
+         * @brief Checks if the buffer is full.
+         * @return true if the buffer contains window_size samples.
+         */
+        bool isFull() const noexcept;
+
+        /**
+         * @brief Gets the current number of samples in the buffer.
+         * @return size_t The number of samples.
+         */
+        size_t getCount() const noexcept;
+
+        /**
+         * @brief Gets the window size.
+         * @return size_t The maximum number of samples in the window.
+         */
+        size_t getWindowSize() const noexcept;
+
+        /**
+         * @brief Checks if this is a time-aware filter.
+         * @return bool True if window duration is set.
+         */
+        bool isTimeAware() const noexcept { return m_buffer.isTimeAware(); }
+
+        /**
+         * @brief Exports the buffer contents.
+         * @return std::vector<T> A vector containing all samples in the buffer.
+         */
+        std::vector<T> getBufferContents() const;
+
+        /**
+         * @brief Restores the buffer contents.
+         * @param bufferData The samples to restore to the buffer.
+         */
+        void setBufferContents(const std::vector<T> &bufferData);
+
+        /**
+         * @brief Access to the policy for state serialization.
+         * @return Policy& Reference to the internal policy object.
+         */
+        Policy &getPolicy();
+
+        /**
+         * @brief Const access to the policy.
+         * @return const Policy& Const reference to the internal policy object.
+         */
+        const Policy &getPolicy() const;
+
+        /**
+         * @brief Exports the complete filter state (buffer + policy state).
+         *
+         * This is a generic state serialization method that works with any policy
+         * that implements getState(). Returns a pair of buffer contents and policy state.
+         *
+         * @return std::pair<std::vector<T>, PolicyState> Buffer contents and policy state.
+         */
+        auto getState() const -> std::pair<std::vector<T>, decltype(std::declval<Policy>().getState())>
+        {
+            return {m_buffer.toVector(), m_policy.getState()};
+        }
+
+        /**
+         * @brief Restores the complete filter state (buffer + policy state).
+         *
+         * This is a generic state deserialization method that works with any policy
+         * that implements setState(). Restores both buffer contents and policy state.
+         *
+         * @param bufferData The buffer contents to restore.
+         * @param policyState The policy state to restore (type depends on policy).
+         */
+        template <typename PolicyState>
+        void setState(const std::vector<T> &bufferData, const PolicyState &policyState)
+        {
+            m_buffer.fromVector(bufferData);
+            m_policy.setState(policyState);
+        }
+
+    private:
+        CircularBufferArray<T> m_buffer;
+        Policy m_policy;
+    };
+
+} // namespace dsp::utils

package/src/native/utils/TimeSeriesBuffer.cc

@@ -0,0 +1,205 @@
+#include "TimeSeriesBuffer.h"
+
+namespace dsp::utils
+{
+    // -----------------------------------------------------------------------------
+    // Constructor
+    // -----------------------------------------------------------------------------
+    template <typename T>
+    TimeSeriesBuffer<T>::TimeSeriesBuffer(size_t max_samples, uint64_t window_duration_ms)
+        : m_max_samples(max_samples), m_window_duration_ms(window_duration_ms)
+    {
+    }
+
+    // -----------------------------------------------------------------------------
+    // push - Adds a new timestamped sample
+    // Automatically enforces window constraints after insertion
+    // -----------------------------------------------------------------------------
+    template <typename T>
+    void TimeSeriesBuffer<T>::push(TimestampType timestamp, T value)
+    {
+        m_samples.emplace_back(timestamp, value);
+        enforceWindowConstraints();
+    }
+
+    // -----------------------------------------------------------------------------
+    // removeOlderThan - Removes samples older than cutoff timestamp
+    // -----------------------------------------------------------------------------
+    template <typename T>
+    size_t TimeSeriesBuffer<T>::removeOlderThan(TimestampType cutoff_timestamp)
+    {
+        size_t removed = 0;
+        while (!m_samples.empty() && m_samples.front().first < cutoff_timestamp)
+        {
+            m_samples.pop_front();
+            ++removed;
+        }
+        return removed;
+    }
+
+    // -----------------------------------------------------------------------------
+    // front - Gets the oldest sample (does not remove)
+    // -----------------------------------------------------------------------------
+    template <typename T>
+    const typename TimeSeriesBuffer<T>::Sample &TimeSeriesBuffer<T>::front() const
+    {
+        if (m_samples.empty())
+        {
+            throw std::out_of_range("TimeSeriesBuffer::front() called on empty buffer");
+        }
+        return m_samples.front();
+    }
+
+    // -----------------------------------------------------------------------------
+    // back - Gets the newest sample (does not remove)
+    // -----------------------------------------------------------------------------
+    template <typename T>
+    const typename TimeSeriesBuffer<T>::Sample &TimeSeriesBuffer<T>::back() const
+    {
+        if (m_samples.empty())
+        {
+            throw std::out_of_range("TimeSeriesBuffer::back() called on empty buffer");
+        }
+        return m_samples.back();
+    }
+
+    // -----------------------------------------------------------------------------
+    // popFront - Removes the oldest sample
+    // -----------------------------------------------------------------------------
+    template <typename T>
+    void TimeSeriesBuffer<T>::popFront()
+    {
+        if (m_samples.empty())
+        {
+            throw std::out_of_range("TimeSeriesBuffer::popFront() called on empty buffer");
+        }
+        m_samples.pop_front();
+    }
+
+    // -----------------------------------------------------------------------------
+    // size - Returns the current number of samples
+    // -----------------------------------------------------------------------------
+    template <typename T>
+    size_t TimeSeriesBuffer<T>::size() const noexcept
+    {
+        return m_samples.size();
+    }
+
+    // -----------------------------------------------------------------------------
+    // empty - Checks if buffer is empty
+    // -----------------------------------------------------------------------------
+    template <typename T>
+    bool TimeSeriesBuffer<T>::empty() const noexcept
+    {
+        return m_samples.empty();
+    }
+
+    // -----------------------------------------------------------------------------
+    // clear - Removes all samples
+    // -----------------------------------------------------------------------------
+    template <typename T>
+    void TimeSeriesBuffer<T>::clear() noexcept
+    {
+        m_samples.clear();
+    }
+
+    // -----------------------------------------------------------------------------
+    // toVector - Exports all samples as a vector
+    // -----------------------------------------------------------------------------
+    template <typename T>
+    std::vector<typename TimeSeriesBuffer<T>::Sample> TimeSeriesBuffer<T>::toVector() const
+    {
+        return std::vector<Sample>(m_samples.begin(), m_samples.end());
+    }
+
+    // -----------------------------------------------------------------------------
+    // fromVector - Restores buffer from vector
+    // -----------------------------------------------------------------------------
+    template <typename T>
+    void TimeSeriesBuffer<T>::fromVector(const std::vector<Sample> &samples)
+    {
+        m_samples.clear();
+        for (const auto &sample : samples)
+        {
+            m_samples.push_back(sample);
+        }
+    }
+
+    // -----------------------------------------------------------------------------
+    // getTimeSpan - Returns time difference between newest and oldest sample
+    // -----------------------------------------------------------------------------
+    template <typename T>
+    uint64_t TimeSeriesBuffer<T>::getTimeSpan() const noexcept
+    {
+        if (m_samples.size() < 2)
+        {
+            return 0;
+        }
+        return m_samples.back().first - m_samples.front().first;
+    }
+
+    // -----------------------------------------------------------------------------
+    // begin/end - Iterator access
+    // -----------------------------------------------------------------------------
+    template <typename T>
+    typename std::deque<typename TimeSeriesBuffer<T>::Sample>::const_iterator
+    TimeSeriesBuffer<T>::begin() const noexcept
+    {
+        return m_samples.begin();
+    }
+
+    template <typename T>
+    typename std::deque<typename TimeSeriesBuffer<T>::Sample>::const_iterator
+    TimeSeriesBuffer<T>::end() const noexcept
+    {
+        return m_samples.end();
+    }
+
+    // -----------------------------------------------------------------------------
+    // getMaxSamples - Returns the max sample count constraint
+    // -----------------------------------------------------------------------------
+    template <typename T>
+    size_t TimeSeriesBuffer<T>::getMaxSamples() const noexcept
+    {
+        return m_max_samples;
+    }
+
+    // -----------------------------------------------------------------------------
+    // getWindowDuration - Returns the time window constraint
+    // -----------------------------------------------------------------------------
+    template <typename T>
+    uint64_t TimeSeriesBuffer<T>::getWindowDuration() const noexcept
+    {
+        return m_window_duration_ms;
+    }
+
+    // -----------------------------------------------------------------------------
+    // enforceWindowConstraints - Private helper to maintain window limits
+    // Called automatically after each push()
+    // -----------------------------------------------------------------------------
+    template <typename T>
+    void TimeSeriesBuffer<T>::enforceWindowConstraints()
+    {
+        // Enforce time-based window (if enabled)
+        if (m_window_duration_ms > 0 && m_samples.size() > 1)
+        {
+            TimestampType newest_timestamp = m_samples.back().first;
+            TimestampType cutoff = newest_timestamp - m_window_duration_ms;
+            removeOlderThan(cutoff);
+        }
+
+        // Enforce sample-count window (if enabled)
+        while (m_max_samples > 0 && m_samples.size() > m_max_samples)
+        {
+            m_samples.pop_front();
+        }
+    }
+
+    // -----------------------------------------------------------------------------
+    // Explicit template instantiations
+    // -----------------------------------------------------------------------------
+    template class TimeSeriesBuffer<int>;
+    template class TimeSeriesBuffer<float>;
+    template class TimeSeriesBuffer<double>;
+
+} // namespace dsp::utils