Class

Class Date provides methods for storing and manipulating calendar dates.

Consider using class Time instead of class Date if:

You need both dates and times; Date handles only dates.
You need only Gregorian dates (and not Julian dates); see Julian and Gregorian Calendars.

A Date object, once created, is immutable, and cannot be modified.

Creating a Date

You can create a date for the current date, using Date.today:

Date.today

You can create a specific date from various combinations of arguments:

Date.new takes integer year, month, and day-of-month:
```
Date.new(1999, 12, 31)
```
Date.ordinal takes integer year and day-of-year:
```
Date.ordinal(1999, 365)
```
Date.jd takes integer Julian day:
```
Date.jd(2451544)
```
Date.commercial takes integer commercial data (year, week, day-of-week):
```
Date.commercial(1999, 52, 5)
```

Date.parse takes a string, which it parses heuristically:

Date.parse('1999-12-31')
Date.parse('31-12-1999')
Date.parse('1999-365')
Date.parse('1999-W52-5')

Date.strptime takes a date string and a format string, then parses the date string according to the format string:

Date.strptime('1999-12-31', '%Y-%m-%d')
Date.strptime('31-12-1999', '%d-%m-%Y')
Date.strptime('1999-365', '%Y-%j')
Date.strptime('1999-W52-5', '%G-W%V-%u')
Date.strptime('1999 52 5', '%Y %U %w')
Date.strptime('1999 52 5', '%Y %W %u')
Date.strptime('fri31dec99', '%a%d%b%y')

See also the specialized methods in “Specialized Format Strings” in Formats for Dates and Times

Argument `limit`

Certain singleton methods in Date that parse string arguments also take optional keyword argument limit, which can limit the length of the string argument.

When limit is:

Non-negative: raises ArgumentError if the string length is greater than limit.
Other numeric or nil: ignores limit.
Other non-numeric: raises TypeError.

Constants

An array of strings of abbreviated day names in English. The first is “Sun”.

An array of strings of abbreviated month names in English. The first element is nil.

An array of strings of the full names of days of the week in English. The first is “Sunday”.

The Julian day number of the day of calendar reform for England and her colonies.

The Julian day number of the day of calendar reform for the proleptic Gregorian calendar.

The Julian day number of the day of calendar reform for Italy and some catholic countries.

The Julian day number of the day of calendar reform for the proleptic Julian calendar.

An array of strings of full month names in English. The first element is nil.

No documentation available

Class Methods

Returns a new Date object constructed from the arguments.

Argument cwyear gives the year, and should be an integer.

Argument cweek gives the index of the week within the year, and should be in range (1..53) or (-53..-1); in some years, 53 or -53 will be out-of-range; if negative, counts backward from the end of the year:

Date.commercial(2022, 1, 1).to_s
Date.commercial(2022, 52, 1).to_s

Argument cwday gives the indes of the weekday within the week, and should be in range (1..7) or (-7..-1); 1 or -7 is Monday; if negative, counts backward from the end of the week:

Date.commercial(2022, 1, 1).to_s
Date.commercial(2022, 1, -7).to_s

When cweek is 1:

If January 1 is a Friday, Saturday, or Sunday, the first week begins in the week after:

Date::ABBR_DAYNAMES[Date.new(2023, 1, 1).wday]
Date.commercial(2023, 1, 1).to_s
Date.commercial(2023, 1, 7).to_s

Otherwise, the first week is the week of January 1, which may mean some of the days fall on the year before:

Date::ABBR_DAYNAMES[Date.new(2020, 1, 1).wday]
Date.commercial(2020, 1, 1).to_s
Date.commercial(2020, 1, 7).to_s

See argument start.

Returns a new Date object with values parsed from string, which should be a valid HTTP date format:

d = Date.new(2001, 2, 3)
s = d.httpdate
Date.httpdate(s)

See:

Argument start.
Argument limit.

Related: Date._httpdate (returns a hash).

Returns a hash of values parsed from string, which should be a valid HTTP date format:

d = Date.new(2001, 2, 3)
s = d.httpdate
Date._httpdate(s)

Related: Date.httpdate (returns a Date object).

Returns a new Date object with values parsed from string, which should contain an ISO 8601 formatted date:

d = Date.new(2001, 2, 3)
s = d.iso8601
Date.iso8601(s)

See:

Argument start.
Argument limit.

Related: Date._iso8601 (returns a hash).

Returns a hash of values parsed from string, which should contain an ISO 8601 formatted date:

d = Date.new(2001, 2, 3)
s = d.iso8601
Date._iso8601(s)

See argument limit.

Related: Date.iso8601 (returns a Date object).

Returns a new Date object formed from the arguments:

Date.jd(2451944).to_s
Date.jd(2451945).to_s
Date.jd(0).to_s

The returned date is:

Gregorian, if the argument is greater than or equal to start:

Date::ITALY
Date.jd(Date::ITALY).gregorian?
Date.jd(Date::ITALY + 1).gregorian?

Julian, otherwise
```
Date.jd(Date::ITALY - 1).julian?
```

See argument start.

Related: Date.new.

Returns a new Date object with values parsed from string, which should be a valid JIS X 0301 format:

d = Date.new(2001, 2, 3)
s = d.jisx0301
Date.jisx0301(s)

For no-era year, legacy format, Heisei is assumed.

Date.jisx0301('13.02.03')

See:

Argument start.
Argument limit.

Related: Date._jisx0301 (returns a hash).

Returns a hash of values parsed from string, which should be a valid JIS X 0301 date format:

d = Date.new(2001, 2, 3)
s = d.jisx0301
Date._jisx0301(s)

See argument limit.

Related: Date.jisx0301 (returns a Date object).

Returns a new Date object constructed from the given arguments:

Date.new(2022).to_s
Date.new(2022, 2).to_s
Date.new(2022, 2, 4).to_s

Argument month should be in range (1..12) or range (-12..-1); when the argument is negative, counts backward from the end of the year:

Date.new(2022, -11, 4).to_s

Argument mday should be in range (1..n) or range (-n..-1) where n is the number of days in the month; when the argument is negative, counts backward from the end of the month.

See argument start.

Related: Date.jd.

Returns a new Date object formed fom the arguments.

With no arguments, returns the date for January 1, -4712:

Date.ordinal.to_s

With argument year, returns the date for January 1 of that year:

Date.ordinal(2001).to_s
Date.ordinal(-2001).to_s

With positive argument yday == n, returns the date for the nth day of the given year:

Date.ordinal(2001, 14).to_s

With negative argument yday, counts backward from the end of the year:

Date.ordinal(2001, -14).to_s

Raises an exception if yday is zero or out of range.

See argument start.

Related: Date.jd, Date.new.

Note: This method recognizes many forms in string, but it is not a validator. For formats, see “Specialized Format Strings” in Formats for Dates and Times If string does not specify a valid date, the result is unpredictable; consider using Date._strptime instead.

Returns a new Date object with values parsed from string:

Date.parse('2001-02-03')
Date.parse('20010203')
Date.parse('3rd Feb 2001')

If comp is true and the given year is in the range (0..99), the current century is supplied; otherwise, the year is taken as given:

Date.parse('01-02-03', true)
Date.parse('01-02-03', false)

See:

Argument start.
Argument limit.

Related: Date._parse (returns a hash).

Note: This method recognizes many forms in string, but it is not a validator. For formats, see “Specialized Format Strings” in Formats for Dates and Times

If string does not specify a valid date, the result is unpredictable; consider using Date._strptime instead.

Returns a hash of values parsed from string:

Date._parse('2001-02-03')

If comp is true and the given year is in the range (0..99), the current century is supplied; otherwise, the year is taken as given:

Date._parse('01-02-03', true)
Date._parse('01-02-03', false)

See argument limit.

Related: Date.parse(returns a Date object).

Returns a new Date object with values parsed from string, which should be a valid RFC 2822 date format:

d = Date.new(2001, 2, 3)
s = d.rfc2822
Date.rfc2822(s)

See:

Argument start.
Argument limit.

Related: Date._rfc2822 (returns a hash).

Returns a hash of values parsed from string, which should be a valid RFC 2822 date format:

d = Date.new(2001, 2, 3)
s = d.rfc2822
Date._rfc2822(s)

See argument limit.

Related: Date.rfc2822 (returns a Date object).

Returns a new Date object with values parsed from string, which should be a valid RFC 3339 format:

d = Date.new(2001, 2, 3)
s = d.rfc3339
Date.rfc3339(s)

See:

Argument start.
Argument limit.

Related: Date._rfc3339 (returns a hash).

Returns a hash of values parsed from string, which should be a valid RFC 3339 format:

d = Date.new(2001, 2, 3)
s = d.rfc3339
Date._rfc3339(s)

See argument limit.

Related: Date.rfc3339 (returns a Date object).

Returns a new Date object with values parsed from string, which should be a valid RFC 2822 date format:

d = Date.new(2001, 2, 3)
s = d.rfc2822
Date.rfc2822(s)

See:

Argument start.
Argument limit.

Related: Date._rfc2822 (returns a hash).

Returns a hash of values parsed from string, which should be a valid RFC 2822 date format:

d = Date.new(2001, 2, 3)
s = d.rfc2822
Date._rfc2822(s)

See argument limit.

Related: Date.rfc2822 (returns a Date object).

Returns a new Date object with values parsed from string, according to the given format:

Date.strptime('2001-02-03', '%Y-%m-%d')
Date.strptime('03-02-2001', '%d-%m-%Y')
Date.strptime('2001-034', '%Y-%j')
Date.strptime('2001-W05-6', '%G-W%V-%u')
Date.strptime('2001 04 6', '%Y %U %w')
Date.strptime('2001 05 6', '%Y %W %u')
Date.strptime('sat3feb01', '%a%d%b%y')

For other formats, see Formats for Dates and Times. (Unlike Date.strftime, does not support flags and width.)

See argument start.

See also strptime(3).

Related: Date.strptime (returns a Date object).

Returns a new Date object constructed from the present date:

Date.today.to_s

See argument start.

Returns true if the arguments define a valid ordinal date, false otherwise:

Date.valid_date?(2001, 2, 3)
Date.valid_date?(2001, 2, 29)
Date.valid_date?(2001, 2, -1)

See argument start.

Related: Date.jd, Date.new.

Returns true if the arguments define a valid commercial date, false otherwise:

Date.valid_commercial?(2001, 5, 6)
Date.valid_commercial?(2001, 5, 8)

See Date.commercial.

See argument start.

Related: Date.jd, Date.commercial.

Returns true if the arguments define a valid ordinal date, false otherwise:

Date.valid_date?(2001, 2, 3)
Date.valid_date?(2001, 2, 29)
Date.valid_date?(2001, 2, -1)

See argument start.

Related: Date.jd, Date.new.

Implemented for compatibility; returns true unless jd is invalid (i.e., not a Numeric).

Date.valid_jd?(2451944)

See argument start.

Related: Date.jd.

Returns true if the arguments define a valid ordinal date, false otherwise:

Date.valid_ordinal?(2001, 34)
Date.valid_ordinal?(2001, 366)

See argument start.

Related: Date.jd, Date.ordinal.

Returns a new Date object with values parsed from string, which should be a valid XML date format:

d = Date.new(2001, 2, 3)
s = d.xmlschema
Date.xmlschema(s)

See:

Argument start.
Argument limit.

Related: Date._xmlschema (returns a hash).

Returns a hash of values parsed from string, which should be a valid XML date format:

d = Date.new(2001, 2, 3)
s = d.xmlschema
Date._xmlschema(s)

See argument limit.

Related: Date.xmlschema (returns a Date object).

Instance Methods

Returns a new Date object representing the date n months earlier; n should be a numeric:

(Date.new(2001, 2, 3) << 1).to_s
(Date.new(2001, 2, 3) << -2).to_s

When the same day does not exist for the new month, the last day of that month is used instead:

(Date.new(2001, 3, 31) << 1).to_s
(Date.new(2001, 3, 31) << -6).to_s

This results in the following, possibly unexpected, behaviors:

d0 = Date.new(2001, 3, 31)
d0 << 2
d0 << 1 << 1
d0 = Date.new(2001, 3, 31)
d1 = d0 << 1
d2 = d1 << -1

Compares self and other, returning:

-1 if other is larger.
0 if the two are equal.
1 if other is smaller.
nil if the two are incomparable.

Argument other may be:

Another Date object:

d = Date.new(2022, 7, 27)
prev_date = d.prev_day
next_date = d.next_day
d <=> next_date
d <=> d
d <=> prev_date

A DateTime object:

d <=> DateTime.new(2022, 7, 26)
d <=> DateTime.new(2022, 7, 27)
d <=> DateTime.new(2022, 7, 28)

A numeric (compares self.ajd to other):

d <=> 2459788
d <=> 2459787
d <=> 2459786
d <=> d.ajd

Any other object:
```
d <=> Object.new
```

Returns true if self and other represent the same date, false if not, nil if the two are not comparable.

Argument other may be:

Another Date object:

d = Date.new(2022, 7, 27)
prev_date = d.prev_day
next_date = d.next_day
d === prev_date
d === d
d === next_date

A DateTime object:

d === DateTime.new(2022, 7, 26)
d === DateTime.new(2022, 7, 27)
d === DateTime.new(2022, 7, 28)

A numeric (compares self.jd to other):

d === 2459788
d === 2459787
d === 2459786
d === d.jd

An object not comparable:
```
d === Object.new
```

Returns a new Date object representing the date n months later; n should be a numeric:

(Date.new(2001, 2, 3) >> 1).to_s
(Date.new(2001, 2, 3) >> -2).to_s

When the same day does not exist for the new month, the last day of that month is used instead:

(Date.new(2001, 1, 31) >> 1).to_s
(Date.new(2001, 1, 31) >> -4).to_s

This results in the following, possibly unexpected, behaviors:

d0 = Date.new(2001, 1, 31)
d1 = d0 >> 1
d2 = d1 >> 1
d0 = Date.new(2001, 1, 31)
d1 = d0 >> 1
d2 = d1 >> -1

If the other is a date object, returns a Rational whose value is the difference between the two dates in days. If the other is a numeric value, returns a date object pointing other days before self. If the other is a fractional number, assumes its precision is at most nanosecond.

Date.new(2001,2,3) - 1
DateTime.new(2001,2,3) - Rational(1,2)
Date.new(2001,2,3) - Date.new(2001)
DateTime.new(2001,2,3) - DateTime.new(2001,2,2,12)

Returns a date object pointing other days after self. The other should be a numeric value. If the other is a fractional number, assumes its precision is at most nanosecond.

Date.new(2001,2,3) + 1
DateTime.new(2001,2,3) + Rational(1,2)
DateTime.new(2001,2,3) + Rational(-1,2)
DateTime.jd(0,12) + DateTime.new(2001,2,3).ajd

Returns the astronomical Julian day number. This is a fractional number, which is not adjusted by the offset.

DateTime.new(2001,2,3,4,5,6,'+7').ajd
DateTime.new(2001,2,2,14,5,6,'-7').ajd

Returns the astronomical modified Julian day number. This is a fractional number, which is not adjusted by the offset.

DateTime.new(2001,2,3,4,5,6,'+7').amjd
DateTime.new(2001,2,2,14,5,6,'-7').amjd

Equivalent to strftime with argument '%a %b %e %T %Y' (or its shorthand form '%c'):

Date.new(2001, 2, 3).asctime

See asctime.

Methods Date#as_json and Date.json_create may be used to serialize and deserialize a Date object; see Marshal.

Method Date#as_json serializes self, returning a 2-element hash representing self:

require 'json/add/date'
x = Date.today.as_json

Method JSON.create deserializes such a hash, returning a Date object:

Date.json_create(x)

Returns the commercial-date weekday index for self (see Date.commercial); 1 is Monday:

Date.new(2001, 2, 3).cwday

Returns commercial-date week index for self (see Date.commercial):

Date.new(2001, 2, 3).cweek

Returns commercial-date year for self (see Date.commercial):

Date.new(2001, 2, 3).cwyear
Date.new(2000, 1, 1).cwyear

Returns the fractional part of the day in range (Rational(0, 1)…Rational(1, 1)):

DateTime.new(2001,2,3,12).day_fraction

Returns a hash of the name/value pairs, to use in pattern matching. Possible keys are: :year, :month, :day, :wday, :yday.

Possible usages:

d = Date.new(2022, 10, 5)
if d in wday: 3, day: ..7
  puts "first Wednesday of the month"
end
case d
in year: ...2022
  puts "too old"
in month: ..9
  puts "quarter 1-3"
in wday: 1..5, month:
  puts "working day in month #{month}"
end

Note that deconstruction by pattern can also be combined with class check:

if d in Date(wday: 3, day: ..7)
  puts "first Wednesday of the month"
end

Equivalent to step with arguments min and -1.

Returns true if self is a Friday, false otherwise.

Returns true if the date is on or after the date of calendar reform, false otherwise:

Date.new(1582, 10, 15).gregorian?
(Date.new(1582, 10, 15) - 1).gregorian?

Equivalent to strftime with argument '%a, %d %b %Y %T GMT'; see Formats for Dates and Times:

Date.new(2001, 2, 3).httpdate

Returns false

Returns a string representation of self:

Date.new(2001, 2, 3).inspect

Equivalent to strftime with argument '%Y-%m-%d' (or its shorthand form '%F');

Date.new(2001, 2, 3).iso8601

Returns the Julian day number. This is a whole number, which is adjusted by the offset as the local time.

DateTime.new(2001,2,3,4,5,6,'+7').jd
DateTime.new(2001,2,3,4,5,6,'-7').jd

Returns a string representation of the date in self in JIS X 0301 format.

Date.new(2001, 2, 3).jisx0301

Returns true if the date is before the date of calendar reform, false otherwise:

(Date.new(1582, 10, 15) - 1).julian?
Date.new(1582, 10, 15).julian?

Returns the Lilian day number, which is the number of days since the beginning of the Gregorian calendar, October 15, 1582.

Date.new(2001, 2, 3).ld

Returns true if the year is a leap year, false otherwise:

Date.new(2000).leap?
Date.new(2001).leap?

Returns the day of the month in range (1..31):

Date.new(2001, 2, 3).mday

Returns the modified Julian day number. This is a whole number, which is adjusted by the offset as the local time.

DateTime.new(2001,2,3,4,5,6,'+7').mjd
DateTime.new(2001,2,3,4,5,6,'-7').mjd

Returns the month in range (1..12):

Date.new(2001, 2, 3).mon

Returns true if self is a Monday, false otherwise.

Returns a copy of self with the given start value:

d0 = Date.new(2000, 2, 3)
d0.julian?
d1 = d0.new_start(Date::JULIAN)
d1.julian?

See argument start.

Returns a new Date object representing the following day:

d = Date.new(2001, 2, 3)
d.to_s
d.next.to_s

Equivalent to Date#+ with argument n.

Equivalent to >> with argument n.

Equivalent to >> with argument n * 12.

Equivalent to Date#- with argument n.

Equivalent to << with argument n.

Equivalent to << with argument n * 12.

Equivalent to strftime with argument '%a, %-d %b %Y %T %z'; see Formats for Dates and Times:

Date.new(2001, 2, 3).rfc2822

Equivalent to strftime with argument '%FT%T%:z'; see Formats for Dates and Times:

Date.new(2001, 2, 3).rfc3339

Returns true if self is a Saturday, false otherwise.

Returns the Julian start date for calendar reform; if not an infinity, the returned value is suitable for passing to Date#jd:

d = Date.new(2001, 2, 3, Date::ITALY)
s = d.start
Date.jd(s).to_s
d = Date.new(2001, 2, 3, Date::ENGLAND)
s = d.start
Date.jd(s).to_s
Date.new(2001, 2, 3, Date::GREGORIAN).start
Date.new(2001, 2, 3, Date::JULIAN).start

See argument start.

Calls the block with specified dates; returns self.

The first date is self.
Each successive date is date + step, where step is the numeric step size in days.
The last date is the last one that is before or equal to limit, which should be a Date object.

Example:

limit = Date.new(2001, 12, 31)
Date.new(2001).step(limit){|date| p date.to_s if date.mday == 31 }

Output:

"2001-01-31"
"2001-03-31"
"2001-05-31"
"2001-07-31"
"2001-08-31"
"2001-10-31"
"2001-12-31"

Returns an Enumerator if no block is given.

Returns a string representation of the date in self, formatted according the given format:

Date.new(2001, 2, 3).strftime

For other formats, see Formats for Dates and Times.

Returns true if self is a Sunday, false otherwise.

Returns true if self is a Thursday, false otherwise.

Returns self.

Returns a DateTime whose value is the same as self:

Date.new(2001, 2, 3).to_datetime

Returns a JSON string representing self:

require 'json/add/date'
puts Date.today.to_json

Output:

{"json_class":"Date","y":2023,"m":11,"d":21,"sg":2299161.0}

Returns a string representation of the date in self in ISO 8601 extended date format ('%Y-%m-%d'):

Date.new(2001, 2, 3).to_s

Returns a new Time object with the same value as self; if self is a Julian date, derives its Gregorian date for conversion to the Time object:

Date.new(2001, 2, 3).to_time
Date.new(2001, 2, 3, Date::JULIAN).to_time

Returns true if self is a Tuesday, false otherwise.

Equivalent to step with arguments max and 1.

Returns the day of week in range (0..6); Sunday is 0:

Date.new(2001, 2, 3).wday

Returns true if self is a Wednesday, false otherwise.

Returns the day of the year, in range (1..366):

Date.new(2001, 2, 3).yday

Returns the year:

Date.new(2001, 2, 3).year
(Date.new(1, 1, 1) - 1).year

Creating a Date

Argument limit

Argument `limit`