kronos 0.1.3 → 0.1.4

data/README.md

@@ -55,20 +55,59 @@ In contrast, other date parsing libraries, such as [Chronic](http://github.com/m
 
 Kronos is currently implemented as a thin wrapper over [ParseDate](http://ruby-doc.org/stdlib/libdoc/parsedate/rdoc/index.html).
 
-## Future Plans
+## Date Comparisons
 
-In the future, I would like Kronos to be able to handle date-related comparisons properly.
+Kronos handles date-related comparisons more intelligently.
 
-The Ruby date libraries that I have seen make the assumption that you are specifying a point (i.e. a particular date), not an interval (such as an entire month or year). Comparing intervals adds a little bit of complexity. For example:
+Many Ruby date libraries make the assumption that you are specifying a point (i.e. a particular date), not an interval (such as an entire month or year). Kronos, on the other hand, lets you specify dates that are intervals:
 
-    year = Kronos.parse("1974")
-    month = Kronos.parse("March 1974")
-    year < month    # => false
-    year > month    # => false
-    month == year   # => false
-    year.in?(month) # => false
-    month.in?(year) # => true
+	k_1973       = Kronos.parse("1973")
+	k_1974       = Kronos.parse("1974")
+	k_march_1974 = Kronos.parse("March 1974")
+
+With Kronos, you can compare date objects as follows:
+
+	k_1973 < k_1973          # => true
+    k_1973 < k_march_1974    # => true
+
+### A Note about Kronos Comparison Operators
+
+Kronos interprets "<" as "Does the date interval on the left occur completely before the date interval on the right?" In other words, if there is overlap, the result will be false.
+
+Here's an example. If you ask "Does the year 1974 came before March 1974?" a careful response might be: "Actually, part of it comes before and part of it comes after. Your question does not really make sense because March 1974 is contained within the year 1974."
+
+Because of this, Konos comparison operators (<, ==, >) behave a little bit differently for Kronos objects than for, say, integers. Given any two integers m and n, you can be sure that one of the operators holds. For example:
+
+	m = 1
+	n = 2
+	m < n   # => true
+	m == n  # => false
+	m > n   # => false
+
+However, given two Kronos objects k1 and k2 you cannot guarantee that one of the operators will hold. For example:
+
+    k_1974 < k_march_1974    # => false
+    k_1973 == k_march_1974   # => false
+	k_1974 > k_march_1974    # => false
+
+Since the two dates are unequal but overlap, Kronos will always return false.
+
+### Future Work
+
+I plan to implement the `in?` method as follows:
+
+	k_march_1974.in?(k_1974) # => true
+	k_1974.in?(k_march_1974) # => false
+
+## History
+
+We import a lot of data from government Web sites as part of our work at the Sunlight Labs (the technical arm of the Sunlight Foundation). I did not want to store date-related information in a way that made it seem more precise than it really was, so I wrote this little library. -David
+
+## Contributors
+
+David James (djsun)
+Eric Mill (klondike)
 
 ## Feedback
 
-I would appreciate your feedback. Thanks! (David James, Sunlight Labs, Washington, DC)
+We would appreciate your feedback. Thanks!

data/VERSION

@@ -1 +1 @@
-0.1.3
+0.1.4

data/kronos.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{kronos}
-  s.version = "0.1.3"
+  s.version = "0.1.4"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["David James"]
-  s.date = %q{2009-12-11}
+  s.date = %q{2010-03-09}
   s.description = %q{Kronos provides flexible date parsing. Currently just a thin layer on top of ParseDate.}
   s.email = %q{djames@sunlightfoundation.com}
   s.extra_rdoc_files = [
@@ -25,18 +25,22 @@ Gem::Specification.new do |s|
      "VERSION",
      "kronos.gemspec",
      "lib/kronos.rb",
+     "spec/compare_spec.rb",
      "spec/kronos_spec.rb",
      "spec/spec.opts",
-     "spec/spec_helper.rb"
+     "spec/spec_helper.rb",
+     "spec/valid_spec.rb"
   ]
   s.homepage = %q{http://github.com/djsun/kronos}
   s.rdoc_options = ["--charset=UTF-8"]
   s.require_paths = ["lib"]
-  s.rubygems_version = %q{1.3.5}
+  s.rubygems_version = %q{1.3.6}
   s.summary = %q{Simple and flexible date parsing.}
   s.test_files = [
-    "spec/kronos_spec.rb",
-     "spec/spec_helper.rb"
+    "spec/compare_spec.rb",
+     "spec/kronos_spec.rb",
+     "spec/spec_helper.rb",
+     "spec/valid_spec.rb"
   ]
 
   if s.respond_to? :specification_version then

data/lib/kronos.rb

@@ -29,6 +29,94 @@ class Kronos
     self
   end
   
+  def valid?
+    if day
+      return false unless month && year
+    end
+    if month
+      return false unless year
+    end
+    true
+  end
+
+  def <(other)
+    if !self.year || !other.year
+      false
+    elsif self.year < other.year
+      true
+    elsif self.year > other.year
+      false
+    elsif self.year == other.year
+      if !self.month || !other.month
+        false
+      elsif self.month < other.month
+        true
+      elsif self.month > other.month
+        false
+      elsif self.month == other.month
+        if !self.day || !other.day
+          false
+        elsif self.day < other.day
+          true
+        elsif self.day > other.day
+          false
+        elsif self.day == other.day
+          false
+        else
+          raise "Unexpected"
+        end
+      end
+    else
+      raise "Unexpected"
+    end
+  end
+  
+  def <=(other)
+    (self < other) || (self == other)
+  end
+  
+  def ==(other)
+    self.year == other.year &&
+    self.month == other.month &&
+    self.day == other.day 
+  end
+  
+  def >=(other)
+    (self > other) || (self == other)
+  end
+  
+  def >(other)
+    if !self.year || !other.year
+      false
+    elsif self.year < other.year
+      false
+    elsif self.year > other.year
+      true
+    elsif self.year == other.year
+      if !self.month || !other.month
+        false
+      elsif self.month < other.month
+        false
+      elsif self.month > other.month
+        true
+      elsif self.month == other.month
+        if !self.day || !other.day
+          false
+        elsif self.day < other.day
+          false
+        elsif self.day > other.day
+          true
+        elsif self.day == other.day
+          false
+        else
+          raise "Unexpected"
+        end
+      end
+    else
+      raise "Unexpected"
+    end
+  end
+  
   def to_hash
     h = {}
     h['year']  = year  if year

data/spec/compare_spec.rb

@@ -0,0 +1,229 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+
+describe "Kronos Comparisons" do
+  
+  def new_kronos(year=nil, month=nil, day=nil)
+    k = Kronos.new
+    k.year  = year if year
+    k.month = month if month
+    k.day   = day if day
+    k
+  end
+  
+  describe "2005 vs 2005" do
+    before do
+      @k1 = new_kronos(2005)
+      @k2 = new_kronos(2005)
+    end
+
+    it "should not be <" do
+      (@k1 < @k2).should == false
+    end
+
+    it "should be <=" do
+      (@k1 <= @k2).should == true
+    end
+
+    it "should be ==" do
+      (@k1 == @k2).should == true
+    end
+
+    it "should be >=" do
+      (@k1 >= @k2).should == true
+    end
+
+    it "should not be >" do
+      (@k1 > @k2).should == false
+    end
+
+  end
+  
+  describe "2005 vs 2006" do
+    before do
+      @k1 = new_kronos(2005)
+      @k2 = new_kronos(2006)
+    end
+
+    it "should be <" do
+      (@k1 < @k2).should == true
+    end
+
+    it "should be <=" do
+      (@k1 <= @k2).should == true
+    end
+
+    it "should not be ==" do
+      (@k1 == @k2).should == false
+    end
+
+    it "should not be >" do
+      (@k1 > @k2).should == false
+    end
+
+    it "should not be >=" do
+      (@k1 >= @k2).should == false
+    end
+  end
+
+  describe "March 2005 vs 2006" do
+    before do
+      @k1 = new_kronos(2005, 3)
+      @k2 = new_kronos(2006)
+    end
+
+    it "should be <" do
+      (@k1 < @k2).should == true
+    end
+
+    it "should be <=" do
+      (@k1 <= @k2).should == true
+    end
+
+    it "should not be ==" do
+      (@k1 == @k2).should == false
+    end
+
+    it "should not be >" do
+      (@k1 > @k2).should == false
+    end
+
+    it "should not be >=" do
+      (@k1 >= @k2).should == false
+    end
+  end
+
+  describe "April 2000 vs May 2000" do
+    before do
+      @k1 = new_kronos(2000, 4)
+      @k2 = new_kronos(2000, 5)
+    end
+
+    it "should be <" do
+      (@k1 < @k2).should == true
+    end
+
+    it "should be <=" do
+      (@k1 <= @k2).should == true
+    end
+
+    it "should not be ==" do
+      (@k1 == @k2).should == false
+    end
+
+    it "should not be >" do
+      (@k1 > @k2).should == false
+    end
+
+    it "should not be >=" do
+      (@k1 >= @k2).should == false
+    end
+  end
+
+  describe "April 10, 2000 vs May 1, 2000" do
+    before do
+      @k1 = new_kronos(2000, 4, 10)
+      @k2 = new_kronos(2000, 5, 1)
+    end
+
+    it "should be <" do
+      (@k1 < @k2).should == true
+    end
+
+    it "should be <=" do
+      (@k1 <= @k2).should == true
+    end
+
+    it "should not be ==" do
+      (@k1 == @k2).should == false
+    end
+
+    it "should not be >" do
+      (@k1 > @k2).should == false
+    end
+
+    it "should not be >=" do
+      (@k1 >= @k2).should == false
+    end
+  end
+
+  describe "April 10, 2000 vs May 2000" do
+    before do
+      @k1 = new_kronos(2000, 4, 10)
+      @k2 = new_kronos(2000, 5)
+    end
+
+    it "should be <" do
+      (@k1 < @k2).should == true
+    end
+
+    it "should be <=" do
+      (@k1 <= @k2).should == true
+    end
+
+    it "should not be ==" do
+      (@k1 == @k2).should == false
+    end
+
+    it "should not be >" do
+      (@k1 > @k2).should == false
+    end
+
+    it "should not be >=" do
+      (@k1 >= @k2).should == false
+    end
+  end
+
+  describe "April 10, 2000 vs April 8, 2000" do
+    before do
+      @k1 = new_kronos(2000, 4, 10)
+      @k2 = new_kronos(2000, 4, 8)
+    end
+
+    it "should not be <" do
+      (@k1 < @k2).should == false
+    end
+
+    it "should not be <=" do
+      (@k1 <= @k2).should == false
+    end
+
+    it "should not be ==" do
+      (@k1 == @k2).should == false
+    end
+
+    it "should be >" do
+      (@k1 > @k2).should == true
+    end
+
+    it "should be >=" do
+      (@k1 >= @k2).should == true
+    end
+  end
+  
+  describe "(blank) vs 2000" do
+    before do
+      @k1 = new_kronos()
+      @k2 = new_kronos(2000)
+    end
+  
+    it "should not be <" do
+      (@k1 < @k2).should == false
+    end
+  
+    it "should not be <=" do
+      (@k1 <= @k2).should == false
+    end
+  
+    it "should not be ==" do
+      (@k1 == @k2).should == false
+    end
+  
+    it "should not be >" do
+      (@k1 > @k2).should == false
+    end
+  
+    it "should not be >=" do
+      (@k1 >= @k2).should == false
+    end
+  end
+end

data/spec/valid_spec.rb

@@ -0,0 +1,29 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+
+describe "Kronos Comparisons" do
+  
+  def new_kronos(year=nil, month=nil, day=nil)
+    k = Kronos.new
+    k.year  = year if year
+    k.month = month if month
+    k.day   = day if day
+    k
+  end
+  
+  it "year only is valid" do
+    new_kronos(2005).valid?.should == true
+  end
+
+  it "month and year is valid" do
+    new_kronos(2005, 8).valid?.should == true
+  end
+
+  it "month, day, and year is valid" do
+    new_kronos(2005, 8, 22).valid?.should == true
+  end
+
+  it "day and year is invalid" do
+    new_kronos(2005, nil, 22).valid?.should == false
+  end
+
+end

metadata

@@ -1,7 +1,12 @@
 --- !ruby/object:Gem::Specification 
 name: kronos
 version: !ruby/object:Gem::Version 
-  version: 0.1.3
+  prerelease: false
+  segments: 
+  - 0
+  - 1
+  - 4
+  version: 0.1.4
 platform: ruby
 authors: 
 - David James
@@ -9,19 +14,23 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-12-11 00:00:00 -05:00
+date: 2010-03-09 00:00:00 -05:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: rspec
-  type: :development
-  version_requirement: 
-  version_requirements: !ruby/object:Gem::Requirement 
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
+        segments: 
+        - 1
+        - 2
+        - 9
         version: 1.2.9
-    version: 
+  type: :development
+  version_requirements: *id001
 description: Kronos provides flexible date parsing. Currently just a thin layer on top of ParseDate.
 email: djames@sunlightfoundation.com
 executables: []
@@ -40,9 +49,11 @@ files:
 - VERSION
 - kronos.gemspec
 - lib/kronos.rb
+- spec/compare_spec.rb
 - spec/kronos_spec.rb
 - spec/spec.opts
 - spec/spec_helper.rb
+- spec/valid_spec.rb
 has_rdoc: true
 homepage: http://github.com/djsun/kronos
 licenses: []
@@ -56,21 +67,25 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      segments: 
+      - 0
       version: "0"
-  version: 
 required_rubygems_version: !ruby/object:Gem::Requirement 
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      segments: 
+      - 0
       version: "0"
-  version: 
 requirements: []
 
 rubyforge_project: 
-rubygems_version: 1.3.5
+rubygems_version: 1.3.6
 signing_key: 
 specification_version: 3
 summary: Simple and flexible date parsing.
 test_files: 
+- spec/compare_spec.rb
 - spec/kronos_spec.rb
 - spec/spec_helper.rb
+- spec/valid_spec.rb