tick-tock 1.0.0

data/.document

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

data/.rspec

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

data/Gemfile

@@ -0,0 +1,9 @@
+source "http://rubygems.org"
+
+group :development do
+  gem "rspec", "~> 2.8.0"
+  gem "rdoc", "~> 3.12"
+  gem "bundler", "~> 1.0.0"
+  gem "jeweler", "~> 1.8.3"
+  gem "rcov", ">= 0"
+end

data/Gemfile.lock

@@ -0,0 +1,33 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    diff-lcs (1.1.3)
+    git (1.2.5)
+    jeweler (1.8.3)
+      bundler (~> 1.0)
+      git (>= 1.2.5)
+      rake
+      rdoc
+    json (1.6.5)
+    rake (0.9.2.2)
+    rcov (1.0.0)
+    rdoc (3.12)
+      json (~> 1.4)
+    rspec (2.8.0)
+      rspec-core (~> 2.8.0)
+      rspec-expectations (~> 2.8.0)
+      rspec-mocks (~> 2.8.0)
+    rspec-core (2.8.0)
+    rspec-expectations (2.8.0)
+      diff-lcs (~> 1.1.2)
+    rspec-mocks (2.8.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 1.0.0)
+  jeweler (~> 1.8.3)
+  rcov
+  rdoc (~> 3.12)
+  rspec (~> 2.8.0)

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2012 Ian Goodrich
+
+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,181 @@
+= tick-tock
+
+== DESCRIPTION
+
+A gem that provides a simple mechanism for timing and reporting how long your code takes to run.  Benchmark is great but, for simple timing needs, I prefer a narrower API.  Often, I just want to know how long something took without having to add temporary variables and fuss over the output.
+
+== INSTALL
+
+  gem install tick-tock
+
+== FEATURES
+
+* Easy API
+* Flexible API
+* Simple, easy to read output
+* Handles milliseconds, seconds, minutes, hours, days, weeks, and years
+
+== USAGE
+
+=== Usage Scenario 0
+$> TickTock.time { sleep 4 }
+ => 4s 0ms
+
+=== Usage Scenario 1
+
+For simple, everyday use.
+
+  t = TickTock.time do
+    # do stuff
+    sleep 10
+  end
+  puts "That took #{t}"
+
+  That took 10s 0ms
+
+  t = TickTock.time do
+    sleep 314503737247018
+  end
+  puts "That took #{t}"
+
+  That took 10000y 12w 5d 13h 14m 7s 18ms
+
+
+=== Usage Scenario 2
+
+TickTock.time returns a TickTock::Duration.  These can be added together like so:
+
+  thing1 = TickTock.time do
+    sleep 10
+  end
+  puts "Thing 1 took: #{thing1}"
+
+  thing2 = TickTock.time do
+    sleep 55
+  end
+  puts "Thing 2 took: #{thing2}"
+
+  puts "In total, that took #{thing1 + thing2}"
+
+  Thing 1 took: 10s 0ms
+  Thing 2 took: 55s 0ms
+  In total, that took 1m 5s 0ms
+
+
+=== Usage Scenario 3 - collecting parameter
+
+If you'd rather, you can get a fresh instance of a TickTock::Duration with a call to #fresh.  Then, you can pass the duration into TickTock::time.  This might be useful if you want to pass around a duration to other methods and accumualte timings.  Do this, like so:
+
+  total = TickTock.fresh
+  thing1 = TickTock.time(total) do
+    sleep 10
+  end
+  puts "Thing 1 took #{thing1}"
+
+  thing2 = TickTock.time(total) do
+    sleep 55
+  end
+  puts "Thing 2 took #{thing2}"
+
+  puts "In total, that took #{t}"
+
+  Thing 1 took: 10s 0ms
+  Thing 2 took: 55s 0ms
+  In total, that took 1m 5s 0ms
+
+
+=== Usage Scenario 4 - running total
+
+Or, you might want to accumulate a running total like so:
+
+  total = TickTock.fresh
+  total += TickTock.time do
+    sleep 4
+  end
+  total += TickTock.time do
+    sleep 15
+  end
+  total += TickTock.time do
+    sleep 19
+  end
+  puts "In total, that took #{t}"
+
+  In total, that took 38s 0ms
+
+=== Usage Scenario 5 - using duration on it's own
+
+  duraton = TickTock::Duration.new(314503737247018)
+  puts "That's a long time: #{duration}"
+
+  That's a long time: 10000y 12w 5d 13h 14m 7s 18ms
+
+
+  duration = TickTock::Duration.from_start_to_finish(4.years.ago, Time.now)
+  puts "That's not so long: #{duration}"
+
+  That's not so long: 4y 0w 0d 0h 0m 0s 0s
+
+
+  duration = TickTock::Duration.from_pieces(10, 20, 30)
+  puts "Pieces example 1: #{duration}"
+
+  Pieces example 1: 30m 20s 10ms
+
+
+  duration = TickTock::Duration.from_pieces(5, 10, 15, 20, 25, 30, 35)
+  puts "Pieces example 2: #{duration}"
+
+  Pieces example 2: 35y 30w 25d 20h 15m 10s 5ms
+
+
+== Example Duration Output
+
+#to_s method only outputs as much as needed and in a brief, easy to understand format
+
+With a duration of 5 milliseconds:
+
+  5ms
+
+With a duration of 45 second, 5 milliseconds:
+
+  45s 5ms
+
+With a duration of 5 minutes, 45 seconds, and 15 milliseconds
+
+  5m 45s 15ms
+
+With a duration of 4 hours, 5 minutes, 45 seconds, and 15 milliseconds
+
+  4h 5m 45s 15ms
+
+With a duration of 6 days, 4 hours, 5 minutes, 45 seconds, and 15 milliseconds
+
+  6d 4h 5m 45s 15ms
+
+With a duration of 9 weeks, 6 days, 4 hours, 5 minutes, 45 seconds, and 15 milliseconds
+
+  9w 6d 4h 5m 45s 15ms
+
+With a duration of 1014 years, 9 weeks, 6 days, 4 hours, 5 minutes, 45 seconds, and 15 milliseconds
+
+  1014y 9w 6d 4h 5m 45s 15ms
+
+
+
+== Contributing to tick-tock
+
+Feel free to request a feature, point out a bug, or fork/etc.
+ 
+* 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) 2012 Ian Goodrich. See LICENSE.txt for
+further details.
+

data/Rakefile

@@ -0,0 +1,49 @@
+# encoding: utf-8
+
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'rake'
+
+require 'jeweler'
+Jeweler::Tasks.new do |gem|
+  # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
+  gem.name = "tick-tock"
+  gem.homepage = "http://github.com/igoodrich/tick-tock"
+  gem.license = "MIT"
+  gem.summary = %Q{A gem that provides a simple mechanism for timing and reporting how long your code takes to run}
+  gem.description = %Q{A gem that provides a simple mechanism for timing and reporting how long your code takes to run.  Benchmark is great but, for simple timing needs, I prefer a narrower API.  Often, I just want to know how long something took without having to add temporary variables and fuss over the output.}
+  gem.email = "igoodrich@gmail.com"
+  gem.authors = ["Ian Goodrich"]
+  # dependencies defined in Gemfile
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.pattern = FileList['spec/**/*_spec.rb']
+end
+
+RSpec::Core::RakeTask.new(:rcov) do |spec|
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+task :default => :spec
+
+require 'rdoc/task'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "tick-tock #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+1.0.0

data/lib/tick-tock.rb

@@ -0,0 +1,17 @@
+require 'tick-tock/duration'
+require 'tick-tock/formatter'
+
+module TickTock
+
+  def self.fresh
+    TickTock::Duration.new
+  end
+
+  def self.time(duration = nil)
+    start = Time.now
+    yield
+    this_timing = TickTock::Duration.from_times(start, Time.now)
+    duration.nil? ? this_timing : duration + this_timing
+  end
+
+end

data/lib/tick-tock/duration.rb

@@ -0,0 +1,105 @@
+module TickTock
+
+  class Duration
+
+    MILLIS_IN_SECOND = 1000
+    MILLIS_IN_MINUTE = MILLIS_IN_SECOND * 60
+    MILLIS_IN_HOUR = MILLIS_IN_MINUTE * 60
+    MILLIS_IN_DAY = MILLIS_IN_HOUR * 24
+    MILLIS_IN_WEEK = MILLIS_IN_DAY * 7
+    MILLIS_IN_YEAR = MILLIS_IN_WEEK * 52
+
+    attr_reader :raw_millis
+
+    def self.from_times(start, finish)
+      Duration.new(((finish - start) * 1000).to_i)
+    end
+
+    def self.from_pieces(millis=0, seconds=0, minutes=0, hours=0, days=0, weeks=0, years=0)
+      Duration.new(millis +
+                   seconds * MILLIS_IN_SECOND +
+                   minutes * MILLIS_IN_MINUTE +
+                   hours * MILLIS_IN_HOUR +
+                   days * MILLIS_IN_DAY +
+                   weeks * MILLIS_IN_WEEK +
+                   years * MILLIS_IN_YEAR)
+    end
+
+    def initialize(millis = 0)
+      @raw_millis = millis
+      @formatter = TickTock::Formatter.new(self)
+    end
+
+    def +(other)
+      Duration.new(raw_millis + other.raw_millis)
+    end
+
+    def -(other)
+      Duration.new(raw_millis - other.raw_millis)
+    end
+
+    def years
+      raw_millis / MILLIS_IN_YEAR
+    end
+
+    def weeks
+      (raw_millis - years_in_millis) / MILLIS_IN_WEEK
+    end
+
+    def days
+      (raw_millis - years_in_millis - weeks_in_millis) / MILLIS_IN_DAY
+    end
+
+    def hours
+      (raw_millis - years_in_millis - weeks_in_millis - days_in_millis) / MILLIS_IN_HOUR
+    end
+
+    def minutes
+      (raw_millis - years_in_millis - weeks_in_millis - days_in_millis - hours_in_millis) / MILLIS_IN_MINUTE
+    end
+
+    def seconds
+      (raw_millis - years_in_millis - weeks_in_millis - days_in_millis - hours_in_millis - minutes_in_millis) / MILLIS_IN_SECOND
+    end
+
+    def millis
+      raw_millis - years_in_millis - weeks_in_millis - days_in_millis - hours_in_millis - minutes_in_millis - seconds_in_millis
+    end
+
+    def to_s
+      @formatter.to_s
+    end
+
+    def inspect
+      to_s
+    end
+
+    private
+
+    def years_in_millis
+      MILLIS_IN_YEAR * years
+    end
+
+    def weeks_in_millis
+      MILLIS_IN_WEEK * weeks
+    end
+
+    def days_in_millis
+      MILLIS_IN_DAY * days
+    end
+
+    def hours_in_millis
+      MILLIS_IN_HOUR * hours
+    end
+
+    def minutes_in_millis
+      MILLIS_IN_MINUTE * minutes
+    end
+
+    def seconds_in_millis
+      MILLIS_IN_SECOND * seconds
+    end
+
+  end
+
+end

data/lib/tick-tock/formatter.rb

@@ -0,0 +1,58 @@
+module TickTock
+  class Formatter
+
+    attr_reader :duration
+
+    def initialize(duration)
+      @duration = duration
+    end
+
+    def to_s
+      "".tap do |s|
+        s << " #{duration.years}y" if include_years?
+        s << " #{duration.weeks}w" if include_weeks?
+        s << " #{duration.days}d" if include_days?
+        s << " #{duration.hours}h" if include_hours?
+        s << " #{duration.minutes}m" if include_minutes?
+        s << " #{duration.seconds}s" if include_seconds?
+        s << " #{duration.millis}ms" if include_millis?
+        s.lstrip!
+      end
+    end
+
+    private
+
+    def include_millis?
+      true
+    end
+
+    def include_seconds?
+      at_or_beyond? TickTock::Duration::MILLIS_IN_SECOND
+    end
+
+    def include_minutes?
+      at_or_beyond? TickTock::Duration::MILLIS_IN_MINUTE
+    end
+
+    def include_hours?
+      at_or_beyond? TickTock::Duration::MILLIS_IN_HOUR
+    end
+
+    def include_days?
+      at_or_beyond? TickTock::Duration::MILLIS_IN_DAY
+    end
+
+    def include_weeks?
+      at_or_beyond? TickTock::Duration::MILLIS_IN_WEEK
+    end
+
+    def include_years?
+      at_or_beyond? TickTock::Duration::MILLIS_IN_YEAR
+    end
+
+    def at_or_beyond?(boundary)
+      @duration.raw_millis >= boundary
+    end
+
+  end
+end

data/spec/duration_spec.rb

@@ -0,0 +1,429 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+
+describe "Duration" do
+
+  before(:all) do
+    @ms_in_a_second = 1000
+    @ms_in_a_minute = @ms_in_a_second * 60
+    @ms_in_an_hour = @ms_in_a_minute * 60
+    @ms_in_a_day = @ms_in_an_hour * 24
+    @ms_in_a_week = @ms_in_a_day * 7
+    @ms_in_a_year = @ms_in_a_week * 52
+  end
+
+  describe "creation" do
+
+    it "should know how many millis it was made with" do
+      d = TickTock::Duration.new(4321)
+      d.raw_millis.should == 4321
+    end
+
+    it "should use zero if no millis specified" do
+      d = TickTock::Duration.new
+      d.raw_millis.should == 0
+    end
+
+  end
+
+  describe "#years" do
+
+    it "should have 0 years when the duration has fewer than the number of millis in a year" do
+      TickTock::Duration.new.years.should == 0
+      TickTock::Duration.new(@ms_in_a_week * 51).years.should == 0
+      TickTock::Duration.new(@ms_in_a_year - 1).years.should == 0
+    end
+
+    it "should have 1 year at the boundary" do
+      TickTock::Duration.new(@ms_in_a_year).years.should == 1
+      TickTock::Duration.new(@ms_in_a_year + @ms_in_a_week * 17).years.should == 1
+    end
+
+    it "should have 11 years if it's got a lot of millis" do
+      TickTock::Duration.new(@ms_in_a_year * 11).years.should == 11
+    end
+
+  end
+
+  describe "#weeks" do
+
+    it "should have 0 weeks when the duration has fewer than the number of millis in a week" do
+      TickTock::Duration.new.weeks.should == 0
+      TickTock::Duration.new(@ms_in_a_day * 4).weeks.should == 0
+      TickTock::Duration.new(@ms_in_a_week - 1).weeks.should == 0
+    end
+
+    it "should have 1 week when the duration is at the boundary" do
+      TickTock::Duration.new(@ms_in_a_week).weeks.should == 1
+    end
+
+    it "should be able to handle multiple weeks less than a year" do
+      TickTock::Duration.new(@ms_in_a_week * 30).weeks.should == 30
+      TickTock::Duration.new(@ms_in_a_week * 51).weeks.should == 51
+    end
+
+    it "should account for a year if the duration is more than a year" do
+      TickTock::Duration.new(@ms_in_a_year).weeks.should == 0
+      TickTock::Duration.new(@ms_in_a_year + @ms_in_a_week - 1).weeks.should == 0
+      TickTock::Duration.new(@ms_in_a_year + @ms_in_a_week).weeks.should == 1
+    end
+
+    it "should work with multiple years and multiple weeks" do
+      tick_tock_duration = TickTock::Duration.new(@ms_in_a_year * 8 + @ms_in_a_week * 40)
+      tick_tock_duration.weeks.should == 40
+      tick_tock_duration.years.should == 8
+    end
+
+  end
+
+  describe "#days" do
+
+    it "should have 0 days when the duration has fewer than the number of millis in a day" do
+      TickTock::Duration.new.weeks.should == 0
+      TickTock::Duration.new(@ms_in_an_hour * 10).days.should == 0
+      TickTock::Duration.new(@ms_in_a_day - 1).days.should == 0
+    end
+
+    it "should should have 1 day when at the day boundary" do
+      TickTock::Duration.new(@ms_in_a_day).days.should == 1
+    end
+
+    it "should should have 1 day when just under the 2 day boundary" do
+      TickTock::Duration.new(@ms_in_a_day * 2 - 1).days.should == 1
+    end
+
+    it "should work when just over a week" do
+      duration = TickTock::Duration.new(@ms_in_a_week + 1)
+      duration.weeks.should == 1
+      duration.days.should == 0
+    end
+
+    it "should work with multiple weeks when just over a week" do
+      duration = TickTock::Duration.new((@ms_in_a_week * 2) + (@ms_in_a_day * 3))
+      duration.weeks.should == 2
+      duration.days.should == 3
+    end
+
+    it "should work with multiple years, weeks, and days" do
+      duration = TickTock::Duration.new((@ms_in_a_year * 5) + (@ms_in_a_week * 2) + (@ms_in_a_day * 3))
+      duration.years.should == 5
+      duration.weeks.should == 2
+      duration.days.should == 3
+    end
+
+  end
+
+  describe "#hours" do
+
+    it "should have 0 hours when the duration has fewer millis than there are in an hour" do
+      duration = TickTock::Duration.new(@ms_in_an_hour - 1)
+      duration.hours.should == 0
+    end
+
+    it "should have 1 hour when the duration is exactly one hour in millis" do
+      duration = TickTock::Duration.new(@ms_in_an_hour)
+      duration.hours.should == 1
+    end
+
+    it "should have 23 hours when the duration is just under a day" do
+      duration = TickTock::Duration.new(@ms_in_a_day - 1)
+      duration.hours.should == 23
+    end
+
+    it "should have 0 hours when the duration is exactly a day" do
+      duration = TickTock::Duration.new(@ms_in_a_day)
+      duration.hours.should == 0
+    end
+
+    it "should have 0 hours when the duration is a day and up to 1 hour" do
+      duration = TickTock::Duration.new(@ms_in_a_day + (@ms_in_an_hour - 1))
+      duration.hours.should == 0
+    end
+
+    it "should have 1 hours when the duration is exactly a day and an hour" do
+      duration = TickTock::Duration.new(@ms_in_a_day + (@ms_in_an_hour))
+      duration.hours.should == 1
+    end
+
+  end
+
+  describe "#minutes" do
+
+    it "should have 0 minutes if millis are 0" do
+      duration = TickTock::Duration.new(0)
+      duration.minutes.should == 0
+    end
+
+    it "should have 0 minutes when just less than the boundary between 0 minutes and 1 minute" do
+      duration = TickTock::Duration.new(@ms_in_a_minute - 1)
+      duration.minutes.should == 0
+    end
+
+    it "should have 1 minute when it has exactly one minute of millis" do
+      duration = TickTock::Duration.new(@ms_in_a_minute)
+      duration.minutes.should == 1
+    end
+
+    it "should have 1 minute up to the 2 minute boundary" do
+      duration = TickTock::Duration.new(@ms_in_a_minute * 2 - 1)
+      duration.minutes.should == 1
+    end
+
+    it "should have 59 minutes up to the hour boundary" do
+      duration = TickTock::Duration.new(@ms_in_an_hour - 1)
+      duration.minutes.should == 59
+    end
+
+    it "should have 0 minutes at the hour boundary" do
+      duration = TickTock::Duration.new(@ms_in_an_hour)
+      duration.minutes.should == 0
+    end
+
+    it "should cross the hour boundary gracefully" do
+      duration = TickTock::Duration.new(@ms_in_an_hour + 1)
+      duration.hours.should == 1
+      duration.minutes.should == 0
+    end
+
+  end
+
+  describe "#seconds" do
+
+    it "should have 0 seconds if millis are 0" do
+      duration = TickTock::Duration.new(0)
+      duration.seconds.should == 0
+    end
+
+    it "should have 0 seconds up until 1 second of millis" do
+      duration = TickTock::Duration.new(999)
+      duration.seconds.should == 0
+    end
+
+    it "should have 1 second at exactly 1 second of millis" do
+      duration = TickTock::Duration.new(1000)
+      duration.seconds.should == 1
+    end
+
+    it "should have 1 second up to 2 seconds of millis" do
+      duration = TickTock::Duration.new(1999)
+      duration.seconds.should == 1
+    end
+
+    it "should have 2 seconds after 2 seconds of millis" do
+      duration = TickTock::Duration.new(2001)
+      duration.seconds.should == 2
+    end
+
+  end
+
+  describe "#millis" do
+
+    it "should have 0 seconds if millis are 0" do
+      duration = TickTock::Duration.new(0)
+      duration.millis.should == 0
+    end
+
+    it "should count millis up to 1 second" do
+      duration = TickTock::Duration.new(999)
+      duration.millis.should == 999
+    end
+
+    it "should reset at 1 second" do
+      duration = TickTock::Duration.new(1000)
+      duration.millis.should == 0
+    end
+
+    it "should count between 1000 and 2000 millis" do
+      duration = TickTock::Duration.new(1457)
+      duration.millis.should == 457
+    end
+
+  end
+
+  describe "all the bits at once" do
+
+    it "should account for milliseconds, seconds, minutes, hours, days, weeks, and years" do
+      duration = TickTock::Duration.new((@ms_in_a_year * 6) + (@ms_in_a_week * 17) + (@ms_in_a_day * 5) + (@ms_in_an_hour * 4) + (@ms_in_a_minute * 14) + (@ms_in_a_second * 45) + 973)
+      duration.years.should == 6
+      duration.weeks.should == 17
+      duration.days.should == 5
+      duration.hours.should == 4
+      duration.minutes.should == 14
+      duration.seconds.should == 45
+      duration.millis.should == 973
+    end
+
+  end
+
+  describe ".start_to_finish" do
+
+    it "should allow creation from two times" do
+      start = Time.utc(2012, 12, 10)
+      finish = Time.utc(2012, 12, 10, 4)
+      duration = TickTock::Duration.from_times(start, finish)
+      duration.years.should == 0
+      duration.weeks.should == 0
+      duration.days.should == 0
+      duration.hours.should == 4
+      duration.minutes.should == 0
+      duration.seconds.should == 0
+      duration.millis.should == 0
+    end
+
+  end
+
+
+  describe ".from_pieces" do
+
+    it "should allow creation from just millis" do
+      duration = TickTock::Duration.from_pieces(10)
+      duration.years.should == 0
+      duration.weeks.should == 0
+      duration.days.should == 0
+      duration.hours.should == 0
+      duration.minutes.should == 0
+      duration.seconds.should == 0
+      duration.millis.should == 10
+    end
+
+    it "should allow creation from millis and seconds" do
+      duration = TickTock::Duration.from_pieces(10, 40)
+      duration.years.should == 0
+      duration.weeks.should == 0
+      duration.days.should == 0
+      duration.hours.should == 0
+      duration.minutes.should == 0
+      duration.seconds.should == 40
+      duration.millis.should == 10
+    end
+
+    it "should allow creation from millis, seconds, and minutes" do
+      duration = TickTock::Duration.from_pieces(10, 40, 20)
+      duration.years.should == 0
+      duration.weeks.should == 0
+      duration.days.should == 0
+      duration.hours.should == 0
+      duration.minutes.should == 20
+      duration.seconds.should == 40
+      duration.millis.should == 10
+    end
+
+    it "should allow creation from millis, seconds, minutes, and hours" do
+      duration = TickTock::Duration.from_pieces(10, 40, 20, 5)
+      duration.years.should == 0
+      duration.weeks.should == 0
+      duration.days.should == 0
+      duration.hours.should == 5
+      duration.minutes.should == 20
+      duration.seconds.should == 40
+      duration.millis.should == 10
+    end
+
+    it "should allow creation from millis, seconds, minutes, hours, and days" do
+      duration = TickTock::Duration.from_pieces(10, 40, 20, 5, 2)
+      duration.years.should == 0
+      duration.weeks.should == 0
+      duration.days.should == 2
+      duration.hours.should == 5
+      duration.minutes.should == 20
+      duration.seconds.should == 40
+      duration.millis.should == 10
+    end
+
+    it "should allow creation from millis, seconds, minutes, hours, days, and weeks" do
+      duration = TickTock::Duration.from_pieces(10, 40, 20, 5, 2, 40)
+      duration.years.should == 0
+      duration.weeks.should == 40
+      duration.days.should == 2
+      duration.hours.should == 5
+      duration.minutes.should == 20
+      duration.seconds.should == 40
+      duration.millis.should == 10
+    end
+
+    it "should allow creation from millis, seconds, minutes, hours, days, weeks, and years" do
+      duration = TickTock::Duration.from_pieces(10, 40, 20, 5, 2, 40, 1023)
+      duration.years.should == 1023
+      duration.weeks.should == 40
+      duration.days.should == 2
+      duration.hours.should == 5
+      duration.minutes.should == 20
+      duration.seconds.should == 40
+      duration.millis.should == 10
+    end
+
+    it "should overflow lesser bits into more significant bits" do
+      duration = TickTock::Duration.from_pieces(2223, 70, 65, 5, 2, 40, 1023)
+      duration.years.should == 1023
+      duration.weeks.should == 40
+      duration.days.should == 2
+      duration.hours.should == 6
+      duration.minutes.should == 6
+      duration.seconds.should == 12
+      duration.millis.should == 223
+    end
+
+  end
+
+  describe "addition" do
+
+    it "should support simple addition" do
+      duration1 = TickTock::Duration.from_pieces(823)
+      duration2 = TickTock::Duration.from_pieces(455)
+      duration = duration1 + duration2
+      duration.years.should == 0
+      duration.weeks.should == 0
+      duration.days.should == 0
+      duration.hours.should == 0
+      duration.minutes.should == 0
+      duration.seconds.should == 1
+      duration.millis.should == 278
+    end
+
+    it "should support adding a bunch together" do
+      duration1 = TickTock::Duration.from_pieces(10)
+      duration2 = TickTock::Duration.from_pieces(0, 34)
+      duration3 = TickTock::Duration.from_pieces(0, 0, 4)
+      duration4 = TickTock::Duration.from_pieces(0, 0, 0, 10)
+      duration = duration1 + duration2 + duration3 + duration4
+      duration.years.should == 0
+      duration.weeks.should == 0
+      duration.days.should == 0
+      duration.hours.should == 10
+      duration.minutes.should == 4
+      duration.seconds.should == 34
+      duration.millis.should == 10
+    end
+
+    it "should work with +=" do
+      duration = TickTock::Duration.from_pieces(10)
+      extra = TickTock::Duration.from_pieces(0, 34)
+      duration += extra
+      duration.years.should == 0
+      duration.weeks.should == 0
+      duration.days.should == 0
+      duration.hours.should == 0
+      duration.minutes.should == 0
+      duration.seconds.should == 34
+      duration.millis.should == 10
+    end
+
+  end
+
+  describe "subtraction" do
+
+    it "should support simple subtraction" do
+      duration1 = TickTock::Duration.from_pieces(823)
+      duration2 = TickTock::Duration.from_pieces(455)
+      duration = duration1 - duration2
+      duration.years.should == 0
+      duration.weeks.should == 0
+      duration.days.should == 0
+      duration.hours.should == 0
+      duration.minutes.should == 0
+      duration.seconds.should == 0
+      duration.millis.should == 368
+    end
+
+  end
+
+end

data/spec/formatter_spec.rb

@@ -0,0 +1,107 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+
+describe "Formatter" do
+
+  # "1s 0ms"
+
+
+  describe "progressive output" do
+
+    it "should output only millis if zero" do
+      duration = TickTock::Duration.new(0)
+      formatter = TickTock::Formatter.new(duration)
+      formatter.to_s.should == "0ms"
+    end
+
+    it "should output millis" do
+      duration = TickTock::Duration.new(1)
+      formatter = TickTock::Formatter.new(duration)
+      formatter.to_s.should == "1ms"
+    end
+
+    it "should output only millis if less than second" do
+      duration = TickTock::Duration.new(999)
+      formatter = TickTock::Formatter.new(duration)
+      formatter.to_s.should == "999ms"
+    end
+
+    it "should output seconds and millis if exactly 1 second" do
+      duration = TickTock::Duration.new(1000)
+      formatter = TickTock::Formatter.new(duration)
+      formatter.to_s.should == "1s 0ms"
+    end
+
+    it "should output seconds and millis only up to 1 minute" do
+      duration = TickTock::Duration.new(59999)
+      formatter = TickTock::Formatter.new(duration)
+      formatter.to_s.should == "59s 999ms"
+    end
+
+    it "should output minutes, seconds, and millis at exactly 1 minute" do
+      duration = TickTock::Duration.new(60000)
+      formatter = TickTock::Formatter.new(duration)
+      formatter.to_s.should == "1m 0s 0ms"
+    end
+
+    it "should output minutes, seconds, and millis up to 1 hour" do
+      duration = TickTock::Duration.new(TickTock::Duration::MILLIS_IN_HOUR - 1)
+      formatter = TickTock::Formatter.new(duration)
+      formatter.to_s.should == "59m 59s 999ms"
+    end
+
+    it "should output hours, minutes, seconds, and millis at exactly hour" do
+      duration = TickTock::Duration.new(TickTock::Duration::MILLIS_IN_HOUR)
+      formatter = TickTock::Formatter.new(duration)
+      formatter.to_s.should == "1h 0m 0s 0ms"
+    end
+
+    it "should output hours, minutes, seconds, and millis up to 1 day" do
+      duration = TickTock::Duration.new(TickTock::Duration::MILLIS_IN_DAY - 1)
+      formatter = TickTock::Formatter.new(duration)
+      formatter.to_s.should == "23h 59m 59s 999ms"
+    end
+
+    it "should output days, hours, minutes, seconds, and millis at exactly 1 day" do
+      duration = TickTock::Duration.new(TickTock::Duration::MILLIS_IN_DAY)
+      formatter = TickTock::Formatter.new(duration)
+      formatter.to_s.should == "1d 0h 0m 0s 0ms"
+    end
+
+    it "should output days, hours, minutes, seconds, and millis up to 1 week" do
+      duration = TickTock::Duration.new(TickTock::Duration::MILLIS_IN_WEEK - 1)
+      formatter = TickTock::Formatter.new(duration)
+      formatter.to_s.should == "6d 23h 59m 59s 999ms"
+    end
+
+    it "should output weeks, days, hours, minutes, seconds, and millis at exactly 1 week" do
+      duration = TickTock::Duration.new(TickTock::Duration::MILLIS_IN_WEEK)
+      formatter = TickTock::Formatter.new(duration)
+      formatter.to_s.should == "1w 0d 0h 0m 0s 0ms"
+    end
+
+    it "should output weeks, days, hours, minutes, seconds, and millis up to 1 year" do
+      duration = TickTock::Duration.new(TickTock::Duration::MILLIS_IN_YEAR - 1)
+      formatter = TickTock::Formatter.new(duration)
+      formatter.to_s.should == "51w 6d 23h 59m 59s 999ms"
+    end
+
+    it "should output years, weeks, days, hours, minutes, seconds, and millis at exactly 1 year" do
+      duration = TickTock::Duration.new(TickTock::Duration::MILLIS_IN_YEAR)
+      formatter = TickTock::Formatter.new(duration)
+      formatter.to_s.should == "1y 0w 0d 0h 0m 0s 0ms"
+    end
+
+    it "should output years, weeks, days, hours, minutes, seconds, and millis for a long time" do
+      duration = TickTock::Duration.new((TickTock::Duration::MILLIS_IN_YEAR * 10000) +
+                                        (TickTock::Duration::MILLIS_IN_WEEK * 12) +
+                                        (TickTock::Duration::MILLIS_IN_DAY * 5) +
+                                        (TickTock::Duration::MILLIS_IN_HOUR * 13) +
+                                        (TickTock::Duration::MILLIS_IN_MINUTE * 14) +
+                                        (TickTock::Duration::MILLIS_IN_SECOND * 7) + 18)
+      formatter = TickTock::Formatter.new(duration)
+      formatter.to_s.should == "10000y 12w 5d 13h 14m 7s 18ms"
+    end
+
+  end
+
+end

data/spec/spec_helper.rb

@@ -0,0 +1,12 @@
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+require 'rspec'
+require 'tick-tock'
+
+# Requires supporting files with custom matchers and macros, etc,
+# in ./support/ and its subdirectories.
+Dir["#{File.dirname(__FILE__)}/support/**/*.rb"].each {|f| require f}
+
+RSpec.configure do |config|
+  
+end

data/spec/tick-tock_spec.rb

@@ -0,0 +1,22 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+
+describe "TickTock" do
+
+  it "calls block and returns duration" do
+    flubber = 10
+    duration = TickTock.time do
+      flubber = 12
+    end
+    duration.should_not be_nil
+    flubber.should == 12
+  end
+
+  it "can use the same duration if passed in" do
+    duration1 = double("duration1")
+    duration1.should_receive(:+)
+    duration2 = TickTock.time(duration1) do
+
+    end
+  end
+
+end

data/tick-tock.gemspec

@@ -0,0 +1,67 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = "tick-tock"
+  s.version = "1.0.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Ian Goodrich"]
+  s.date = "2012-07-09"
+  s.description = "A gem that provides a simple mechanism for timing and reporting how long your code takes to run.  Benchmark is great but, for simple timing needs, I prefer a narrower API.  Often, I just want to know how long something took without having to add temporary variables and fuss over the output."
+  s.email = "igoodrich@gmail.com"
+  s.extra_rdoc_files = [
+    "LICENSE.txt",
+    "README.rdoc"
+  ]
+  s.files = [
+    ".document",
+    ".rspec",
+    "Gemfile",
+    "Gemfile.lock",
+    "LICENSE.txt",
+    "README.rdoc",
+    "Rakefile",
+    "VERSION",
+    "lib/tick-tock.rb",
+    "lib/tick-tock/duration.rb",
+    "lib/tick-tock/formatter.rb",
+    "spec/duration_spec.rb",
+    "spec/formatter_spec.rb",
+    "spec/spec_helper.rb",
+    "spec/tick-tock_spec.rb",
+    "tick-tock.gemspec"
+  ]
+  s.homepage = "http://github.com/igoodrich/tick-tock"
+  s.licenses = ["MIT"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = "1.8.15"
+  s.summary = "A gem that provides a simple mechanism for timing and reporting how long your code takes to run"
+
+  if s.respond_to? :specification_version then
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_development_dependency(%q<rspec>, ["~> 2.8.0"])
+      s.add_development_dependency(%q<rdoc>, ["~> 3.12"])
+      s.add_development_dependency(%q<bundler>, ["~> 1.0.0"])
+      s.add_development_dependency(%q<jeweler>, ["~> 1.8.3"])
+      s.add_development_dependency(%q<rcov>, [">= 0"])
+    else
+      s.add_dependency(%q<rspec>, ["~> 2.8.0"])
+      s.add_dependency(%q<rdoc>, ["~> 3.12"])
+      s.add_dependency(%q<bundler>, ["~> 1.0.0"])
+      s.add_dependency(%q<jeweler>, ["~> 1.8.3"])
+      s.add_dependency(%q<rcov>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<rspec>, ["~> 2.8.0"])
+    s.add_dependency(%q<rdoc>, ["~> 3.12"])
+    s.add_dependency(%q<bundler>, ["~> 1.0.0"])
+    s.add_dependency(%q<jeweler>, ["~> 1.8.3"])
+    s.add_dependency(%q<rcov>, [">= 0"])
+  end
+end
+

metadata

@@ -0,0 +1,157 @@
+--- !ruby/object:Gem::Specification 
+name: tick-tock
+version: !ruby/object:Gem::Version 
+  hash: 23
+  prerelease: 
+  segments: 
+  - 1
+  - 0
+  - 0
+  version: 1.0.0
+platform: ruby
+authors: 
+- Ian Goodrich
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2012-07-09 00:00:00 Z
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  version_requirements: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 47
+        segments: 
+        - 2
+        - 8
+        - 0
+        version: 2.8.0
+  name: rspec
+  prerelease: false
+  type: :development
+  requirement: *id001
+- !ruby/object:Gem::Dependency 
+  version_requirements: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 31
+        segments: 
+        - 3
+        - 12
+        version: "3.12"
+  name: rdoc
+  prerelease: false
+  type: :development
+  requirement: *id002
+- !ruby/object:Gem::Dependency 
+  version_requirements: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 23
+        segments: 
+        - 1
+        - 0
+        - 0
+        version: 1.0.0
+  name: bundler
+  prerelease: false
+  type: :development
+  requirement: *id003
+- !ruby/object:Gem::Dependency 
+  version_requirements: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 49
+        segments: 
+        - 1
+        - 8
+        - 3
+        version: 1.8.3
+  name: jeweler
+  prerelease: false
+  type: :development
+  requirement: *id004
+- !ruby/object:Gem::Dependency 
+  version_requirements: &id005 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  name: rcov
+  prerelease: false
+  type: :development
+  requirement: *id005
+description: A gem that provides a simple mechanism for timing and reporting how long your code takes to run.  Benchmark is great but, for simple timing needs, I prefer a narrower API.  Often, I just want to know how long something took without having to add temporary variables and fuss over the output.
+email: igoodrich@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE.txt
+- README.rdoc
+files: 
+- .document
+- .rspec
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.rdoc
+- Rakefile
+- VERSION
+- lib/tick-tock.rb
+- lib/tick-tock/duration.rb
+- lib/tick-tock/formatter.rb
+- spec/duration_spec.rb
+- spec/formatter_spec.rb
+- spec/spec_helper.rb
+- spec/tick-tock_spec.rb
+- tick-tock.gemspec
+homepage: http://github.com/igoodrich/tick-tock
+licenses: 
+- MIT
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.8.15
+signing_key: 
+specification_version: 3
+summary: A gem that provides a simple mechanism for timing and reporting how long your code takes to run
+test_files: []
+