[ANN] tod - Time of day

[Jack Christensen]

* tod Project Page:https://github.com/JackC/tod

Supplies TimeOfDay class that includes parsing, strftime, comparison, and
arithmetic.


Installation
============

gem install tod

Examples
========

Loading Tod
-----------

require 'tod'

Creating from hour, minute, and second
--------------------------------------

TimeOfDay.new 8 # => 08:00:00
TimeOfDay.new 8, 15, 30 # => 08:15:30

Parsing text
------------

Strings only need to contain an hour. Minutes, seconds, AM or PM, and colons
are all optional.

TimeOfDay.parse "8" # => 08:00:00
TimeOfDay.parse "8am" # => 08:00:00
TimeOfDay.parse "8pm" # => 20:00:00
TimeOfDay.parse "8p" # => 20:00:00
TimeOfDay.parse "9:30" # => 09:30:00
TimeOfDay.parse "15:30" # => 15:30:00
TimeOfDay.parse "3:30pm" # => 15:30:00
TimeOfDay.parse "1230" # => 12:30:00
TimeOfDay.parse "3:25:58" # => 03:25:58
TimeOfDay.parse "515p" # => 17:15:00
TimeOfDay.parse "151253" # => 15:12:53

Adding or subtracting time
-----------------------------

Seconds can be added to or subtracted TimeOfDay objects. Time correctly wraps
around midnight.

TimeOfDay.new(8) + 3600 # => 09:00:00
TimeOfDay.new(8) - 3600 # => 07:00:00
TimeOfDay.new(0) - 30 # => 23:59:30
TimeOfDay.new(23,59,45) + 30 # => 00:00:15

Comparing
--------------------

TimeOfDay includes Comparable.

TimeOfDay.new(8)< TimeOfDay.new(9) # => true
TimeOfDay.new(8) == TimeOfDay.new(9) # => false
TimeOfDay.new(9) == TimeOfDay.new(9) # => true
TimeOfDay.new(10)> TimeOfDay.new(9) # => true

Formatting
----------

Format strings are passed to Time#strftime.

TimeOfDay.new(8,30).strftime("%H:%M") # => "08:30"
TimeOfDay.new(17,15).strftime("%I:%M %p") # => "05:15 PM"
TimeOfDay.new(22,5,15).strftime("%I:%M:%S %p") # => "10:05:15 PM"

Convenience methods for dates and times
---------------------------------------

Tod adds Date#on and Time#to_time_of_day. If you do not want the core extensions
then require 'tod/time_of_day' instead of 'tod'.

tod = TimeOfDay.new 8, 30 # => 08:30:00
tod.on Date.today # => 2010-12-29 08:30:00 -0600
Date.today.at tod # => 2010-12-29 08:30:00 -0600
Time.now.to_time_of_day # => 16:30:43