periodoxical 0.8.3 → 0.9.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 78125f7c8e33a8588c933d7b0438daa5d0913394fe9c141e752dd73fc1968d88
-  data.tar.gz: 60acbba0684d36991ac7bffcb21dc8a97e27bfb313d1ab9641668463e73c718c
+  metadata.gz: 1028e4261c9759e49e7446a1ff506fcb4d3b789b4bdd1ef40dbec0bd8df18ae8
+  data.tar.gz: c7dece06fabe86ede77b98203bea7716d0d1e039393f1e6e693c8a232615ef01
 SHA512:
-  metadata.gz: df7a8cc7abe1139af195aebe455feb7c66b75e27e3a8d43e4c862ec362111756a461b7293efe3c3fdcca50eb1f70d5fdb5de04e740014a4fc33fe3f324e8d6ec
-  data.tar.gz: '070876a087c2712b12f497054966f9cd98ac3d0e3eab1e4337e165e2ea42cef5ea4dd5b43b714393d92d14ddab2119b426128cf9d85f5de845b9e32959f72b1d'
+  metadata.gz: '08dc98ece1a24ed33564c60f32c31fcf76defddbab51fbf2c0c3df04b296759767fc1dde8a4ed744a24b700fe812ce97bcdc06c052c382e61872c55426116258'
+  data.tar.gz: c8edb8ea410b88c5888edda103752c27c149e4e06421b74fb7c4a29ed0f09ae32726536ed495702156b8e6e054da0a5140e1a3487bbbac4468abb94ed7cfb79f

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    periodoxical (0.8.3)
+    periodoxical (0.9.3)
       tzinfo (~> 2.0, >= 2.0.0)
       week_of_month (= 1.2.6)
 

data/README.md

@@ -291,7 +291,7 @@ Periodoxical.generate(
 ]
 ```
 
-### Example 7 - Exclude time blocks using the `exclusion_dates` parameter
+### Example 7 - Exclude time blocks using the `exclusion_dates` and `exclusion_times` parameters
 As a Ruby dev, I want to generate timeblocks for **8AM - 9AM** on **Mondays**, except for the **Monday of June 10, 2024**.
 
 ```rb
@@ -328,10 +328,68 @@ Periodoxical.generate(
 ]
 ```
 
+As a Ruby dev, I want to generate timeblocks for **8AM - 9AM**, and **10AM - 11AM** on **Mondays**, except for those that conflict (meaning overlap) with the time block of **10:30AM - 11:30AM** on the **Monday of June 10, 2024**.  I can skip the conflicting time blocks by using the `exclusion_times` parameter.
+
+```rb
+Periodoxical.generate(
+  time_zone: 'America/Los_Angeles',
+  start_date: '2024-06-3',
+  limit: 4,
+  days_of_week: %(mon),
+  time_blocks: [
+      { start_time: '8:00AM', end_time: '9:00AM' },
+      { start_time: '10:00AM', end_time: '11:00AM' },
+  ],
+  exclusion_times: [
+    {
+        start: '2024-06-10T10:30:00-07:00',
+        end: '2024-06-10T11:30:00-07:00',
+    }
+  ],
+)
+# =>
+[
+    {
+      start: #<DateTime 2024-06-03T08:00:00-0700>,
+      end: #<DateTime 2024-06-03T09:00:00-0700>,
+    },
+    {
+      start: #<DateTime 2024-06-03T10:00:00-0700>,
+      end: #<DateTime 2024-06-03T11:00:00-0700>,
+    },
+    {
+      start: #<DateTime 2024-06-10T08:00:00-0700>,
+      end: #<DateTime 2024-06-10T09:00:00-0700>,
+    },
+    # The June 10 10AM - 11AM was skipped because it overlapped with the June 10 10:30AM - 11:30AM exclusion time.
+    {
+      start: #<DateTime 2024-06-17T08:00:00-0700>,
+      end: #<DateTime 2024-06-17T09:00:00-0700>,
+    },
+    {
+      start: #<DateTime 2024-06-17T10:00:00-0700>,
+      end: #<DateTime 2024-06-17T11:00:00-0700>,
+    },
+    {
+      start: #<DateTime 2024-06-24T08:00:00-0700>,
+      end: #<DateTime 2024-06-24T09:00:00-0700>,
+    },
+]
+```
+
 ### Example 8 - Every-other-nth day-of-week rules (ie. every other Tuesday, every 3rd Wednesday, every 10th Friday)
 
 As a Ruby dev, I want to generate timeblocks for **9AM- 10AM** on **every Monday**, but **every other Tuesday**, and **every other 3rd Wednesday**. I can do this using the `days_of_week` parameter, but also using the `every` and `every_other_nth` keys to specify the every-other-nth-rules.
 
+This can be visualized as:
+
+<div align="center">
+  <img width="600" alt="alt_google_cal_image" src="https://github.com/StevenJL/periodoxical/assets/2191808/d663da17-a94a-4715-886a-8223b129dd60">
+  <p><i>(image courtesy of calendar.google.com)</i></p>
+</div>
+
+<br>
+
 ```rb
 Periodoxical.generate(
   time_zone: 'America/Los_Angeles',
@@ -464,7 +522,8 @@ Periodoxical.generate(
     {
       start: #<DateTime: 2028-11-23T17:00:00-0800>,
       end: #<DateTime: 2028-11-23T18:00:00-0800>,
-    }
+    },
+    ...
 ]
 ```
 

data/lib/periodoxical/validation.rb

@@ -99,6 +99,14 @@ module Periodoxical
       unless( @limit || @end_date)
         raise "Either `limit` or `end_date` must be provided"
       end
+
+      if @exclusion_times
+        @exclusion_times.each do |tb|
+          unless tb[:start] < tb[:end]
+            raise "Exclusion times must have `start` before `end`. #{tb[:start]} not before #{tb[:end]}"
+          end
+        end
+      end
     end
   end
 end

data/lib/periodoxical/version.rb

@@ -1,3 +1,3 @@
 module Periodoxical
-  VERSION = "0.8.3"
+  VERSION = "0.9.3"
 end

data/lib/periodoxical.rb

@@ -44,6 +44,19 @@ module Periodoxical
     # @param [Aray<String>] exclusion_dates
     #   Dates to be excluded when generating the time blocks
     #   Ex: ['2024-06-10', '2024-06-14']
+    # @param [Aray<Hash>] exclusion_times
+    #   Timeblocks to be excluded when generating the time blocks if there is conflict (ie. overlap)
+    #   Ex: [
+    #         {
+    #           start: '2024-06-10T10:30:00-07:00',
+    #           end: '2024-06-10T11:30:00-07:00'
+    #         },
+    #         {
+    #           start: '2024-06-10T14:30:00-07:00',
+    #           end: '2024-06-10T15:30:00-07:00'
+    #         },
+    #       ]
+    #
     # @param [Hash<Array<Hash>>] day_of_week_time_blocks
     #   To be used when hours are different between days of the week
     #   Ex: {
@@ -58,6 +71,7 @@ module Periodoxical
       day_of_week_time_blocks: nil,
       limit: nil,
       exclusion_dates: nil,
+      exclusion_times: nil,
       time_zone: 'Etc/UTC',
       days_of_week: nil,
       nth_day_of_week_in_month: nil,
@@ -84,6 +98,11 @@ module Periodoxical
       @exclusion_dates = if exclusion_dates && !exclusion_dates.empty?
                            exclusion_dates.map { |ed| Date.parse(ed) }
                          end
+      @exclusion_times = if exclusion_times
+                           exclusion_times.map do |et|
+                             { start: DateTime.parse(et[:start]), end: DateTime.parse(et[:end]) }
+                           end
+                         end
       validate!
     end
 
@@ -184,6 +203,9 @@ module Periodoxical
     #  }
     #  Generates time block but also checks if we should stop generating
     def append_to_output_and_check_limit(time_block)
+      # Check if this particular time is conflicts with any times from `exclusion_times`.
+      return if overlaps_with_an_excluded_time?(time_block)
+
       @output << {
         start: time_str_to_object(@current_date, time_block[:start_time]),
         end: time_str_to_object(@current_date, time_block[:end_time])
@@ -350,5 +372,43 @@ module Periodoxical
     def update_days_of_week_running_tally!
       @days_of_week_running_tally[@current_day_of_week.to_sym] = @days_of_week_running_tally[@current_day_of_week.to_sym] + 1
     end
+
+    # @return [Boolean]
+    #   Whether or not the given `time_block` in the @current_date and
+    #   @time_zone overlaps with the times in `exclusion_times`.
+    def overlaps_with_an_excluded_time?(time_block)
+      return false unless @exclusion_times
+
+      @exclusion_times.each do |exclusion_timeblock|
+        return true if overlap?(
+          exclusion_timeblock,
+          {
+            start: time_str_to_object(@current_date, time_block[:start_time]),
+            end: time_str_to_object(@current_date, time_block[:end_time]),
+          }
+        )
+      end
+
+      false
+    end
+
+    # @param [Hash] time_block_1, time_block_2
+    #  Ex: {
+    #    start: #<DateTime>,
+    #    end: #<DateTime>,
+    #  }
+    def overlap?(time_block_1, time_block_2)
+      tb_1_start = time_block_1[:start]
+      tb_1_end = time_block_1[:end]
+      tb_2_start = time_block_2[:start]
+      tb_2_end = time_block_2[:end]
+
+      # Basicall overlap is when one starts before the other has ended
+      return true if tb_1_end > tb_2_start && tb_1_end < tb_2_end
+      # By symmetry
+      return true if tb_2_end > tb_1_start && tb_2_end < tb_1_end
+
+      false
+    end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: periodoxical
 version: !ruby/object:Gem::Version
-  version: 0.8.3
+  version: 0.9.3
 platform: ruby
 authors:
 - Steven Li
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-06-03 00:00:00.000000000 Z
+date: 2024-06-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: tzinfo