periods 0.0.3 → 0.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b340e86339eee67b5f7915f6df4d6e809aba2107
-  data.tar.gz: 0d613dce4f4898974d2953797e8cd9cd0b6b72b1
+  metadata.gz: 8bca4bb489addf1c13b97b9393036dea7c7a8750
+  data.tar.gz: 6f9b873e913d076b08d1ea25aa6d8ccc1a275c55
 SHA512:
-  metadata.gz: f299f089e6a1c016005d0120b8784cb317bd7ed73061dd76906fb35eb1b4a2c81da882928608b974f1c54bbda33e9f9993a6c7f362754a4a77575b82e26d92d8
-  data.tar.gz: adc4461e7f2d1e8b2cf112a0bb8baddf9e3732ded407f6ed66d933f9493cbfc2f936d9da25336eb449cfebe817d319c17fe676c25b7d80d6aa3589354707c3e2
+  metadata.gz: 0fd1215e00f8890bab21bda707d6904a43d05aaa8717c3885e9114a9b41cc13fc16e3d30324ea8ade7669c4af1ea192266d5efe17bee639a66ea21bffd022ac0
+  data.tar.gz: 47461d42951e77ff77f8c57dd185b66b96e0e67f8a69ff7364996490ae1d90cb70d7b95ed323c13cb8cf972c693eb01ac4fbe498f715f925028e5ef198a244f5

data/.yardopts

@@ -0,0 +1,6 @@
+--protected
+--no-private
+-
+LICENSE
+README.md
+lib/**/*.rb

data/README.md

@@ -35,14 +35,11 @@ Require `periods` in your app:
 
 A period is defined by a start and end date:
 
-    period = Period.for(Date.new(2015,6,25), Date.new(2015,8,19))
-    period.days      # => 56
-    period.next      # => 20.08.2015 - 14.10.2015
-    period.next.days # => 56
+    period = Period.new(Date.new(2015,6,25), Date.new(2015,8,19))
 
 The start and end date can be a string too:
 
-    period = Period.for('25.06.2015', '19.08.2015')
+    period = Period.new('25.06.2015', '19.08.2015')
 
 All period models respond to the following interface:
 
@@ -55,42 +52,100 @@ All period models respond to the following interface:
 
 Special period models may define additional methods (see below).
 
+#### days
+
+    period = Period.new('25.06.2015', '19.08.2015')
+    period.days # => 56
+
+#### next
+
+    period = Period.new('25.06.2015', '19.08.2015')
+    period.next # => 20.08.2015 - 14.10.2015
+
+#### previous
+
+    period = Period.new('25.06.2015', '19.08.2015')
+    period.previous # => 30.04.2015 - 24.06.2015
+
+#### include?
+
+Test whether a date or a period is included in the given period:
+
+    period = Period.new('25.06.2015', '19.08.2015')
+    period.include?(Date.new(2015,6,25)) # => true
+    period.include?('25.06.2015') # => true
+    period.include?('24.06.2015') # => false
+    
+    period.include?(Period.new('25.06.2015', '19.08.2015')) # => true
+    period.include?(Period.new('26.06.2015', '19.08.2015')) # => true
+    period.include?(Period.new('24.06.2015', '19.08.2015')) # => false
+    period.include?(Period.new('25.06.2015', '20.08.2015')) # => false
+
 ### MonthlyPeriod
 
 If you need a constant monthly range use `MonthlyPeriod`:
 
-    monthly = MonthPeriod.for('01.01.2015') # => 01.01.2015 - 31.01.2015
-    monthly.next # => 01.02.2015 - 28.02.2015
-
     monthly = MonthPeriod.for('25.06.2015') # => 25.06.2015 - 24.07.2015
-    monthly.next        # => 25.07.2015 - 24.08.2015
-    monthly.start_date  # Date(25.06.2015)
-    monthly.end_date    # Date(24.07.2015)
-    
+    monthly.next     # => 25.07.2015 - 24.08.2015
+    monthly.previous # => 25.05.2015 - 24.06.2015
+
 ### Month
 
 If you need a calendar month starting at first day of month and ending at last day of month use `Month`:
 
-    january = Month.for('01.01.2015') # => 01.01.2015 - 31.01.2015
-    january.next # => 01.02.2015 - 28.02.2015
-
     june = MonthPeriod.for('25.06.2015') # => 01.06.2015 - 30.06.2015
-    june.next   # => 01.07.2015 - 31.07.2015
-    june.month  # => 6
-    june.year   # => 2015
+    june.next     # => 01.07.2015 - 31.07.2015
+    june.previous # => 01.05.2015 - 31.05.2015
+    june.month    # => 6
+    june.year     # => 2015
 
 ### QuarterlyPeriod
 
+    period = QuarterlyPeriod.for('25.06.2015') # => 25.06.2015 - 24.09.2015
+
 ### Quarter
 
+A quarter starts at first day of a month and ends at last day three months later:
+
+    quarter = Quarter.for('01.02.2015') # => 01.02.2015 - 30.04.2015
+    quarter.next     # => 01.05.2015 - 31.07.2015
+    quarter.previous # => 01.11.2014 - 31.01.2015
+    
+    quarter = Quarter.for('01.12.2015') # => 01.12.2015 - 29.02.2016
+    quarter.start_year # => 2015
+    quarter.end_year   # => 2016
+    quarter.months     # => [Month.for('01.12.2015'), Month.for('01.01.2016'), Month.for('01.02.2016')]
+
 ### HalfyearlyPeriod
 
+A HalfyearlyPeriod starts at the given date and ends six month later:
+
+    period = HalfyearlyPeriod.for('25.06.2015') # =>  25.06.2015 - 24.12.2015
+
 ### Halfyear
 
-### Yearly
+A Halfyear starts at the first day of a month and ends six month later:
+
+    halfyear = HalfyearlyPeriod.for('25.06.2015') # =>  01.06.2015 - 30.11.2015
+    halfyear.next       # => 25.12.2015 - 24.06.2016
+    halfyear.previous   # => 25.12.2014 - 24.06.2015
+    halfyear.months     # => [Month.for('01.06.2015'), ..., Month.for('01.11.2015')]
+
+### YearlyPeriod
+
+A YearlyPeriod starts at the given date and ends one year later:
+
+    period = YearlyPeriod.for('25.06.2015') # => 25.06.2015 - 24.06.2016
 
 ### Year
 
+A year starts at first day of a month and ends one year later:
+
+    year = Year.for('01.02.2015') # => 01.02.2015 - 31.01.2016
+    year.next       # => 01.02.2016 - 31.01.2017
+    year.previous   # => 01.02.2014 - 31.01.2015
+    year.months     # => [Month.for('01.02.2015'), ..., Month.for('01.01.2016')]
+    
 ### If constants already exist
 
 In case constants like `Month` already exist in your code stop requiring `periods` in your `Gemfile`:
@@ -121,6 +176,7 @@ Write your own classes:
 
 * Implement Week
 * Use Time not Date
+* Optimize README
 * Comment Code
 
 ## Contributing

data/lib/periods/modules/period.rb

@@ -10,17 +10,54 @@ module Periods
       end
 
       module InstanceMethods
-        attr_reader :start_date, :end_date
 
+        # Returns the start date of this period.
+        # @return [Date] the start date of this period.
+        attr_reader :start_date
+
+        # Returns the end date of this period.
+        # @return [Date] the end date of this period.
+        attr_reader :end_date
+
+        ##
+        # Initialize a new period with its start and end date.
+        #
+        # @example
+        #
+        #    period = Period.new('10.04.2015', '20.05.2015')
+        #
         def initialize(start_date, end_date)
           @start_date = Date.parse(start_date.to_s)
           @end_date = Date.parse(end_date.to_s)
         end
 
+        ##
+        # Test whether the given period is equal to this one.
+        # A period is considered equal if it has the same start and end date.
+        #
+        # @return [Boolean] true if period is equal, false otherwise.
+        #
+        # @since 0.0.3
+        #
+        # @example
+        #
+        #    period1 = Period.new('10.04.2015', '20.05.2015')
+        #    period2 = Period.new('10.04.2015', '20.05.2015')
+        #    period3 = Period.new('09.04.2015', '20.05.2015')
+        #    period1 == period2 # => true
+        #    period1 == period3 # => false
+        #
         def ==(period)
           start_date == period.start_date && end_date == period.end_date
         end
 
+        ##
+        # Test whether the given period is older, newer or equal to this one.
+        #
+        # @return [Fixnum] 1 if period is older, -1 if newer, 0 if equal.
+        #
+        # @since 0.0.3
+        #
         def <=>(period)
           if start_date > period.start_date
             1
@@ -31,18 +68,106 @@ module Periods
           end
         end
 
+        ##
+        # Returns next period.
+        #
+        # @return [Period] the next period.
+        #
+        # @since 0.0.3
+        #
+        # @see Periods::Modules::Period#previous
+        #
+        # @example
+        #
+        #    period = Period.new('10.04.2015', '20.05.2015')
+        #    period.next # => 21.05.2015 - 30.06.2015
+        #
         def next
           self.class.new(start_date + days, end_date + days)
         end
 
+        ##
+        # Returns previous period.
+        #
+        # @return [Period] the previous period.
+        #
+        # @since 0.0.3
+        #
+        # @see Periods::Modules::Period#next
+        #
+        # @example
+        #
+        #    period = Period.new('10.04.2015', '20.05.2015')
+        #    period.previous # => 28.02.2015 - 09.04.2015
+        #
         def previous
           self.class.new(start_date - days, end_date - days)
         end
 
+        ##
+        # Returns number of days in period.
+        #
+        # @return [Fixnum] the number of days in period.
+        #
+        # @since 0.0.3
+        #
+        # @example
+        #
+        #    Period.new('10.04.2015', '20.05.2015').days # => 41
+        #
         def days
           end_date.yday - start_date.yday + 1
         end
 
+        ##
+        # Returns start year of period.
+        #
+        # @return [Fixnum] start year of period.
+        #
+        # @since 0.0.3
+        #
+        # @example
+        #
+        #    Period.new('10.04.2015', '20.05.2016').start_year # => 2015
+        #
+        def start_year
+          start_date.year
+        end
+
+        ##
+        # Returns end year of period.
+        #
+        # @return [Fixnum] end year of period.
+        #
+        # @since 0.0.3
+        #
+        # @example
+        #
+        #    Period.new('10.04.2015', '20.05.2016').end_year # => 2016
+        #
+        def end_year
+          end_date.year
+        end
+
+        ##
+        # Test whether the given date or period is included in this one.
+        #
+        # @return [Boolean] true if date or period is included, false otherwise.
+        #
+        # @since 0.0.3
+        #
+        # @example
+        #
+        #    Period.new('10.04.2015', '20.05.2015').include?('10.04.2015') # => true
+        #    Period.new('10.04.2015', '20.05.2015').include?('20.05.2015') # => true
+        #    Period.new('10.04.2015', '20.05.2015').include?('09.04.2015') # => false
+        #    Period.new('10.04.2015', '20.05.2015').include?('21.05.2015') # => false
+        #
+        #    Period.new('10.04.2015', '20.05.2015').include?(Period.new('10.04.2015', '20.05.2015')) # => true
+        #    Period.new('10.04.2015', '20.05.2015').include?(Period.new('15.04.2015', '15.05.2015')) # => true
+        #    Period.new('10.04.2015', '20.05.2015').include?(Period.new('09.04.2015', '20.05.2015')) # => false
+        #    Period.new('10.04.2015', '20.05.2015').include?(Period.new('10.04.2015', '21.05.2015')) # => false
+        #
         def include?(period)
           if period.is_a?(Date)
             start_date <= period && period <= end_date
@@ -56,6 +181,17 @@ module Periods
           end
         end
 
+        ##
+        # Return string representation of period.
+        #
+        # @return [String] the string representation of period.
+        #
+        # @since 0.0.3
+        #
+        # @example
+        #
+        #    Period.new('10.04.2015', '20.05.2015').to_s # => '10.04.2015 -  20.05.2015'
+        #
         def to_s
           "#{start_date.strftime("%d.%m.%Y")} - #{end_date.strftime("%d.%m.%Y")}"
         end

data/lib/periods/modules/quarter.rb

@@ -35,14 +35,6 @@ module Periods
             Periods::Month.for(start_date.next_month(2)) ]
         end
 
-        def start_year
-          start_date.year
-        end
-
-        def end_year
-          end_date.year
-        end
-
         private
 
           def beginning_of_month(date)

data/lib/periods/modules/year.rb

@@ -47,10 +47,6 @@ module Periods
           (self.next.start_date - start_date).to_i
         end
 
-        def year
-          start_date.year
-        end
-
         def months
           months = [Periods::Month.for(start_date)]
           1.upto(11) do |idx|

data/lib/periods/version.rb

@@ -1,3 +1,3 @@
 module Periods
-  VERSION = "0.0.3"
+  VERSION = "0.0.4"
 end

data/spec/lib/halfyear_spec.rb

@@ -8,23 +8,23 @@ describe Halfyear do
   it_behaves_like "Lint Check"
 
   describe ".for" do
-    it "returns month of given date included" do
-      month = described_class.for('25.06.2015')
+    it "returns halfyear of given date included" do
+      halfyear = described_class.for('25.06.2015')
 
-      expect(month.start_date).to eq Date('01.06.2015')
-      expect(month.end_date).to eq Date('30.11.2015')
+      expect(halfyear.start_date).to eq Date('01.06.2015')
+      expect(halfyear.end_date).to eq Date('30.11.2015')
     end
   end
 
   describe "#next" do
-    it "returns next month" do
+    it "returns next halfyear" do
       expect(described_class.for('25.06.2015').next).to eq described_class.for('01.12.2015')
       expect(described_class.for('01.07.2015').next).to eq described_class.for('01.01.2016')
     end
   end
 
   describe "#previous" do
-    it "returns previous month" do
+    it "returns previous halfyear" do
       expect(described_class.for('25.06.2015').previous).to eq described_class.for('01.12.2014')
       expect(described_class.for('01.07.2015').previous).to eq described_class.for('01.01.2015')
     end

data/spec/lib/halfyearly_period_spec.rb

@@ -17,14 +17,14 @@ describe HalfyearlyPeriod do
   end
 
   describe "#next" do
-    it "returns next quarter" do
+    it "returns next period" do
       expect(described_class.for('25.06.2015').next).to eq described_class.for('25.12.2015')
       expect(described_class.for('01.07.2015').next).to eq described_class.for('01.01.2016')
     end
   end
 
   describe "#previous" do
-    it "returns previous quarter" do
+    it "returns previous period" do
       expect(described_class.for('25.06.2015').previous).to eq described_class.for('25.12.2014')
       expect(described_class.for('01.07.2015').previous).to eq described_class.for('01.01.2015')
     end

data/spec/lib/period_spec.rb

@@ -55,6 +55,20 @@ describe Period do
     end
   end
 
+  describe "#start_year" do
+    it "returns start year of quarter" do
+      expect(new_period("25.06.2015", "19.08.2015").start_year).to eq 2015
+      expect(new_period("25.06.2015", "20.05.2016").start_year).to eq 2015
+    end
+  end
+
+  describe "#end_year" do
+    it "returns end year of quarter" do
+      expect(new_period("25.06.2015", "19.08.2015").end_year).to eq 2015
+      expect(new_period("25.06.2015", "20.05.2016").end_year).to eq 2016
+    end
+  end
+
   describe "#include?" do
     context "date included" do
       it "returns true" do

data/spec/lib/quarter_spec.rb

@@ -101,17 +101,4 @@ describe Quarter do
     end
   end
 
-  describe "#start_year" do
-    it "returns start year of quarter" do
-      expect(described_class.for('01.06.2015').start_year).to eq 2015
-      expect(described_class.for('01.06.2016').start_year).to eq 2016
-    end
-  end
-
-  describe "#end_year" do
-    it "returns end year of quarter" do
-      expect(described_class.for('01.06.2015').end_year).to eq 2015
-      expect(described_class.for('01.12.2015').end_year).to eq 2016
-    end
-  end
 end

data/spec/lib/year_spec.rb

@@ -8,36 +8,28 @@ describe Year do
   it_behaves_like "Lint Check"
 
   describe ".for" do
-    it "returns month of given date included" do
-      month = described_class.for('25.06.2015')
+    it "returns year of given date included" do
+      year = described_class.for('25.06.2015')
 
-      expect(month.start_date).to eq Date('01.06.2015')
-      expect(month.end_date).to eq Date('31.05.2016')
+      expect(year.start_date).to eq Date('01.06.2015')
+      expect(year.end_date).to eq Date('31.05.2016')
     end
   end
 
   describe "#next" do
-    it "returns next month" do
+    it "returns next year" do
       expect(described_class.for('25.06.2015').next).to eq described_class.for('01.06.2016')
       expect(described_class.for('01.07.2015').next).to eq described_class.for('01.07.2016')
     end
   end
 
   describe "#previous" do
-    it "returns previous month" do
+    it "returns previous year" do
       expect(described_class.for('25.06.2015').previous).to eq described_class.for('01.06.2014')
       expect(described_class.for('01.06.2015').previous).to eq described_class.for('01.06.2014')
     end
   end
 
-  describe "#year" do
-    it "returns year number" do
-      expect(described_class.for('01.01.2015').year).to eq 2015
-      expect(described_class.for('01.12.2015').year).to eq 2015
-      expect(described_class.for('01.01.2014').year).to eq 2014
-    end
-  end
-
   describe "#months" do
     it "returns months of year" do
       expect(described_class.for('01.06.2015').months).

data/spec/lib/yearly_period_spec.rb

@@ -17,14 +17,14 @@ describe YearlyPeriod do
   end
 
   describe "#next" do
-    it "returns next quarter" do
+    it "returns next period" do
       expect(described_class.for('25.06.2015').next).to eq described_class.for('25.06.2016')
       expect(described_class.for('01.07.2015').next).to eq described_class.for('01.07.2016')
     end
   end
 
   describe "#previous" do
-    it "returns previous quarter" do
+    it "returns previous period" do
       expect(described_class.for('25.06.2015').previous).to eq described_class.for('25.06.2014')
       expect(described_class.for('01.07.2015').previous).to eq described_class.for('01.07.2014')
     end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: periods
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.0.4
 platform: ruby
 authors:
 - Thomas Baustert
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-05-14 00:00:00.000000000 Z
+date: 2015-05-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -62,6 +62,7 @@ files:
 - ".gitignore"
 - ".rspec"
 - ".travis.yml"
+- ".yardopts"
 - Gemfile
 - LICENSE
 - README.md