clock

Clock interface with support for UTC and local timezones, timezone coercion, and dependency substitution.

Synopsis

require 'clock'

# Get current time
utc_time = Clock::UTC.now # Current time in the UTC timezone
local_time = Clock::Local.now # Current time in the local timezone

# Get an ISO8601 representation of the current time
str_time = Clock::UTC.iso8601 # "2018-08-14T13:04:42.650Z"

# Parse a string representation of time
time = Clock.parse(str_time) # Time instance

# Convert local time to UTC
Clock::UTC.coerce(local_time) # Time instance in UTC

# Clock for another timezone
clock = Clock::Localized.build('America/Los_Angeles')
clock.iso8601 # "2018-08-14T06:40:34-07:00"

Implementation

The clock interface has 3 implementations:

UTC for working with UTC time
Local for working with system local time
Localized for working with timezones in an arbitrary locale

Interface

Each of the implementations has the following methods:

now returns the current time
iso8601 returns the current time as an ISO8601 time string
iso8601(time) returns the given time as an ISO8601 time string
coerce(time) Converts the given time to the clock's timezone
parse(str) Converts a string representation of time to a time value
elapsed_milliseconds(start_time, end_time) Calculates the difference in milliseconds between two times
timestamp Returns the current time as a numerical float timestamp
timestamp(time) Returns the given time as a numerical float timestamp

The methods of each clock are available on the instance of a clock as well as on its class.

Utility Interface

Clock module can be used as a function library providing quick access to the capabilities offered by the individual clock implementations.

time = Clock.now

str_time = Clock.iso8601
str_time = Clock.iso8601(time)

time = Clock.parse(str_time)

timestamp = Clock.timestamp
timestamp = Clock.timestamp(time)

local_time = Clock.local
local_time = Clock.local(time)

utc_time = Clock.utc
utc_time = Clock.utc(time)

local_time = Clock.localized(time, identifier)

milliseconds = Clock.elapsed_milliseconds(start_time, end_time)

Dependency Configuration

This library was written according to The Doctrine of Useful Objects. As such, it can be configured as :clock, and has a useful inert substitute.

require 'clock'

class MyClass
  dependency :clock, Clock::UTC

  def self.build
    instance = new

    Clock::UTC.configure(instance)

    instance
  end
end

instance = MyClass.new

now = Clock::UTC.now # current Time
instance.clock.now = now
instance.clock.iso8601 # current Time serialized as a string

License

The clock library is released under the MIT License.