philiprehberger-cron_parser 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d11c034aa656522a0e2ca5e145ca68f974b1b0eb9aeafad15797ee5a53d859f1
-  data.tar.gz: 874e7abb865fa66511d7a407e7e0cc4ea0dfd8e8a637ff75225cffc9db5f0206
+  metadata.gz: 2d7e8b08d65ab34dacc640a348cd965a7a604840a0a5c10ad13327740ddb323e
+  data.tar.gz: 353889bda7ae0edd7074fc0a3a84056dff6ca731ab5daa65fa4c4ace54cedacf
 SHA512:
-  metadata.gz: c8053224dd61f4defd352fbdf106351f995de7b16b6f10b610a40e99c47f577c0b27d241587aa74cd4299da2d7a4601c6879844eb63d68ce47dfcaa383ce5847
-  data.tar.gz: f830772d6a686fec8dcf8f857a68b4be1f162bf70f0ebde4146f7228b44f5aadc18dbe567ce8570fcd4d5c5fa3125ab2ef56313978cec0320caa5b7796d458b5
+  metadata.gz: b3a8cef0c91c1f4056005b846d1b1d9960abca68cb1821c1fe602b9d4f8e9b73e4d70df8b11fd4971b46e0f4c65fbd9bfa6c466713f3a664037f1b373de93821
+  data.tar.gz: a89b2d2bef776c9f2ff5f0edba5fd163db301e0566ed0a9a6062b5af2633ec45731f90fae38e46ef4a4cf7f376804b7a21f6bff9f42b334527214cd540e4ceb8

data/CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-05-12
+
+### Added
+- `Expression#each_in(from:, to:, &block)` iterator over every matching occurrence in an inclusive window; returns an Enumerator when no block is given so callers can chain `Enumerable` methods like `first`, `take`, and `lazy`
+
+## [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,29 @@ 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
+```
+
+### Iterating 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.each_in(from: from, to: to) { |t| puts t }
+
+# Without a block, returns an Enumerator
+cron.each_in(from: from, to: to).first(2)
+# => [2026-04-30 09:00:00, 2026-04-30 09:15:00]
+```
+
 ### Human-Readable Description
 
 ```ruby
@@ -118,6 +141,8 @@ 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#each_in(from:, to:, &block)` | Yield each matching occurrence in `[from, to]`; returns an Enumerator without a block |
 | `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,56 @@ 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
+
+      # Iterate every matching time within an inclusive `[from, to]` window.
+      #
+      # When called with a block, yields each occurrence and returns `self`.
+      # Without a block, returns an `Enumerator` so callers can chain `Enumerable`
+      # methods (`take`, `lazy`, `to_a`, ...).
+      #
+      # @param from [Time] start of the window
+      # @param to [Time] end of the window
+      # @yieldparam time [Time] a matching occurrence
+      # @return [self, Enumerator] self when a block is given, otherwise an Enumerator
+      # @raise [Error] if `to` is earlier than `from`
+      def each_in(from:, to:, &block)
+        raise Error, '`to` must be greater than or equal to `from`' if to < from
+
+        return enum_for(:each_in, from: from, to: to) unless block
+
+        cursor = round_to_minute(from) - 60
+        loop do
+          cursor = self.next(from: cursor)
+          break if cursor > to
+
+          block.call(cursor)
+        end
+        self
+      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.5.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.5.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-09 00:00:00.000000000 Z
+date: 2026-05-12 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.