Methods
advance ago change dst_adjustment elapse hence round set stamp stamp to_time trunc
Constants
FORMAT = { :db => "%Y-%m-%d %H:%M:%S", :dbase => "%Y-%m-%d %H:%M:%S", :datbase => "%Y-%m-%d %H:%M:%S", :utc => "%Y-%m-%d %H:%M:%S", :number => "%Y%m%d%H%M%S", :short => "%d %b %H:%M", :time => "%H:%M", :long => "%B %d, %Y %H:%M", :day1st => "%d-%m-%Y %H:%M", :dmYHM => "%d-%m-%Y %H:%M", :rfc822 => "%a, %d %b %Y %H:%M:%S %z", nil => "%a %b %d %H:%M:%S %Z %Y"
Public Class methods
elapse() {|| ...}

Tracks the elapse time of a code block.

  Time.elapse { sleep 1 }  #=> 0.999188899993896

  CREDIT: Hal Fulton
# File lib/core/facets/time/elapse.rb, line 9
  def self.elapse
    raise "Need block" unless block_given?
    t0 = now.to_f
    yield
    now.to_f - t0
  end
stamp(*args)

Produce time stamp for Time.now. See stamp.

  CREDIT: Trans
# File lib/core/facets/time/stamp.rb, line 24
  def self.stamp(*args)
    now.stamp(*args)
  end
Public Instance methods
advance(options)

Uses Date to provide precise Time calculations for years, months, and days. The options parameter takes a hash with any of these keys: :years, :months, :weeks, :days, :hours, :minutes, :seconds.

  CREDIT: ActiveSupport
# File lib/core/facets/time/advance.rb, line 9
  def advance(options)
    d = to_date.advance(options)
    time_advanced_by_date = change(:year => d.year, :month => d.month, :day => d.day)
    seconds_to_advance = (options[:seconds] || 0) + (options[:minutes] || 0) * 60 + (options[:hours] || 0) * 3600
    seconds_to_advance == 0 ? time_advanced_by_date : time_advanced_by_date.since(seconds_to_advance)
  end
ago(number, units=:seconds)

Returns a new Time representing the time a number of time-units ago.

# File lib/core/facets/time/hence.rb, line 15
    def ago(number, units=:seconds)
      time =(
        case units.to_s.downcase.to_sym
        when :years
          set(:year => (year - number))
        when :months
          #years = ((month - number) / 12).to_i
          y = ((month - number) / 12).to_i
          m = ((month - number - 1) % 12) + 1
          set(:year => (year - y), :month => m)
        when :weeks
          self - (number * 604800)
        when :days
          self - (number * 86400)
        when :hours
          self - (number * 3600)
        when :minutes
          self - (number * 60)
        when :seconds, nil
          self - number
        else
          raise ArgumentError, "unrecognized time units -- #{units}"
        end
      )
      dst_adjustment(time)
    end
change(options)

Returns a new Time where one or more of the elements have been changed according to the options parameter. The time options (hour, minute, sec, usec) reset cascadingly, so if only the hour is passed, then minute, sec, and usec is set to 0. If the hour and minute is passed, then sec and usec is set to 0.

 t = Time.now            #=> Sat Dec 01 14:10:15 -0500 2007
 t.change(:hour => 11)   #=> Sat Dec 01 11:00:00 -0500 2007
# File lib/core/facets/time/change.rb, line 13
  def change(options)
    opts=options; #{}; options.each_pair{ |k,v| opts[k] = v.to_i }
    self.class.send(
      self.utc? ? :utc : :local,
      opts[:year]  || self.year,
      opts[:month] || self.month,
      opts[:day]   || self.day,
      opts[:hour]  || self.hour,
      opts[:min]   || (opts[:hour] ? 0 : self.min),
      opts[:sec]   || ((opts[:hour] || opts[:min]) ? 0 : self.sec),
      opts[:usec]  || ((opts[:hour] || opts[:min] || opts[:sec]) ? 0 : self.usec)
    )
  end
dst_adjustment(time)

Adjust DST

TODO: Can‘t seem to get this to pass ActiveSupport tests.

      Even though it is essentially identical to the
      ActiveSupport code (see Time#since in time/calculations.rb).
      It handels all but 4 tests.
# File lib/core/facets/time/hence.rb, line 80
    def dst_adjustment(time)
      self_dst = self.dst? ? 1 : 0
      time_dst = time.dst? ? 1 : 0
      seconds  = (self - time).abs
      if (seconds >= 86400 && self_dst != time_dst)
        time + ((self_dst - time_dst) * 60 * 60)
      else
        time
      end
    end
hence(number, units=:seconds)

Returns a new Time representing the time a number of time-units hence.

# File lib/core/facets/time/hence.rb, line 45
    def hence(number, units=:seconds)
      time =(
        case units.to_s.downcase.to_sym
        when :years
          set( :year=>(year + number) )
        when :months
          y = ((month + number) / 12).to_i
          m = ((month + number - 1) % 12) + 1
          set(:year => (year + y), :month => m)
        when :weeks
          self + (number * 604800)
        when :days
          self + (number * 86400)
        when :hours
          self + (number * 3600)
        when :minutes
          self + (number * 60)
        when :seconds
          self + number
        else
          raise ArgumentError, "unrecognized time units -- #{units}"
        end
      )
      dst_adjustment(time)
    end
round(amount)

Round time at the nearest range (in seconds).

  t = Time.now
  =>
  t.round(60*60) # 1 hour
  =>
# File lib/core/facets/time/round.rb, line 12
  def round(amount)
    (self+amount/2.0).trunc(amount)
  end
set(options)

Like change but does not reset earlier times.

NOTE: It would be better, probably if this were called "change".

      and that #change were called "reset".
# File lib/core/facets/time/set.rb, line 8
  def set(options)
    opts={}; options.each_pair{ |k,v| opts[k] = v.to_i }
    self.class.send( self.utc? ? :utc : :local,
      opts[:year]  || self.year,
      opts[:month] || self.month,
      opts[:day]   || self.day,
      opts[:hour]  || self.hour,
      opts[:min]   || self.min,
      opts[:sec]   || self.sec,
      opts[:usec]  || self.usec
    )
  end
stamp(fmt = nil)

Create a time stamp.

  Time.now.stamp(:short)    #=> "01 Dec 15:15"

Supported formats come from the Time::FORMAT constant.

  CREDIT: Trans
# File lib/core/facets/time/stamp.rb, line 36
  def stamp(fmt = nil)
    unless String === fmt
      fmt = FORMAT[fmt]
    end
    strftime(fmt).strip
  end
to_time()

To be able to keep Dates and Times interchangeable on conversions.

# File lib/core/facets/time/to_time.rb, line 8
    def to_time
      getlocal 
    end
trunc(amount)

Truncate time at give range (in seconds).

  t = Time.now
  =>
  t.trunc(60*60) # 1 hour
  =>
# File lib/core/facets/time/trunc.rb, line 10
  def trunc(amount)
    self - (self.to_i % amount)
  end