Date

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 # => #<Date: 1999-12-31>

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

• Date.new takes integer year, month, and day-of-month:

  Example

  Run in Playground

  Date.new(1999, 12, 31) # => #<Date: 1999-12-31>
  

• Date.ordinal takes integer year and day-of-year:

  Example

  Run in Playground

  Date.ordinal(1999, 365) # => #<Date: 1999-12-31>
  

• Date.jd takes integer Julian day:

  Example

  Run in Playground

  Date.jd(2451544) # => #<Date: 1999-12-31>
  

• Date.commercial takes integer commercial data (year, week, day-of-week):

  Example

  Run in Playground

  Date.commercial(1999, 52, 5) # => #<Date: 1999-12-31>
  

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

  Example

  Run in Playground

  Date.parse('1999-12-31')    # => #<Date: 1999-12-31>
  Date.parse('31-12-1999')    # => #<Date: 1999-12-31>
  Date.parse('1999-365')      # => #<Date: 1999-12-31>
  Date.parse('1999-W52-5')    # => #<Date: 1999-12-31>
  

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

  Example

  Run in Playground

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

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.