# DateTime (Class)

In: | date.rb date/format.rb
Parent: | Date

Class representing a date and time.

See the documentation to the file date.rb for an overview.

DateTime objects are immutable once created.

## Other methods.

The following methods are defined in Date, but declared private there. They are made public in DateTime. They are documented here.

### hour()

Get the hour-of-the-day of the time. This is given using the 24-hour clock, counting from midnight. The first hour after midnight is hour 0; the last hour of the day is hour 23.

### min()

Get the minute-of-the-hour of the time.

### sec()

Get the second-of-the-minute of the time.

### sec_fraction()

Get the fraction of a second of the time. This is returned as a `Rational`.

### zone()

Get the time zone as a String. This is representation of the time offset such as "+1000", not the true time-zone name.

### offset()

Get the time zone offset as a fraction of a day. This is returned as a `Rational`.

### new_offset(of=0)

Create a new DateTime object, identical to the current one, except with a new time zone offset of `of`. `of` is the new offset from UTC as a fraction of a day.

## Methods

_strptime civil commercial jd new now ordinal parse strftime strptime valid_time?

## Public Class methods

valid_time?(h, min, s)

Do hour `h`, minute `min`, and second `s` constitute a valid time?

If they do, returns their value as a fraction of a day. If not, returns nil.

The 24-hour clock is used. Negative values of `h`, `min`, and `sec` are treating as counting backwards from the end of the next larger unit (e.g. a `min` of -2 is treated as 58). No wraparound is performed.

[Source]

    # File date.rb, line 1105
      def self.valid_time? (h, min, s)
        h   += 24 if h   < 0
        min += 60 if min < 0
        s   += 60 if s   < 0
        return unless (0..24) === h and
                      (0..59) === min and
                      (0..59) === s
        time_to_day_fraction(h, min, s)
      end

jd(jd=0, h=0, min=0, s=0, of=0, sg=ITALY)

Create a new DateTime object corresponding to the specified Julian Day Number `jd` and hour `h`, minute `min`, second `s`.

The 24-hour clock is used. Negative values of `h`, `min`, and `sec` are treating as counting backwards from the end of the next larger unit (e.g. a `min` of -2 is treated as 58). No wraparound is performed. If an invalid time portion is specified, an ArgumentError is raised.

`of` is the offset from UTC as a fraction of a day (defaults to 0). `sg` specifies the Day of Calendar Reform.

All day/time values default to 0.

[Source]

    # File date.rb, line 1128
      def self.jd(jd=0, h=0, min=0, s=0, of=0, sg=ITALY)
        unless (jd = valid_jd?(jd, sg)) and
               (fr = valid_time?(h, min, s))
          raise ArgumentError, 'invalid date'
        end
        new0(jd_to_ajd(jd, fr, of), of, sg)
      end

ordinal(y=-4712, d=1, h=0, min=0, s=0, of=0, sg=ITALY)

Create a new DateTime object corresponding to the specified Ordinal Date and hour `h`, minute `min`, second `s`.

The 24-hour clock is used. Negative values of `h`, `min`, and `sec` are treating as counting backwards from the end of the next larger unit (e.g. a `min` of -2 is treated as 58). No wraparound is performed. If an invalid time portion is specified, an ArgumentError is raised.

`of` is the offset from UTC as a fraction of a day (defaults to 0). `sg` specifies the Day of Calendar Reform.

`y` defaults to -4712, and `d` to 1; this is Julian Day Number day 0. The time values default to 0.

[Source]

    # File date.rb, line 1150
      def self.ordinal(y=-4712, d=1, h=0, min=0, s=0, of=0, sg=ITALY)
        unless (jd = valid_ordinal?(y, d, sg)) and
               (fr = valid_time?(h, min, s))
          raise ArgumentError, 'invalid date'
        end
        new0(jd_to_ajd(jd, fr, of), of, sg)
      end

civil(y=-4712, m=1, d=1, h=0, min=0, s=0, of=0, sg=ITALY)

Create a new DateTime object corresponding to the specified Civil Date and hour `h`, minute `min`, second `s`.

The 24-hour clock is used. Negative values of `h`, `min`, and `sec` are treating as counting backwards from the end of the next larger unit (e.g. a `min` of -2 is treated as 58). No wraparound is performed. If an invalid time portion is specified, an ArgumentError is raised.

`of` is the offset from UTC as a fraction of a day (defaults to 0). `sg` specifies the Day of Calendar Reform.

`y` defaults to -4712, `m` to 1, and `d` to 1; this is Julian Day Number day 0. The time values default to 0.

[Source]

    # File date.rb, line 1172
      def self.civil(y=-4712, m=1, d=1, h=0, min=0, s=0, of=0, sg=ITALY)
        unless (jd = valid_civil?(y, m, d, sg)) and
               (fr = valid_time?(h, min, s))
          raise ArgumentError, 'invalid date'
        end
        new0(jd_to_ajd(jd, fr, of), of, sg)
      end

new(y=-4712, m=1, d=1, h=0, min=0, s=0, of=0, sg=ITALY)

Alias for civil

commercial(y=1582, w=41, d=5, h=0, min=0, s=0, of=0, sg=ITALY)

Create a new DateTime object corresponding to the specified Commercial Date and hour `h`, minute `min`, second `s`.

The 24-hour clock is used. Negative values of `h`, `min`, and `sec` are treating as counting backwards from the end of the next larger unit (e.g. a `min` of -2 is treated as 58). No wraparound is performed. If an invalid time portion is specified, an ArgumentError is raised.

`of` is the offset from UTC as a fraction of a day (defaults to 0). `sg` specifies the Day of Calendar Reform.

`y` defaults to 1582, `w` to 41, and `d` to 5; this is the Day of Calendar Reform for Italy and the Catholic countries. The time values default to 0.

[Source]

    # File date.rb, line 1197
      def self.commercial(y=1582, w=41, d=5, h=0, min=0, s=0, of=0, sg=ITALY)
        unless (jd = valid_commercial?(y, w, d, sg)) and
               (fr = valid_time?(h, min, s))
          raise ArgumentError, 'invalid date'
        end
        new0(jd_to_ajd(jd, fr, of), of, sg)
      end

strptime(str='-4712-01-01T00:00:00Z', fmt='%FT%T%Z', sg=ITALY)

Create a new DateTime object by parsing from a String according to a specified format.

`str` is a String holding a date-time representation. `fmt` is the format that the date-time is in. See date/format.rb for details on supported formats.

The default `str` is ’-4712-01-01T00:00:00Z’, and the default `fmt` is ’%FT%T%Z’. This gives midnight on Julian Day Number day 0.

`sg` specifies the Day of Calendar Reform.

An ArgumentError will be raised if `str` cannot be parsed.

[Source]

    # File date.rb, line 1236
      def self.strptime(str='-4712-01-01T00:00:00Z', fmt='%FT%T%Z', sg=ITALY)
        elem = _strptime(str, fmt)
        new_with_hash(elem, sg)
      end

parse(str='-4712-01-01T00:00:00Z', comp=false, sg=ITALY)

Create a new DateTime object by parsing from a String, without specifying the format.

`str` is a String holding a date-time representation. `comp` specifies whether to interpret 2-digit years as 19XX (>= 69) or 20XX (< 69); the default is not to. The method will attempt to parse a date-time from the String using various heuristics; see _parse in date/format.rb for more details. If parsing fails, an ArgumentError will be raised.

The default `str` is ’-4712-01-01T00:00:00Z’; this is Julian Day Number day 0.

`sg` specifies the Day of Calendar Reform.

[Source]

    # File date.rb, line 1256
      def self.parse(str='-4712-01-01T00:00:00Z', comp=false, sg=ITALY)
        elem = _parse(str, comp)
        new_with_hash(elem, sg)
      end

now(sg=ITALY)

Create a new DateTime object representing the current time.

`sg` specifies the Day of Calendar Reform.

[Source]

    # File date.rb, line 1266
      def self.now(sg=ITALY)
        i = Time.now
        a = i.to_a[0..5].reverse
        jd = civil_to_jd(*(a[0,3] << sg))
        fr = time_to_day_fraction(*(a[3,3])) + i.usec.to_r/86400000000
        d = Time.gm(*i.to_a).to_i - i.to_i
        d += d / d.abs if d.nonzero?
        of = (d / 60).to_r/1440
        new0(jd_to_ajd(jd, fr, of), of, sg)
      end

_strptime(str, fmt='%FT%T%Z')

[Source]

    # File date/format.rb, line 527
      def self._strptime(str, fmt='%FT%T%Z')
        super(str, fmt)
      end

## Public Instance methods

strftime(fmt='%FT%T%Z')

[Source]

    # File date/format.rb, line 531
      def strftime(fmt='%FT%T%Z')
        super(fmt)
      end

[Validate]