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

Distance

TimeOfDay.new(9).distance_to(TimeOfDay.new(17)) # => 28800
TimeOfDay.new(20).distance_to(TimeOfDay.new(2)) # => 21600

Between

TimeOfDay.new(12).between?(TimeOfDay.new(9), TimeOfDay.new(17)) # => true
TimeOfDay.new(7).between?(TimeOfDay.new(9), TimeOfDay.new(17))  # => true
TimeOfDay.new(2).between?(TimeOfDay.new(20), TimeOfDay.new(4))  # => true
TimeOfDay.new(18).between?(TimeOfDay.new(20), TimeOfDay.new(4)) # => false

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
DateTime.now.to_time_of_day                     # => 16:30:43

Rails Time Zone Support

If Rails time zone support is loaded, Date#on and TimeOfDay#at will automatically use Time.zone.

Active Record Serializable Attribute Support

TimeOfDay implements a custom serialization contract for activerecord serialize which allows to store TimeOfDay directly in a column of the time type. Example:

class Order < ActiveRecord::Base
  serialize :time, Tod::TimeOfDay
end
order = Order.create(time: TimeOfDay.new(9,30))
order.time                                      # => 09:30:00

Compatibility

Tod is compatible with Ruby 1.9.3 and 2.0.0 and Rails 3.0, 3.1, 3.2, and 4.0.

History

1.2.2 (November 16, 2013)

• Fix dumping nil or empty string to PostgreSQL time column (Maik Arnold)

1.2.1 (September 30, 2013)

• Added DateTime#to_time_of_day (Jonathan Pares)

1.2.0 (July 16, 2013)

• Added ActiveRecord TimeOfDay serialization to time column (Maxim-Filimonov)

1.1.1 (April 12, 2013)

• Added to_i and from_i as aliases of second_of_day and from_second_of_day (Johnny Shields)

1.1.0 (February 13, 2013)

• Added Rails time zone support

1.0.0 (December 29, 2010)

• Initial Release

License

Copyright (c) 2010-2013 Jack Christensen, released under the MIT license