continuance 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 1ecc48f905df3cf9c02090295747570b3bf66e71
+  data.tar.gz: 1f21afe9f4c2d9772bc075e8a6bfe37569aee0f9
+SHA512:
+  metadata.gz: c0436131cd8662586b5fd6c320edd0618d032b6759946cce8a2439048c86509269461bd52666b805cc80feb7cb20cbbca8c717b7bb73615ea150618ef0433702
+  data.tar.gz: 244d4ab1500e50b139c0b55c50565f759c64b8c8807efdf4755a0b6c93c0bfa973846182f5aa04a9fef6e1f630740a6f3975916160a09f4ef2e10799d9a1320d

data/README.md

@@ -0,0 +1,71 @@
+Continuance
+===========
+
+Continuance is a library for handling duration as opposed to absolute time.
+At present the minimum resolution for measuring duration in Continuance is in hours, with
+the maximum resolution being a nanosecond.
+
+Current Build Status:
+[ ![Codeship Status for shirren/continuance](https://codeship.com/projects/c20de200-f6d0-0132-1815-2e788669a94e/status?branch=master)](https://codeship.com/projects/86171)
+
+## Installation
+
+The continuance gem runs with all Ruby versions >= 1.9.3.
+
+```ruby
+gem 'continuance'
+```
+
+## Example
+
+To create a duration of 1 hour is simply.
+
+```ruby
+Continuance::Duration.new(1, 0, 0, 0)
+```
+
+or with a named argument.
+
+```ruby
+Continuance::Duration.new(hours = 1)
+```
+
+To create a duration of 1 hour and 5 minutes is simply.
+
+```ruby
+Continuance::Duration.new(1, 5, 0, 0)
+```
+
+Once again named arguments can be used if preferred. Now to create a more complex duration of 1 hour, 10 minutes, 23.005 seconds.
+
+```ruby
+Continuance::Duration.new(1, 10, 23, 5_000_000)
+```
+
+As we can see the 4th argument of the constructor takes the point second value as a measure nanoseconds. Continuance only supports unsigned whole numbers for each unit. If there is a need to support signed floating point numbers we will look into it.
+
+## Math Operations
+
+Duration objects support the math operation `+` and `-`. So a duration object can be either be added to another or subtracted from another. The result of each of these operations is another duration object.
+
+For example to add a duration of 1 hour 5 minutes to 6 minutes 32 seconds we can write the following code.
+
+ ```ruby
+Continuance::Duration.new(1, 0, 5, 0) + Continuance::Duration.new(0, 0, 6, 32)
+```
+
+## Collection Operations
+
+At present Continuance provides `total` and `average` aggregate operations on a collection of duration objects. The Ruby code below demonstrates how to use these collection operations.
+
+ ```ruby
+duration1 = Continuance::Duration.new(1, 0, 5, 0)
+duration2 = Continuance::Duration.new(0, 0, 6, 32)
+durations = Continuance::Duration.new([duration1, duration2])
+average = durations.average
+total = durations.total
+```
+
+The average method returns a Duration object, where as total returns the total number of seconds as a floating point value, this could change in the future. The order of complexity of both operations is `O(n)`.
+
+Report bugs on GitHub.

data/Rakefile

@@ -0,0 +1,17 @@
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'rdoc/task'
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Continuance'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.md')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+Bundler::GemHelper.install_tasks

data/lib/continuance.rb

@@ -0,0 +1,3 @@
+# Module Continuance
+module Continuance
+end

data/lib/continuance/base_date.rb

@@ -0,0 +1,13 @@
+require 'time'
+
+# To calculate duration in Ruby we need to calculate time
+# differences, but in Ruby when you are dealing with finer units
+# like days, hours, minutes etc we need to make sure the base YY-MM-DD is
+# set to 1970-01-01 to remove potential errors
+class BaseDate
+  attr_reader :val
+
+  def initialize
+    @val = Time.new(1970, 1, 1)
+  end
+end

data/lib/continuance/core/yaml_configuration.rb

@@ -0,0 +1,20 @@
+require 'singleton'
+require 'yaml'
+
+module Continuance
+  module Core
+    # The configuration class abstracts access to the underlying YAML file
+    class YamlConfiguration
+      include Singleton
+
+      # If the configuration loader fails for any reason then just
+      # return an empty hash
+      def load(configuration_key)
+        config_file_path = File.join(Rails.root, "config/#{configuration_key}.yml")
+        YAML.load_file(config_file_path)[Rails.env]
+        rescue
+          {}
+      end
+    end
+  end
+end

data/lib/continuance/duration.rb

@@ -0,0 +1,85 @@
+require 'time'
+require 'continuance/base_date'
+
+# Continuance module
+module Continuance
+  # Duration is a measure of how long something takes to do
+  # where our resolution is limited to hours, minutes, seconds
+  # and nano seconds which should be enough to measure anything
+  class Duration
+    include Comparable
+
+    attr_reader :hours, :minutes
+    attr_reader :seconds, :nano_seconds
+
+    # Default constructor which creates a base time marker in order
+    # to calculate proper times when a duration is specified as a string
+    def initialize(hours = 0, minutes = 0, seconds = 0, nano_seconds = 0)
+      @hours = hours
+      @minutes = minutes
+      @seconds = seconds
+      @nano_seconds = nano_seconds
+    end
+
+    # Should be able to calculate the difference between two durations objects
+    # as seconds
+    def -(other)
+      other_time = Time.strptime(other.to_s, '%H:%M:%S.%N', BaseDate.new.val)
+      self_time = Time.strptime(to_s, '%H:%M:%S.%N', BaseDate.new.val)
+      convert_to(self_time - other_time)
+    end
+
+    # Should be able to calculate the sum of two durations objects
+    # as seconds, this is returned as a float value
+    def +(other)
+      convert_to(to_f + other.to_f)
+    end
+
+    # A duration can be serialized to a string, this is used not only for visual
+    # purposes, but to also use in other computations like the difference operation
+    def to_s
+      sub_sec = @nano_seconds.to_f / (10**9)
+      sub_sec_str = sub_sec.to_s.gsub('0.', '')
+      "#{@hours}:#{@minutes}:#{@seconds}.#{sub_sec_str}"
+    end
+
+    # Converts a duration object to it's equivalent number of seconds, this value
+    # is returned as a float value
+    def to_f
+      # TODO: This calculation can result in floating point errors when the duration
+      # is converted to and from a float value
+      (@hours * 3600) + (@minutes * 60) + @seconds + (@nano_seconds.to_f / 10**9)
+    end
+
+    # Total equivalence implementation including the objects type
+    def eql?(other)
+      other.class == self.class && self == other
+    end
+
+    # Comparable implementation for a duration object
+    def <=>(other)
+      if to_f < other.to_f
+        -1
+      elsif to_f > other.to_f
+        1
+      else
+        0
+      end
+    end
+
+    # A duration can be created by specifying the time as a string and providing a valid
+    # format for the time. The supported formats are listed at
+    # http://ruby-doc.org/core-2.2.1/Time.html
+    def self.create(duration, format)
+      time_val = Time.strptime(duration, format, BaseDate.new.val)
+      Duration.new(time_val.hour, time_val.min, time_val.sec, time_val.nsec)
+    end
+
+    private
+
+    # Converts a time in seconds to a duration object
+    def convert_to(time_as_float)
+      Duration.create(time_as_float.to_s, '%S.%N')
+    end
+  end
+end

data/lib/continuance/durations.rb

@@ -0,0 +1,39 @@
+# Module Continuance
+module Continuance
+  # Durations takes a collection of duration objects on which some standard
+  # collection operations can be performed such as average etc
+  class Durations
+    attr_reader :items
+
+    # Constructor can take a sequence of duration objects, objects outside
+    # of durations are ignored
+    def initialize(items = [])
+      @items = items
+    end
+
+    # Given a series of durations, this function calculates the average duration
+    # by converting each duration to an absolute float value
+    def average
+      time = Time.at(avg_as_f).utc.strftime('%H:%M:%S:%N')
+      Duration.create(time, '%H:%M:%S:%L')
+    end
+
+    # Provides a sum of all the durations
+    def total
+      items.inject(0.0) do |sum, duration|
+        sum += duration.to_f if duration.respond_to?(:to_f)
+      end
+    end
+
+    private
+
+    # Calculates the average of the time as a float
+    def avg_as_f
+      if items.empty?
+        0.0
+      else
+        total / items.size
+      end
+    end
+  end
+end

data/lib/continuance/version.rb

@@ -0,0 +1,4 @@
+# Major.Minor.Patch version numbering
+module Continuance
+  VERSION = '0.0.1'
+end

data/spec/continuance/base_date_spec.rb

@@ -0,0 +1,13 @@
+require 'spec_helper'
+require 'continuance/base_date'
+
+# Specs for bullet points
+module Continuance
+  describe BaseDate do
+    let(:base_date) { BaseDate.new }
+
+    it 'should always be set to 1970-01-01' do
+      expect(base_date.val).to eq(Time.new(1970, 1, 1))
+    end
+  end
+end

data/spec/continuance/core/yaml_configuration_spec.rb

@@ -0,0 +1,14 @@
+require 'spec_helper'
+require 'continuance/core/yaml_configuration'
+
+# Specs for bullet points
+module Continuance
+  # Specs for yaml configuration
+  module Core
+    describe YamlConfiguration do
+      it 'should be able to handle missing configuration files' do
+        YamlConfiguration.instance.load('dummy')
+      end
+    end
+  end
+end

data/spec/continuance/duration_spec.rb

@@ -0,0 +1,109 @@
+require 'spec_helper'
+require 'continuance/duration'
+
+# Specs for bullet points
+module Continuance
+  describe Duration do
+    it 'should be able to measure Duration to a nanosecond' do
+      duration = Duration.create('00:00.000000001', '%H:%M.%N')
+      expect(duration.nano_seconds).to eq(1)
+    end
+
+    it 'should be able to measure Duration to a microsecond' do
+      duration = Duration.create('00:00.0000001', '%H:%M.%N')
+      expect(duration.nano_seconds).to eq(100)
+    end
+
+    it 'should be able to measure Duration to a millisecond' do
+      duration = Duration.create('00:00.001', '%H:%M.%L')
+      expect(duration.nano_seconds).to eq(100_000_0)
+    end
+
+    it 'should be able to measure Duration to a nanosecond' do
+      duration = Duration.create('00:00.000000001', '%H:%M.%L')
+      expect(duration.nano_seconds).to eq(1)
+    end
+
+    it 'should be able to measure Duration to a second' do
+      duration = Duration.create('00:00.1', '%H:%M.%S')
+      expect(duration.seconds).to eq(1)
+    end
+
+    it 'should be able to measure Duration to a minute' do
+      duration = Duration.create('00:01:00', '%H:%M:%S')
+      expect(duration.minutes).to eq(1)
+      expect(duration.hours).to eq(0)
+      expect(duration.seconds).to eq(0)
+    end
+
+    it 'should be able to measure Duration to a hour' do
+      duration = Duration.create('01:00:00', '%H:%M:%S')
+      expect(duration.minutes).to eq(0)
+      expect(duration.hours).to eq(1)
+      expect(duration.seconds).to eq(0)
+    end
+
+    it 'should be subtractable from a lesser duration' do
+      duration1 = Duration.create('00:00:02', '%H:%M:%S')
+      duration2 = Duration.create('00:00:03', '%H:%M:%S')
+      expect(duration2 - duration1).to eq(Duration.new(0, 0, 1, 0))
+    end
+
+    it 'should be subtractable from a duration with a different resolution' do
+      duration1 = Duration.create('00:00:00.005', '%H:%M:%S.%N')
+      duration2 = Duration.create('00:00:01', '%H:%M:%S')
+      expect(duration2 - duration1).to eq(Duration.new(0, 0, 0, 995_000_000))
+    end
+
+    it 'should be subtractable from a duration with a vastly different resolution' do
+      duration1 = Duration.create('00:00:00.005', '%H:%M:%S.%N')
+      duration2 = Duration.create('00:01:00', '%H:%M:%S')
+      expect(duration2 - duration1).to eq(Duration.new(0, 0, 59, 995_000_000))
+    end
+
+    it 'should be addable to a lesser duration' do
+      duration1 = Duration.create('00:00:02', '%H:%M:%S')
+      duration2 = Duration.create('00:00:03', '%H:%M:%S')
+      expect(duration2 + duration1).to eq(Duration.new(0, 0, 5, 0))
+    end
+
+    it 'should be addable to a duration with a different resolution' do
+      duration1 = Duration.create('00:00:00.005', '%H:%M:%S.%N')
+      duration2 = Duration.create('00:00:01', '%H:%M:%S')
+      expect(duration2 + duration1).to eq(Duration.new(0, 0, 1, 5_000_000))
+    end
+
+    it 'should be addable to a duration with a vastly different resolution' do
+      duration1 = Duration.create('00:00:00.005', '%H:%M:%S.%N')
+      duration2 = Duration.create('00:01:00', '%H:%M:%S')
+      expect(duration2 + duration1).to eq(Duration.new(0, 1, 0, 5_000_000))
+    end
+
+    context 'with a lesser value' do
+      let(:duration1) { Duration.new(0, 0, 0, 100) }
+      let(:duration2) { Duration.new(0, 0, 0, 101) }
+
+      it 'should report as so when compared' do
+        expect(duration1).to be < duration2
+      end
+    end
+
+    context 'with an equal value' do
+      let(:duration1) { Duration.new(0, 0, 0, 100) }
+      let(:duration2) { Duration.new(0, 0, 0, 100) }
+
+      it 'should report as so when compared' do
+        expect(duration1).to eql(duration2)
+      end
+    end
+
+    context 'with a greater value' do
+      let(:duration1) { Duration.new(0, 0, 0, 101) }
+      let(:duration2) { Duration.new(0, 0, 0, 100) }
+
+      it 'should report as so when compared' do
+        expect(duration1).to be > duration2
+      end
+    end
+  end
+end

data/spec/continuance/durations_spec.rb

@@ -0,0 +1,49 @@
+require 'spec_helper'
+require 'continuance/duration'
+require 'continuance/durations'
+
+# Specs for Continuance durations
+module Continuance
+  describe Durations do
+    context 'with an empty collection' do
+      let(:durations) { Durations.new }
+
+      it 'should be able to calculate the total' do
+        expect(durations.total).to eq(0.0)
+      end
+
+      it 'should be able to calculate an average' do
+        expect(durations.average).to eq(Duration.new)
+      end
+    end
+
+    context 'with a single duration' do
+      let(:duration)  { Duration.new(1, 1, 1, 0) }
+      let(:durations) { Durations.new([duration]) }
+
+      it 'should be able to calculate the total' do
+        expect(durations.total).to eq(3661.0)
+      end
+
+      it 'should be able to calculate an average' do
+        expect(durations.average).to eq(Duration.new(1, 1, 1, 0))
+      end
+    end
+
+    context 'with multiple durations' do
+      let(:duration1)  { Duration.new(1, 0, 0, 0) }
+      let(:duration2)  { Duration.new(0, 1, 0, 0) }
+      let(:duration3)  { Duration.new(0, 0, 1, 0) }
+      let(:duration4)  { Duration.new(0, 0, 0, 1_000_000) }
+      let(:durations) { Durations.new([duration1, duration2, duration3, duration4]) }
+
+      it 'should be able to calculate the total' do
+        expect(durations.total).to eq(3661.001)
+      end
+
+      it 'should be able to calculate an average' do
+        expect(durations.average).to eq(Duration.new(0, 15, 15, 250_250_000))
+      end
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,83 @@
+require 'byebug'
+
+# This file was generated by the `rspec --init` command. Conventionally, all
+# specs live under a `spec` directory, which RSpec adds to the `$LOAD_PATH`.
+# The generated `.rspec` file contains `--require spec_helper` which will cause this
+# file to always be loaded, without a need to explicitly require it in any files.
+#
+# Given that it is always loaded, you are encouraged to keep this file as
+# light-weight as possible. Requiring heavyweight dependencies from this file
+# will add to the boot time of your test suite on EVERY test run, even for an
+# individual file that may not need all of that loaded. Instead, make a
+# separate helper file that requires this one and then use it only in the specs
+# that actually need it.
+#
+# The `.rspec` file also contains a few flags that are not defaults but that
+# users commonly want.
+#
+# See http://rubydoc.info/gems/rspec-core/RSpec/Core/Configuration
+RSpec.configure do |config|
+  # The settings below are suggested to provide a good initial experience
+  # with RSpec, but feel free to customize to your heart's content.
+  # These two settings work together to allow you to limit a spec run
+  # to individual examples or groups you care about by tagging them with
+  # `:focus` metadata. When nothing is tagged with `:focus`, all examples
+  # get run.
+  # config.filter_run :focus
+  # config.run_all_when_everything_filtered = true
+
+  # Many RSpec users commonly either run the entire suite or an individual
+  # file, and it's useful to allow more verbose output when running an
+  # individual spec file.
+  if config.files_to_run.one?
+    # RSpec filters the backtrace by default so as not to be so noisy.
+    # This causes the full backtrace to be printed when running a single
+    # spec file (e.g. to troubleshoot a particular spec failure).
+    config.full_backtrace = true
+
+    # Use the documentation formatter for detailed output,
+    # unless a formatter has already been configured
+    # (e.g. via a command-line flag).
+    config.default_formatter = 'doc'
+  end
+
+  # Print the 10 slowest examples and example groups at the
+  # end of the spec run, to help surface which specs are running
+  # particularly slow.
+  config.profile_examples = 10
+
+  # Run specs in random order to surface order dependencies. If you find an
+  # order dependency and want to debug it, you can fix the order by providing
+  # the seed, which is printed after each run.
+  #     --seed 1234
+  config.order = :random
+
+  # Seed global randomization in this process using the `--seed` CLI option.
+  # Setting this allows you to use `--seed` to deterministically reproduce
+  # test failures related to randomization by passing the same `--seed` value
+  # as the one that triggered the failure.
+  # Kernel.srand config.seed
+
+  # rspec-expectations config goes here. You can use an alternate
+  # assertion/expectation library such as wrong or the stdlib/minitest
+  # assertions if you prefer.
+  config.expect_with :rspec do |expectations|
+    # Enable only the newer, non-monkey-patching expect syntax.
+    # For more details, see:
+    #   - http://myronmars.to/n/dev-blog/2012/06/rspecs-new-expectation-syntax
+    expectations.syntax = :expect
+  end
+
+  # rspec-mocks config goes here. You can use an alternate test double
+  # library (such as bogus or mocha) by changing the `mock_with` option here.
+  config.mock_with :rspec do |mocks|
+    # Enable only the newer, non-monkey-patching expect syntax.
+    # For more details, see:
+    #   - http://teaisaweso.me/blog/2013/05/27/rspecs-new-message-expectation-syntax/
+    mocks.syntax = :expect
+
+    # Prevents you from mocking or stubbing a method that does not exist on
+    # a real object. This is generally recommended.
+    mocks.verify_partial_doubles = true
+  end
+end

metadata

@@ -0,0 +1,63 @@
+--- !ruby/object:Gem::Specification
+name: continuance
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Shirren Premaratne
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-06-17 00:00:00.000000000 Z
+dependencies: []
+description: Continuance is a library for handling durations as opposed to time. A
+  duration represents a finite period of time meaurable in hours, minutes, seconds
+  and nanoseconds.
+email:
+- shirren.premaratne@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- Rakefile
+- lib/continuance.rb
+- lib/continuance/base_date.rb
+- lib/continuance/core/yaml_configuration.rb
+- lib/continuance/duration.rb
+- lib/continuance/durations.rb
+- lib/continuance/version.rb
+- spec/continuance/base_date_spec.rb
+- spec/continuance/core/yaml_configuration_spec.rb
+- spec/continuance/duration_spec.rb
+- spec/continuance/durations_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/shirren/continuance
+licenses: []
+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.4.8
+signing_key: 
+specification_version: 4
+summary: Continuance is a library for handling durations as opposed to time.
+test_files:
+- spec/continuance/base_date_spec.rb
+- spec/continuance/core/yaml_configuration_spec.rb
+- spec/continuance/duration_spec.rb
+- spec/continuance/durations_spec.rb
+- spec/spec_helper.rb