time_frame 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 45120e4f1dda9a59b63972c578060e6e94863907
+  data.tar.gz: 60bea2d8848eeb0fd283bd8b7d484341944cae63
+SHA512:
+  metadata.gz: 40e9e0a39e8a81cfe6b0c31c7d0124c7f5e8eb99a741af5d1ab1dd808e123b91afdac459801fa8de1ceb69c5c88f8e7eeea0b12a74f84e100510a0de8167914d
+  data.tar.gz: 270624b7fdde20d0f3a37cc4be3b72a4189313554fc00d851fa56f0394d675849c2d60c0817a0ccdb4cddf89cd8f0f70c8c796f4dc59c10caf4e05e1728aaa9e

data/.gitignore

@@ -0,0 +1,20 @@
+.DS_Store
+*~
+.#*
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+*.swp
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.rubocop.yml

@@ -0,0 +1,12 @@
+AllCops:
+  Exclude: []
+
+# Setting the line length to a maximum of 80 chars.
+LineLength:
+  Enabled: true
+  Max: 80
+
+# Disabling the regex checks for now, since it fails with some generated gemspec
+# lines.
+RegexpLiteral:
+  Enabled: false

data/.ruby-version

@@ -0,0 +1 @@
+2.1.2

data/Gemfile

@@ -0,0 +1,17 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in plan-logic.gemspec
+gemspec
+
+gem 'bundler'
+gem 'rake'
+
+group :development, :test do
+  gem 'rubocop'
+  gem 'geminabox'
+end
+
+group :test do
+  gem 'simplecov'
+  gem 'rspec'
+end

data/Gemfile.lock

@@ -0,0 +1,84 @@
+PATH
+  remote: .
+  specs:
+    time_frame (0.0.0)
+      activesupport (~> 4.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activesupport (4.1.1)
+      i18n (~> 0.6, >= 0.6.9)
+      json (~> 1.7, >= 1.7.7)
+      minitest (~> 5.1)
+      thread_safe (~> 0.1)
+      tzinfo (~> 1.1)
+    ast (2.0.0)
+    builder (3.2.2)
+    diff-lcs (1.2.5)
+    docile (1.1.3)
+    faraday (0.9.0)
+      multipart-post (>= 1.2, < 3)
+    geminabox (0.12.4)
+      builder
+      faraday
+      httpclient (>= 2.2.7)
+      nesty
+      sinatra (>= 1.2.7)
+    httpclient (2.3.4.1)
+    i18n (0.6.9)
+    json (1.8.1)
+    minitest (5.3.3)
+    multi_json (1.10.0)
+    multipart-post (2.0.0)
+    nesty (1.0.2)
+    parser (2.1.9)
+      ast (>= 1.1, < 3.0)
+      slop (~> 3.4, >= 3.4.5)
+    powerpack (0.0.9)
+    rack (1.5.2)
+    rack-protection (1.5.3)
+      rack
+    rainbow (2.0.0)
+    rake (10.3.1)
+    rspec (2.14.1)
+      rspec-core (~> 2.14.0)
+      rspec-expectations (~> 2.14.0)
+      rspec-mocks (~> 2.14.0)
+    rspec-core (2.14.8)
+    rspec-expectations (2.14.5)
+      diff-lcs (>= 1.1.3, < 2.0)
+    rspec-mocks (2.14.6)
+    rubocop (0.21.0)
+      json (>= 1.7.7, < 2)
+      parser (~> 2.1.9)
+      powerpack (~> 0.0.6)
+      rainbow (>= 1.99.1, < 3.0)
+      ruby-progressbar (~> 1.4)
+    ruby-progressbar (1.5.0)
+    simplecov (0.8.2)
+      docile (~> 1.1.0)
+      multi_json
+      simplecov-html (~> 0.8.0)
+    simplecov-html (0.8.0)
+    sinatra (1.4.5)
+      rack (~> 1.4)
+      rack-protection (~> 1.4)
+      tilt (~> 1.3, >= 1.3.4)
+    slop (3.5.0)
+    thread_safe (0.3.3)
+    tilt (1.4.1)
+    tzinfo (1.1.0)
+      thread_safe (~> 0.1)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler
+  geminabox
+  rake
+  rspec
+  rubocop
+  simplecov
+  time_frame!

data/README.md

@@ -0,0 +1,120 @@
+# TimeFrame
+
+## Description
+
+The time frame class provides an specialized and enhanced frame for time values.
+
+## Installation
+
+`gem install time_frame`
+
+## Usage
+
+You can create a `TimeFrame` instance by specifying `min` and `max`
+
+```ruby
+time_frame = TimeFrame.new(min: Time.now, max: Time.now + 1.day)
+```
+
+or just by specifying a `min` and `duration`
+
+```ruby
+time_frame = TimeFrame.new(min: Time.now, duration: 1.day)
+```
+
+Let's play around a bit:
+
+```ruby
+# Create a time frame instance from today with duration of 1 day
+time_frame = TimeFrame.new(min: Time.now, duration: 1.day)
+# => 2014-05-07 14:58:47 +0200..2014-05-08 14:58:47 +0200
+
+# Get the duration
+time_frame.duration
+# => 86400.0 seconds
+
+# Shift the whole time frame by... let's say... 2 days!
+later = time_frame.shift_by(2.days)
+# => 2014-05-09 14:58:47 +0200..2014-05-10 14:58:47 +0200
+
+# Shifting can also be done in the other direction...
+earlier = time_frame.shift_by(-2.days)
+# => 2014-05-05 14:58:47 +0200..2014-05-06 14:58:47 +0200
+
+# Is another time covered by our time frame?
+my_time = Time.new(2014, 5, 7, 16)
+time_frame.cover?(my_time)
+# => true
+
+# Deviation to another time?
+earlier_time = time_frame.min - 1.day
+later_time = time_frame.max + 4.days
+time_frame.deviation_of(earlier_time)
+# => -86400.0
+time_frame.deviation_of(later_time)
+# => 345600.0
+# No deviation expected here:
+time_frame.deviation_of(time_frame.min + 20.minutes)
+# => 0
+# ... yay!
+
+# Shifting to another time... duration remains:
+time_frame.shift_to(Time.new(2016, 1, 1))
+# => 2016-01-01 00:00:00 +0100..2016-01-02 00:00:00 +0100
+
+# Checking whether another time frame overlaps:
+other_frame = TimeFrame.new(
+  min: time_frame.min - 3.days,
+  max: time_frame.min + 40.minutes
+)
+time_frame.overlaps?(other_frame)
+# => true
+
+# Time frame without another time frame:
+time_frame = TimeFrame.new(min: Time.new(2014, 5, 12), duration: 1.day)
+# => 2014-05-12 00:00:00 +0200..2014-05-13 00:00:00 +0200
+other = TimeFrame.new(min: Time.new(2014, 5, 12, 19), duration: 10.minutes)
+# => 2014-05-12 19:00:00 +0200..2014-05-12 19:10:00 +0200
+time_frame.without(other)
+# => [2014-05-12 00:00:00 +0200..2014-05-12 19:00:00 +0200, 2014-05-12 19:10:00 +0200..2014-05-13 00:00:00 +0200]
+another = other.shift_by(15.minutes)
+# => 2014-05-12 19:15:00 +0200..2014-05-12 19:25:00 +0200
+# You can also use an array for substraction:
+time_frame.without(*[other, another])
+# => [2014-05-12 00:00:00 +0200..2014-05-12 19:00:00 +0200, 2014-05-12 19:10:00 +0200..2014-05-12 19:15:00 +0200, 2014-05-12 19:25:00 +0200..2014-05-13 00:00:00 +0200]
+
+# Use of the mathematical &. The intersection is returned:
+time_frame = TimeFrame.new(min: Time.new(2014), duration: 1.day)
+# => 2014-01-01 00:00:00 +0100..2014-01-02 00:00:00 +0100
+other_time_frame = time_frame.shift_by(12.hours)
+# => 2014-01-01 12:00:00 +0100..2014-01-02 12:00:00 +0100
+time_frame & other_time_frame
+# => 2014-01-01 12:00:00 +0100..2014-01-02 00:00:00 +0100
+
+```
+
+These are the most common functionalities of the `TimeFrame` class, but there is quite more to discover. If you have an array of time frames, you can compute their union and pairwise intersection using `TimeFrame.union` and `TimeFrame.intersection`. For two sorted arrays of time frames, you can traverse all overlaps of time frames in the first array with time frames in the second array in **linear time** using `TimeFrame.each_overlap`.
+
+```ruby
+
+# each_overlap in a real life sample:
+
+husband_at_home = [
+  TimeFrame.new(min: Time.new(2014, 2, 1), duration: 2.days),
+  TimeFrame.new(min: Time.new(2014, 5, 1), duration: 4.days),
+  TimeFrame.new(min: Time.new(2014, 7, 1), duration: 10.days)
+]
+
+mother_in_law_visits = [
+  TimeFrame.new(min: Time.new(2014, 2, 2), duration: 1.days),
+  TimeFrame.new(min: Time.new(2014, 7, 3), duration: 2.days)
+]
+
+TimeFrame.each_overlap(mother_in_law_visits, husband_at_home) do |overlap|
+  puts "Houston... we have a problem... from #{overlap.min} to #{overlap.max}"
+end
+
+```
+
+## Does `TimeFrame` inherit from `Range`?
+No. Ruby's `Range` class is multi-purpose, it can hold contiuous values (like floats), as well as discrete values (like integers) and behaves differently according to their type. Instance methods like `#each` or `#size` just don't make sense for time values, the same is true for all methods provided by the `Enumerable` mixin.

data/Rakefile

@@ -0,0 +1,9 @@
+require 'rspec/core/rake_task'
+require 'rubocop/rake_task'
+require 'bundler/gem_tasks'
+
+Rubocop::RakeTask.new
+
+RSpec::Core::RakeTask.new :spec
+
+task default: [:spec, :rubocop]

data/lib/time_frame.rb

@@ -0,0 +1,11 @@
+require 'active_support/core_ext'
+
+# avoid i18n deprecation warning
+I18n.enforce_available_locales = false
+
+require 'time_frame/time_frame_splitter'
+require 'time_frame/time_frame_covered'
+require 'time_frame/time_frame_overlaps'
+require 'time_frame/time_frame_uniter'
+
+require 'time_frame/time_frame'

data/lib/time_frame/time_frame.rb

@@ -0,0 +1,124 @@
+# class that models a time frame
+class TimeFrame
+  include Splitter
+  attr_reader :min, :max
+
+  def initialize(args)
+    min = args.fetch(:min)
+    max = args.fetch(:max, nil) || min + args.fetch(:duration)
+    check_bounds(max, min)
+    @max = max
+    @min = min
+  end
+
+  def duration
+    (max - min).seconds
+  end
+
+  def ==(other)
+    min == other.min &&
+      max == other.max
+  end
+
+  def cover?(element)
+    if element.respond_to?(:min) && element.respond_to?(:max)
+      return min <= element.min && element.max <= max
+    end
+    min <= element && element <= max
+  end
+
+  def deviation_of(item)
+    case
+    when item.respond_to?(:min) && item.respond_to?(:max)
+      [deviation_of(item.min), deviation_of(item.max)].min_by { |a| a.abs }
+    when cover?(item)
+      0
+    when item < min
+      item - min
+    else
+      item - max
+    end
+  end
+
+  def empty?
+    min == max
+  end
+
+  def self.union(time_frames, options = {})
+    Uniter.new(time_frames, options).unite
+  end
+
+  def self.intersection(time_frames)
+    time_frames.reduce(time_frames.first) do |intersection, time_frame|
+      return unless intersection
+      intersection & time_frame
+    end
+  end
+
+  # Returns true if the interior intersect.
+  def overlaps?(other)
+    other.max > min && other.min < max
+  end
+
+  def &(other)
+    new_min = [min, other.min].max
+    new_max = [max, other.max].min
+    TimeFrame.new(min: new_min, max: new_max) if new_min <= new_max
+  end
+
+  def shift_by(duration)
+    TimeFrame.new(min: @min + duration, duration: self.duration)
+  end
+
+  def shift_to(time)
+    TimeFrame.new(min: time, duration: duration)
+  end
+
+  def without(*args)
+    frames = args.select { |frame| overlaps?(frame) }
+    frames = TimeFrame.union(frames)
+
+    frames.reduce([self]) do |result, frame_to_exclude|
+      last_frame = result.pop
+      result + last_frame.without_frame(frame_to_exclude)
+    end
+  end
+
+  def self.covering_time_frame_for(time_frames)
+    CoveredFrame.new(time_frames).frame
+  end
+
+  def self.each_overlap(frames1, frames2)
+    Overlaps.new(frames1, frames2).each do |first, second|
+      yield(first, second)
+    end
+  end
+
+  def inspect
+    "#{min}..#{max}"
+  end
+
+  protected
+
+  def without_frame(other)
+    intersection = self & other
+    # this case is never used up to now (15.03.2013),
+    # since without selects the values correctly
+    return [self] unless intersection
+
+    result = []
+    if intersection.min > min
+      result << TimeFrame.new(min: min, max: intersection.min)
+    end
+    if intersection.max < max
+      result << TimeFrame.new(min: intersection.max, max: max)
+    end
+    result
+  end
+
+  private
+
+  def check_bounds(max, min)
+    fail ArgumentError, 'min is greater than max.' if min > max
+  end
+end

data/lib/time_frame/time_frame_covered.rb

@@ -0,0 +1,15 @@
+class TimeFrame
+  # Getting the covering time frame from a bunch of time_frame's.
+  class CoveredFrame
+    def initialize(time_frames)
+      @time_frames = time_frames
+    end
+
+    def frame
+      return nil unless @time_frames.any?
+      min = @time_frames.min_by(&:min).min
+      max = @time_frames.max_by(&:max).max
+      TimeFrame.new(min: min, max: max)
+    end
+  end
+end

data/lib/time_frame/time_frame_overlaps.rb

@@ -0,0 +1,47 @@
+class TimeFrame
+  # Traverses all intersections of in the cross product of two arrays of
+  # time_frames and yields the block for each pair (linear runtime)
+  #
+  # NOTE:
+  # * requires each of the arrays to consist of pairwise disjoint elements
+  # * requires each of the arrays to be sorted
+  class Overlaps
+    def initialize(array1, array2)
+      @array1 = array1.dup
+      @array2 = array2.dup
+    end
+
+    def each(&block)
+      return [] if @array1.empty? || @array2.empty?
+      yield_current_items(&block) if current_items_overlapping?
+      while arrays_have_many_items?
+        shift
+        yield_current_items(&block) if current_items_overlapping?
+      end
+    end
+
+    private
+
+    def shift
+      if @array2.one? ||
+          @array1.many? && @array1.second.min < @array2.second.min
+        @array1.shift
+      else
+        @array2.shift
+      end
+    end
+
+    def arrays_have_many_items?
+      @array1.many? || @array2.many?
+    end
+
+    def yield_current_items
+      yield @array1.first, @array2.first
+    end
+
+    def current_items_overlapping?
+      time_frame = @array1.first & @array2.first
+      time_frame && time_frame.duration > 0
+    end
+  end
+end