working_hours 0.9.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 4c941c0a9419ac6c9518eb678158e34a1bd7a1c2
+  data.tar.gz: 2d67809674b2e66e74a8df2300feba9d6afc0ed4
+SHA512:
+  metadata.gz: 22c7e703ea00a9237d6c6050dce76e48e7521c7041358eb2d6ae7d4f1fcf2a79db0557c80001e499e18a7a63af9c2f36fce7cff71204fd3bdad91040c0855300
+  data.tar.gz: 45fb3490c70fa7e22d6b92f7eebdc60ef296b185378ab62a56fd0247ca04cfb91fb4b27bf7c95179de0edb6506e5f4944aa3613d60f8d5e6d81f7a4d9a618623

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format progress

data/.travis.yml

@@ -0,0 +1,13 @@
+language: ruby
+rvm:
+  - 2.0.0
+  - 2.1.2
+  - ruby-head
+gemfile:
+  - gemfiles/Gemfile.activesupport-3.2.x
+  - gemfiles/Gemfile.activesupport-4.0.x
+  - gemfiles/Gemfile.activesupport-4.1.x
+  - gemfiles/Gemfile.activesupport-edge
+matrix:
+  allow_failures:
+    - gemfile: gemfiles/Gemfile.activesupport-edge

data/Gemfile

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

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Intrepidd
+
+MIT License
+
+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,150 @@
+# WorkingHours
+
+[![Build Status](https://travis-ci.org/Intrepidd/working_hours.svg?branch=master)](https://travis-ci.org/Intrepidd/working_hours)
+
+A modern ruby gem allowing to do time calculation with working hours.
+
+Compatible and tested with:
+- Ruby `2.0`, `2.1`
+- ActiveSupport `3.2.x`, `4.0.x` and `4.1.x`
+
+## Installation
+
+Gemfile:
+
+```ruby
+gem 'working_hours'
+```
+
+## Usage
+
+```ruby
+require 'working_hours'
+
+# Move forward
+1.working.day.from_now
+2.working.hours.from_now
+15.working.minutes.from_now
+
+# Move backward
+1.working.day.ago
+2.working.hours.ago
+15.working.minutes.ago
+
+# Start from custom Date or Time
+Date.new(2014, 12, 31) + 8.working.days # => Mon, 12 Jan 2015
+Time.utc(2014, 8, 4, 8, 32) - 4.working.hours # => 2014-08-01 13:00:00
+
+# Compute working days between two dates
+friday.working_days_until(monday) # => 1
+# Time is considered at end of day, so:
+# - friday to saturday = 0 working days
+# - sunday to monday = 1 working days
+
+# Compute working duration (in seconds) between two times
+from = Time.utc(2014, 8, 3, 8, 32) # sunday 8:32am
+to = Time.utc(2014, 8, 4, 10, 32) # monday 10:32am
+from.working_time_until(to) # => 5520 (1.hour + 32.minutes)
+
+# Know if a day is worked
+Date.new(2014, 12, 28).working_day? # => false
+
+# Know if a time is worked
+Time.utc(2014, 8, 4, 7, 16).in_working_hours? # => false
+```
+
+## Configuration
+
+The working hours configuration is thread local and consists of a hash defining working periods for each day, a time zone and a list of days off.
+
+```ruby
+# Configure working hours
+WorkingHours::Config.working_hours = {
+  :tue => {'09:00' => '12:00', '13:00' => '17:00'},
+  :wed => {'09:00' => '12:00', '13:00' => '17:00'},
+  :thu => {'09:00' => '12:00', '13:00' => '17:00'},
+  :fri => {'09:00' => '12:00', '13:00' => '17:00'},
+  :sat => {'10:00' => '15:00'}
+}
+
+# Configure timezone (uses activesupport, defaults to UTC)
+WorkingHours::Config.time_zone = 'Paris'
+
+# Configure holidays
+WorkingHours::Config.holidays = [Date.new(2014, 12, 31)]
+```
+
+> Once the config has been set, internal objects are frozen and you **can't** modify them (ex: `holidays << Date.today`). This is because the configuration is precompiled to a computing friendly form and changes would not be taken into account. To change the config you **must use** one of the 3 setters shown above.
+
+## No core extensions / monkey patching
+
+Core extensions (monkey patching to add methods on Time, Date, Numbers, etc.) are handy but not appreciated by everyone. WorkingHours can also be used **without any monkey patching**:
+
+```ruby
+require 'working_hours/module'
+
+# Move forward
+WorkingHours::Duration.new(1, :days).from_now
+WorkingHours::Duration.new(2, :hours).from_now
+WorkingHours::Duration.new(15, :minutes).from_now
+
+# Move backward
+WorkingHours::Duration.new(1, :days).ago
+WorkingHours::Duration.new(2, :hours).ago
+WorkingHours::Duration.new(15, :minutes).ago
+
+# Start from custom Date or Time
+WorkingHours::Duration.new(8, :days).since(Date.new(2014, 12, 31)) # => Mon, 12 Jan 2015
+WorkingHours::Duration.new(4, :hours).until(Time.utc(2014, 8, 4, 8, 32)) # => 2014-08-01 13:00:00
+
+# Compute working days between two dates
+WorkingHours.working_days_between(friday, monday) # => 1
+# Time is considered at end of day, so:
+# - friday to saturday = 0 working days
+# - sunday to monday = 1 working days
+
+# Compute working duration (in seconds) between two times
+from = Time.utc(2014, 8, 3, 8, 32) # sunday 8:32am
+to = Time.utc(2014, 8, 4, 10, 32) # monday 10:32am
+WorkingHours.working_time_between(from, to) # => 5520 (1.hour + 32.minutes)
+
+# Know if a day is worked
+WorkingHours.working_day?(Date.new(2014, 12, 28)) # => false
+
+# Know if a time is worked
+WorkingHours.in_working_hours?(Time.utc(2014, 8, 4, 7, 16)) # => false
+```
+
+## Use in your class/module
+
+If you want to use working hours inside a specific class or module, you can include its computation methods like this:
+
+```ruby
+require 'working_hours'
+
+class Order
+  include WorkingHours::Computation
+
+  def shipping_date_estimate
+    order_date + 2.working.days
+  end
+end
+```
+
+> This also works with zero monkey patch by requiring `working_hours/module`
+
+## Timezones
+
+This gem uses a simple but efficient approach in dealing with timezones. When you define your working hours **you have to choose** a timezome associated with it (in the config example, the working hours are in Paris time). Then, any time used in calcultation will be converted to this timezone first, so you don't have to worry if your times are local or UTC as long as they are correct :)
+
+## Alternatives
+
+There is a gem called [business_time](https://github.com/bokmann/business_time) already available to do this kind of computation and it was of great help to us. But we decided to start another one because business_time is suffering from a [few](https://github.com/bokmann/business_time/issues/50) [bugs](https://github.com/bokmann/business_time/pull/84) and inconsistencies regarding timezones. It also lacks essential features to us (like working minutes computation).
+
+## Contributing
+
+1. Fork it ( http://github.com/<my-github-username>/working_hours/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,11 @@
+require "bundler/gem_tasks"
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec
+
+desc "Open an irb session preloaded with working_hours"
+task :console do
+  sh "irb -rubygems -I lib -r working_hours.rb"
+end

data/gemfiles/Gemfile.activesupport-3.2.x

@@ -0,0 +1,5 @@
+source 'https://rubygems.org'
+
+gemspec :path => '..'
+
+gem 'activesupport', '~> 3.2'

data/gemfiles/Gemfile.activesupport-4.0.x

@@ -0,0 +1,5 @@
+source 'https://rubygems.org'
+
+gemspec :path => '..'
+
+gem 'activesupport', '~> 4.0'

data/gemfiles/Gemfile.activesupport-4.1.x

@@ -0,0 +1,5 @@
+source 'https://rubygems.org'
+
+gemspec :path => '..'
+
+gem 'activesupport', '~> 4.1'

data/gemfiles/Gemfile.activesupport-head

@@ -0,0 +1,5 @@
+source 'https://rubygems.org'
+
+gemspec :path => '..'
+
+gem 'activesupport', github: 'rails/rails'

data/lib/working_hours/computation.rb

@@ -0,0 +1,186 @@
+require 'active_support/all'
+require 'working_hours/config'
+
+module WorkingHours
+  module Computation
+
+    def add_days origin, days
+      time = in_config_zone(origin)
+      while days > 0
+        time += 1.day
+        days -= 1 if working_day?(time)
+      end
+      while days < 0
+        time -= 1.day
+        days += 1 if working_day?(time)
+      end
+      convert_to_original_format time, origin
+    end
+
+    def add_hours origin, hours
+      add_minutes origin, hours * 60
+    end
+
+    def add_minutes origin, minutes
+      add_seconds origin, minutes * 60
+    end
+
+    def add_seconds origin, seconds
+      time = in_config_zone(origin).round
+      while seconds > 0
+        # roll to next business period
+        time = advance_to_working_time(time)
+        # look at working ranges
+        time_in_day = time.seconds_since_midnight
+        wh_config[:working_hours][time.wday].each do |from, to|
+          if time_in_day >= from and time_in_day < to
+            # take all we can
+            take = [to - time_in_day, seconds].min
+            # advance time
+            time += take
+            # decrease seconds
+            seconds -= take
+          end
+        end
+      end
+      while seconds < 0
+        # roll to previous business period
+        time = return_to_working_time(time)
+        # look at working ranges
+        time_in_day = time.seconds_since_midnight
+        wh_config[:working_hours][time.wday].reverse_each do |from, to|
+          if time_in_day > from and time_in_day <= to
+            # take all we can
+            take = [time_in_day - from, -seconds].min
+            # advance time
+            time -= take
+            # decrease seconds
+            seconds += take
+          end
+        end
+      end
+      convert_to_original_format time, origin
+    end
+
+    def advance_to_working_time time
+      time = in_config_zone(time).round
+      loop do
+        # skip holidays and weekends
+        while not working_day?(time)
+          time = (time + 1.day).beginning_of_day
+        end
+        # find first working range after time
+        time_in_day = time.seconds_since_midnight
+        (Config.precompiled[:working_hours][time.wday] || {}).each do |from, to|
+          return time if time_in_day >= from and time_in_day < to
+          return time + (from - time_in_day) if from >= time_in_day
+        end
+        # if none is found, go to next day and loop
+        time = (time + 1.day).beginning_of_day
+      end
+    end
+
+    def return_to_working_time time
+      time = in_config_zone(time).round
+      loop do
+        # skip holidays and weekends
+        while not working_day?(time)
+          time = (time - 1.day).end_of_day
+        end
+        # find last working range before time
+        time_in_day = time.seconds_since_midnight
+        (Config.precompiled[:working_hours][time.wday] || {}).reverse_each do |from, to|
+          # round is used to suppress miliseconds hack from `end_of_day`
+          return time.round if time_in_day > from and time_in_day <= to
+          return (time - (time_in_day - to)).round if to <= time_in_day
+        end
+        # if none is found, go to previous day and loop
+        time = (time - 1.day).end_of_day
+      end
+    end
+
+    def working_day? time
+      time = in_config_zone(time)
+      Config.precompiled[:working_hours][time.wday].present? and not Config.precompiled[:holidays].include?(time.to_date)
+    end
+
+    def in_working_hours? time
+      time = in_config_zone(time)
+      return false if not working_day?(time)
+      time_in_day = time.seconds_since_midnight
+      Config.precompiled[:working_hours][time.wday].each do |from, to|
+        return true if time_in_day >= from and time_in_day < to
+      end
+      false
+    end
+
+    def working_days_between from, to
+      if to < from
+        -working_days_between(to, from)
+      else
+        from = in_config_zone(from)
+        to = in_config_zone(to)
+        days = 0
+        while from.to_date < to.to_date
+          from += 1.day
+          days += 1 if working_day?(from)
+        end
+        days
+      end
+    end
+
+    def working_time_between from, to
+      if to < from
+        -working_time_between(to, from)
+      else
+        from = advance_to_working_time(in_config_zone(from))
+        to = in_config_zone(to).round
+        distance = 0
+        while from < to
+          # look at working ranges
+          time_in_day = from.seconds_since_midnight
+          wh_config[:working_hours][from.wday].each do |begins, ends|
+            if time_in_day >= begins and time_in_day < ends
+              # take all we can
+              take = [ends - time_in_day, to - from].min
+              # advance time
+              from += take
+              # increase counter
+              distance += take
+            end
+          end
+          # roll to next business period
+          from = advance_to_working_time(from)
+        end
+        distance
+      end
+    end
+
+    private
+
+    def wh_config
+      WorkingHours::Config.precompiled
+    end
+
+    # fix for ActiveRecord < 4, doesn't implement in_time_zone for Date
+    def in_config_zone time
+      if time.respond_to? :in_time_zone
+        time.in_time_zone(wh_config[:time_zone])
+      elsif time.is_a? Date
+        wh_config[:time_zone].local(time.year, time.month, time.day)
+      else
+        raise TypeError.new("Can't convert #{time.class} to a Time")
+      end
+    end
+
+    def convert_to_original_format time, original
+      case original
+      when Date then time.to_date
+      when DateTime then time.to_datetime
+      when Time then time.to_time
+      else time
+      end
+    end
+
+  end
+end

data/lib/working_hours/config.rb

@@ -0,0 +1,152 @@
+require 'set'
+require 'working_hours/deep_freeze'
+
+module WorkingHours
+  InvalidConfiguration = Class.new StandardError
+
+  class Config
+    extend WorkingHours::DeepFreeze
+
+    TIME_FORMAT = /\A([0-1][0-9]|2[0-3]):([0-5][0-9])\z/
+    DAYS_OF_WEEK = [:sun, :mon, :tue, :wed, :thu, :fri, :sat]
+
+    class << self
+
+      def working_hours
+        config[:working_hours]
+      end
+
+      def working_hours=(val)
+        validate_working_hours! val
+        config[:working_hours] = deep_freeze(val)
+        config.delete :precompiled
+      end
+
+      def holidays
+        config[:holidays]
+      end
+
+      def holidays=(val)
+        validate_holidays! val
+        config[:holidays] = deep_freeze(val)
+        config.delete :precompiled
+      end
+
+      # Returns an optimized for computing version
+      def precompiled
+        config[:precompiled] ||= begin
+          compiled = {working_hours: []}
+          working_hours.each do |day, hours|
+            compiled[:working_hours][DAYS_OF_WEEK.index(day)] = {}
+            hours.each do |start, finish|
+              compiled[:working_hours][DAYS_OF_WEEK.index(day)][compile_time(start)] = compile_time(finish)
+            end
+          end
+          compiled[:holidays] = Set.new(holidays)
+          compiled[:time_zone] = time_zone
+          compiled
+        end
+      end
+
+      def time_zone
+        config[:time_zone]
+      end
+
+      def time_zone=(val)
+        zone = validate_time_zone! val
+        config[:time_zone] = zone.freeze
+        config.delete :precompiled
+      end
+
+      def reset!
+        Thread.current[:working_hours] = default_config
+      end
+
+      private
+
+      def config
+        Thread.current[:working_hours] ||= default_config
+      end
+
+      def default_config
+        {
+          working_hours: {
+            mon: {'09:00' => '17:00'},
+            tue: {'09:00' => '17:00'},
+            wed: {'09:00' => '17:00'},
+            thu: {'09:00' => '17:00'},
+            fri: {'09:00' => '17:00'}
+          }.freeze,
+          holidays: [].freeze,
+          time_zone: ActiveSupport::TimeZone['UTC'].freeze
+        }
+      end
+
+      def compile_time time
+        hour = time[TIME_FORMAT,1].to_i
+        min = time[TIME_FORMAT,2].to_i
+        hour * 3600 + min * 60
+      end
+
+      def validate_working_hours! week
+        if week.empty?
+          raise InvalidConfiguration.new "No working hours given"
+        end
+        if (invalid_keys = (week.keys - DAYS_OF_WEEK)).any?
+          raise InvalidConfiguration.new "Invalid day identifier(s): #{invalid_keys.join(', ')} - must be 3 letter symbols"
+        end
+        week.each do |day, hours|
+          if not hours.is_a? Hash
+            raise InvalidConfiguration.new "Invalid type for `#{day}`: #{hours.class} - must be Hash"
+          elsif hours.empty?
+            raise InvalidConfiguration.new "No working hours given for day `#{day}`"
+          end
+          last_time = nil
+          hours.each do |start, finish|
+            if not start =~ TIME_FORMAT
+              raise InvalidConfiguration.new "Invalid time: #{start} - must be 'HH:MM'"
+            elsif not finish =~ TIME_FORMAT
+              raise InvalidConfiguration.new "Invalid time: #{finish} - must be 'HH:MM'"
+            elsif start >= finish
+              raise InvalidConfiguration.new "Invalid range: #{start} => #{finish} - ends before it starts"
+            elsif last_time and start < last_time
+              raise InvalidConfiguration.new "Invalid range: #{start} => #{finish} - overlaps previous range"
+            end
+            last_time = finish
+          end
+        end
+      end
+
+      def validate_holidays! holidays
+        if not holidays.is_a? Array
+          raise InvalidConfiguration.new "Invalid type for holidays: #{holidays.class} - must be Array"
+        end
+        holidays.each do |day|
+          if not day.is_a? Date
+            raise InvalidConfiguration.new "Invalid holiday: #{day} - must be Date"
+          end
+        end
+      end
+
+      def validate_time_zone! zone
+        if zone.is_a? String
+          res = ActiveSupport::TimeZone[zone]
+          if res.nil?
+            raise InvalidConfiguration.new "Unknown time zone: #{zone}"
+          end
+        elsif zone.is_a? ActiveSupport::TimeZone
+          res = zone
+        else
+          raise InvalidConfiguration.new "Invalid time zone: #{zone.inspect} - must be String or ActiveSupport::TimeZone"
+        end
+        res
+      end
+
+    end
+
+    private
+
+    def initialize
+    end
+  end
+end

data/lib/working_hours/core_ext/date_and_time.rb

@@ -0,0 +1,57 @@
+require 'active_support/time_with_zone'
+require 'working_hours/module'
+
+module WorkingHours
+  module CoreExt
+    module DateAndTime
+
+      def +(other)
+        if (other.is_a?(WorkingHours::Duration))
+          other.since(self)
+        else
+          super(other)
+        end
+      end
+
+      def -(other)
+        if (other.is_a?(WorkingHours::Duration))
+          other.until(self)
+        else
+          super(other)
+        end
+      end
+
+      def working_days_until(other)
+        WorkingHours.working_days_between(self, other)
+      end
+
+      def working_time_until(other)
+        WorkingHours.working_time_between(self, other)
+      end
+
+      def working_day?
+        WorkingHours.working_day?(self)
+      end
+
+      def in_working_hours?
+        WorkingHours.in_working_hours?(self)
+      end
+    end
+  end
+end
+
+class Date
+  prepend WorkingHours::CoreExt::DateAndTime
+end
+
+class DateTime
+  prepend WorkingHours::CoreExt::DateAndTime
+end
+
+class Time
+  prepend WorkingHours::CoreExt::DateAndTime
+end
+
+class ActiveSupport::TimeWithZone
+  prepend WorkingHours::CoreExt::DateAndTime
+end

data/lib/working_hours/core_ext/fixnum.rb

@@ -0,0 +1,15 @@
+require "working_hours/duration_proxy"
+
+module WorkingHours
+  module CoreExt
+    module Fixnum
+
+      def working
+        WorkingHours::DurationProxy.new(self)
+      end
+
+    end
+  end
+end
+
+Fixnum.send(:include, WorkingHours::CoreExt::Fixnum)

data/lib/working_hours/deep_freeze.rb

@@ -0,0 +1,12 @@
+module WorkingHours
+  module DeepFreeze
+    def deep_freeze object
+      if object.is_a? Array
+        object.replace(object.dup.each { |_, value| deep_freeze(value) })
+      elsif object.is_a? Hash
+        object.replace(object.dup.each { |_, value| deep_freeze(value) })
+      end
+      object.freeze
+    end
+  end
+end