philiprehberger-ring_buffer 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8d3a987697f096aa8b9d085eeb0a4bcd6f83a5af1a0c2afcae477a6e789bbcdf
-  data.tar.gz: 66b3843e018fbb2f2e02d72d6b727e7cae71a64c299ac7e4e29747aebc8cf351
+  metadata.gz: 296d9b4ccfe2ca3cacba6bf34911e142381b0f8e40d2cdf0ed8f23432ff957a3
+  data.tar.gz: cfe72d59c6b58f6d0be55488a17d1760c3914ecad2ed5a91bd2dc903c8d8c8a1
 SHA512:
-  metadata.gz: 10d2a15e1fc6afeb68d4c8a760170eddbec9c833c3c552fb72d9c3ea72d9efe5c741c1f0beca5375592344ffbac699b27d49fd3c18f75988bbc0e289078eb7f4
-  data.tar.gz: be638339a29c4492487f1aefca54a2235256b09a7a8f3c07eda3b72a7e5df29e9aea9f77d9e2a7225ef9c54735b6ab17a173e0b1153edb23549ca9e0a3b1f133
+  metadata.gz: 5268f470fe0f0ca1ba767f7e4c5c4f121686d2b6ae57a83b2aafae19600f88dc1dbef2b5a097001d407afeaa8d0e48613df80aafccf7cf745aff47b247fd8f7f
+  data.tar.gz: 00c612791299049a02e35df9c4d3ff9fe8e0106beb37408b351df13a8875b7ea40b53540d61139f98ec814122dbee73bee7a6c62ba5b571dd7c1bf0101d9fe77

data/CHANGELOG.md

@@ -7,6 +7,19 @@ and this gem adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-04-15
+
+### Added
+- `#moving_average(window:)` for sliding window averages over buffer elements
+- `#ema(alpha:)` for exponential moving average calculation
+
+## [0.5.0] - 2026-04-14
+
+### Added
+- `#concat(*values)` to push multiple values at once
+- `#percentile(p)` for arbitrary percentile calculation with linear interpolation
+- `#sample(n)` to return random element(s) from the buffer
+
 ## [0.4.0] - 2026-04-14
 
 ### Added
@@ -78,6 +91,8 @@ and this gem adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 - Last-n element retrieval
 - Enumerable support
 
+[0.6.0]: https://github.com/philiprehberger/rb-ring-buffer/releases/tag/v0.6.0
+[0.5.0]: https://github.com/philiprehberger/rb-ring-buffer/releases/tag/v0.5.0
 [0.4.0]: https://github.com/philiprehberger/rb-ring-buffer/releases/tag/v0.4.0
 [0.3.0]: https://github.com/philiprehberger/rb-ring-buffer/releases/tag/v0.3.0
 [0.2.0]: https://github.com/philiprehberger/rb-ring-buffer/releases/tag/v0.2.0

data/README.md

@@ -117,6 +117,46 @@ buf.resize(2)
 buf.to_a         # => [2, 3] (keeps most recent)
 ```
 
+### Batch Push
+
+```ruby
+buf = Philiprehberger::RingBuffer.new(5)
+buf.concat(1, 2, 3, 4, 5)
+buf.to_a  # => [1, 2, 3, 4, 5]
+```
+
+### Percentile
+
+```ruby
+buf = Philiprehberger::RingBuffer.new(100)
+(1..100).each { |v| buf.push(v) }
+
+buf.percentile(25)   # => 25.75
+buf.percentile(50)   # => 50.5
+buf.percentile(75)   # => 75.25
+buf.percentile(90)   # => 90.1
+```
+
+### Moving Averages
+
+```ruby
+buf = Philiprehberger::RingBuffer.new(5)
+[1, 2, 3, 4, 5].each { |v| buf.push(v) }
+
+buf.moving_average(window: 3)  # => [2.0, 3.0, 4.0]
+buf.ema(alpha: 0.5)            # => 4.0625
+```
+
+### Random Sampling
+
+```ruby
+buf = Philiprehberger::RingBuffer.new(5)
+[10, 20, 30, 40, 50].each { |v| buf.push(v) }
+
+buf.sample       # => random element
+buf.sample(2)    # => [random, random]
+```
+
 ### Enumerable
 
 ```ruby
@@ -144,7 +184,10 @@ buf.select(&:odd?)        # => [1, 3]
 | `#first(n)` | First n elements (oldest) |
 | `#last(n)` | Last n elements (most recent) |
 | `#clear` | Remove all elements, reset state |
+| `#concat(*values)` | Push multiple values at once |
 | `#resize(new_capacity)` | Change buffer capacity, keeping most recent elements |
+| `#percentile(p)` | Calculate the p-th percentile (0-100) with interpolation |
+| `#sample(n)` | Random element (or array of n random elements) |
 | `#inspect` | Human-readable string representation |
 | `#average` | Average of numeric elements |
 | `#sum` | Sum of numeric elements |
@@ -153,6 +196,8 @@ buf.select(&:odd?)        # => [1, 3]
 | `#variance` | Population variance |
 | `#stddev` | Population standard deviation |
 | `#median` | Median value |
+| `#moving_average(window:)` | Sliding window averages (oldest to newest) |
+| `#ema(alpha:)` | Exponential moving average (single float) |
 
 ## Development
 

data/lib/philiprehberger/ring_buffer/version.rb

@@ -2,6 +2,6 @@
 
 module Philiprehberger
   class RingBuffer
-    VERSION = '0.4.0'
+    VERSION = '0.6.0'
   end
 end

data/lib/philiprehberger/ring_buffer.rb

@@ -244,6 +244,84 @@ module Philiprehberger
       self
     end
 
+    # Push multiple values at once
+    #
+    # @param values [Array<Object>] values to push
+    # @return [self]
+    def concat(*values)
+      values.each { |v| push(v) }
+      self
+    end
+
+    # Calculate the p-th percentile of numeric elements
+    #
+    # Uses linear interpolation between nearest ranks.
+    #
+    # @param p [Numeric] percentile (0-100)
+    # @return [Float, nil] the percentile value, or nil if empty
+    # @raise [Error] if p is outside 0-100
+    def percentile(p)
+      raise Error, 'percentile must be between 0 and 100' unless p.is_a?(Numeric) && p >= 0 && p <= 100
+      return nil if empty?
+
+      sorted = to_a.sort
+      return sorted.first.to_f if sorted.length == 1
+
+      rank = (p / 100.0) * (sorted.length - 1)
+      lower = rank.floor
+      upper = rank.ceil
+      return sorted[lower].to_f if lower == upper
+
+      sorted[lower] + ((sorted[upper] - sorted[lower]) * (rank - lower))
+    end
+
+    # Return a random element or array of random elements
+    #
+    # @param n [Integer, nil] number of elements (nil for single element)
+    # @return [Object, Array, nil]
+    def sample(n = nil)
+      arr = to_a
+      return nil if arr.empty? && n.nil?
+      return [] if arr.empty? && n
+
+      n.nil? ? arr.sample : arr.sample(n)
+    end
+
+    # Sliding window averages over elements oldest to newest
+    #
+    # @param window [Integer] window size
+    # @return [Array<Float>]
+    def moving_average(window:)
+      raise Error, 'buffer is empty' if empty?
+      raise Error, 'window must be a positive integer' unless window.is_a?(Integer) && window.positive?
+      raise Error, 'window exceeds buffer size' if window > @count
+
+      arr = to_a
+      arr.each { |v| raise Error, 'all elements must be numeric' unless v.is_a?(Numeric) }
+
+      (0..(arr.length - window)).map do |i|
+        arr[i, window].sum.to_f / window
+      end
+    end
+
+    # Exponential moving average
+    #
+    # @param alpha [Float] smoothing factor (0 < alpha <= 1)
+    # @return [Float]
+    def ema(alpha:)
+      raise Error, 'buffer is empty' if empty?
+      raise Error, 'alpha must be between 0 (exclusive) and 1 (inclusive)' unless alpha.is_a?(Numeric) && alpha.positive? && alpha <= 1
+
+      arr = to_a
+      arr.each { |v| raise Error, 'all elements must be numeric' unless v.is_a?(Numeric) }
+
+      result = arr.first.to_f
+      arr.drop(1).each do |v|
+        result = (alpha * v) + ((1 - alpha) * result)
+      end
+      result
+    end
+
     # Human-readable string representation
     #
     # @return [String]

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: philiprehberger-ring_buffer
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-14 00:00:00.000000000 Z
+date: 2026-04-16 00:00:00.000000000 Z
 dependencies: []
 description: Fixed-capacity ring buffer that overwrites oldest entries on overflow,
   with index access, push/pop/shift mutation, oldest/newest peek, built-in statistics