time_ext 0.1.0 → 0.2.0

data/.gitignore

@@ -20,3 +20,5 @@ pkg
 
 ## PROJECT::SPECIFIC
 .yardoc/*
+*.gemspec
+doc/*

data/README.md

@@ -10,20 +10,54 @@ This gem extends the abilities of Ruby's built-in Time class by building on top
 
 ## Basic Usage
 
-    require "time/ext"
-    Time.now.round(:week)
+### Pure Ruby
+
+    require "time/ext" # or "time_ext"
+    Time.utc(2010, 6, 19).round(:month) #=> Thu Jul 01 00:00:00 UTC 2010
     #=> Beginning of this week, or next week depending on which date is closest
+    Time.now.each_hour.until(6.hours.from_now) { |t| puts t.to_s }
+    #=> Prints the time at one hour interals from now till 6 hours from now
+
+### Rails 2.x
+
+    config.gem "time_ext"
+
+### Rails 3.x
+
+    gem "time_ext"
 
 
 ## Documentation
 
-A decently informative documentation is available [here][docs] on [rdoc.info][].
+Complete class and method documentation is available [here][docs] on [rdoc.info][].
+
+### Calculations
+
+ActiveSupport includes some handy `#beginning_of_*` and `#end_of_*` methods among others for year, month, week, and day. TimeExt adds the same methods for quarter (3 months), hour, minute, and second. Additionally it also adds a set of familiar math methods, `#floor`, `#ceil`, and `#round`. Each of them takes a unit argument (day, month, etc.), and goes about it's operation to that unit type.
+
+### Iterations
+
+You can easily iterate over specific units of time with the `#each`, `#beginning_of_each`, `#map_each`, and `#map_beginning_of_each` methods. Each method takes a unit input, just like the `#floor` method for example. But the iteration methods also have dynamic unit methods, like so:
+
+    time = Time.local(2010, 07, 10)
+    time.map_each(:hour).until(time + 6.hours) { |t| t.hour } #=> [1, 2, 3, 4, 5, 6]
+    time.map_each_hour.until(time + 6.hours) { |t| t.hour } #=> [1, 2, 3, 4, 5, 6]
+    
+The `#until` method defines when to stop the iteration. You can also use the `#from` method, which then iterates from the time passed into `#from` till the time of the object you're calling each on. If don't specify a end/start time, it'll assume you want all units within it's scope. Or in less gibberish, calling `#each_hour` will iterate every hour for a whole day, or 24 hours. If you're iterating by the minute, it'll stop after an hour.
+
+Here's a couple of more examples:
+
+    time.map_each_hour.until(time + 6.hours) { |t| t.hour } #=> [1, 2, 3, 4, 5, 6]
+    time.until(time + 6.hours).map_each_hour { |t| t.hour } #=> [1, 2, 3, 4, 5, 6]
+    (time + 6.hours).map_each_hour.from(time) { |t| t.hour } #=> [1, 2, 3, 4, 5, 6]
+    (time + 6.hours).from(time).map_each_hour { |t| t.hour } #=> [1, 2, 3, 4, 5, 6]
 
-The main reason I created this gem was for the `round`, `floor`, and `ceil` methods. Each of them takes a unit argument, which can be one of the following: `:sec`, `:min`, `:hour`, `:day`, `:week`, `:month`, `:quarter`, and `:year`.
+I recommend you read the complete class [documentation][docs] for the Time object to see all the new methods available.
 
 
 ## To-Do
 
+* Some cleaner code.
 * Improve ReadMe file.
 * Improve documentation.
 

data/VERSION

@@ -1 +1 @@
-0.1.0
+0.2.0

data/lib/time_ext/{time.rb → core_ext/time/calculations.rb}

@@ -32,15 +32,25 @@ class Time
   end
   alias :beginning_of_closest :round
   
+  # Returns a new Time representing the previoius unit specified (defaults to second).
+  def prev(unit = :sec)
+    send("prev_#{unit}")
+  end
+  
+  # Returns a new Time representing the next unit specified (defaults to second).
+  def next(unit = :sec)
+    send("next_#{unit}")
+  end
+  
   # Short-hand for seconds_ago(1).
   def prev_second
-    ago(1)
+    seconds_ago(1)
   end
   alias :prev_sec :prev_second
   
   # Short-hand for seconds_since(1).
   def next_second
-    since(1)
+    seconds_since(1)
   end
   alias :next_sec :next_second
   
@@ -149,6 +159,11 @@ class Time
     since((quarters * 3).months)
   end
   
+  # Returns a new Time representing the end of the unit specified (defaults to second).
+  def end_of(unit = :sec)
+    send("end_of_#{unit}")
+  end
+  
   # Returns a new Time representing the start of the second, XX:XX:XX.000000 (.000000000 in ruby1.9).
   def beginning_of_second
     change(:usec => 0)

data/lib/time_ext/core_ext/time/iterations.rb

@@ -0,0 +1,79 @@
+class Time
+  include TimeExt::MethodChain
+  
+  # Used by #each, #map_each and similar methods to iterate over ranges of time.
+  def iterate(unit, options = {}, &block)
+    options.reverse_merge!(:map_result => false, :beginning_of => false, :include_start => false)
+    if block_given?
+      units = [:year, :month, :day, :hour, :min, :sec, :usec]
+      parent_unit = units[units.index(unit)-1]
+      @until ||= (!parent_unit.nil?) ? self.send("#{parent_unit}s_since", 1) : self.send("#{unit}s_since", 1)
+      time = self.clone
+      direction = (self < @until) ? :f : :b
+      succ_method = (direction == :f) ? "next_#{unit}" : "prev_#{unit}"
+      time = time.beginning_of(unit) if options[:beginning_of]
+      time = time.send(succ_method) if !options[:include_start]
+      results = []
+      while (direction == :f && time <= @until) || (direction == :b && time >= @until)
+        options[:map_result] ? results << yield(time) : yield(time)
+        time = time.send(succ_method)
+      end
+      options[:map_result] ? results : self
+    else
+      add_to_chain(:iterate, unit, options)
+      self
+    end
+  end
+  
+  # Used togeter with #each and other iteration methods to specify end of interation.
+  def until(time, &block)
+    time = time.to_time if time.is_a?(::Date)
+    @until = time
+    return call_chain(block) if block_given?
+    self
+  end
+  alias :till :until
+  
+  # Used together with #each and other interation methods to specify start of iteration, and end will be current object.
+  def from(time, &block)
+    time = time.to_time if time.is_a?(::Date)
+    method, args = @method_chain.pop if block_given?
+    if !method.nil?
+      time.until(self).send(method, *args, &block)
+    else
+      time.until(self)
+    end
+  end
+  
+  # Executes passed block for each "unit" of time specified, with a new time object for each interval passed to the block.
+  def each(unit, options = {}, &block)
+    iterate(unit, options.merge(:map_result => false), &block)
+  end
+  
+  # Executes passed block for each "unit" of time specified, with a new time object set to the beginning of "unit" for each interval passed to the block.
+  def beginning_of_each(unit, options = {}, &block)
+    iterate(unit, options.merge(:map_result => false, :beginning_of => true), &block)
+  end
+  
+  # Executes passed block for each "unit" of time specified, returning an array with the return values from the passed block.
+  def map_each(unit, options = {}, &block)
+    iterate(unit, options.merge(:map_result => true), &block)
+  end
+  
+  # Executes passed block for each "unit" of time specified, returning an array with the return values from passed block. Additionally the time object passed into the block is set to the beginning of specified "unit".
+  def map_beginning_of_each(unit, options = {}, &block)
+    iterate(unit, options.merge(:map_result => true, :beginning_of => true), &block)
+  end
+  
+  # Dynamically define convenience methods, like #each_hour instead of #each(:hour).
+  [:year, :month, :day, :hour, :min, :sec].each do |unit|
+    [:each, :beginning_of_each, :map_each, :map_beginning_of_each].each do |method|
+      define_method "#{method}_#{unit}" do |*args, &block|
+        send(method, unit, *args, &block)
+      end
+      class_eval { alias :"#{method}_minute" :"#{method}_min" } if unit == :min
+      class_eval { alias :"#{method}_second" :"#{method}_sec" } if unit == :sec
+    end
+  end
+  
+end

data/lib/time_ext/method_chain.rb

@@ -0,0 +1,18 @@
+module TimeExt
+  module MethodChain
+    
+    def add_to_chain(method, *args, &block)
+      @method_chain ||= []
+      @method_chain << [method.to_sym, args, block]
+    end
+    
+    def call_chain(custom_block = nil, &block)
+      method, args, iblock = @method_chain.pop
+      return nil if method.nil?
+      iblock = custom_block if !custom_block.nil?
+      method, args, iblock = yield(method, args, iblock) if block_given?
+      self.send(method, *args, &iblock)
+    end
+    
+  end
+end

data/lib/time_ext.rb

@@ -1,3 +1,13 @@
 require 'rubygems'
 require 'active_support'
-require 'time_ext/time'
+require 'time_ext/method_chain'
+require 'time_ext/core_ext/time/calculations'
+require 'time_ext/core_ext/time/iterations'
+
+module TimeExt
+  
+  module Base
+    TIME_EXT_UNITS = [:year, :month, :day, :hour, :min, :sec, :usec]
+  end
+  
+end

data/spec/{time_ext_spec.rb → time_calculations_spec.rb}

@@ -1,6 +1,6 @@
 require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
 
-describe "TimeExt" do
+describe "Time Calculations" do
   
   before(:each) do
     @time = Time.local(2010, 8, 28, 15, 57, 17, 78430)

data/spec/time_iterations_spec.rb

@@ -0,0 +1,69 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+
+describe "Time Iterations" do
+  
+  before(:each) do
+    @now = Time.now
+  end
+  
+  it "should iterate over time objects with #each" do
+    times = []
+    result = @now.each(:hour) { |time| times << time }
+    times.should have(24).items
+    times.should == (1..24).map { |i| @now + i.hours }
+    result.should == @now
+  end
+  
+  it "should iterate over time objects with #beginning_of_each" do
+    times = []
+    result = @now.beginning_of_each_hour { |time| times << time }
+    times.should have(24).items
+    times.should == (1..24).map { |i| @now.beginning_of_hour + i.hours }
+    result.should == @now
+  end
+  
+  it "should iterate over time objects with #map_each" do
+    result = @now.map_each_hour { |time| time }
+    result.should have(24).items
+    result.should == (1..24).map { |i| @now + i.hours }
+  end
+  
+  it "should iterate over time objects with #map_beginning_of_each" do
+    result = @now.map_beginning_of_each(:hour) { |time| time }
+    result.should have(24).items
+    result.should == (1..24).map { |i| @now.beginning_of_hour + i.hours }
+  end
+  
+  it "should iterate over time objects with #each and #until via method chaining" do
+    match = (1..6).map { |i| @now + i.hours }
+    
+    times = []
+    result = @now.each(:hour).until(@now + 6.hours) { |time| times << time }
+    times.should == match
+    result.should == @now
+    
+    times = []
+    result = @now.until(@now + 6.hours).each_hour { |time| times << time }
+    times.should == match
+    result.should == @now
+  end
+  
+  it "should iterate over time objects with #map_each and #until via method chaining" do
+    match = (1..6).map { |i| @now + i.hours }
+    @now.map_each_hour.until(@now + 6.hours) { |time| time }.should == match
+    @now.until(@now + 6.hours).map_each(:hour) { |time| time }.should == match
+  end
+  
+  it "should iterate over time objects backwards with #until set in the past" do
+    match = (1..6).map { |i| @now - i.hours }
+    @now.map_each_hour.until(@now - 6.hours) { |time| time }.should == match
+    @now.until(@now - 6.hours).map_each(:hour) { |time| time }.should == match
+  end
+  
+  it "should iterate over time objects with #map_each and #from via method chaining" do
+    match = (1..6).map { |i| @now + i.hours }
+    (@now + 6.hours).map_each_hour.from(@now) { |time| time }.should == match
+    (@now + 6.hours).from(@now).map_each(:hour) { |time| time }.should == match
+  end
+  
+end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: time_ext
 version: !ruby/object:Gem::Version 
-  hash: 27
+  hash: 23
   prerelease: false
   segments: 
   - 0
-  - 1
+  - 2
   - 0
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors: 
 - Jim Myhrberg
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-07-27 00:00:00 +03:00
+date: 2010-07-29 00:00:00 +03:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -80,27 +80,15 @@ files:
 - README.md
 - Rakefile
 - VERSION
-- doc/Time.html
-- doc/_index.html
-- doc/class_list.html
-- doc/css/common.css
-- doc/css/full_list.css
-- doc/css/style.css
-- doc/file.README.html
-- doc/file_list.html
-- doc/frames.html
-- doc/index.html
-- doc/js/app.js
-- doc/js/full_list.js
-- doc/js/jquery.js
-- doc/method_list.html
-- doc/top-level-namespace.html
 - lib/time/ext.rb
 - lib/time_ext.rb
-- lib/time_ext/time.rb
+- lib/time_ext/core_ext/time/calculations.rb
+- lib/time_ext/core_ext/time/iterations.rb
+- lib/time_ext/method_chain.rb
 - spec/spec.opts
 - spec/spec_helper.rb
-- spec/time_ext_spec.rb
+- spec/time_calculations_spec.rb
+- spec/time_iterations_spec.rb
 has_rdoc: true
 homepage: http://github.com/jimeh/time_ext
 licenses: []
@@ -137,4 +125,5 @@ specification_version: 3
 summary: Extends the abilities of Ruby's built-in Time class by building on top of ActiveSupport.
 test_files: 
 - spec/spec_helper.rb
-- spec/time_ext_spec.rb
+- spec/time_calculations_spec.rb
+- spec/time_iterations_spec.rb