timeframe 0.0.1

data/.document

@@ -0,0 +1,5 @@
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/.gitignore

@@ -0,0 +1,21 @@
+## MAC OS
+.DS_Store
+
+## TEXTMATE
+*.tmproj
+tmtags
+
+## EMACS
+*~
+\#*
+.\#*
+
+## VIM
+*.swp
+
+## PROJECT::GENERAL
+coverage
+rdoc
+pkg
+
+## PROJECT::SPECIFIC

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Andy Rossmeissl
+
+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/README.rdoc

@@ -0,0 +1,13 @@
+= timeframe
+
+A Ruby class for describing and interacting with timeframes.
+
+== Documentation
+
+== Acknoweldgements
+
+The good parts of Timeframe all came from the gentlemen at Fingertips[http://fngtps.com].
+
+== Copyright
+
+Copyright (c) 2010 Andy Rossmeissl.

data/Rakefile

@@ -0,0 +1,46 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "timeframe"
+    gem.summary = %Q{Date intervals}
+    gem.description = %Q{A Ruby class for describing and interacting with timeframes.}
+    gem.email = "andy@rossmeissl.net"
+    gem.homepage = "http://github.com/rossmeissl/timeframe"
+    gem.authors = ["Andy Rossmeissl"]
+    gem.add_development_dependency "rspec", ">= 1.2.9"
+    gem.add_dependency 'activesupport', '= 3.0.0.beta4'
+    gem.add_dependency 'andand'
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+require 'spec/rake/spectask'
+Spec::Rake::SpecTask.new(:spec) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.spec_files = FileList['spec/**/*_spec.rb']
+end
+
+Spec::Rake::SpecTask.new(:rcov) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+task :spec => :check_dependencies
+
+task :default => :spec
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "timeframe #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.0.1

data/lib/timeframe.rb

@@ -0,0 +1,297 @@
+require 'rubygems'
+require 'active_support/version'
+%w{
+  active_support/core_ext/array/extract_options
+  active_support/core_ext/string/conversions
+  active_support/core_ext/date/conversions
+  active_support/core_ext/integer/time
+  active_support/core_ext/numeric/time
+}.each do |active_support_3_requirement|
+  require active_support_3_requirement
+end if ActiveSupport::VERSION::MAJOR == 3
+require 'andand'
+require 'timeframe/ykk'
+
+# Encapsulates a timeframe between two dates. The dates provided to the class are always until the last date. That means
+# that the last date is excluded.
+#
+#   # from 2007-10-01 00:00:00.000 to 2007-10-31 23:59:59.999
+#   Timeframe.new(Date(2007,10,1), Date(2007,11,1))
+#   # and holds 31 days
+#   Timeframe.new(Date(2007,10,1), Date(2007,11,1)).days #=> 31
+class Timeframe
+  attr_accessor :from, :to
+
+  # Creates a new instance of Timeframe. You can either pass a start and end Date or a Hash with named arguments,
+  # with the following options:
+  #
+  #   <tt>:month</tt>: Start date becomes the first day of this month, and the end date becomes the first day of
+  #   the next month. If no <tt>:year</tt> is specified, the current year is used.
+  #   <tt>:year</tt>: Start date becomes the first day of this year, and the end date becomes the first day of the
+  #   next year.
+  #
+  # By default, Timeframe.new will die if the resulting Timeframe would cross year boundaries. This can be overridden
+  # by setting the <tt>:skip_year_boundary_crossing_check</tt> option.
+  #
+  # Examples:
+  #
+  #   Timeframe.new Date.new(2007, 2, 1), Date.new(2007, 4, 1) # February and March
+  #   Timeframe.new :year => 2004 # The year 2004
+  #   Timeframe.new :month => 4 # April
+  #   Timeframe.new :year => 2004, :month => 2 # Feburary 2004
+  def initialize(*args)
+    options = args.extract_options!
+
+    if month = options[:month]
+      month = Date.parse(month).month if month.is_a? String
+      year = options[:year] || Date.today.year
+      from = Date.new(year, month, 1)
+      to   = from.next_month
+    elsif year = options[:year]
+      from = Date.new(year, 1, 1)
+      to   = Date.new(year+1, 1, 1)
+    end
+
+    from ||= args.shift.andand.to_date
+    to ||= args.shift.andand.to_date
+
+    raise ArgumentError, "Please supply a start and end date, `#{args.map(&:inspect).to_sentence}' is not enough" if from.nil? or to.nil?
+    raise ArgumentError, "Start date #{from} should be earlier than end date #{to}" if from > to
+    raise ArgumentError, 'Timeframes that cross year boundaries are dangerous' unless options[:skip_year_boundary_crossing_check] or from.year == to.yesterday.year or from == to
+
+    @from, @to = from, to
+  end
+  
+  def inspect # :nodoc:
+    "<Timeframe(#{object_id}) #{days} days starting #{from} ending #{to}>"
+  end
+
+  # The number of days in the timeframe
+  #
+  #   Timeframe.new(Date.new(2007, 11, 1), Date.new(2007, 12, 1)).days #=> 30
+  #   Timeframe.new(:month => 1).days #=> 31
+  #   Timeframe.new(:year => 2004).days #=> 366
+  def days
+    (to - from).to_i
+  end
+  
+  # Returns a string representation of the timeframe
+  def to_s
+    if [from.day, from.month, to.day, to.month].uniq == [1]
+      from.year.to_s
+    elsif from.day == 1 and to.day == 1 and to.month - from.month == 1
+      "#{Date::MONTHNAMES[from.month]} #{from.year}"
+    else
+      "the period from #{from.strftime('%d %B')} to #{to.yesterday.strftime('%d %B %Y')}"
+    end
+  end
+
+  # Returns true when a Date or other Timeframe is included in this Timeframe
+  def include?(obj)
+    # puts "checking to see if #{date} is between #{from} and #{to}" if Emitter::DEBUG
+    case obj
+    when Date
+      (from...to).include?(obj)
+    when Time
+      # (from...to).include?(obj.to_date)
+      raise "this wasn't previously supported, but it could be"
+    when Timeframe
+      from <= obj.from and to >= obj.to
+    end
+  end
+  
+  # Returns true when the parameter Timeframe is properly included in the Timeframe
+  def proper_include?(other_timeframe)
+    raise ArgumentError, 'Proper inclusion only makes sense when testing other Timeframes' unless other_timeframe.is_a? Timeframe
+    (from < other_timeframe.from) and (to > other_timeframe.to)
+  end
+  
+  # Returns true when this timeframe is equal to the other timeframe
+  def ==(other)
+    # puts "checking to see if #{self} is equal to #{other}" if Emitter::DEBUG
+    return false unless other.is_a?(Timeframe)
+    from == other.from and to == other.to
+  end
+  alias :eql? :==
+    
+  # Calculates a hash value for the Timeframe, used for equality checking and Hash lookups.
+  #--
+  # This needs to be an integer or else it won't use #eql?
+  def hash
+    from.hash + to.hash
+  end
+  alias :to_param :hash
+  
+  # Returns an array of month-long subtimeframes
+  #--
+  # TODO: rename to month_subtimeframes
+  def months
+    raise ArgumentError, "Please only provide whole-month timeframes to Timeframe#months" unless from.day == 1 and to.day == 1
+    raise ArgumentError, 'Timeframes that cross year boundaries are dangerous during Timeframe#months' unless from.year == to.yesterday.year
+    year = from.year # therefore this only works in the from year
+    (from.month..to.yesterday.month).map { |m| Timeframe.new :month => m, :year => year }
+  end
+  
+  # Returns the relevant year as a Timeframe
+  def year
+    raise ArgumentError, 'Timeframes that cross year boundaries are dangerous during Timeframe#year' unless from.year == to.yesterday.year
+    Timeframe.new :year => from.year
+  end
+  
+  # Divides a Timeframe into component parts, each no more than a month long.
+  #--
+  # multiyear safe
+  def month_subtimeframes
+    (from.year..to.yesterday.year).map do |year|
+      (1..12).map do |month|
+        Timeframe.new(:year => year, :month => month) & self
+      end
+    end.flatten.compact
+  end
+  
+  # Like #month_subtimeframes, but will discard partial months
+  # multiyear safe
+  def full_month_subtimeframes
+    month_subtimeframes.map { |st| Timeframe.new(:year => st.from.year, :month => st.from.month) }
+  end
+  
+  # Divides a Timeframe into component parts, each no more than a year long.
+  #--
+  # multiyear safe
+  def year_subtimeframes
+    (from.year..to.yesterday.year).map do |year|
+      Timeframe.new(:year => year) & self
+    end
+  end
+  
+  # Like #year_subtimeframes, but will discard partial years
+  #--
+  # multiyear safe
+  def full_year_subtimeframes
+    (from.year..to.yesterday.year).map do |year|
+      Timeframe.new :year => year
+    end
+  end
+  
+  # Crop a Timeframe to end no later than the provided date.
+  #--
+  # multiyear safe  
+  def ending_no_later_than(date)
+    if to < date
+      self
+    elsif from >= date
+      nil
+    else
+      Timeframe.multiyear from, date
+    end
+  end
+    
+  # Returns a timeframe representing the intersection of the given timeframes
+  def &(other_timeframe)
+    this_timeframe = self
+    if other_timeframe == this_timeframe
+      this_timeframe
+    elsif this_timeframe.from > other_timeframe.from and this_timeframe.to < other_timeframe.to
+      this_timeframe
+    elsif other_timeframe.from > this_timeframe.from and other_timeframe.to < this_timeframe.to
+      other_timeframe
+    elsif this_timeframe.from >= other_timeframe.to or this_timeframe.to <= other_timeframe.from
+      nil
+    else
+      Timeframe.new [this_timeframe.from, other_timeframe.from].max, [this_timeframe.to, other_timeframe.to].min, :skip_year_boundary_crossing_check => true
+    end
+  end
+  
+  # Returns the fraction (as a Float) of another Timeframe that this Timeframe represents
+  def /(other_timeframe)
+    raise ArgumentError, 'You can only divide a Timeframe by another Timeframe' unless other_timeframe.is_a? Timeframe
+    self.days.to_f / other_timeframe.days.to_f
+  end
+  
+  # Crop a Timeframe by another Timeframe
+  def crop(container)
+    raise ArgumentError, 'You can only crop a timeframe by another timeframe' unless container.is_a? Timeframe
+    self.class.new [from, container.from].max, [to, container.to].min
+  end
+  
+  # Returns an array of Timeframes representing the gaps left in the Timeframe after removing all given Timeframes
+  def gaps_left_by(*timeframes)
+    # remove extraneous timeframes
+    timeframes.reject! { |t| t.to <= from }
+    timeframes.reject! { |t| t.from >= to }
+    
+    # crop timeframes
+    timeframes.map! { |t| t.crop self }
+    
+    # remove proper subtimeframes
+    timeframes.reject! { |t| timeframes.detect { |u| u.proper_include? t } }
+    
+    # escape
+    return [self] if  timeframes.empty?
+
+    timeframes.sort! { |x, y| x.from <=> y.from }
+    
+    timeframes.collect(&:to).unshift(from).extend(Ykk).ykk(timeframes.collect(&:from).push(to)) do |gap|
+      Timeframe.new(*gap) if gap[1] > gap[0]
+    end.compact
+  end
+  
+  # Returns true if the union of the given Timeframes includes the Timeframe
+  def covered_by?(*timeframes)
+    gaps_left_by(*timeframes).empty?
+  end
+  
+  # Returns the same Timeframe, only a year earlier
+  def last_year
+    self.class.new((from - 1.year), (to - 1.year))
+  end
+  
+  def to_json # :nodoc:
+    { :from => from, :to => to }.to_json
+  end
+  
+  class << self
+    # Shortcut method to return the Timeframe representing the current year (as defined by Time.now)
+    def this_year
+      new :year => Time.now.year
+    end
+    
+    # Construct a new Timeframe, but constrain it by another
+    def constrained_new(from, to, constraint)
+      raise ArgumentError, 'Need Date, Date, Timeframe as args' unless from.is_a? Date and to.is_a? Date and constraint.is_a? Timeframe
+      raise ArgumentError, "Start date #{from} should be earlier than end date #{to}" if from > to
+      if to <= constraint.from or from >= constraint.to
+        new constraint.from, constraint.from
+      elsif from.year == to.yesterday.year
+        new(from, to) & constraint
+      elsif from.year < constraint.from.year and constraint.from.year < to.yesterday.year
+        constraint
+      else
+        new [constraint.from, from].max, [constraint.to, to].min
+      end
+    end
+    
+    # Shortcut for #new that automatically skips year boundary crossing checks
+    def multiyear(from, to)
+      from = Date.parse(from) if from.is_a?(String)
+      to = Date.parse(to) if to.is_a?(String)
+      new from, to, :skip_year_boundary_crossing_check => true
+    end
+    
+    # Create a multiyear timeframe +/- number of years around today
+    def mid(number)
+      from = Time.zone.today - number.years
+      to = Time.zone.today + number.years
+      multiyear from, to
+    end
+    
+    # Construct a new Timeframe by parsing an ISO 8601 time interval string
+    # http://en.wikipedia.org/wiki/ISO_8601#Time_intervals
+    def interval(interval)
+      raise ArgumentError, 'Intervals should be specified as a string' unless interval.is_a? String
+      raise ArgumentError, 'Intervals should be specified according to ISO 8601, method 1, eliding times' unless interval =~ /^\d\d\d\d-\d\d-\d\d\/\d\d\d\d-\d\d-\d\d$/
+
+      new(*interval.split('/').map { |date| Date.parse date })
+    end
+  end
+end

data/lib/timeframe/ykk.rb

@@ -0,0 +1,6 @@
+module Ykk
+  def ykk(*arys, &blk) # YKK: a better zipper
+    return zip(*arys) unless block_given?
+    zip(*arys).collect { |a| yield a }
+  end
+end

data/spec/spec.opts

@@ -0,0 +1 @@
+--color

data/spec/spec_helper.rb

@@ -0,0 +1,10 @@
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+require 'timeframe'
+require 'spec'
+require 'spec/autorun'
+require 'date'
+
+Spec::Runner.configure do |config|
+  
+end

data/spec/timeframe_spec.rb

@@ -0,0 +1,248 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+require 'date'
+
+describe Timeframe do
+  describe 'initialization' do
+    it 'should create a timeframe using date strings' do
+      tf = Timeframe.new('2008-02-14', '2008-05-10')
+      tf.from.should == Date.parse('2008-02-14')
+      tf.to.should == Date.parse('2008-05-10')
+    end
+    it 'should create a timeframe using date objects' do
+      start = Date.parse('2008-02-14')
+      finish = Date.parse('2008-05-10')
+      tf = Timeframe.new(start, finish)
+      tf.from.should == start
+      tf.to.should == finish
+    end
+    it "should accept months" do
+      timeframe = Timeframe.new(:month => 1)
+      timeframe.from.should == Date.today.change(:month => 1, :day => 1)
+      timeframe.to.should == Date.today.change(:month => 2, :day => 1)
+    end
+    it "should accept month names" do
+      timeframe = Timeframe.new(:month => 'february')
+      timeframe.from.should == Date.today.change(:month => 2, :day => 1)
+      timeframe.to.should == Date.today.change(:month => 3, :day => 1)
+    end
+    it "should accept years" do
+      timeframe = Timeframe.new(:year => 2004)
+      timeframe.from.should == Date.new(2004, 1, 1)
+      timeframe.to.should == Date.new(2005, 1, 1)
+    end
+    it "should accept years and months" do
+      timeframe = Timeframe.new(:year => 2005, :month => 5)
+      timeframe.from.should == Date.new(2005, 5, 1)
+      timeframe.to.should == Date.new(2005, 6, 1)
+    end
+    it "should not accept just one date argument" do
+      lambda {
+        Timeframe.new Date.new(2007, 2, 1)
+      }.should raise_error(ArgumentError, /supply/)
+    end
+    it "should not accept end date that is earlier than start date" do
+      lambda {
+        timeframe = Timeframe.new Date.new(2008, 1, 1), Date.new(2007, 1, 1)
+      }.should raise_error(ArgumentError, /earlier/)
+    end
+    it "should not accept timeframes that cross year boundaries" do
+      lambda {
+        timeframe = Timeframe.new Date.new(2007, 1, 1), Date.new(2008, 1, 2)
+      }.should raise_error(ArgumentError, /cross/)
+    end
+    it "should optionally accept timeframes that cross year boundaries" do
+      lambda {
+        timeframe = Timeframe.new Date.new(2007, 1, 1), Date.new(2008, 1, 2), :skip_year_boundary_crossing_check => true
+      }.should_not raise_error
+    end
+  end
+
+  describe '#inspect' do
+    it 'should return the time frame in readable text' do
+      start = Date.parse('2008-02-14')
+      finish = Date.parse('2008-05-10')
+      tf = Timeframe.new(start, finish)
+      tf.inspect.should =~ /<Timeframe\(-?\d+\) 86 days starting 2008-02-14 ending 2008-05-10>/
+    end
+  end
+
+  describe '.constrained_new' do
+    let(:start) { Date.parse('2008-02-14') }
+    let(:finish) { Date.parse('2008-05-10') }
+    let(:constraint_start) { Date.parse('2008-01-01') }
+    let(:constraint_finish) { Date.parse('2008-12-01') }
+    let(:constraint) { Timeframe.new(constraint_start, constraint_finish) }
+
+    it "should allow for constrained creation" do
+      constraint = Timeframe.new :year => 2008
+      may = Timeframe.new Date.new(2008,5,1), Date.new(2008,6,1)
+      january = Timeframe.new Date.new(2008,1,1), Date.new(2008,2,1)
+      Timeframe.constrained_new(may.from, may.to, constraint).should == may
+      Timeframe.constrained_new(Date.new(2007,1,1), Date.new(2010,1,1), constraint).should == constraint
+      Timeframe.constrained_new(Date.new(2007,11,1), Date.new(2008,2,1), constraint).should == january
+    end
+    it 'should return a timeframe spanning start and end date if within constraint' do
+      tf = Timeframe.constrained_new(start, finish, constraint)
+      tf.from.should == start
+      tf.to.should == finish
+    end
+    it 'should return a timeframe spanning constraint start and end date if outside constraint' do
+      constraint = Timeframe.new(start, finish)
+      tf = Timeframe.constrained_new(constraint_start, constraint_finish, constraint)
+      tf.from.should == start
+      tf.to.should == finish
+    end
+    it 'should return a timeframe starting at constraint start' do
+      start = Date.parse('2008-01-01')
+      constraint_start = Date.parse('2008-01-14')
+      constraint = Timeframe.new(constraint_start, constraint_finish)
+      tf = Timeframe.constrained_new(start, finish, constraint)
+      tf.from.should == constraint_start
+      tf.to.should == finish
+    end
+    it 'should return a timeframe ending at constraint end' do
+      constraint_finish = Date.parse('2008-04-14')
+      constraint = Timeframe.new(constraint_start, constraint_finish)
+      tf = Timeframe.constrained_new(start, finish, constraint)
+      tf.from.should == start
+      tf.to.should == constraint_finish
+    end
+    it "should return a 0-length timeframe when constraining a timeframe by a disjoint timeframe" do
+      constraint = Timeframe.new :year => 2010
+      timeframe = Timeframe.constrained_new(
+        Date.new(2009,1,1), Date.new(2010,1,1), constraint)
+      timeframe.days.should == 0
+    end
+  end
+
+  describe '.this_year' do
+    it "should return the current year" do
+      Timeframe.this_year.should == Timeframe.new(:year => Time.now.year)
+    end
+  end
+
+  describe '#days' do
+    it "should return them number of days included" do
+      #TODO: make these separate "it" blocks, per best practices
+      Timeframe.new(Date.new(2007, 1, 1), Date.new(2008, 1, 1)).days.should == 365
+      Timeframe.new(Date.new(2008, 1, 1), Date.new(2009, 1, 1)).days.should == 366 #leap year
+      Timeframe.new(Date.new(2007, 11, 1), Date.new(2007, 12, 1)).days.should == 30
+      Timeframe.new(Date.new(2007, 11, 1), Date.new(2008, 1, 1)).days.should == 61
+      Timeframe.new(Date.new(2007, 2, 1), Date.new(2007, 3, 1)).days.should == 28
+      Timeframe.new(Date.new(2008, 2, 1), Date.new(2008, 3, 1)).days.should == 29
+      Timeframe.new(Date.new(2008, 2, 1), Date.new(2008, 2, 1)).days.should == 0
+    end
+  end
+
+  describe '#include?' do
+    it "should know if a certain date is included in the Timeframe" do
+      #TODO: make these separate "it" blocks, per best practices
+      timeframe = Timeframe.new :year => 2008, :month => 2
+      [
+        Date.new(2008, 2, 1),
+        Date.new(2008, 2, 5),
+        Date.new(2008, 2, 29)
+      ].each do |date|
+        timeframe.include?(date).should == true
+      end
+      [
+        Date.new(2008, 1, 1),
+        Date.new(2007, 2, 1),
+        Date.new(2008, 3, 1)
+      ].each do |date|
+        timeframe.include?(date).should == false
+      end
+    end
+  end
+
+  describe '#==' do
+    it "should be able to know if it's equal to another Timeframe object" do
+      Timeframe.new(:year => 2007).should == Timeframe.new(:year => 2007)
+      Timeframe.new(:year => 2004, :month => 1).should == Timeframe.new(:year => 2004, :month => 1)
+    end
+    
+    it "should hash equal hash values when the timeframe is equal" do
+      Timeframe.new(:year => 2007).hash.should == Timeframe.new(:year => 2007).hash
+      Timeframe.new(:year => 2004, :month => 1).hash.should == Timeframe.new(:year => 2004, :month => 1).hash
+    end
+  end
+
+  describe '#months' do
+    it "should return an array of month-long subtimeframes" do
+      Timeframe.new(:year => 2009).months.length.should == 12
+    end
+    it "should not return an array of month-long subtimeframes if provided an inappropriate range" do
+      lambda { 
+        Timeframe.new(Date.new(2009, 3, 2), Date.new(2009, 3, 5)).months
+      }.should raise_error(ArgumentError, /whole/)
+      lambda {
+        Timeframe.new(Date.new(2009, 1, 1), Date.new(2012, 1, 1), :skip_year_boundary_crossing_check => true).months
+      }.should raise_error(ArgumentError, /dangerous during/)
+    end
+  end
+
+  describe '#year' do
+    it "should return the relevant year of a timeframe" do
+      Timeframe.new(Date.new(2009, 2, 1), Date.new(2009, 4, 1)).year.should == Timeframe.new(:year => 2009)
+    end
+    it "should not return the relevant year of a timeframe if provided an inappropriate range" do
+      lambda {
+        Timeframe.new(Date.new(2009, 1, 1), Date.new(2012, 1, 1), :skip_year_boundary_crossing_check => true).year
+      }.should raise_error(ArgumentError, /dangerous during/)
+    end
+  end
+
+  describe '#&' do
+    it "should return its intersection with another timeframe" do
+      #TODO: make these separate "it" blocks, per best practices
+      (Timeframe.new(:month => 4) & Timeframe.new(:month => 6)).should be_nil
+      (Timeframe.new(:month => 4) & Timeframe.new(:month => 5)).should be_nil
+      (Timeframe.new(:month => 4) & Timeframe.new(:month => 4)).should == Timeframe.new(:month => 4)
+      (Timeframe.new(:year => Time.now.year) & Timeframe.new(:month => 4)).should == Timeframe.new(:month => 4)
+      (Timeframe.new(Date.new(2009, 2, 1), Date.new(2009, 6, 1)) & Timeframe.new(Date.new(2009, 4, 1), Date.new(2009, 8, 1))).should == Timeframe.new(Date.new(2009, 4, 1), Date.new(2009, 6, 1))
+    end
+  end
+
+  describe '#/' do
+    it "should return a fraction of another timeframe" do 
+      (Timeframe.new(:month => 4, :year => 2009) / Timeframe.new(:year => 2009)).should == (30.0 / 365.0)
+    end
+  end
+
+  describe '#gaps_left_by' do
+    it "should be able to ascertain gaps left by a list of other Timeframes" do
+      Timeframe.new(:year => 2009).gaps_left_by(
+        Timeframe.new(:year => 2009, :month => 3),
+        Timeframe.new(:year => 2009, :month => 5),
+        Timeframe.new(Date.new(2009, 8, 1), Date.new(2009, 11, 1)),
+        Timeframe.new(Date.new(2009, 9, 1), Date.new(2009, 10, 1))
+      ).should == 
+        [ Timeframe.new(Date.new(2009, 1, 1), Date.new(2009, 3, 1)),
+          Timeframe.new(Date.new(2009, 4, 1), Date.new(2009, 5, 1)),
+          Timeframe.new(Date.new(2009, 6, 1), Date.new(2009, 8, 1)),
+          Timeframe.new(Date.new(2009, 11, 1), Date.new(2010, 1, 1)) ]
+    end
+  end
+
+  describe '#covered_by?' do
+    it "should be able to ascertain gaps left by a list of other Timeframes" do
+      Timeframe.new(:year => 2009).covered_by?(
+        Timeframe.new(:month => 1, :year => 2009), 
+        Timeframe.new(Date.new(2009, 2, 1), Date.new(2010, 1, 1))
+      ).should be_true
+    end
+  end
+
+  describe '#last_year' do
+    it "should return its predecessor in a previous year" do
+      Timeframe.this_year.last_year.should ==
+        Timeframe.new(Date.new(Date.today.year - 1, 1, 1), Date.new(Date.today.year, 1, 1))
+    end
+  end
+  
+  describe 'Timeframe:class#interval' do
+    it 'should parse ISO 8601 interval format' do
+      Timeframe.interval('2009-01-01/2010-01-01').should == Timeframe.new(:year => 2009)
+    end
+  end
+end

metadata

@@ -0,0 +1,114 @@
+--- !ruby/object:Gem::Specification 
+name: timeframe
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 0
+  - 1
+  version: 0.0.1
+platform: ruby
+authors: 
+- Andy Rossmeissl
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-07-15 00:00:00 -04:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 1
+        - 2
+        - 9
+        version: 1.2.9
+  type: :development
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: activesupport
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - "="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 3
+        - 0
+        - 0
+        - beta4
+        version: 3.0.0.beta4
+  type: :runtime
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: andand
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :runtime
+  version_requirements: *id003
+description: A Ruby class for describing and interacting with timeframes.
+email: andy@rossmeissl.net
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README.rdoc
+files: 
+- .document
+- .gitignore
+- LICENSE
+- README.rdoc
+- Rakefile
+- VERSION
+- lib/timeframe.rb
+- lib/timeframe/ykk.rb
+- spec/spec.opts
+- spec/spec_helper.rb
+- spec/timeframe_spec.rb
+has_rdoc: true
+homepage: http://github.com/rossmeissl/timeframe
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.6
+signing_key: 
+specification_version: 3
+summary: Date intervals
+test_files: 
+- spec/spec_helper.rb
+- spec/timeframe_spec.rb