artic 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 677bcdd6f44140488725e808cc21352cae9a637d
+  data.tar.gz: f8c0969a9fe9a90483bbe8daede9739b6f59f0c2
+SHA512:
+  metadata.gz: 4892f61298533796efdb513c5f34a1a15cea5c999a9485c8da110df61482170acbbe7cbb1f33ecb84402671279a2060b8d052337f8b349a8cfa1c47edaa32f35
+  data.tar.gz: 7c4199ff8a5478a62eb36a94e02a5c0a2e15c0e929c402cb0d81df5da44abffe682b3e1f3e9988b6ec22515284f0cb837c037a44fbd864ca4ec40a1d20dc715e

data/.gitignore

@@ -0,0 +1,10 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+/spec/examples.txt

data/.rspec

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

data/.rubocop.yml

@@ -0,0 +1,62 @@
+require: rubocop-rspec
+
+AllCops:
+  TargetRubyVersion: 2.3
+  Include:
+    - '**/Gemfile'
+    - '**/Rakefile'
+  Exclude:
+   - 'bin/*'
+   - 'db/**/*'
+   - 'vendor/bundle/**/*'
+   - 'spec/spec_helper.rb'
+   - 'spec/rails_helper.rb'
+   - 'spec/support/**/*'
+   - 'config/**/*'
+   - 'Rakefile'
+   - 'Gemfile'
+
+Style/BlockDelimiters:
+  Exclude:
+    - 'spec/**/*'
+
+Style/AlignParameters:
+  EnforcedStyle: with_fixed_indentation
+
+Style/ClosingParenthesisIndentation:
+  Enabled: false
+
+Metrics/LineLength:
+  Max: 100
+  AllowURI: true
+
+Style/FirstParameterIndentation:
+  Enabled: false
+
+Style/MultilineMethodCallIndentation:
+  EnforcedStyle: indented
+
+Style/IndentArray:
+  EnforcedStyle: consistent
+
+Style/IndentHash:
+  EnforcedStyle: consistent
+
+Style/SignalException:
+  EnforcedStyle: semantic
+
+Style/BracesAroundHashParameters:
+  EnforcedStyle: context_dependent
+
+Lint/EndAlignment:
+  AlignWith: variable
+  AutoCorrect: true
+
+Style/AndOr:
+  EnforcedStyle: conditionals
+
+Metrics/MethodLength:
+  Max: 15
+
+RSpec/MessageExpectation:
+  Enabled: false

data/.travis.yml

@@ -0,0 +1,9 @@
+rvm:
+  - 2.3.0
+before_install:
+  - gem update --system
+  - gem update bundler
+  - gem cleanup bundler
+branches:
+  only:
+    - master

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in agenda.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 Alessandro Desantis
+
+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,141 @@
+# A.R.TI.C.
+
+[![Gem Version](https://img.shields.io/gem/v/artic.svg?maxAge=3600&style=flat-square)](https://rubygems.org/gems/artic)
+[![Build Status](https://img.shields.io/travis/alessandro1997/artic.svg?maxAge=3600&style=flat-square)](https://travis-ci.org/alessandro1997/artic)
+[![Dependency Status](https://img.shields.io/gemnasium/alessandro1997/artic.svg?maxAge=3600&style=flat-square)](https://gemnasium.com/github.com/alessandro1997/artic)
+[![Code Climate](https://img.shields.io/codeclimate/github/alessandro1997/artic.svg?maxAge=3600&style=flat-square)](https://codeclimate.com/github/alessandro1997/artic)
+
+**A** **R**uby gem for **TI**me **C**omputations.
+
+A.R.TI.C. can take questions like:
+
+> If I'm available 9am-5pm on Mondays and I have a meeting from 10am to 1pm and another from 3pm
+> to 4pm next Monday, when am I _free_ next Monday?
+
+And give you an answer like:
+
+> You are free in these time slots:
+>
+> - 9am-10am;
+> - 1pm-3pm;
+> - 4pm-5pm.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'artic'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install artic
+
+## Usage
+
+First of all, you will need to create a new calendar:
+
+```ruby
+calendar = Artic::Calendar.new
+```
+
+### Setting available times
+
+Now you can start defining the free slots in your calendar:
+
+```ruby
+calendar.availabilities << Artic::Availability.new(:monday, '09:00'..'11:00')
+calendar.availabilities << Artic::Availability.new(:monday, '11:00'..'13:00')
+calendar.availabilities << Artic::Availability.new(:monday, '15:00'..'19:00')
+```
+
+If you want, you can also use specific dates in place of days of the week:
+
+```ruby
+calendar.availabilities << Artic::Availability.new(Date.parse('2016-10-03'), '15:00'..'19:00')
+```
+
+Or you can mix the two! In this case, we won't consider the availability slots for that day of the
+week when calculating availabilities:
+
+```ruby
+calendar.availabilities << Artic::Availability.new(:monday, '09:00'..'17:00')
+
+# Only available 15-19 on Monday, October 3rd 2016.
+calendar.availabilities << Artic::Availability.new(Date.parse('2016-10-03'), '15:00'..'19:00')
+```
+
+### Defining occupations
+
+You can also define some specific slots when you will be busy with something:
+
+```ruby
+calendar.occupations << Artic::Occupation.new(Date.parse('2016-09-26'), '10:00'..'12:00'))
+```
+
+The times do not have to respect your availability slots:
+
+```ruby
+calendar.occupations << Artic::Occupation.new(Date.parse('2016-09-26'), '18:00'..'20:00'))
+```
+
+### Computing available slots
+
+This is where the fun part begins. Suppose you want to get your work hours on Mondays:
+
+```ruby
+calendar.available_slots_on(:monday)
+# => Artic::Collection::AvailabilityCollection[
+#   Artic::Availability<:monday, 09:00..13:00>,
+#   Artic::Availability<:monday, 15:00..19:00>
+# ]
+
+# We overrode this, remember?
+calendar.available_slots_on(Date.parse('2016-10-03'))
+# => Artic::Collection::AvailabilityCollection[
+#   Artic::Availability<2016-10-03 15:00..10:00>
+# ]
+```
+
+### Computing free slots
+
+Or maybe you want to see when you have time for a meeting a particular Monday?
+
+In that case, use `#free_slots_on` and we'll take care of removing any occupied times from your
+available slots:
+
+```ruby
+calendar.free_slots_on(Date.parse('2016-09-26'))
+# => Artic::Collection::AvailabilityCollection[
+#   Artic::Availability<2016-09-26 09:00..13:00>,
+#   Artic::Availability<2016-09-26 15:00..18:00>
+# ]
+```
+
+## Caveats
+
+- All times should be in the same timezone (ideally, UTC).
+
+## 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`. To release a new
+version, update the version number in `version.rb`, and then run `bundle exec rake release`, which
+will create a git tag for the version, push git commits and tags, and push the `.gem` file to
+[rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/alessandro1997/artic.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/artic.gemspec

@@ -0,0 +1,33 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'artic/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "artic"
+  spec.version       = Artic::VERSION
+  spec.authors       = ["Alessandro Desantis"]
+  spec.email         = ["desa.alessandro@gmail.com"]
+
+  spec.summary       = %q{A Ruby gem for time computations.}
+  spec.homepage      = "https://github.com/alessandro1997/artic"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency 'tzinfo', '~> 1.2.2'
+  spec.add_dependency 'tzinfo-data', '~> 1.2016.7'
+
+  spec.add_development_dependency "bundler"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "rspec"
+  spec.add_development_dependency "pry"
+  spec.add_development_dependency 'rubocop'
+  spec.add_development_dependency 'rubocop-rspec'
+  spec.add_development_dependency 'fuubar'
+end

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "artic"
+
+# 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

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/lib/artic.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+require 'tzinfo'
+
+require 'artic/version'
+
+require 'artic/time_range'
+
+require 'artic/availability'
+require 'artic/occupation'
+
+require 'artic/collection/availability_collection'
+require 'artic/collection/occupation_collection'
+
+require 'artic/calendar'
+
+# Artic is a Ruby gem for time computations.
+#
+# It can solve problems like: if I'm available 9am-5pm on Mondays and I have a meeting from 10am
+# to 1pm and another from 3pm to 4pm next Monday, when am I free next Monday?
+#
+# @author Alessandro Desantis
+module Artic
+end

data/lib/artic/availability.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+module Artic
+  # Availability represents a slot of time in a givn day of the week or date when you're available.
+  #
+  # @author Alessandro Desantis
+  class Availability
+    DAYS_OF_WEEK = %i(monday tuesday wednesday thursday friday saturday sunday).freeze
+
+    # @!attribute [r] day_of_week
+    #   @todo Rename to +wday+
+    #   @return [Symbol] the day of the week, as a lowercase symbol (e.g. +:monday+)
+    #
+    # @!attribute [r] date
+    #   @return [Date] the date of this availability
+    #
+    # @!attribute [r] time_range
+    #   @return [TimeRange] the time range of this availability
+    attr_reader :day_of_week, :date, :time_range
+
+    # Initializes the availability.
+    #
+    # @param dow_or_date [Symbol|Date] a day of the week (e.g. +:monday+) or date
+    # @param time_range [TimeRange|Range] a time range
+    #
+    # @raise [ArgumentError] if an invalid day of the week is passed
+    def initialize(dow_or_date, time_range)
+      @date = dow_or_date if dow_or_date.is_a?(Date)
+      @day_of_week = (@date ? @date.strftime('%A').downcase : dow_or_date).to_sym
+      @time_range = TimeRange.build(time_range)
+
+      validate_day_of_week
+    end
+
+    # Returns the identifier used to create this availability (i.e. either a day of the week or
+    # date).
+    #
+    # @return [Date|Symbol]
+    def identifier
+      date || day_of_week
+    end
+
+    # Returns whether the availability is appliable to the given date (i.e. the date is the same
+    # or the weekday is the same).
+    #
+    # @param date [Date]
+    #
+    # @return [Boolean]
+    def for_date?(date)
+      if self.date
+        self.date == date
+      else
+        day_of_week == date.strftime('%A').downcase.to_sym
+      end
+    end
+
+    # Determines whether this availability and the one passed as an argument represent the same
+    # day/time range combination, by checking for equality of both the identifier and the time
+    # range.
+    #
+    # @param other [Availability]
+    #
+    # @return [Boolean]
+    def ==(other)
+      identifier == other.identifier && time_range == other.time_range
+    end
+
+    # Returns whether this availability should be before, after or in the same position of the
+    # availability passed as an argument, by following these rules:
+    #
+    #   * availabilities with a weekday come before those with a date;
+    #   * if both availabilities are for a weekday, the day and time ranges are compared;
+    #   * if both availabilities are for a date, the date and time ranges are compared.
+    #
+    # @return [Fixnum] -1 if this availability should come before the argument, 0 if it should
+    #   be at the same position, 1 if it should come after the argument.
+    #
+    # @see TimeRange#<=>
+    def <=>(other)
+      # availabilities for weekdays come before availabilities for specific dates
+      return -1 if date.nil? && !other.date.nil?
+      return 1 if !date.nil? && other.date.nil?
+
+      if date.nil? && other.date.nil? # both availabilities are for a weekday
+        if day_of_week == other.day_of_week # availabilities are for the same weekday
+          time_range.min <=> other.time_range.min # compare times
+        else # availabilities are for different weekdays
+          index1 = DAYS_OF_WEEK.index(day_of_week)
+          index2 = DAYS_OF_WEEK.index(other.day_of_week)
+
+          index1 <=> index2 # compares weekdays
+        end
+      else # both availabilities are for a date
+        if date == other.date # both availabilities are for the same date
+          time_range.min <=> other.time_range.min # compare times
+        else # availabilities are for different dates
+          date <=> other.date # compare dates
+        end
+      end
+    end
+
+    private
+
+    def validate_day_of_week
+      fail(
+        ArgumentError,
+        "#{day_of_week} is not a valid day of the week"
+      ) unless DAYS_OF_WEEK.include?(day_of_week)
+    end
+  end
+end

data/lib/artic/calendar.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+module Artic
+  # A calendar keeps track of both your availabilities and your occupations.
+  #
+  # @author Alessandro Desantis
+  class Calendar
+    # @!attribute [r] availabilities
+    #   @return [Collection::AvailabilityCollection]
+    #
+    # @!attribute [r] occupations
+    #   @return [Collection::OccupationCollection]
+    attr_reader :availabilities, :occupations
+
+    # Initializes the calendar.
+    def initialize
+      @availabilities = Collection::AvailabilityCollection.new
+      @occupations = Collection::OccupationCollection.new
+    end
+
+    # Returns the slots available on the given day of the week or date, including any slots that
+    # might be occupied on the given date.
+    #
+    # If the passed argument is an instance of +Date+ but no availabilities have been defined
+    # for that specific date, returns any availabilities defined for that day of the week.
+    #
+    # @param dow_or_date [Date|Symbol] a day of the week or date
+    #
+    # @return Collection::AvailabilityCollection
+    #
+    # @example
+    #   calendar.available_slots_on(:monday) # => #<Artic::Collection::AvailabilityCollection>
+    # @example
+    #   calendar.available_slots_on(Date.tomorrow) # => #<Artic::Collection::AvailabilityCollection>
+    #
+    # @see Collection::AvailabilityCollection#normalize
+    def available_slots_on(dow_or_date)
+      if !availabilities.identifier?(dow_or_date) && dow_or_date.is_a?(Date) && availabilities.identifier?(dow_or_date.strftime('%A').downcase)
+        return available_slots_on(dow_or_date.strftime('%A').downcase)
+      end
+
+      availabilities.normalize dow_or_date
+    end
+
+    # Returns the slots free on the given date, computed by calling {Occupation#bisect} on each
+    # of the availability slots.
+    #
+    # @param date [Date]
+    #
+    # @return Collection::AvailabilityCollection
+    #
+    # @see Collection::OccupationCollection#bisect
+    def free_slots_on(date)
+      availabilities = available_slots_on(date).flat_map do |availability|
+        occupations.bisect(availability)
+      end
+
+      Collection::AvailabilityCollection.new availabilities
+    end
+  end
+end

data/lib/artic/collection/availability_collection.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+module Artic
+  module Collection
+    # Keeps a collection of availabilities and performs calculations on them.
+    #
+    # @author Alessandro Desantis
+    class AvailabilityCollection < Array
+      # Returns all the identifiers in this collection.
+      #
+      # @return [Array<Symbol|Date>]
+      def identifiers
+        map(&:identifier).uniq
+      end
+
+      # Returns whether an identifier exists in this collection.
+      #
+      # @param identifier [Symbol,Date]
+      #
+      # @return [Boolean]
+      def identifier?(identifier)
+        identifiers.include? cast_identifier(identifier)
+      end
+
+      # Returns all the availabilities with the given identifier, without normalizing them.
+      #
+      # @param identifier [Symbol|Date] a weekday or a date
+      #
+      # @return AvailabilityCollection
+      def by_identifier(identifier)
+        identifier = cast_identifier identifier
+        availabilities = select { |availability| availability.identifier == identifier }
+        self.class.new availabilities
+      end
+
+      # Normalizes all the availabilities with the given identifier in this collection by sorting
+      # them and merging any contiguous availability slots.
+      #
+      # @param identifier [Symbol|Date]
+      #
+      # @return AvailabilityCollection
+      def normalize(identifier)
+        availabilities = by_identifier(identifier).sort
+
+        normalized_availabilities = availabilities.inject([]) do |accumulator, availability|
+          next (accumulator << availability) if accumulator.empty?
+
+          last_availability = accumulator.pop
+
+          next (
+            accumulator + [last_availability, availability]
+          ) unless last_availability.time_range.overlaps?(availability.time_range)
+
+          new_time_range = Range.new(
+            [last_availability.time_range.min, availability.time_range.min].min,
+            [last_availability.time_range.max, availability.time_range.max].max
+          )
+
+          accumulator << Availability.new(availability.identifier, new_time_range)
+        end
+
+        self.class.new normalized_availabilities
+      end
+
+      # Normalizes all the availabilities in this collection by sorting them and merging any
+      # contiguous availability slots.
+      #
+      # @return AvailabilityCollection
+      #
+      # @see #normalize
+      def normalize_all
+        normalized_availabilities = identifiers.flat_map do |identifier|
+          normalize identifier
+        end
+
+        self.class.new normalized_availabilities.sort
+      end
+
+      private
+
+      def cast_identifier(identifier)
+        identifier.is_a?(String) ? identifier.to_sym : identifier
+      end
+    end
+  end
+end

data/lib/artic/collection/occupation_collection.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+module Artic
+  module Collection
+    # Keeps a collection of occupations.
+    #
+    # @author Alessandro Desantis
+    class OccupationCollection < Array
+      # Returns all the dates in this collection.
+      #
+      # @return [Array<Date>]
+      def dates
+        map(&:date).uniq
+      end
+
+      # Returns whether a date exists in this collection.
+      #
+      # @param date [Date]
+      #
+      # @return [Boolean]
+      def date?(date)
+        dates.include? date
+      end
+
+      # Returns all the occupations for the given date, without normalizing them.
+      #
+      # @param date [Date]
+      #
+      # @return OccupationCollection
+      def by_date(date)
+        occupations = select { |occupation| occupation.date == date }
+        self.class.new occupations
+      end
+
+      # Normalizes all the occupations with the given identifier in this collection by sorting
+      # them and merging any contiguous availability slots.
+      #
+      # @param date [Date]
+      #
+      # @return AvailabilityCollection
+      def normalize(date)
+        occupations = by_date(date).sort
+
+        normalized_occupations = occupations.inject([]) do |accumulator, occupation|
+          next (accumulator << occupation) if accumulator.empty?
+
+          last_occupation = accumulator.pop
+
+          next (
+            accumulator + [last_occupation, occupation]
+          ) unless last_occupation.time_range.overlaps?(occupation.time_range)
+
+          new_time_range = Range.new(
+            [last_occupation.time_range.min, occupation.time_range.min].min,
+            [last_occupation.time_range.max, occupation.time_range.max].max
+          )
+
+          accumulator << Occupation.new(occupation.date, new_time_range)
+        end
+
+        self.class.new normalized_occupations
+      end
+
+      # Normalizes all the occupations in this collection by sorting them and merging any
+      # contiguous availability slots.
+      #
+      # @return OccupationCollection
+      #
+      # @see #normalize
+      def normalize_all
+        normalized_occupations = dates.sort.flat_map do |date|
+          normalize date
+        end
+
+        self.class.new normalized_occupations
+      end
+
+      # Sorts the occupations in the collection, then bisects the availability until all the
+      # occupations have been accounted for.
+      #
+      # @param availability [Availability]
+      #
+      # @return AvailabilityCollection
+      #
+      # @see Occupation#bisect
+      def bisect(availability)
+        availabilities = normalize_all.inject([availability]) do |accumulator, occupation|
+          accumulator + occupation.bisect(accumulator.pop)
+        end
+
+        AvailabilityCollection.new availabilities
+      end
+    end
+  end
+end

data/lib/artic/occupation.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+module Artic
+  # An occupation represents a slot of time in a given date where you are not available.
+  #
+  # @author Alessandro Desantis
+  class Occupation
+    attr_reader :date, :time_range
+
+    # Initializes the occupation.
+    #
+    # @param date [Date] the date of the occupation
+    # @param time_range [TimeRange|Range] the time range of the occupation
+    def initialize(date, time_range)
+      @date = date
+      @time_range = TimeRange.build(time_range)
+    end
+
+    # Converts the occupation to a range of +DateTime+ objects.
+    #
+    # @return [Range]
+    #
+    # @see TimeRange#with_date
+    def to_range
+      time_range.with_date(date)
+    end
+
+    # Returns whether the occupation overlaps the availability (i.e. whether there's at least one
+    # moment in time shared by both the availability and the occupation).
+    #
+    # @param availability [Availability]
+    #
+    # @return [Boolean]
+    def overlaps?(availability)
+      return false unless availability.for_date?(date)
+
+      availability_range = availability.time_range.with_date(date)
+      (availability_range.min <= to_range.max) && (availability_range.max >= to_range.min)
+    end
+
+    # Returns whether the occupation covers the availability (i.e. whether all moments of the
+    # availability are also part of the occupation).
+    #
+    # @param availability [Availability]
+    #
+    # @return [Boolean]
+    def covers?(availability)
+      return false unless availability.for_date?(date)
+
+      availability_range = availability.time_range.with_date(date)
+      to_range.min <= availability_range.min && to_range.max >= availability_range.max
+    end
+
+    # Determines whether this occupation and the one passed as an argument represent the same
+    # day/time range combination, by checking for equality of both the date and the time
+    # range.
+    #
+    # @param other [Occupation]
+    #
+    # @return [Boolean]
+    def ==(other)
+      date == other.date && time_range == other.time_range
+    end
+
+    # Compares this occupation with another one by comparing their ranges' start.
+    #
+    # @param other [Occupation]
+    #
+    # @return [Fixnum] -1 if this occupation should come before the other one, 0 if it should be
+    #   in the same position, 1 if it should come after the other one
+    def <=>(other)
+      to_range.min <=> other.to_range.min
+    end
+
+    # Reduces the time range of the given availability or bisects it into two availabilities,
+    # depending on where the occupation falls within the availability.
+    #
+    # If the occupation completely covers the availability, returns an empty collection.
+    #
+    # If the occupation does not overlap the availability at all, returns a collection with
+    # the original availability.
+    #
+    # @param availability [Availability]
+    #
+    # @return Collection::AvailabilityCollection a collection of availabilities where the time
+    #   slot assigned to the occupation has been removed
+    #
+    # @example
+    #   occupation = Artic::Occupation.new(Date.today, '08:00'..'14:00')
+    #   availability = Artic::Availability.new(Date.today, '09:00'..'18:00')
+    #
+    #   occupation.bisect(availability)
+    #   # => [
+    #   #   #<Artic::Availability 14:00..18:00>
+    #   # ]
+    #
+    # @example
+    #   occupation = Artic::Occupation.new(Date.today, '12:00'..'14:00')
+    #   availability = Artic::Availability.new(Date.today, '09:00'..'18:00')
+    #
+    #   occupation.bisect(availability)
+    #   # => [
+    #   #   #<Artic::Availability 09:00..12:00>,
+    #   #   #<Artic::Availability 14:00..18:00>
+    #   # ]
+    #
+    # @example
+    #   occupation = Artic::Occupation.new(Date.today, '16:00'..'20:00')
+    #   availability = Artic::Availability.new(Date.today, '09:00'..'18:00')
+    #
+    #   occupation.bisect(availability)
+    #   # => [
+    #   #   #<Artic::Availability 09:00..16:00>
+    #   # ]
+    def bisect(availability)
+      return Collection::AvailabilityCollection.new if covers?(availability)
+      return Collection::AvailabilityCollection.new([availability]) unless overlaps?(availability)
+
+      bisected_ranges = time_range.bisect(availability.time_range)
+
+      availabilities = bisected_ranges.map do |bisected_range|
+        Availability.new(date, bisected_range)
+      end
+
+      Collection::AvailabilityCollection.new availabilities
+    end
+  end
+end

data/lib/artic/time_range.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+module Artic
+  # Represents a range of two times in the same day (e.g. 09:00-17:00).
+  #
+  # @author Alessandro Desantis
+  class TimeRange < Range
+    TIME_REGEX = /\A^(0\d|1\d|2[0-3]):[0-5]\d$\z/
+
+    class << self
+      # Builds a time range from the provided value.
+      #
+      # @param range [Range|TimeRange] a range of times (e.g. +'09:00'..'18:00'+ or
+      #   a +TimeRange+ object)
+      #
+      # @return [TimeRange] the passed time range or a new time range
+      def build(range)
+        range.is_a?(TimeRange) ? range : TimeRange.new(range.min, range.max)
+      end
+    end
+
+    # Initializes a new range.
+    #
+    # @param min [String] the start time (in HH:MM format)
+    # @param max [String] the end time (in HH:MM format)
+    #
+    # @raise [ArgumentError] if the start time or the end time is invalid
+    # @raise [ArgumentError] if the start time is after the end time
+    def initialize(min, max)
+      super
+      validate_range
+    end
+
+    # Returns whether the two ranges overlap (i.e. whether there's at least a moment in time that
+    # belongs to both ranges).
+    #
+    # @param other [TimeRange]
+    #
+    # @return [Boolean]
+    def overlaps?(other)
+      min <= other.max && max >= other.min
+    end
+
+    # Returns whether this range completely covers the one given.
+    #
+    # @param other [TimeRange]
+    #
+    # @return [Boolean]
+    def covers?(other)
+      min <= other.min && max >= other.max
+    end
+
+    # Returns a range of +DateTime+ objects for this time range.
+    #
+    # @param date [Date] the date to use for the range
+    #
+    # @return [Range]
+    def with_date(date)
+      Range.new(
+        DateTime.parse("#{date} #{min}"),
+        DateTime.parse("#{date} #{max}")
+      )
+    end
+
+    # Uses this range to bisect another.
+    #
+    # If this range does not overlap the other, returns an array with the original range.
+    #
+    # If this range completely covers the other, returns an empty array.
+    #
+    # @param other [TimeRange]
+    #
+    # @return [Array<TimeRange>]
+    #
+    # @example
+    #   range1 = TimeRange.new('10:00'..'12:00')
+    #   range2 = TimeRange.new('09:00'..'18:00')
+    #   range3 = TimeRange.new('08:00'..'11:00')
+    #
+    #   range1.bisect(range2)
+    #   # => [
+    #   #   #<TimeRange 09:00..10:00>,
+    #   #   #<TimeRange 12:00..18:00>
+    #   # ]
+    #
+    #   range2.bisect(range1)
+    #   # => []
+    #
+    #   range3.bisect(range2)
+    #   # => [
+    #   #   #<TimeRange 11:00..18:00>
+    #   # ]
+    #
+    #   range2.bisect(range3)
+    #   # => [
+    #   #   #<TimeRange 08:00..09:00>
+    #   # ]
+    def bisect(other)
+      return [other] unless overlaps?(other)
+      return [] if covers?(other)
+
+      if min <= other.min && max <= other.max
+        [max..other.max]
+      elsif min >= other.min && max <= other.max
+        [
+          (other.min..min),
+          (max..other.max)
+        ]
+      elsif min >= other.min && max >= other.max
+        [other.min..min]
+      end
+    end
+
+    private
+
+    def validate_range
+      fail(
+        ArgumentError,
+        "#{min} is not a valid time"
+      ) unless min =~ TIME_REGEX
+
+      fail(
+        ArgumentError,
+        "#{max} is not a valid time"
+      ) unless max =~ TIME_REGEX
+
+      fail(
+        ArgumentError,
+        "#{min} is greater than #{max}"
+      ) if min > max
+    end
+  end
+end

data/lib/artic/version.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+module Artic
+  VERSION = '1.0.0'
+end

metadata

@@ -0,0 +1,189 @@
+--- !ruby/object:Gem::Specification
+name: artic
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Alessandro Desantis
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2016-10-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: tzinfo
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.2.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.2.2
+- !ruby/object:Gem::Dependency
+  name: tzinfo-data
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.2016.7
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.2016.7
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: fuubar
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: 
+email:
+- desa.alessandro@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".rubocop.yml"
+- ".travis.yml"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- artic.gemspec
+- bin/console
+- bin/setup
+- lib/artic.rb
+- lib/artic/availability.rb
+- lib/artic/calendar.rb
+- lib/artic/collection/availability_collection.rb
+- lib/artic/collection/occupation_collection.rb
+- lib/artic/occupation.rb
+- lib/artic/time_range.rb
+- lib/artic/version.rb
+homepage: https://github.com/alessandro1997/artic
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.5.1
+signing_key: 
+specification_version: 4
+summary: A Ruby gem for time computations.
+test_files: []