partial-date 1.1.4 → 1.1.5

data/ChangeLog.textile

@@ -1,3 +1,13 @@
+h3. 1.1.5 / 2012-05-30
+
+* Allow negative years and year range from -1048576 to 1048576 (20 bits).
+* Implemented negative year with signing mask. 
+* Year is no longer mandatory
+* Created more specific error classes
+* Implemented readonly attribute Date#bits to allow public access to the bit store for comparison in <=>.
+* Moved bits.rb back into date.rb
+
+
 h3. 1.1.4 / 2012-05-29
 
 * Changed error messages for month and day to 0 - 12 and 0 - 31 respectively (since zero values are allowed).

data/README.textile

@@ -1,16 +1,19 @@
 h1. partial-date
 
+* See the "ChangeLog":https://github.com/58bits/partial-date/blob/master/ChangeLog.textile for details of this release.
+
 * "Homepage":https://github.com/58bits/partial-date#readme
 * "Issues":https://github.com/58bits/partial-date/issues
 * "Documentation":http://rubydoc.info/gems/partial-date/frames
 
+
 h2. Description
 
-A simple date class that can be used to store partial date values in a single column/attribute. An example use case would include an archive, or catalogue entry where the complete date is unknown. Year is mandatory, but month and day are optional.
+A simple date class that can be used to store partial date values in a single column/attribute. An example use case would include an archive, or catalogue entry where the complete date is unknown. Year is optional and can be a negative value. Month and day are optional, but month must be set before day.
 
 h2. Features
 
-PartialDate::Date uses a 23 bit register as the backing store for date instances, and bit fiddling to get or set year, month and day values. As such it will perform well in a loop or collection of date objects.
+PartialDate::Date uses a 30 bit register as the backing store for date instances, and bit fiddling to get or set year, month and day values. As such it will perform well in a loop or collection of date objects.
 
 Use @date.value@ to get or set an Integer value that can be used to rehydrate a date object, or save the date value to a persistance store in a readable Integer form e.g. 20121201 for 2012 December 01. 
 

data/lib/partial-date.rb

@@ -1,5 +1,4 @@
 require 'partial-date/version'
 require 'partial-date/error'
-require 'partial-date/bits'
 require 'partial-date/date'
 require 'date'

data/lib/partial-date/date.rb

@@ -1,7 +1,28 @@
 
 # Public module containing Date, Error and Version types.
 module PartialDate
+  
+  # Key:
+  #   The first 5 bits are the day (max 31)
+  #   The next 4 bits are the month (max 12)
+  #   The next 20 bits are the year (max 1048576)
+  #   The most significant bit (MSB) is a 1 bit sign bit (for negative years).
 
+  DAY_MASK    = 0b000000000000000000000000011111
+  MONTH_MASK  = 0b000000000000000000000111100000
+  YEAR_MASK   = 0b011111111111111111111000000000
+  SIGN_MASK   = 0b100000000000000000000000000000
+
+  ZERO_SIGN_MASK  = 0b011111111111111111111111111111
+  ZERO_YEAR_MASK  = 0b100000000000000000000111111111
+  ZERO_MONTH_MASK = 0b111111111111111111111000011111
+  ZERO_DAY_MASK   = 0b111111111111111111111111000000
+
+  SIGN_SHIFT = 29
+  YEAR_SHIFT = 9
+  MONTH_SHIFT = 5
+
+  
   # Public: A class for handling partial date storage. Partial dates are stored
   # as an 8 digit integer with optional month and day values.
   #
@@ -19,6 +40,15 @@ module PartialDate
   class Date
     include Comparable
 
+    # Public: Readonly accessor for the raw bit integer date value.
+    # This allows us to perform our <=> comparions against this 
+    # value instead of comparing year, month and day, or date.value
+    # which requires multiplication to calculate.
+    #
+    # Returns the single Integer backing store with 'bits' flipped 
+    # for year, month and day.
+    attr_reader :bits
+
     # Public: Create a new partial date class from a block of integers
     # or strings.
     #
@@ -73,7 +103,7 @@ module PartialDate
     #
     # Returns an integer representation of a partial date.
     def value
-      Bits.get_date(@bits)
+      self.class.get_date(@bits)
     end
 
     # Public: Set a date value using an interger in partial date format.
@@ -84,10 +114,10 @@ module PartialDate
     #
     # Returns nothing  
     def value=(value)
-      if value.is_a?(Integer) && (value >= 10000 && value <= 99991231)
-        @bits = Bits.set_date(@bits, value)
+      if value.is_a?(Integer) && (value >= -10485761231 && value <= 10485761231)
+        @bits = self.class.set_date(@bits, value)
       else
-        raise PartialDateError, "Date value must be an integer betwen 10000 and 99991231"
+        raise PartialDateError, "Date value must be an integer betwen -10485761231 and 10485761231"
       end
     end
 
@@ -105,55 +135,53 @@ module PartialDate
     def year=(value)
 
       if value.nil?
-        raise PartialDateError, "Year cannot be nil"
+        raise YearError, "Year cannot be nil"
       end
 
       if value.is_a?(String) 
-        if value =~ /\A\d{4}\z/
+        if value =~ /\A\d{1,7}\z/
           value = value.to_i
         else
-          raise PartialDateError, "Year must be a valid four digit string or integer between 1 and 9999"
+          raise YearError, "Year must be a valid string or integer from -1048576 to 1048576"
         end
       end
 
-      if value.is_a?(Integer) && (value <= 9999 && value > 0) 
-        @bits = Bits.set_year(@bits, value)
+      if value.is_a?(Integer) && (value >= -1048576 && value <= 1048576) 
+        @bits = self.class.set_year(@bits, value)
       else
-        raise PartialDateError, "Year must be an integer between 1 and 9999"
+        raise YearError, "Year must be an integer integer from -1048576 to 1048576"
       end
     end
 
     # Public: Get the year from a partial date.
     def year
-      Bits.get_year(@bits)
+      self.class.get_year(@bits)
     end
 
     # Public: Set the month of a partial date.
     def month=(value)
 
-      raise PartialDateError, "A year must be set before a month" if year == 0
-
       value = 0 if value.nil?
 
       if value.is_a?(String) 
         if value =~ /\A\d{1,2}\z/ 
           value = value.to_i
         else
-          raise PartialDateError, "Month must be a valid one or two digit string or integer between 0 and 12"
+          raise MonthError, "Month must be a valid one or two digit string or integer between 0 and 12"
         end
       end
 
       if value.is_a?(Integer) && (value <= 12 && value >= 0)
-        @bits = Bits.set_month(@bits, value)
-        @bits = Bits.set_day(@bits, 0) if value == 0
+        @bits = self.class.set_month(@bits, value)
+        @bits = self.class.set_day(@bits, 0) if value == 0
       else
-        raise PartialDateError, "Month must an be integer between 0 and 12"
+        raise MonthError, "Month must an be integer between 0 and 12"
       end
     end
 
     # Public: Get the month from a partial date.
     def month
-      Bits.get_month(@bits)
+      self.class.get_month(@bits)
     end
 
 
@@ -161,7 +189,7 @@ module PartialDate
     # nil and empty strings are allowed.
     def day=(value)
 
-      raise PartialDateError, "A month must be set before a day" if month == 0
+      raise DayError, "A month must be set before a day" if month == 0
 
       value = 0 if value.nil?
 
@@ -169,25 +197,25 @@ module PartialDate
         if value =~ /\A\d{1,2}\z/
           value = value.to_i
         else
-          raise PartialDateError, "Day must be a valid one or two digit string or integer between 0 and 31"
+          raise DayError, "Day must be a valid one or two digit string or integer between 0 and 31"
         end
       end
 
       if value.is_a?(Integer) && (value >= 0 && value <= 31)
         begin
           date = ::Date.civil(self.year, self.month, value) if value > 0
-          @bits = Bits.set_day(@bits, value)
+          @bits = self.class.set_day(@bits, value)
         rescue 
-          raise PartialDateError, "Day must be a valid day for the given month"
+          raise DayError, "Day must be a valid day for the given month"
         end
       else
-        raise PartialDateError, "Day must be an integer between 0 and 31"
+        raise DayError, "Day must be an integer between 0 and 31"
       end
     end
 
     # Public: Get the day from a partial date.
     def day
-      Bits.get_day(@bits)
+      self.class.get_day(@bits)
     end
 
     # Public: Returns a formatted string representation of the partial date.
@@ -200,41 +228,79 @@ module PartialDate
     #
     # Returns string representation of date.
     def to_s
-      if self.year > 0
-        result = self.year.to_s.rjust(4, '0') 
-        result = result + "-" + self.month.to_s.rjust(2, '0') if self.month > 0
-        result = result + "-" + self.day.to_s.rjust(2, '0') if self.day > 0
+      if year > 0
+        result = year.to_s.rjust(4, '0') 
+        result = result + "-" + month.to_s.rjust(2, '0') if month > 0
+        result = result + "-" + day.to_s.rjust(2, '0') if day > 0
         return result
       else
         return ""
       end
     end
 
-    # Public: Spaceship operator for date comparisons. Comparisons start
-    # with year, then month, then day - which are bitmask functions and 
-    # faster than 'self.value' which requires math to produce the integer.
+    # Public: Spaceship operator for date comparisons. Comparisons are
+    # made using the bit containing backing store. However the sign bit 
+    # is in MSB - so we need to left shift both values by 1 first.
     #
     # Returns -1, 1, or 0
     def <=>(other_date)
-      if self.year < other_date.year
-        -1
-      elsif self.year > other_date.year
-        1
-      else
-        if self.month < other_date.month
-          -1
-        elsif self.month > other_date.month
-          1
+        (@bits << 1) <=> (other_date.bits << 1)
+    end
+
+
+    def self.get_date(register)
+        date = (get_year(register) * 10000).abs + (get_month(register) * 100) + get_day(register) 
+        if get_sign(register) == 1
+          date * -1
         else
-          if self.day < other_date.day
-            -1
-          elsif self.day > other_date.day
-            1
-          else
-            0
-          end
+          date
         end
+    end
+
+    def self.set_date(register, value)
+        register = set_sign(register, 1) if value < 0
+        register = set_year(register, (value.abs / 10000).abs)
+        register = set_month(register, ((value - (value / 10000).abs * 10000) / 100).abs)
+        register = set_day(register, value - (value / 100).abs * 100)
+    end
+
+    def self.get_sign(register)
+      (register & SIGN_MASK) >> SIGN_SHIFT
+    end
+
+    def self.set_sign(register, value)
+      register = (register & ZERO_SIGN_MASK) | (value << SIGN_SHIFT)
+    end
+
+    def self.get_year(register)
+      year = (register & YEAR_MASK) >> YEAR_SHIFT
+      if get_sign(register) == 1 
+        year * -1
+      else
+        year
       end
     end
+
+    def self.set_year(register, value)
+      register = set_sign(register, 1) if value < 0
+      register = (register & ZERO_YEAR_MASK) | (value.abs << YEAR_SHIFT)
+    end
+
+    def self.get_month(register)
+      (register & MONTH_MASK) >> MONTH_SHIFT
+    end
+
+    def self.set_month(register, value)
+      register = (register & ZERO_MONTH_MASK) | (value << MONTH_SHIFT)
+    end
+
+    def self.get_day(register)
+      register & DAY_MASK
+    end
+
+    def self.set_day(register, value)
+      register = (register & ZERO_DAY_MASK) | value
+    end
+
   end
 end

data/lib/partial-date/error.rb

@@ -1,4 +1,13 @@
 module PartialDate
   class PartialDateError < StandardError
   end
+
+  class YearError < PartialDateError 
+  end
+
+  class MonthError < PartialDateError 
+  end
+
+  class DayError < PartialDateError 
+  end
 end

data/lib/partial-date/version.rb

@@ -1,4 +1,4 @@
 module PartialDate
   # partial-date version
-    VERSION = "1.1.4"
+    VERSION = "1.1.5"
 end

data/spec/date_spec.rb

@@ -44,7 +44,7 @@ describe PartialDate::Date do
   end
 
   it "should not allow an invalid date value to be set in a date instance" do
-    expect {new_date = PartialDate::Date.new {|d| d.value = 100000000}}.to raise_error(PartialDate::PartialDateError, "Date value must be an integer betwen 10000 and 99991231")
+    expect {new_date = PartialDate::Date.new {|d| d.value = 10485761232 }}.to raise_error(PartialDate::PartialDateError, "Date value must be an integer betwen -10485761231 and 10485761231")
   end
 
   it "should return a string representation of date in the correct format" do
@@ -62,55 +62,63 @@ describe PartialDate::Date do
     new_date.to_s.should match(/\A\d{4}\z/)
   end
 
-  describe "Year" do
-    it "should raise an error if year is set to nil" do
-      expect {date.year = nil}.to raise_error(PartialDate::PartialDateError)
+  describe "Sign" do
+    it "should be set to 1" do
+      register = 0
+      register = PartialDate::Date.set_sign(register, 1)
+      PartialDate::Date.get_sign(register).should == 1
     end
-
-    it "should raise an error if year is set to an invalid string" do
-      expect {date.year = "ABCD" }.to raise_error(PartialDate::PartialDateError, "Year must be a valid four digit string or integer between 1 and 9999")
+    it "should be 1 if year is a negative value" do
+      register = 0
+      register = PartialDate::Date.set_year(register, -9999)
+      PartialDate::Date.get_sign(register).should == 1
     end
 
-    it "should raise an error if year is set to a five digit string" do
-      expect {date.year = "10000" }.to raise_error(PartialDate::PartialDateError, "Year must be a valid four digit string or integer between 1 and 9999")
+    it "should be 0 if year is a positive value" do
+      register = 0
+      register = PartialDate::Date.set_year(register, 9999)
+      PartialDate::Date.get_sign(register).should == 0
     end
+  end
+
 
-    it "should raise an error if year is set to a value greater than 9999" do
-      expect {date.year = 10000 }.to raise_error(PartialDate::PartialDateError, "Year must be an integer between 1 and 9999")
+  describe "Year" do
+    it "should raise an error if year is set to nil" do
+      expect {date.year = nil}.to raise_error(PartialDate::YearError)
     end
 
-    it "should raise an error if year is set to zero" do
-      expect {date.year = 0 }.to raise_error(PartialDate::PartialDateError, "Year must be an integer between 1 and 9999")
+    it "should raise an error if year is set to an invalid string" do
+      expect {date.year = "ABCD" }.to raise_error(PartialDate::YearError, "Year must be a valid string or integer from -1048576 to 1048576")
     end
 
-    it "should raise an error if year is set to a value less than zero" do
-      expect {date.year = -1 }.to raise_error(PartialDate::PartialDateError, "Year must be an integer between 1 and 9999")
+    it "should raise an error if year is set to a value greater than 1048576" do
+      expect {date.year = 1048577 }.to raise_error(PartialDate::YearError, "Year must be an integer integer from -1048576 to 1048576")
     end
 
-    it "should return a year when a year is set" do
+    it "should return a postive year when a positive year is set" do
       date.year = 2050
       date.year.should == 2050
     end
+
+    it "should return a negative year when a negative year is set" do
+      date.year = -9999
+      date.year.should == -9999
+    end
   end
 
   describe "Month" do
     before(:each) { date.year = 2000 }
 
-    it "should raise an error if a month is set before a year" do
-      no_year = PartialDate::Date.new
-      expect {no_year.month = 10}.to raise_error(PartialDate::PartialDateError, "A year must be set before a month")
-    end
-
     it "should raise an error if month is set to an invalid string" do
-      expect {date.month = "AB"}.to raise_error(PartialDate::PartialDateError, "Month must be a valid one or two digit string or integer between 0 and 12")
+      expect {date.month = "AB"}.to raise_error(PartialDate::MonthError, "Month must be a valid one or two digit string or integer between 0 and 12")
     end
 
     it "should raise an error if month is set to a value greater than 12" do
-      expect {date.month = 13}.to raise_error(PartialDate::PartialDateError, "Month must an be integer between 0 and 12")
+      expect {date.month = 13}.to raise_error(PartialDate::MonthError, "Month must an be integer between 0 and 12")
     end
 
     it "should raise an error if month is set to a value less than zero" do
-      expect {date.month = -1}.to raise_error(PartialDate::PartialDateError, "Month must an be integer between 0 and 12")
+      expect {date.month = -1}.to raise_error(PartialDate::MonthError, "Month must an be integer between 0 and 12")
     end
 
     it "should allow the month to be set to zero" do
@@ -134,23 +142,23 @@ describe PartialDate::Date do
 
     it "should raise an error if a day is set before a year and month" do
       no_month = PartialDate::Date.new
-      expect {no_month.day = 10}.to raise_error(PartialDate::PartialDateError, "A month must be set before a day")
+      expect {no_month.day = 10}.to raise_error(PartialDate::DayError, "A month must be set before a day")
     end
 
     it "should raise an error if day is set to an invalid string" do
-      expect {date.day = "AB"}.to raise_error(PartialDate::PartialDateError, "Day must be a valid one or two digit string or integer between 0 and 31")
+      expect {date.day = "AB"}.to raise_error(PartialDate::DayError, "Day must be a valid one or two digit string or integer between 0 and 31")
     end
 
     it "should raise an error if day is set to a value less than zero" do
-      expect {date.day = -1}.to raise_error(PartialDate::PartialDateError, "Day must be an integer between 0 and 31")
+      expect {date.day = -1}.to raise_error(PartialDate::DayError, "Day must be an integer between 0 and 31")
     end
 
     it "should raise an error if day is set to a value greater than 31" do
-      expect {date.day = 32}.to raise_error(PartialDate::PartialDateError, "Day must be an integer between 0 and 31")
+      expect {date.day = 32}.to raise_error(PartialDate::DayError, "Day must be an integer between 0 and 31")
     end
 
     it "should raise an error if the day is an invalid day for the given month" do
-      expect {date.day = 31}.to raise_error(PartialDate::PartialDateError, "Day must be a valid day for the given month")
+      expect {date.day = 31}.to raise_error(PartialDate::DayError, "Day must be a valid day for the given month")
     end
 
     it "should return zero when set to nil" do

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: partial-date
 version: !ruby/object:Gem::Version
-  version: 1.1.4
+  version: 1.1.5
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-05-28 00:00:00.000000000 Z
+date: 2012-05-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rubygems-tasks
@@ -78,7 +78,6 @@ files:
 - README.textile
 - Rakefile
 - lib/partial-date.rb
-- lib/partial-date/bits.rb
 - lib/partial-date/date.rb
 - lib/partial-date/error.rb
 - lib/partial-date/version.rb

data/lib/partial-date/bits.rb

@@ -1,52 +0,0 @@
-module PartialDate
-
-  class Bits
-
-    # Key:
-    #   The firt 5 bits are the day (max 31)
-    #   The next 4 bits are the month (max 12)
-    #   The topmost/leftmost 14 bits are the year (max 9999)
-
-    DAY_MASK = 0b00000000000000000011111
-    MONTH_MASK = 0b00000000000000111100000
-    YEAR_MASK = 0b11111111111111000000000
-
-    ZERO_YEAR_MASK = 0b00000000000000111111111
-    ZERO_MONTH_MASK = 0b11111111111111000011111
-    ZERO_DAY_MASK = 0b11111111111111111000000
-
-    def self.get_date(register)
-        (get_year(register) * 10000) + (get_month(register) * 100) + get_day(register)
-    end
-
-    def self.set_date(register, value)
-        register = set_year(register, (value / 10000).abs)
-        register = set_month(register, ((value - (value / 10000).abs * 10000) / 100).abs)
-        register = set_day(register, value - (value / 100).abs * 100)
-    end
-
-    def self.get_year(register)
-      (register & YEAR_MASK) >> 9
-    end
-
-    def self.set_year(register, value)
-      register = (register & ZERO_YEAR_MASK) | (value << 9)
-    end
-
-    def self.get_month(register)
-      (register & MONTH_MASK) >> 5
-    end
-
-    def self.set_month(register, value)
-      register = (register & ZERO_MONTH_MASK) | (value << 5)
-    end
-
-    def self.get_day(register)
-      register & DAY_MASK
-    end
-
-    def self.set_day(register, value)
-      register = (register & ZERO_DAY_MASK) | value
-    end
-  end
-end