philiprehberger-interval 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ecb8d7c68d3603d44c8df9a87a224c52300377809ad98ab1d19fe1a89ec13449
-  data.tar.gz: 75b3438103596f8a4de7f358a9f1cc25cd39fe5e80a47dfb6f25d38852e26964
+  metadata.gz: 8aaad786d674299bcc97c96acb85df9aad7bcd91b3794404a6aad674946c8461
+  data.tar.gz: 1ec309715dd29b1f132481150d32a1c00d95413d3c0ad3aca1d6ea79420daa0e
 SHA512:
-  metadata.gz: 78198caa2a0cf621b3545997e8fdfb58ad7424d7304e7d4367873dd69eaa02db2c91f1ed5a95cd365074be886063fb91941dea72180b2ce4e099c6e1982fddcf
-  data.tar.gz: 2dbb700fce8cd9cf5d973ab0baabece8e8b94e8d79f71939a805418f7fdfdbf626ca183ae9ab0fc18c2c036f21a2c0de9ddd28d90e1978da02139ac8eb3d1178
+  metadata.gz: 34ff8595dd0ede63f6cc187e06ba0de8a51fb80d15d777845c72512f8721402e225e54dbefc56089eb44610549e6de4307e03c2503a133cd9844e8446c5dbe80
+  data.tar.gz: 27c3dc2e5c9215554f995de13fbed3090311f0f09e337ea1b8d100d68e526731de1d089b141dbcb2c938421b1a8a5dd9ada07d95d3d9b123aaa72a0ab1b70f6e

data/CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-04-21
+
+### Added
+- `Range#touching?` — strict boundary-touching predicate
+- `Range#length` — alias for `#size`
+
+### Fixed
+- `bug_report.yml` — require Ruby version; add Gem version input per guide
+
+## [0.5.0] - 2026-04-16
+
+### Added
+- `Range#sample(n = nil)` — return a random Float within the interval, or an array of n random Floats; respects open/closed boundaries via rejection sampling; raises on empty intervals; returns start for point intervals
+
 ## [0.4.0] - 2026-04-15
 
 ### Added

data/README.md

@@ -84,6 +84,19 @@ Philiprehberger::Interval.gaps(intervals)
 # => [[7, 10]]
 ```
 
+### Sampling Random Values
+
+Return one or more random Floats from within an interval. Open boundaries are respected via rejection sampling:
+
+```ruby
+interval = Philiprehberger::Interval.new(1.0, 5.0)
+interval.sample        # => 3.247... (single Float)
+interval.sample(3)     # => [1.823..., 4.501..., 2.964...]
+
+open = Philiprehberger::Interval.new(1.0, 5.0, type: :open)
+open.sample            # => always strictly between 1.0 and 5.0
+```
+
 ### Finding a Common Intersection
 
 Compute the overlap shared by every interval, or `nil` if any pair is disjoint:
@@ -97,6 +110,20 @@ Philiprehberger::Interval.intersection([
 # => [5, 8]
 ```
 
+### Touching Intervals
+
+Check whether two intervals meet at exactly one point with no overlap and no gap — useful when partitioning a range so every value is covered exactly once:
+
+```ruby
+a = Philiprehberger::Interval.new(1, 5, type: :right_open) # [1, 5)
+b = Philiprehberger::Interval.new(5, 10, type: :closed)    # [5, 10]
+a.touching?(b) # => true  (5 covered once)
+
+c = Philiprehberger::Interval.new(1, 5, type: :closed)     # [1, 5]
+d = Philiprehberger::Interval.new(5, 10, type: :closed)    # [5, 10]
+c.touching?(d) # => false (5 covered twice)
+```
+
 ### With Time Values
 
 ```ruby
@@ -113,16 +140,19 @@ shift.include?(Time.new(2026, 1, 1, 12))  # => true
 | `#overlaps?(other)` | Check if two intervals overlap (respects boundary types) |
 | `#contains?(other)` | Check if interval fully contains another |
 | `#adjacent?(other)` | Check if intervals are touching but not overlapping |
+| `#touching?(other)` | Check if intervals meet at a single point with exactly one closed side |
 | `#intersect(other)` | Return the overlap between two intervals |
 | `#overlap_ratio(other)` | Fraction of self covered by other (0.0–1.0) |
 | `#union(other)` | Return the combined interval |
 | `#subtract(other)` | Remove another interval, returning remaining parts |
 | `#size` | Length of the interval |
+| `#length` | Alias for `#size` |
 | `#include?(point)` | Check if a point falls within the interval (respects boundary types) |
 | `#shift(delta)` | Return new interval shifted by delta, preserving type |
 | `#scale(factor, anchor:)` | Scale width around anchor (`:center`, `:left`, `:right`) |
 | `#split(n)` | Split into n equal sub-intervals |
 | `#clamp(value)` | Clamp value to interval bounds |
+| `#sample(n = nil)` | Return a random Float, or array of n Floats, within the interval (respects boundaries) |
 | `.merge(intervals)` | Merge overlapping intervals into non-overlapping set |
 | `.gaps(intervals)` | Find gaps between a set of intervals |
 | `.intersection(intervals)` | Common overlap of a collection of intervals, or `nil` |

data/lib/philiprehberger/interval/range.rb

@@ -112,6 +112,27 @@ module Philiprehberger
       def size
         @finish - @start
       end
+      alias length size
+
+      # Check if this interval strictly touches another at a single endpoint.
+      #
+      # Returns +true+ iff the two intervals share exactly one endpoint value
+      # and exactly one of the two boundaries at that point is closed — so the
+      # meeting point is covered exactly once, with no gap and no overlap.
+      #
+      # @param other [Range] the other interval
+      # @return [Boolean]
+      def touching?(other)
+        return false if overlaps?(other)
+
+        if @finish == other.start
+          right_closed? ^ other.left_closed?
+        elsif other.finish == @start
+          other.right_closed? ^ left_closed?
+        else
+          false
+        end
+      end
 
       # Return the fraction of self that is covered by another interval.
       #
@@ -186,6 +207,26 @@ module Philiprehberger
         end
       end
 
+      # Return one or more random Floats within the interval.
+      #
+      # Without an argument, returns a single random Float. With an integer
+      # argument, returns an array of that many random Floats. Respects boundary
+      # types: open boundaries are excluded via rejection sampling. Returns
+      # +start+ immediately for point intervals (start == finish, closed).
+      #
+      # @param n [Integer, nil] number of samples, or nil for a single value
+      # @return [Float, Array<Float>]
+      # @raise [Error] if the interval is empty
+      def sample(n = nil)
+        raise Error, 'cannot sample an empty interval' if empty?
+
+        if n.nil?
+          sample_one
+        else
+          Array.new(n) { sample_one }
+        end
+      end
+
       # Clamp a value to the interval bounds.
       #
       # @param value [Comparable] the value to clamp
@@ -239,6 +280,22 @@ module Philiprehberger
       def empty?
         @start == @finish && @type != :closed
       end
+
+      private
+
+      def sample_one
+        return @start.to_f if @start == @finish
+
+        lo = @start.to_f
+        hi = @finish.to_f
+
+        loop do
+          value = lo + (rand * (hi - lo))
+          left_ok  = left_closed?  ? value >= lo : value > lo
+          right_ok = right_closed? ? value <= hi : value < hi
+          return value if left_ok && right_ok
+        end
+      end
     end
   end
 end

data/lib/philiprehberger/interval/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: philiprehberger-interval
 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-15 00:00:00.000000000 Z
+date: 2026-04-21 00:00:00.000000000 Z
 dependencies: []
 description: Interval data type supporting closed, open, and half-open boundaries
   with overlap detection, containment, intersection, union, subtraction, shift, scale,