periodical 0.1.1

data/README.md

@@ -0,0 +1,45 @@
+Periodical
+=========
+
+* Author: Samuel G. D. Williams (<http://www.oriontransfer.co.nz>)
+* Copyright (C) 2012 Samuel G. D. Williams.
+* Released under the MIT license.
+
+Periodical is a simple framework for working with durations and periods. A duration measures a range of time bounded by a `from` date and `to` date. A period is a relative unit of time such as `4 weeks`.
+
+Basic Usage
+-----------
+
+The main use case for this framework involves periodic billing or accounting (e.g. calculating fortnightly rental payments).
+
+	duration = Periodical::Duration.new(Date.parse("2010-01-01"), Date.parse("2010-02-01"))
+	period = Periodical::Period.new(2, :weeks)
+	
+	# How many periods in the duration?
+	count = duration / period
+	
+	# Calculate the date which is 2 * (2 weeks)
+	next = period.advance(duration.from, 2)
+
+License
+-------
+
+Copyright (c) 2010, 2011 Samuel G. D. Williams. <http://www.oriontransfer.co.nz>
+
+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/lib/periodical/duration.rb

@@ -0,0 +1,72 @@
+# Copyright (c) 2012 Samuel G. D. Williams. <http://www.oriontransfer.co.nz>
+# 
+# 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.
+
+require 'date'
+
+module Periodical
+	class Duration
+		def initialize(from, to)
+			@from = from
+			@to = to
+		end
+		
+		attr :from
+		attr :to
+		
+		def days
+			@to - @from
+		end
+		
+		def weeks
+			days / 7
+		end
+		
+		def whole_months
+			(@to.year * 12 + @to.month) - (@from.year * 12 + @from.month)
+		end
+		
+		def months
+			whole = self.whole_months
+			
+			partial_start = @from >> whole
+			partial_end = @from >> whole + 1
+			
+			return whole + (@to - partial_start) / (partial_end - partial_start)
+		end
+		
+		def whole_years
+			@to.year - @from.year
+		end
+		
+		def years
+			whole = self.whole_years
+			
+			partial_start = @from >> (whole * 12)
+			partial_end = @from >> ((whole + 1) * 12)
+			
+			return whole + (@to - partial_start) / (partial_end - partial_start)
+		end
+		
+		# Calculate the number of periods between from and to
+		def / period
+			self.send(period.unit) / period.count
+		end
+	end
+end

data/lib/periodical/period.rb

@@ -0,0 +1,101 @@
+# Copyright (c) 2012 Samuel G. D. Williams. <http://www.oriontransfer.co.nz>
+# 
+# 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.
+
+module Periodical
+	class Period
+		VALID_UNITS = [:days, :weeks, :months, :years]
+		
+		# Accepts strings in the format of "2 weeks" or "weeks"
+		def self.parse(value)
+			if Array === value
+				parts = value
+			else
+				parts = value.to_s.split(/\s+/, 2)
+			end
+			
+			if parts.size == 1
+				if parts[0].to_i == 0
+					count = 1
+					unit = parts[0].to_sym
+				else
+					count = parts[0].to_i
+					unit = :days
+					
+					if count == 7
+						count = 1
+						unit = :weeks
+					end
+					
+					if count == 365
+						count = 1
+						unit = :years
+					end
+				end
+			else
+				count = parts[0].to_i
+				unit = parts[1].gsub(/\s+/, '_').downcase.to_sym
+			end
+			
+			unless VALID_UNITS.include? unit
+				raise ArgumentError.new("Invalid unit specified #{unit}!")
+			end
+			
+			if count == 0
+				raise ArgumentError.new("Count must be non-zero!")
+			end
+			
+			return self.new(count, unit)
+		end
+		
+		def initialize(count = 1, unit = :days)
+			@count = count
+			@unit = unit
+		end
+		
+		def to_s
+			"#{@count} #{@unit}"
+		end
+		
+		def to_formatted_s
+			if @count == 1
+				@unit.to_s.gsub(/s$/, '')
+			else
+				to_s
+			end
+		end
+		
+		def advance(date, multiple = 1)
+			total = multiple * @count
+			
+			if unit == :days
+				date + total
+			elsif unit == :weeks
+				date + (total * 7)
+			elsif unit == :months
+				date >> total
+			elsif unit == :years
+				date >> (total * 12)
+			end
+		end
+		
+		attr :unit
+		attr :count
+	end
+end

data/lib/periodical/version.rb

@@ -0,0 +1,29 @@
+# Copyright (c) 2012 Samuel G. D. Williams. <http://www.oriontransfer.co.nz>
+# 
+# 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.
+
+module Periodical
+	module VERSION
+		MAJOR = 0
+		MINOR = 1
+		TINY  = 1
+
+		STRING = [MAJOR, MINOR, TINY].join('.')
+	end
+end

data/lib/periodical.rb

@@ -0,0 +1,22 @@
+# Copyright (c) 2012 Samuel G. D. Williams. <http://www.oriontransfer.co.nz>
+# 
+# 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.
+
+require 'periodical/period'
+require 'periodical/duration'

data/test/helper.rb

@@ -0,0 +1,4 @@
+
+$LOAD_PATH.unshift File.expand_path("../../lib/", __FILE__)
+
+require 'test/unit'

data/test/test_duration.rb

@@ -0,0 +1,34 @@
+
+require 'helper'
+
+require 'periodical'
+
+class DurationTest < Test::Unit::TestCase
+	def setup
+	end
+	
+	def test_duration
+		duration = Periodical::Duration.new(Date.parse("2010-01-01"), Date.parse("2010-02-01"))
+		assert_equal 31, duration.days
+		assert_equal Rational(31, 7), duration.weeks
+		assert_equal 1, duration.months
+		assert_equal Rational(31, 365), duration.years
+		
+		assert_equal 1, duration.whole_months
+		assert_equal 0, duration.whole_years
+	end
+	
+	def test_weekly_period
+		duration = Periodical::Duration.new(Date.parse("2010-01-01"), Date.parse("2010-02-01"))
+		period = Periodical::Period.new(2, :weeks)
+		
+		assert_equal Rational(31, 14), duration / period
+	end
+	
+	def test_monthly_period
+		duration = Periodical::Duration.new(Date.parse("2010-01-01"), Date.parse("2011-03-01"))
+		period = Periodical::Period.new(2, :months)
+		
+		assert_equal Rational(14, 2), duration / period
+	end
+end

data/test/test_period.rb

@@ -0,0 +1,15 @@
+
+require 'helper'
+
+require 'periodical'
+
+class PeriodTest < Test::Unit::TestCase
+	def setup
+	end
+	
+	def test_advance
+		duration = Periodical::Duration.new(Date.parse("2010-01-01"), Date.parse("2011-01-01"))
+		period = Periodical::Period.new(1, :months)
+		assert_equal duration.to, period.advance(duration.from, 12)
+	end
+end

metadata

@@ -0,0 +1,53 @@
+--- !ruby/object:Gem::Specification
+name: periodical
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+  prerelease: 
+platform: ruby
+authors:
+- Samuel Williams
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-07-26 00:00:00.000000000 Z
+dependencies: []
+description: 
+email: samuel.williams@oriontransfer.co.nz
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/periodical/duration.rb
+- lib/periodical/period.rb
+- lib/periodical/version.rb
+- lib/periodical.rb
+- test/helper.rb
+- test/test_duration.rb
+- test/test_period.rb
+- README.md
+homepage: http://www.oriontransfer.co.nz/
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.23
+signing_key: 
+specification_version: 3
+summary: Periodical is a simple framework for working with durations and periods.
+test_files: []
+has_rdoc: