tick-tock

= 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.