Class: Timerizer::WallClock

Inherits:
Object
  • Object
show all
Defined in:
lib/timerizer/wall_clock.rb

Overview

Represents a time, but not a date. ‘7:00 PM’ would be an example of a WallClock object

Defined Under Namespace

Classes: InvalidMeridiemError, TimeOutOfBoundsError

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#new(hash) ⇒ WallClock #new(hour, minute, meridiem) ⇒ WallClock #new(hour, minute, second, meridiem) ⇒ WallClock #new(seconds) ⇒ WallClock

Initialize a new instance of WallClock

Overloads:

  • #new(hash) ⇒ WallClock

    Parameters:

    • units (Hash) —

      The units to initialize with

  • #new(hour, minute, meridiem) ⇒ WallClock

    Parameters:

    • hour (Integer) —

      The hour to initialize with

    • minute (Integer) —

      The minute to initialize with

    • meridiem (Symbol) —

      The meridiem to initialize with (‘:am` or `:pm`)

  • #new(hour, minute, second, meridiem) ⇒ WallClock

    Parameters:

    • hour (Integer) —

      The hour to initialize with

    • minute (Integer) —

      The minute to initialize with

    • second (Integer) —

      The second to initialize with

    • meridiem (Symbol) —

      The meridiem to initialize with (‘:am` or `:pm`)

  • #new(seconds) ⇒ WallClock

    Parameters:

    • seconds (Integer) —

      The number of seconds to initialize with (for use with #to_i)

Raises:

  • InvalidMeridiemError Meridiem is not ‘:am` or `:pm`



29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
 
# File 'lib/timerizer/wall_clock.rb', line 29

def initialize(hour = nil, minute = nil, second = 0, meridiem = :am)
  units = nil
  if hour.is_a?(Integer) && minute.nil?
    units = {second: hour}
  elsif hour.is_a?(Hash)
    units = hour
  end

  if !units.nil?
    second = units[:second] || 0
    minute = units[:minute] || 0
    hour = units[:hour] || 0
  else
    if second.is_a?(String) || second.is_a?(Symbol)
      meridiem = second
      second = 0
    end

    meridiem = meridiem.downcase.to_sym
    if !(meridiem == :am || meridiem == :pm)
      raise InvalidMeridiemError
    elsif meridiem == :pm && hour > 12
      raise TimeOutOfBoundsError, "hour must be <= 12 for PM"
    elsif hour >= 24 || minute >= 60 || second >= 60
      raise TimeOutOfBoundsError
    end

    hour += 12 if (meridiem == :pm and !(hour == 12))
  end

  @seconds =
    Duration.new(hour: hour, minute: minute, second: second).to_seconds

  if @seconds >= 1.day.to_seconds
    raise TimeOutOfBoundsError
  end
end

Class Method Details

.from_string(string) ⇒ WallClock

Takes a string and turns it into a WallClock time

Examples:

WallClock.from_string("10:30 PM")
  # => 10:30:00 PM
WallClock.from_string("13:01:23")
  # => 1:01:23 PM

Parameters:

  • string (String) —

    The string to convert

Returns:

See Also:



76
77
78
79
80
 
# File 'lib/timerizer/wall_clock.rb', line 76

def self.from_string(string)
  time, meridiem = string.split(' ', 2)
  hour, minute, second = time.split(':', 3)
  WallClock.new(hour.to_i, minute.to_i, second.to_i || 0, meridiem || :am)
end

Instance Method Details

#==(time) ⇒ Boolean

Comparse two Timerizer::WallClocks.

Returns:

  • (Boolean) —

    True if the WallClocks are identical



95
96
97
98
99
100
101
 
# File 'lib/timerizer/wall_clock.rb', line 95

def ==(time)
  if time.is_a? WallClock
    self.in_seconds == time.in_seconds
  else
    false
  end
end

#hour(system = :twenty_four_hour) ⇒ Integer

Get the hour of the WallClock.

Parameters:

  • system (Symbol) (defaults to: :twenty_four_hour) —

    The houring system to use (either ‘:twelve_hour` or `:twenty_four_hour`; default `:twenty_four_hour`)

Returns:

  • (Integer) —

    The hour component of the WallClock



136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
 
# File 'lib/timerizer/wall_clock.rb', line 136

def hour(system = :twenty_four_hour)
  hour = self.to_duration.to_units(:hour, :minute, :second).fetch(:hour)
  if system == :twelve_hour
    if hour == 0
      12
    elsif hour > 12
      hour - 12
    else
      hour
    end
  elsif (system == :twenty_four_hour)
    hour
  else
    raise ArgumentError, "system should be :twelve_hour or :twenty_four_hour"
  end
end

#in_hours ⇒ Integer

Get the time of the WallClock, in hours

Returns:

  • (Integer) —

    The total time of the WallClock, in hours



117
118
119
 
# File 'lib/timerizer/wall_clock.rb', line 117

def in_hours
  Duration::new(seconds: @seconds).to_hours
end

#in_minutes ⇒ Integer

Get the time of the WallClock, in minutes

Returns:

  • (Integer) —

    The total time of the WallClock, in minutes



111
112
113
 
# File 'lib/timerizer/wall_clock.rb', line 111

def in_minutes
  Duration::new(seconds: @seconds).to_minutes
end

#in_seconds ⇒ Integer

Get the time of the WallClock, in seconds

Returns:

  • (Integer) —

    The total time of the WallClock, in seconds



105
106
107
 
# File 'lib/timerizer/wall_clock.rb', line 105

def in_seconds
  @seconds
end

#meridiem ⇒ Symbol

Get the meridiem of the WallClock.

Returns:

  • (Symbol) —

    The meridiem (either ‘:am` or `:pm`)



155
156
157
158
159
160
161
 
# File 'lib/timerizer/wall_clock.rb', line 155

def meridiem
  if self.hour > 12 || self.hour == 0
    :pm
  else
    :am
  end
end

#minute ⇒ Integer

Get the minute of the WallClock.

Returns:

  • (Integer) —

    The minute component of the WallClock



129
130
131
 
# File 'lib/timerizer/wall_clock.rb', line 129

def minute
  self.to_duration.to_units(:hour, :minute, :second).fetch(:minute)
end

#on(date) ⇒ Time

Returns the time of the WallClock on a date

Examples:

yesterday at 5:00

time = WallClock.new(5, 00, :pm)
time.on(Date.yesterday)
  => 2000-1-1 17:00:00 -0800

Parameters:

  • date (Date) —

    The date to apply the time on

Returns:

  • (Time) —

    The time after the given date



89
90
91
 
# File 'lib/timerizer/wall_clock.rb', line 89

def on(date)
  date.to_date.to_time + @seconds
end

#second ⇒ Integer

Get the second of the WallClock.

Returns:

  • (Integer) —

    The second component of the WallClock



123
124
125
 
# File 'lib/timerizer/wall_clock.rb', line 123

def second
  self.to_duration.to_units(:hour, :minute, :second).fetch(:second)
end

#to_duration ⇒ Duration

Converts ‘self` to a Duration

Examples:

time = WallClock.new(5, 30, :pm)
time.to_duration
  => 5 hours, 30 minutes

Returns:



175
176
177
 
# File 'lib/timerizer/wall_clock.rb', line 175

def to_duration
  @seconds.seconds
end

#to_i ⇒ Object

Get the time of the WallClock in a more portable format (for a database, for example)

See Also:



181
182
183
 
# File 'lib/timerizer/wall_clock.rb', line 181

def to_i
  self.in_seconds
end

#to_s(system = :twelve_hour, options = {}) ⇒ Object

Convert Timerizer::WallClock to a human-readable format.

Examples:

time = WallClock.new(5, 37, 41, :pm)
time.to_s
  => "5:37:41 PM"
time.to_s(:twenty_four_hour, :use_seconds => true)
  => "17:37:41"
time.to_s(:twelve_hour, :use_seconds => false, :include_meridiem => false)
  => "5:37"
time.to_s(:twenty_four_hour, :use_seconds =>false)
  => "17:37"

Parameters:

  • system (Symbol) (defaults to: :twelve_hour) —

    The hour system to use (‘:twelve_hour` or `:twenty_four_hour`; default `:twelve_hour`)

  • options (Hash) (defaults to: {}) —

    Extra options for the string to use

Options Hash (options):

  • :use_seconds (Boolean) —

    Whether or not to include seconds in the conversion to a string

  • :include_meridian (Boolean) —

    Whether or not to include the meridian for a twelve-hour time

Raises:

  • ArgumentError Argument isn’t a proper system



201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
 
# File 'lib/timerizer/wall_clock.rb', line 201

def to_s(system = :twelve_hour, options = {})
  options  = {use_seconds: true, include_meridiem: true}.merge(options)
  pad = "%02d"
  meridiem = self.meridiem.to_s.upcase
  hour = self.hour(system)
  minute = pad % self.minute
  second = pad % self.second

  string = [hour, minute].join(':')
  if options[:use_seconds]
    string = [string, second].join(':')
  end

  case system
  when :twelve_hour
    options[:include_meridiem] ? [string, meridiem].join(' ') : string
  when :twenty_four_hour
    string
  else
    raise ArgumentError, "system should be :twelve_hour or :twenty_four_hour"
  end
end

#to_wall ⇒ Object

Converts self to Timerizer::WallClock

See Also:



165
166
167
 
# File 'lib/timerizer/wall_clock.rb', line 165

def to_wall
  self
end