# class DateTime

### Public Class Methods

local_offset() click to toggle source

    # File lib/facets/date.rb, line 200
    def self.local_offset
      ::Time.local(2007).utc_offset.to_r / 86400
    end

### Public Instance Methods

advance(options) click to toggle source

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

    # File lib/facets/date.rb, line 286
    def advance(options)
      d = to_date.advance(options)
      datetime_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 ? datetime_advanced_by_date : datetime_advanced_by_date.since(seconds_to_advance)
    end

ago(seconds) click to toggle source

Returns a new DateTime representing the time a number of seconds ago Do not use this method in combination with x.months, use months_ago instead!

    # File lib/facets/date.rb, line 295
    def ago(seconds)
      self.since(-seconds)
    end

beginning_of_day() click to toggle source

Returns a new DateTime representing the start of the day (0:00)

    # File lib/facets/date.rb, line 307
    def beginning_of_day
      change(:hour => 0)
    end

Also aliased as: midnight
change(options) click to toggle source

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

    # File lib/facets/date.rb, line 269
    def change(options)
      ::DateTime.civil(
        options[:year]  || self.year,
        options[:month] || self.month,
        options[:day]   || self.day,
        options[:hour]  || self.hour,
        options[:min]   || (options[:hour] ? 0 : self.min),
        options[:sec]   || ((options[:hour] || options[:min]) ? 0 : self.sec),
        options[:offset]  || self.offset,
        options[:start]  || self.start
      )
    end

end_of_day() click to toggle source

Returns a new DateTime representing the end of the day (23:59:59)

    # File lib/facets/date.rb, line 313
    def end_of_day
      change(:hour => 23, :min => 59, :sec => 59)
    end

future?() click to toggle source

    # File lib/facets/date.rb, line 204
    def future?
      self > ::DateTime.current
    end

getutc()
Alias for: utc
in(seconds)
Alias for: since
midnight()
Alias for: beginning_of_day
past?() click to toggle source

    # File lib/facets/date.rb, line 208
    def past?
      self < ::DateTime.current
    end

seconds_since_midnight() click to toggle source

Seconds since midnight: DateTime.now.seconds_since_midnight

    # File lib/facets/date.rb, line 260
    def seconds_since_midnight
      self.sec + (self.min * 60) + (self.hour * 3600)
    end

since(seconds) click to toggle source

Returns a new DateTime representing the time a number of seconds since the instance time Do not use this method in combination with x.months, use months_since instead!

    # File lib/facets/date.rb, line 301
    def since(seconds)
      self + Rational(seconds.round, 86400)
    end

Also aliased as: in
stamp(format=:default) click to toggle source

Convert to a formatted string. See Time::FORMAT for predefined formats.

This method is aliased to `to_s`.

    datetime = DateTime.civil(2007,12,4,0,0,0,0)   # Tue, 04 Dec 2007 00:00:00 +0000

    datetime.stamp(:db)            # => "2007-12-04 00:00:00"
    datetime.stamp(:db)            # => "2007-12-04 00:00:00"
    datetime.stamp(:number)        # => "20071204000000"
    datetime.stamp(:short)         # => "04 Dec 00:00"
    datetime.stamp(:long)          # => "December 04, 2007 00:00"
    datetime.stamp(:rfc822)        # => "Tue, 04 Dec 2007 00:00:00 +0000"

## Adding your own datetime formats to stamp¶ ↑

DateTime formats are shared with Time. You can add your own to the Time::FORMAT hash. Use the format name as the hash key and a strftime string as the value. Eg.

    Time::FORMAT[:month_and_year] = "%B %Y"

    # File lib/facets/date.rb, line 251
    def stamp(format=:default)
      if formatter = ::Time::FORMAT[format]
        strftime(formatter)
      else
        to_s
      end
    end

to_date() click to toggle source

Converts self to a Ruby Date object; time portion is discarded

    # File lib/facets/date.rb, line 213
    def to_date
      ::Date.new(year, month, day)
    end

to_datetime() click to toggle source

To be able to keep Times, Dates and DateTimes interchangeable on conversions

    # File lib/facets/date.rb, line 226
    def to_datetime
      self
    end

to_f() click to toggle source

Converts self to a floating-point number of seconds since the Unix epoch

    # File lib/facets/date.rb, line 345
    def to_f
      days_since_unix_epoch = self - ::DateTime.civil(1970)
      (days_since_unix_epoch * 86_400).to_f
    end

to_time() click to toggle source

Attempts to convert self to a Ruby Time object; returns self if out of range of Ruby Time class. If self has an offset other than 0, self will just be returned unaltered, since there's no clean way to map it to a Time.

    # File lib/facets/date.rb, line 221
    def to_time
      self.offset == 0 ? ::Time.utc_time(year, month, day, hour, min, sec) : self
    end

utc() click to toggle source

Adjusts DateTime to UTC by adding its offset value; offset is set to 0

Example:

    DateTime.civil(2005,2,21,10,11,12,Rational(-6, 24))      # Mon, 21 Feb 2005 10:11:12 -0600
    DateTime.civil(2005,2,21,10,11,12,Rational(-6, 24)).utc  # Mon, 21 Feb 2005 16:11:12 +0000

    # File lib/facets/date.rb, line 324
    def utc
      new_offset(0)
    end

Also aliased as: getutc
utc?() click to toggle source

Returns true if offset == 0

    # File lib/facets/date.rb, line 330
    def utc?
      offset == 0
    end

utc_offset() click to toggle source

Returns the offset value in seconds

    # File lib/facets/date.rb, line 335
    def utc_offset
      (offset * 86400).to_i
    end

xmlschema() click to toggle source

Converts datetime to an appropriate format for use in XML

    # File lib/facets/date.rb, line 340
    def xmlschema
      strftime("%Y-%m-%dT%H:%M:%S%Z")
    end