time_chunk 0.1.0 → 1.0.0

data/README.md

@@ -0,0 +1,102 @@
+# time_chunk
+
+Iterate over a time range in discrete chunks.
+
+## examples
+
+### Enumerate each hour in a day.
+```ruby
+TimeChunk.each_hour('2013-05-15T00:00:00Z'..'2013-05-15T05:59:59Z') do |range|
+  puts range.inspect
+end
+```
+
+Strings are parsed into `Time` instances automatically.
+
+```
+2013-05-15 00:00:00 UTC..2013-05-15 00:59:59 UTC
+2013-05-15 01:00:00 UTC..2013-05-15 01:59:59 UTC
+2013-05-15 02:00:00 UTC..2013-05-15 02:59:59 UTC
+2013-05-15 03:00:00 UTC..2013-05-15 03:59:59 UTC
+2013-05-15 04:00:00 UTC..2013-05-15 04:59:59 UTC
+2013-05-15 05:00:00 UTC..2013-05-15 05:59:59 UTC
+```
+
+### Enumerate a range of days.
+
+```ruby
+TimeChunk.each_day('2013-05-15T00:00:00Z'..'2013-05-20T23:59:59Z') do |range|
+  puts range.inspect
+end
+```
+
+```
+2013-05-15 00:00:00 UTC..2013-05-15 23:59:59 UTC
+2013-05-16 00:00:00 UTC..2013-05-16 23:59:59 UTC
+2013-05-17 00:00:00 UTC..2013-05-17 23:59:59 UTC
+2013-05-18 00:00:00 UTC..2013-05-18 23:59:59 UTC
+2013-05-19 00:00:00 UTC..2013-05-19 23:59:59 UTC
+2013-05-20 00:00:00 UTC..2013-05-20 23:59:59 UTC
+```
+
+If you supply a range of `Date`s instead of `Time` instances or strings,
+`each_day` will yield `Date` instances instead of a time range.
+
+```ruby
+start = Date.parse '2013-05-15'
+finish = Date.parse '2013-05-20'
+TimeChunk.each_day(start..finish) do |d|
+  puts d.to_s
+end
+```
+
+```
+2013-05-15
+2013-05-16
+2013-05-17
+2013-05-18
+2013-05-19
+2013-05-20
+```
+
+
+### Enumerate using any chunk of time
+
+```ruby
+TimeChunk.iterate('2013-05-15T00:00:00Z'..'2013-05-15T23:59:59Z', 6.hours) do |range|
+  puts range.inspect
+end
+```
+
+```
+2013-05-15 00:00:00 UTC..2013-05-15 05:59:59 UTC
+2013-05-15 06:00:00 UTC..2013-05-15 11:59:59 UTC
+2013-05-15 12:00:00 UTC..2013-05-15 17:59:59 UTC
+2013-05-15 18:00:00 UTC..2013-05-15 23:59:59 UTC
+```
+
+This example uses the `6.hours` convenience method from `ActiveSupport`, but you
+can supply any number of seconds.
+
+### Enumerate using any chunk of days
+
+`iterate_days` is the same as `iterate` except that the step size is specified
+in days instead of seconds.
+
+```ruby
+start = Date.parse '2013-05-01'
+finish = Date.parse '2013-05-31'
+TimeChunk.iterate_days(start..finish, 5) do |range|
+  puts "#{range.begin.to_s} .. #{range.end.to_s}"
+end
+```
+
+```
+2013-05-01 .. 2013-05-05
+2013-05-06 .. 2013-05-10
+2013-05-11 .. 2013-05-15
+2013-05-16 .. 2013-05-20
+2013-05-21 .. 2013-05-25
+2013-05-26 .. 2013-05-30
+2013-05-31 .. 2013-05-31
+```

data/VERSION

@@ -1 +1 @@
-0.1.0
+1.0.0

data/lib/time_chunk.rb

@@ -2,20 +2,33 @@ require 'time'
 
 module TimeChunk
 
-  def self.each_day(range)
+  def self.each_minute(range)
     # &Proc.new : return a proc containing the block passed to the method
     # http://www.ruby-doc.org/core-1.9.3/Proc.html#method-c-new
-    iterate(range, 86400, &Proc.new)
+    iterate(range, 60, &Proc.new)
   end
 
   def self.each_hour(range)
     iterate(range, 3600, &Proc.new)
   end
 
-  def self.each_minute(range)
-    iterate(range, 60, &Proc.new)
+  def self.each_day(range)
+    # if we're given a date range, yield individual dates instead of a range.
+    if range.begin.is_a?(Date)
+      iterate(range, 86400) {|chunk| yield chunk.begin }
+    # otherwise yield a range like all other methods do.
+    else
+      iterate(range, 86400, &Proc.new)
+    end
   end
 
+  # Iterate over any date or time range, yielding a range of no more than
+  # step_size duration (in seconds.) The final yielded range may be smaller than
+  # step_size if the total range is not a perfect multiple of the step_size.
+  #
+  # String arguments will be parsed into Times, and yield Time ranges.
+  # Date ranges will yield Date ranges. Note that step_size is always in seconds
+  #   even for date ranges. If this feels weird, see iterate_days instead.
   def self.iterate(range, step_size)
     if range.first.is_a?(Time)
       begin_at = range.first
@@ -42,4 +55,14 @@ module TimeChunk
       yield current_begin..current_end
     end while current_end < end_at
   end
-end
+
+  # Same as iterate, but with step_size specified in days instead of seconds.
+  def self.iterate_days(range, step_size)
+    if ! range.begin.is_a?(Date) || ! range.end.is_a?(Date)
+      raise ArgumentError, "iterate_days requires a range of dates."
+    end
+
+    iterate(range, step_size*86400, &Proc.new)
+  end
+
+end

data/spec/time_chunk_spec.rb

@@ -105,17 +105,61 @@ describe TimeChunk do
     end
   end
 
-  it "should iterate over each_day" do
-    TimeChunk.each_day('2013-01-01T00:00:00Z'..'2013-01-04T23:59:59Z') do |range|
-      @calls << range
+  describe "each_day" do
+    it "should yield time ranges when given string arguments" do
+      TimeChunk.each_day('2013-01-01T00:00:00Z'..'2013-01-04T23:59:59Z') do |range|
+        @calls << range
+      end
+
+      @calls.should eq [
+        (t('2013-01-01T00:00:00Z')..t('2013-01-01T23:59:59Z')),
+        (t('2013-01-02T00:00:00Z')..t('2013-01-02T23:59:59Z')),
+        (t('2013-01-03T00:00:00Z')..t('2013-01-03T23:59:59Z')),
+        (t('2013-01-04T00:00:00Z')..t('2013-01-04T23:59:59Z')),
+      ]
     end
 
-    @calls.should eq [
-      (t('2013-01-01T00:00:00Z')..t('2013-01-01T23:59:59Z')),
-      (t('2013-01-02T00:00:00Z')..t('2013-01-02T23:59:59Z')),
-      (t('2013-01-03T00:00:00Z')..t('2013-01-03T23:59:59Z')),
-      (t('2013-01-04T00:00:00Z')..t('2013-01-04T23:59:59Z')),
-    ]
+    it "should yield date instances when given date range arguments" do
+      start = Date.parse('2013-05-15')
+      finish = Date.parse('2013-05-20')
+
+      TimeChunk.each_day(start..finish) {|date| @calls << date}
+
+      expected = ["2013-05-15", "2013-05-16", "2013-05-17", "2013-05-18", "2013-05-19", "2013-05-20"]
+      @calls.map(&:to_s).should eq expected
+    end
+
+    it "should raise an error if the start is after the finish" do
+      finish = Date.parse('2013-05-15')
+      start = Date.parse('2013-05-20')
+
+      expect {
+        TimeChunk.each_day(start..finish) {|date| @calls << date}
+      }.to raise_error ArgumentError, "Given range's begin (2013-05-20T05:00:00Z) is after its end (2013-05-15T05:00:00Z)."
+
+    end
+  end
+
+  describe "iterate_days" do
+    it "should iterate in chunks of the given number of days" do
+      start = Date.parse('2013-05-01')
+      finish = Date.parse('2013-05-31')
+
+      TimeChunk.iterate_days(start..finish, 5) do |range|
+        @calls << [range.first.to_s, range.last.to_s]
+      end
+
+      expected = [
+        ["2013-05-01", "2013-05-05"],
+        ["2013-05-06", "2013-05-10"],
+        ["2013-05-11", "2013-05-15"],
+        ["2013-05-16", "2013-05-20"],
+        ["2013-05-21", "2013-05-25"],
+        ["2013-05-26", "2013-05-30"],
+        ["2013-05-31", "2013-05-31"]
+      ]
+      @calls.should eq expected
+    end
   end
 
   it "should iterate over each_hour" do

data/time_chunk.gemspec

@@ -5,16 +5,16 @@
 
 Gem::Specification.new do |s|
   s.name = "time_chunk"
-  s.version = "0.1.0"
+  s.version = "1.0.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Alex Dean"]
-  s.date = "2013-03-08"
+  s.date = "2013-05-17"
   s.description = "Iterate over time ranges in discrete chunks."
   s.email = "alex@crackpot.org"
   s.extra_rdoc_files = [
     "LICENSE.txt",
-    "README.rdoc"
+    "README.md"
   ]
   s.files = [
     ".document",
@@ -22,7 +22,7 @@ Gem::Specification.new do |s|
     "Gemfile",
     "Gemfile.lock",
     "LICENSE.txt",
-    "README.rdoc",
+    "README.md",
     "Rakefile",
     "VERSION",
     "lib/time_chunk.rb",

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: time_chunk
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 1.0.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-03-08 00:00:00.000000000 Z
+date: 2013-05-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -81,14 +81,14 @@ executables: []
 extensions: []
 extra_rdoc_files:
 - LICENSE.txt
-- README.rdoc
+- README.md
 files:
 - .document
 - .rspec
 - Gemfile
 - Gemfile.lock
 - LICENSE.txt
-- README.rdoc
+- README.md
 - Rakefile
 - VERSION
 - lib/time_chunk.rb
@@ -110,7 +110,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -3932107950510678518
+      hash: -197955871905249564
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:

data/README.rdoc

@@ -1,19 +0,0 @@
-= time_chunk
-
-Iterate over a time range in discrete chunks.
-
-== Contributing to time_chunk
- 
-* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet.
-* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it.
-* Fork the project.
-* Start a feature/bugfix branch.
-* Commit and push until you are happy with your contribution.
-* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
-* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
-
-== Copyright
-
-Copyright (c) 2013 Alex Dean. See LICENSE.txt for
-further details.
-