extended_range 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3ebf8471421f9984b9fe5e24a2a148a9f834c84aae7186a702c43e4f29788343
+  data.tar.gz: 8ff3fb81b2800899126f1858c82fb560b8664b22f61242bfa999e5cbd8a325b1
+SHA512:
+  metadata.gz: be50007c896e083f9c54d93d2d00c38af4211362997347f5caa80b4bfc8e98b54c1683b41fdb9c1c2eaabbe67c552b5ef760f79f3c93c97f7ceebd0a49b00793
+  data.tar.gz: 6e603c446b077a04ed4adbfde9490c9a30faf3a35345251d1ab3912ed8462a1901dedcb772ef8c4100b33344abd871e7f349d1bb23241256e700e15b4b234abf

data/.circleci/config.yml

@@ -0,0 +1,21 @@
+version: 2.1
+jobs:
+  build:
+    docker:
+      - image: ruby:3.0.2
+    steps:
+      - checkout
+      - run:
+          name: Install gem dependencies
+          command: bundle install
+      - run:
+          name: Rubocop
+          command: bundle exec rubocop
+      - run:
+          name: RSpec Tests
+          command: |
+            bundle exec rspec --profile 10 \
+              --format RspecJunitFormatter \
+              --out test_results/rspec.xml \
+              --format documentation \
+              $(circleci tests glob "spec/**/*_spec.rb" | circleci tests split --split-by=timings)

data/.gitignore

@@ -0,0 +1,15 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+Gemfile.lock
+
+# rspec failure tracking
+.rspec_status
+
+*.gem

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,34 @@
+AllCops:
+  TargetRubyVersion: 3.0
+
+Style/StringLiterals:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Layout/LineLength:
+  Max: 120
+
+Metrics/AbcSize:
+  Enabled: false
+
+Metrics/BlockLength:
+  Enabled: false
+
+Metrics/CyclomaticComplexity:
+  Enabled: false
+
+Metrics/MethodLength:
+  Enabled: false
+
+Metrics/PerceivedComplexity:
+  Enabled: false
+
+Naming/MethodParameterName:
+  Enabled: false
+
+Style/Documentation:
+  Enabled: false

data/Gemfile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in extended_range.gemspec
+gemspec
+
+gem "rake", "~> 13.0"
+gem "rspec", "~> 3.0"
+gem "rspec_junit_formatter"
+gem "rubocop", "~> 1.7"

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2021 Anthony Felix Hernandez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,43 @@
+# ExtendedRange
+
+[![hernanat](https://circleci.com/gh/hernanat/extended_range/tree/main.svg?style=svg)](https://circleci.com/gh/hernanat/extended_range/tree/main)
+[![Gem Version](https://badge.fury.io/rb/extended_range.svg)](https://badge.fury.io/rb/extended_range)
+
+`extended_range` is a set of extension class and instance methods to Ruby's `Range` class.
+
+Read the [docs](https://rubydoc.info/github/hernanat/extended_range) for more information
+  about its capabilities and how to use it.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "extended_range"
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install extended_range
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec`
+  to run the tests. You can also run `bin/console` for an interactive prompt that will allow
+  you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+## Documentation
+
+Documentation can be viewed at https://rubydoc.info/github/hernanat/extended_range
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/hernanat/extended_range
+
+TODO: contribution guidelines

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/bin/console

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "extended_range"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/extended_range.gemspec

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative "lib/extended_range/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "extended_range"
+  spec.version       = ExtendedRange::VERSION
+  spec.authors       = ["Anthony Felix Hernandez"]
+  spec.email         = ["ant@antfeedr.com"]
+
+  spec.summary       = "Some handy methods for the `Range` class."
+  spec.homepage      = "https://github.com/hernanat/extended_range"
+  spec.license       = "MIT"
+  spec.required_ruby_version = ">= 3.0.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{\A(?:test|spec|features)/}) }
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  # Uncomment to register a new dependency of your gem
+  # spec.add_dependency "example-gem", "~> 1.0"
+
+  spec.add_development_dependency "pry", "~> 0.14"
+  spec.add_development_dependency "yard", "~> 0.9"
+  # For more information and examples about making a new gem, checkout our
+  # guide at: https://bundler.io/guides/creating_gem.html
+end

data/lib/core_extensions/range/checks.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module CoreExtensions
+  module Range
+    module Checks
+      # Checks whether or not `other` overlaps with `self`.
+      #
+      # @param [Range] other The range to check for overlap with `self`.
+      #
+      # @return [Boolean]
+      #
+      # @example Overlapping range
+      #   (1..4).overlaps?(2..6) #=> true
+      #
+      # @example Non-overlapping range
+      #   (1..4).overlaps?(5..7) #=> false
+      def overlaps?(other)
+        return true if self == other
+
+        if endless? || other.endless?
+          endless_range_overlaps?(other)
+        elsif self.end == other.begin || other.end == self.begin
+          # If `a.end` is the same as `b.begin`, but `a.exclude_end?` is true,
+          # then the ranges do not overlap. Similar in the other direction.
+          (self.end == other.begin && !exclude_end?) ||
+            (other.end == self.begin && !other.exclude_end?)
+        else
+          self.begin <= other.end && other.begin <= self.end
+        end
+      end
+
+      # Returns `true` if `self` is endless, `false` otherwise.
+      def endless?
+        self.end.nil?
+      end
+
+      # Returns `true` if `self` is beginless, `false` otherwise.
+      def beginless?
+        self.begin.nil?
+      end
+
+      private
+
+      # `other` is not necessarily endless, neither is `self`.
+      def endless_range_overlaps?(other)
+        # two endless ranges necessarily overlap.
+        if endless? && other.endless?
+          true
+        elsif endless?
+          # self or other is endless, check to see if they overlap by checking if the
+          # endless range's begin falls before the non-endless range's end. We also
+          # include a constraint to prevent open ranges whose end is the same as the
+          # second range's beginning from being considered as overlapping.
+          self.begin <= other.end && !other.exclude_end?
+        else
+          other.begin <= self.end && !exclude_end?
+        end
+      end
+    end
+  end
+end

data/lib/core_extensions/range/operations.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+require_relative "checks"
+
+module CoreExtensions
+  module Range
+    module Operations
+      include Checks
+
+      def self.included(klass)
+        klass.extend(ClassMethods)
+      end
+
+      # Returns a range whose end is included in the range.
+      #
+      # @param delta The amount which should be subtracted from the range end when converting
+      #   to a closed range.
+      #
+      # @return [Range] self if the range is already closed, otherwise return a new range
+      #   where the `begin` is the same as `self`, and the `end` is `self.end - delta`.
+      #
+      # @example Convert an open time range to a closed time range.
+      #   (Time.new(2020)...Time.new(2021)).to_closed_range #=> 2020-01-01 00:00:00 -0800..2020-12-31 23:59:59 -0800
+      #
+      # @example Convert an open time range to a closed time range and specify the delta.
+      #   (Time.new(2020)...Time.new(2021)).to_closed_range(delta: Float::EPSILON)
+      #   #=> 2020-01-01 00:00:00 -0800..2020-12-31 23:59:59 4503599627370495/4503599627370496 -0800
+      def to_closed_range(delta: 1)
+        return self unless exclude_end?
+
+        if delta.is_a?(Proc)
+          (self.begin..(delta.call(self.end)))
+        else
+          (self.begin..self.end - delta)
+        end
+      end
+
+      # Calls {ClassMethods#subtract} with `self` and `other`
+      #
+      # @param [Range] other The range to subtract.
+      #
+      # @return [Array<Range>] An array of ranges obtained from subtracting `other` from `self`.
+      def -(other)
+        self.class.subtract(self, other)
+      end
+
+      # Calls {ClassMethods#merge} with `self` and `*others`
+      #
+      # @param [Range] other The range to merge.
+      #
+      # @return [Array<Range>] An array of merged ranges.
+      def merge(other)
+        self.class.merge(self, other)
+      end
+
+      module ClassMethods
+        # Merge the given ranges together.
+        #
+        # @param [Array<Range>] ranges The ranges objects to merge.
+        #
+        # @return [Array<Range>] An array of potentially merged ranges.
+        #
+        # @example Merge two ranges.
+        #   Range.merge(1..5, 2..6) #=> [1..6]
+        #
+        # @example Merge an endless range with a non-endless range.
+        #   Range.merge(1..5, 2..) #=> [1..]
+        #
+        # @example Merge two endless ranges.
+        #   Range.merge(1.., 2..) #=> [1..]
+        #
+        # @example Can't merge an open range with a range whose start is the same as the open range's end.
+        #   Range.merge(1...3, 3..5) #=> [1...3, 3..5]
+        def merge(*ranges)
+          ranges.sort_by!(&:begin).inject([]) do |merged, range|
+            if merged.empty? || !range.overlaps?(merged.last)
+              merged.append(range)
+            else
+              last_range = merged.pop
+
+              merged.append(merge_ranges(last_range, range))
+            end
+          end
+        end
+
+        # Subtract an array of ranges from the given original range.
+        #
+        # @param [Range] original_range The range to subtract from.
+        #
+        # @param [Array<Range>] subtracted_ranges The ranges to subtract from `original_range`
+        #
+        # @param delta The amount which should be added to the begin of a resulting subrange in
+        #   the event that the previous subrange end was open.
+        #
+        # @example Subtraction of closed, finite ranges.
+        #   Range.subtract(1..20, 2..3, 4..6, 7..12) #=> [1...2, 13..20]
+        #
+        # @example Subtraction of a mixture of closed and open finite ranges.
+        #   Range.subtract(1..20, 2..3, 4...6, 7..12) #=> [1...2, 6...7, 13..20]
+        #
+        # @example Subtraction of finite ranges from an endless range
+        #   Range.subtract(1.., 2..3, 4...6, 7..12) #=> [1...2, 4...7, 13..]
+        #
+        # @example Subtraction of two endless ranges
+        #   Range.subtract(1.., 10..) #=> [1...10]
+        #   Range.subtract(10.., 1..) #=> []
+        def subtract(original_range, *subtracted_ranges, delta: 1)
+          subtracted_ranges.sort_by!(&:begin).inject([original_range]) do |result, subtracted_range|
+            if result.last&.overlaps?(subtracted_range)
+              result.append(*subtract_overlapping_range(result.pop, subtracted_range, delta: delta))
+            else
+              result
+            end
+          end
+        end
+
+        private
+
+        def merge_ranges(a, b)
+          exclude_end = should_merged_exclude_end?(a, b)
+          ::Range.new(a.begin, merged_range_end(a, b), exclude_end)
+        end
+
+        def should_merged_exclude_end?(a, b)
+          return true if a.exclude_end? && b.exclude_end?
+
+          # Deal with endless ranges
+          if a.endless? || b.endless?
+            # If `a.end` is `nil` and `a.exclude_end?` is `true`, then `b.exclude_end?` can't
+            # be `true`, so it suffices to check if `b.end` is not `nil`. If `b.end` is not `nil`,
+            # then the result is an endless range that excludes the end. If `b.end` *is* `nil`,
+            # then the result is an endless range that does *not* exclude the end (because
+            # we know from above that `b.exclude_end?` cannot be `true`.
+            #
+            # The same holds for the inverse statement (i.e. the RHS of the `||` below).
+            #
+            # The goal is to maintain logical consistency for for `exclude_end` even in
+            # the event that the result is an endless range.
+            (a.exclude_end? && a.endless? && !b.endless?) ||
+              (b.exclude_end? && b.endless? && !a.endless?)
+          else
+            (a.exclude_end? && b.end < a.end) || (b.exclude_end? && a.end < b.end)
+          end
+        end
+
+        def merged_range_end(a, b)
+          if a.endless? || b.endless?
+            nil
+          else
+            a.end > b.end ? a.end : b.end
+          end
+        end
+
+        # Subtract range `b` from range `a` and return the resulting range(s)
+        def subtract_overlapping_range(a, b, delta: 1)
+          return [] if a == b
+
+          result = []
+
+          result << (a.begin...b.begin) if a.begin < b.begin
+
+          # If `b` is endless then the entire rest of `a` will be gone.
+          return result if b.endless?
+
+          other_begin = if b.exclude_end?
+                          b.end
+                        else
+                          delta.is_a?(Proc) ? delta.call(b.end) : b.end + delta
+                        end
+
+          result << ::Range.new(other_begin, a.end, a.exclude_end?) if a.endless? || other_begin < a.end
+
+          result
+        end
+      end
+    end
+  end
+end

data/lib/extended_range/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module ExtendedRange
+  VERSION = "0.1.0"
+end

data/lib/extended_range.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require_relative "extended_range/version"
+require_relative "core_extensions/range/operations"
+require_relative "core_extensions/range/checks"
+
+Range.include CoreExtensions::Range::Operations
+Range.include CoreExtensions::Range::Checks

metadata

@@ -0,0 +1,88 @@
+--- !ruby/object:Gem::Specification
+name: extended_range
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Anthony Felix Hernandez
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2021-09-15 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.14'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.14'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+description:
+email:
+- ant@antfeedr.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".circleci/config.yml"
+- ".gitignore"
+- ".rspec"
+- ".rubocop.yml"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- extended_range.gemspec
+- lib/core_extensions/range/checks.rb
+- lib/core_extensions/range/operations.rb
+- lib/extended_range.rb
+- lib/extended_range/version.rb
+homepage: https://github.com/hernanat/extended_range
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/hernanat/extended_range
+  source_code_uri: https://github.com/hernanat/extended_range
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.2.22
+signing_key:
+specification_version: 4
+summary: Some handy methods for the `Range` class.
+test_files: []