Formats for Dates and Times

Several Ruby time-related classes have instance method strftime, which returns a formatted string representing all or part of a date or time:

Each of these methods takes optional argument format, which has zero or more embedded format specifications (see below).

Each of these methods returns the string resulting from replacing each format specification embedded in format with a string form of one or more parts of the date or time.

A simple example:

Time.now.strftime('%H:%M:%S') # => "14:02:07"

A format specification has the form:

%[flags][width]conversion

It consists of:

Except for the leading percent character, the only required part is the conversion specifier, so we begin with that.

Conversion Specifiers

Date (Year, Month, Day)

Time (Hour, Minute, Second, Subsecond)

Timezone

Weekday

Week Number

Week Dates

See ISO 8601 week dates.

t0 = Time.new(2023, 1, 1) # => 2023-01-01 00:00:00 -0600
t1 = Time.new(2024, 1, 1) # => 2024-01-01 00:00:00 -0600

Literals

Shorthand Conversion Specifiers

Each shorthand specifier here is shown with its corresponding longhand specifier.

Flags

Flags may affect certain formatting specifications.

Multiple flags may be given with a single conversion specified; order does not matter.

Padding Flags

Casing Flags

Timezone Flags

Width Specifiers

The integer width specifier gives a minimum width for the returned string:

Time.new(2002).strftime('%Y')       # => "2002"     # No width specifier.
Time.new(2002).strftime('%10Y')     # => "0000002002"
Time.new(2002, 12).strftime('%B')   # => "December" # No width specifier.
Time.new(2002, 12).strftime('%10B') # => "  December"
Time.new(2002, 12).strftime('%3B')  # => "December" # Ignored if too small.

Specialized Format Strings

Here are a few specialized format strings, each based on an external standard.

HTTP Format

The HTTP date format is based on RFC 2616, and treats dates in the format '%a, %d %b %Y %T GMT':

d = Date.new(2001, 2, 3) # => #<Date: 2001-02-03>
# Return HTTP-formatted string.
httpdate = d.httpdate    # => "Sat, 03 Feb 2001 00:00:00 GMT"
# Return new date parsed from HTTP-formatted string.
Date.httpdate(httpdate)  # => #<Date: 2001-02-03>
# Return hash parsed from HTTP-formatted string.
Date._httpdate(httpdate)
# => {:wday=>6, :mday=>3, :mon=>2, :year=>2001, :hour=>0, :min=>0, :sec=>0, :zone=>"GMT", :offset=>0}

RFC 3339 Format

The RFC 3339 date format is based on RFC 3339:

d = Date.new(2001, 2, 3) # => #<Date: 2001-02-03>
# Return 3339-formatted string.
rfc3339 = d.rfc3339      # => "2001-02-03T00:00:00+00:00"
# Return new date parsed from 3339-formatted string.
Date.rfc3339(rfc3339)    # => #<Date: 2001-02-03>
# Return hash parsed from 3339-formatted string.
Date._rfc3339(rfc3339)
# => {:year=>2001, :mon=>2, :mday=>3, :hour=>0, :min=>0, :sec=>0, :zone=>"+00:00", :offset=>0}

RFC 2822 Format

The RFC 2822 date format is based on RFC 2822, and treats dates in the format '%a, %-d %b %Y %T %z']:

d = Date.new(2001, 2, 3) # => #<Date: 2001-02-03>
# Return 2822-formatted string.
rfc2822 = d.rfc2822      # => "Sat, 3 Feb 2001 00:00:00 +0000"
# Return new date parsed from 2822-formatted string.
Date.rfc2822(rfc2822)    # => #<Date: 2001-02-03>
# Return hash parsed from 2822-formatted string.
Date._rfc2822(rfc2822)
# => {:wday=>6, :mday=>3, :mon=>2, :year=>2001, :hour=>0, :min=>0, :sec=>0, :zone=>"+0000", :offset=>0}

JIS X 0301 Format

The JIS X 0301 format includes the Japanese era name, and treats dates in the format '%Y-%m-%d' with the first letter of the romanized era name prefixed:

d = Date.new(2001, 2, 3) # => #<Date: 2001-02-03>
# Return 0301-formatted string.
jisx0301 = d.jisx0301    # => "H13.02.03"
# Return new date parsed from 0301-formatted string.
Date.jisx0301(jisx0301)  # => #<Date: 2001-02-03>
# Return hash parsed from 0301-formatted string.
Date._jisx0301(jisx0301) # => {:year=>2001, :mon=>2, :mday=>3}

ISO 8601 Format Specifications

This section shows format specifications that are compatible with ISO 8601. Details for various formats may be seen at the links.

Examples in this section assume:

t = Time.now # => 2022-06-29 16:49:25.465246 -0500

Dates

See ISO 8601 dates.

Times

See ISO 8601 times.

Combined Date and Time

See ISO 8601 Combined date and time representations.

An ISO 8601 combined date and time representation may be any ISO 8601 date and any ISO 8601 time, separated by the letter T.

For the relevant strftime formats, see width specifiers and width specifiers above.