Class: WallClock

Inherits:
Object
  • Object
show all
Defined in:
lib/timerizer.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`



420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
 
# File 'lib/timerizer.rb', line 420

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 =
    RelativeTime.units_in_seconds.fetch(:hour) * hour +
    RelativeTime.units_in_seconds.fetch(:minute) * minute +
    second

  if @seconds >= RelativeTime.units_in_seconds.fetch(:day)
    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:



469
470
471
472
473
 
# File 'lib/timerizer.rb', line 469

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

Returns:

  • (Boolean) —

    True if the WallClocks are identical



488
489
490
491
492
493
494
 
# File 'lib/timerizer.rb', line 488

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



529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
 
# File 'lib/timerizer.rb', line 529

def hour(system = :twenty_four_hour)
  hour = self.to_relative.hours
  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



510
511
512
 
# File 'lib/timerizer.rb', line 510

def in_hours
  @seconds / RelativeTime.units_in_seconds[:hour]
end

#in_minutes ⇒ Integer

Get the time of the WallClock, in minutes

Returns:

  • (Integer) —

    The total time of the WallClock, in minutes



504
505
506
 
# File 'lib/timerizer.rb', line 504

def in_minutes
  @seconds / RelativeTime.units_in_seconds[:minute]
end

#in_seconds ⇒ Integer

Get the time of the WallClock, in seconds

Returns:

  • (Integer) —

    The total time of the WallClock, in seconds



498
499
500
 
# File 'lib/timerizer.rb', line 498

def in_seconds
  @seconds
end

#meridiem ⇒ Symbol

Get the meridiem of the WallClock.

Returns:

  • (Symbol) —

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



548
549
550
551
552
553
554
 
# File 'lib/timerizer.rb', line 548

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



522
523
524
 
# File 'lib/timerizer.rb', line 522

def minute
  self.to_relative.minutes
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



482
483
484
 
# File 'lib/timerizer.rb', line 482

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



516
517
518
 
# File 'lib/timerizer.rb', line 516

def second
  self.to_relative.seconds
end

#to_i ⇒ Object

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

See Also:



574
575
576
 
# File 'lib/timerizer.rb', line 574

def to_i
  self.in_seconds
end

#to_relative ⇒ RelativeTime

Converts WallClock to RelativeTime

Examples:

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

Returns:



568
569
570
 
# File 'lib/timerizer.rb', line 568

def to_relative
  @seconds.seconds
end

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

Convert 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



594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
 
# File 'lib/timerizer.rb', line 594

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 WallClock

See Also:



558
559
560
 
# File 'lib/timerizer.rb', line 558

def to_wall
  self
end