Methods
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", :short => "%d %b %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"
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", :short => "%d %b %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

[ show source ]

# File lib/core/facets/time/elapse.rb, line 9
  def self.elapse
    raise "Need block" unless block_given?
    t0 = Time.now.to_f
    yield
    Time.now.to_f - t0
  end
elapse() {|| ...}

Tracks the elapse time of a code block. 

  Time.elapse { sleep 1 }  #=> 0.999188899993896

  CREDIT: Hal Fulton

[ show source ]

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

Produce time stamp for Time.now. See stamp. 

  CREDIT: Trans

[ show source ]

# File lib/core/facets/time/stamp.rb, line 22
  def self.stamp(*args)
    now.stamp(*args)
  end
stamp(*args)

Produce time stamp for Time.now. See stamp. 

  CREDIT: Trans

[ show source ]

# File lib/core/facets/time/stamp.rb, line 22
  def self.stamp(*args)
    now.stamp(*args)
  end
Public Instance methods
ago(number, units=:seconds)

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

[ show source ]

# File lib/core/facets/time/hence.rb, line 8
  def ago(number, units=:seconds)
    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
  end
ago(number, units=:seconds)

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

[ show source ]

# File lib/core/facets/time/hence.rb, line 8
  def ago(number, units=:seconds)
    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
  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

 CREDIT: David Hansson (?)

[ show source ]

# File lib/core/facets/time/change.rb, line 15
  def change(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]   || (opts[:hour] ? 0 : self.min),
      opts[:sec]   || ((opts[:hour] || opts[:min]) ? 0 : self.sec),
      opts[:usec]  || ((opts[:hour] || opts[:min] || opts[:usec]) ? 0 : self.usec)
    )
  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

 CREDIT: David Hansson (?)

[ show source ]

# File lib/core/facets/time/change.rb, line 15
  def change(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]   || (opts[:hour] ? 0 : self.min),
      opts[:sec]   || ((opts[:hour] || opts[:min]) ? 0 : self.sec),
      opts[:usec]  || ((opts[:hour] || opts[:min] || opts[:usec]) ? 0 : self.usec)
    )
  end
hence(number, units=:seconds)

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

This method is also aliased as in in

[ show source ]

# File lib/core/facets/time/hence.rb, line 35
  def hence(number, units=:seconds)
    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
  end
hence(number, units=:seconds)

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

[ show source ]

# File lib/core/facets/time/hence.rb, line 35
  def hence(number, units=:seconds)
    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
  end
in(number, units=:seconds)

Alias for hence

in(number, units=:seconds)

Alias for hence

round(amount)

Round time at the nearest range (in seconds). 

  t = Time.now
  =>
  t.round(60*60) # 1 hour
  =>

[ show source ]

# File lib/core/facets/time/round.rb, line 12
  def round(amount)
    (self+amount/2.0).trunc(amount)
  end
round(amount)

Round time at the nearest range (in seconds). 

  t = Time.now
  =>
  t.round(60*60) # 1 hour
  =>

[ show source ]

# 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".

[ show source ]

# File lib/core/facets/time/change.rb, line 33
  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
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".

[ show source ]

# File lib/core/facets/time/change.rb, line 33
  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

[ show source ]

# File lib/core/facets/time/stamp.rb, line 34
  def stamp(fmt = nil)
    unless String === fmt
      fmt = FORMAT[fmt]
    end
    strftime(fmt).strip
  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

[ show source ]

# File lib/core/facets/time/stamp.rb, line 34
  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.

[ show source ]

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

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

[ show source ]

# 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
  =>

[ show source ]

# File lib/core/facets/time/trunc.rb, line 10
  def trunc(amount)
    self - (self.to_i % amount)
  end
trunc(amount)

Truncate time at give range (in seconds). 

  t = Time.now
  =>
  t.trunc(60*60) # 1 hour
  =>

[ show source ]

# File lib/core/facets/time/trunc.rb, line 10
  def trunc(amount)
    self - (self.to_i % amount)
  end