philiprehberger-cron_parser 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d11c034aa656522a0e2ca5e145ca68f974b1b0eb9aeafad15797ee5a53d859f1
-  data.tar.gz: 874e7abb865fa66511d7a407e7e0cc4ea0dfd8e8a637ff75225cffc9db5f0206
+  metadata.gz: 3be8924f48f35f97ea4d356f5368d7907cf23bda63af8af43c4b3776f1a47a69
+  data.tar.gz: 0d0284d3e84fe3b93db4911a30149333bf0faaba73f2857ec28ae95f83455509
 SHA512:
-  metadata.gz: c8053224dd61f4defd352fbdf106351f995de7b16b6f10b610a40e99c47f577c0b27d241587aa74cd4299da2d7a4601c6879844eb63d68ce47dfcaa383ce5847
-  data.tar.gz: f830772d6a686fec8dcf8f857a68b4be1f162bf70f0ebde4146f7228b44f5aadc18dbe567ce8570fcd4d5c5fa3125ab2ef56313978cec0320caa5b7796d458b5
+  metadata.gz: 4cf277261fcf00a553dc1defe27a24b74ace4d34f7760e5033d5b52dbbb2fa87bacb0a36b32e8847bd3af4e2d93381caf3fa17b8f5e6fa0953fc32a3105f2b01
+  data.tar.gz: 6e5f421543e3a2871f1b8e068f12dab5ebec5586ff18ee297dcbca94261cca57e931c72e00af468a783170462edd333939b1e1370d715a5770b32fb3f457f4fc

data/CHANGELOG.md

@@ -7,6 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-04-30
+
+### Added
+- `Expression#count_in(from:, to:)` returns the number of times the expression matches within an inclusive time window — useful for capacity planning and alert tuning
+
 ## [0.3.0] - 2026-04-09
 
 ### Added

data/README.md

@@ -49,6 +49,15 @@ cron.matches?(Time.new(2026, 3, 22, 9, 0, 0))  # => true
 cron.matches?(Time.new(2026, 3, 22, 10, 0, 0)) # => false
 ```
 
+### Counting Occurrences in a Window
+
+```ruby
+cron = Philiprehberger::CronParser.new('*/15 * * * *')
+from = Time.new(2026, 4, 30, 9, 0, 0)
+to   = Time.new(2026, 4, 30, 10, 0, 0)
+cron.count_in(from: from, to: to)  # => 5
+```
+
 ### Human-Readable Description
 
 ```ruby
@@ -118,6 +127,7 @@ Philiprehberger::CronParser.new('0 9 * * MON-FRI') # named weekdays
 | `Expression#next(from:)` | Calculate the next matching time |
 | `Expression#prev(from:)` | Calculate the previous matching time |
 | `Expression#next_n(n, from:)` | Calculate the next N matching times |
+| `Expression#count_in(from:, to:)` | Count occurrences within an inclusive `[from, to]` window |
 | `Expression#matches?(time)` | Check if a time matches the expression |
 | `Expression#human_readable` | Human-readable description of the expression |
 | `Expression#description` | Alias for `human_readable` |

data/lib/philiprehberger/cron_parser/expression.rb

@@ -106,6 +106,30 @@ module Philiprehberger
         results
       end
 
+      # Count occurrences within a time window [from, to].
+      #
+      # The window is inclusive on both ends; `from` is treated as the cursor's
+      # starting point so an exact match at `from` counts only if it lies on a
+      # minute boundary that the schedule fires on.
+      #
+      # @param from [Time] start of the window
+      # @param to [Time] end of the window
+      # @return [Integer] the count of occurrences in the window
+      # @raise [Error] if `to` is earlier than `from`
+      def count_in(from:, to:)
+        raise Error, '`to` must be greater than or equal to `from`' if to < from
+
+        count = 0
+        cursor = round_to_minute(from) - 60
+        loop do
+          cursor = self.next(from: cursor)
+          break if cursor > to
+
+          count += 1
+        end
+        count
+      end
+
       # Return a human-readable description of the expression
       #
       # @return [String]

data/lib/philiprehberger/cron_parser/version.rb

@@ -2,6 +2,6 @@
 
 module Philiprehberger
   module CronParser
-    VERSION = '0.3.0'
+    VERSION = '0.4.0'
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: philiprehberger-cron_parser
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-09 00:00:00.000000000 Z
+date: 2026-05-01 00:00:00.000000000 Z
 dependencies: []
 description: Parse standard 5-field cron expressions and calculate next/previous occurrences,
   match times against patterns, and generate human-readable descriptions.