method

strftime

ruby latest stable - Class: Time

strftime(p1)

public

Formats time according to the directives in the given format string.

The directives begin with a percent (%) character. Any text not listed as a directive will be passed through to the output string.

The directive consists of a percent (%) character, zero or more flags, optional minimum field width, optional modifier and a conversion specifier as follows:

%<flags><width><modifier><conversion>

Flags:

- don't pad a numerical output
_ use spaces for padding
0 use zeros for padding
^ upcase the result string
# change case
: use colons for %z

The minimum field width specifies the minimum width.

The modifiers are "E" and "O". They are ignored.

Format directives:

Date  (Year, Month, Day):
 %Y - Year with century if provided, will pad result at  least 4 digits.
 -0001, 0000, 1995, 2009, 14292, etc.
 %C - year  / 100 (rounded down such as 20 in 2009)
 %y - year  % 100 (00..99)
 %m - Month of the year , zero-padded (01..12)
 %_m blank-padded ( 1..12)
 %-m no-padded (1..12)
 %B - The full month name (``January'')
 %^B uppercased (``JANUARY'')
 %b - The abbreviated month name (``Jan'')
 %^b uppercased (``JAN'')
 %h - Equivalent to %b
 %d - Day of the month, zero-padded (01..31)
 %-d no-padded (1..31)
 %e - Day of the month, blank-padded ( 1..31)
 %j - Day of the year (001..366)
Time (Hour, Minute, Second, Subsecond):
 %H - Hour of the day, 24-hour clock, zero-padded (00..23)
 %k - Hour of the day, 24-hour clock, blank-padded ( 0..23)
 %I - Hour of the day, 12-hour clock, zero-padded (01..12)
 %l - Hour of the day, 12-hour clock, blank-padded ( 1..12)
 %P - Meridian indicator, lowercase (``am'' or ``pm'')
 %p - Meridian indicator, uppercase (``AM'' or ``PM'')
 %M - Minute of the hour (00..59)
 %S - Second of the minute (00..60)
 %L - Millisecond of the second (000..999)
 The digits under millisecond are truncated to not produce 1000.
 %N - Fractional seconds digits, default is 9 digits (nanosecond)
 %3N millisecond (3 digits)
 %6N microsecond (6 digits)
 %9N nanosecond (9 digits)
 %12N picosecond (12 digits)
 %15N femtosecond (15 digits)
 %18N attosecond (18 digits)
 %21N zeptosecond (21 digits)
 %24N yoctosecond (24 digits)
 The digits under the specified length are truncated to avoid
 carry up.
Time zone:
 %z - Time zone as hour and minute offset from UTC (e.g. +0900)
 %:z - hour and minute offset from UTC with a colon (e.g. +09:00)
 %::z - hour, minute and second offset from UTC (e.g. +09:00:00)
 %Z - Abbreviated time zone name or similar information. (OS dependent)
Weekday:
 %A - The full weekday name (``Sunday'')
 %^A uppercased (``SUNDAY'')
 %a - The abbreviated name (``Sun'')
 %^a uppercased (``SUN'')
 %u - Day of the week (Monday is 1, 1..7)
 %w - Day of the week (Sunday is 0, 0..6)
ISO 8601 week-based year and week number:
The first week of YYYY starts with a Monday and includes YYYY-01-04.
The days in the year before the first week are in the last week of
the previous year.
 %G - The week-based year
 %g - The last 2 digits of the week-based year (00..99)
 %V - Week number of the week-based year (01..53)
Week number:
The first week of YYYY that starts with a Sunday or Monday (according to %U
or %W). The days in the year before the first week are in week 0.
 %U - Week number of the year. The week starts with Sunday. (00..53)
 %W - Week number of the year. The week starts with Monday. (00..53)
Seconds since the Epoch:
 %s - Number of seconds since 1970年01月01日 00:00:00 UTC.
Literal string:
 %n - Newline character (\n)
 %t - Tab character (\t)
 %% - Literal ``%'' character
Combination:
 %c - date and time (%a %b %e %T %Y)
 %D - Date (%m/%d/%y)
 %F - The ISO 8601 date format (%Y-%m-%d)
 %v - VMS date (%e-%^b-%4Y)
 %x - Same as %D
 %X - Same as %T
 %r - 12-hour time (%I:%M:%S %p)
 %R - 24-hour time (%H:%M)
 %T - 24-hour time (%H:%M:%S)

This method is similar to strftime() function defined in ISO C and POSIX.

While all directives are locale independent since Ruby 1.9, %Z is platform dependent. So, the result may differ even if the same format string is used in other systems such as C.

%z is recommended over %Z. %Z doesn’t identify the timezone. For example, "CST" is used at America/Chicago (-06:00), America/Havana (-05:00), Asia/Harbin (+08:00), Australia/Darwin (+09:30) and Australia/Adelaide (+10:30). Also, %Z is highly dependent on the operating system. For example, it may generate a non ASCII string on Japanese Windows. i.e. the result can be different to "JST". So the numeric time zone offset, %z, is recommended.

Examples:

t = Time .new (2007,11,19,8,37,48,"-06:00") #=> 2007年11月19日 08:37:48 -0600
t.strftime ("Printed on %m/%d/%Y") #=> "Printed on 11/19/2007"
t.strftime ("at %I:%M%p") #=> "at 08:37AM"

Various ISO 8601 formats:

%Y%m%d => 20071119 Calendar date (basic)
%F => 2007-11-19 Calendar date (extended)
%Y-%m => 2007-11 Calendar date, reduced accuracy, specific month 
%Y => 2007 Calendar date, reduced accuracy, specific year 
%C => 20 Calendar date, reduced accuracy, specific century
%Y%j => 2007323 Ordinal date (basic)
%Y-%j => 2007-323 Ordinal date (extended)
%GW%V%u => 2007W471 Week date (basic)
%G-W%V-%u => 2007-W47-1 Week date (extended)
%GW%V => 2007W47 Week date, reduced accuracy, specific week (basic)
%G-W%V => 2007-W47 Week date, reduced accuracy, specific week (extended)
%H%M%S => 083748 Local time (basic)
%T => 08:37:48 Local time (extended)
%H%M => 0837 Local time, reduced accuracy, specific minute (basic)
%H:%M => 08:37 Local time, reduced accuracy, specific minute (extended)
%H => 08 Local time, reduced accuracy, specific hour 
%H%M%S,%L => 083748,000 Local time with decimal fraction, comma as decimal sign (basic)
%T,%L => 08:37:48,000 Local time with decimal fraction, comma as decimal sign (extended)
%H%M%S.%L => 083748.000 Local time with decimal fraction, full stop as decimal sign (basic)
%T.%L => 08:37:48.000 Local time with decimal fraction, full stop as decimal sign (extended)
%H%M%S%z => 083748-0600 Local time and the difference from UTC (basic)
%T%:z => 08:37:48-06:00 Local time and the difference from UTC (extended)
%Y%m%dT%H%M%S%z => 20071119T083748-0600 Date  and time of day  for calendar date (basic)
%FT%T%:z => 2007年11月19日T08:37:48-06:00 Date  and time of day  for calendar date (extended)
%Y%jT%H%M%S%z => 2007323T083748-0600 Date  and time of day  for ordinal date (basic)
%Y-%jT%T%:z => 2007-323T08:37:48-06:00 Date  and time of day  for ordinal date (extended)
%GW%V%uT%H%M%S%z => 2007W471T083748-0600 Date  and time of day  for week date (basic)
%G-W%V-%uT%T%:z => 2007-W47-1T08:37:48-06:00 Date  and time of day  for week date (extended)
%Y%m%dT%H%M => 20071119T0837 Calendar date and local  time (basic)
%FT%R => 2007-11-19T08:37 Calendar date and local  time (extended)
%Y%jT%H%MZ => 2007323T0837Z Ordinal date and UTC of day  (basic)
%Y-%jT%RZ => 2007-323T08:37Z Ordinal date and UTC of day  (extended)
%GW%V%uT%H%M%z => 2007W471T0837-0600 Week date and local  time and difference from UTC (basic)
%G-W%V-%uT%R%:z => 2007-W47-1T08:37-06:00 Week date and local  time and difference from UTC (extended)

static VALUE
time_strftime(VALUE time, VALUE format)
{
 struct time_object *tobj;
 const char *fmt;
 long len;
 rb_encoding *enc;
 VALUE tmp;
 GetTimeval(time, tobj);
 MAKE_TM(time, tobj);
 StringValue(format);
 if (!rb_enc_str_asciicompat_p(format)) {
 rb_raise(rb_eArgError, "format should have ASCII compatible encoding");
 }
 tmp = rb_str_tmp_frozen_acquire(format);
 fmt = RSTRING_PTR(tmp);
 len = RSTRING_LEN(tmp);
 enc = rb_enc_get(format);
 if (len == 0) {
 rb_warning("strftime called with empty format string");
 return rb_enc_str_new(0, 0, enc);
 }
 else {
 VALUE str = rb_strftime_alloc(fmt, len, enc, &tobj->vtm, tobj->timew,
 TIME_UTC_P(tobj));
 rb_str_tmp_frozen_release(format, tmp);
 if (!str) rb_raise(rb_eArgError, "invalid format: %"PRIsVALUE, format);
 return str;
 }
}

7Notes

Readable strftime

autonomous · Sep 12, 200824 thanks

%a - The abbreviated weekday name (``Sun'')

%A - The full weekday name (``Sunday'')

%b - The abbreviated month name (``Jan'')

%B - The full month name (``January'')

%c - The preferred local date and time representation

%d - Day of the month (01..31) %H - Hour of the day, 24-hour clock (00..23)

%I - Hour of the day, 12-hour clock (01..12)

%j - Day of the year (001..366)

%m - Month of the year (01..12) %M - Minute of the hour (00..59)

%p - Meridian indicator (AM'' or PM'')

%S - Second of the minute (00..60)

%U - Week number of the current year, starting with the first Sunday as the first day of the first week (00..53)

%W - Week number of the current year, starting with the first Monday as the first day of the first week (00..53)

%w - Day of the week (Sunday is 0, 0..6)

%x - Preferred representation for the date alone, no time

%X - Preferred representation for the time alone, no date

%y - Year without a century (00..99) %Y - Year with century

%Z - Time zone name %% - Literal ``%'' character t = Time.now t.strftime("Printed on %m/%d/%Y") #=> "Printed on 04/09/2003" t.strftime("at %I:%M%p") #=> "at 08:56AM"

Hour with/without preceding zero

patrickberkeley · Mar 27, 20094 thanks

One gotcha is the difference between the hour in 12 hour time with and without a preceding zero. In some fonts they look the same.

==== With preceding zero (capital I) Time.now.strftime("%I:%M") # => 05:21

==== Without preceding zero (lowercase L) Time.now.strftime("%l:%M") # => 5:21

Rmoving preceding 0's

tekwiz · Feb 5, 20103 thanks

In most *nix system, adding a - after the % will remove preceding 0s.

So %-d for a single digit day, or %-I for a single digit hour, etc.

Complete Formatting Codes

mindloaf · Mar 12, 20103 thanks

NOTE: Some of these seem only to work for DateTime (e.g. %L, %N)

%a - The abbreviated weekday name ("Sun")

%A - The full weekday name ("Sunday")

%b - The abbreviated month name ("Jan")

%B - The full month name ("January")

%c - The preferred local date and time representation

%C - Century (20 in 2009)

%d - Day of the month (01..31)

%D - Date (%m/%d/%y)

%e - Day of the month, blank-padded ( 1..31)

%F - Equivalent to %Y-%m-%d (the ISO 8601 date format)

%h - Equivalent to %b

%H - Hour of the day, 24-hour clock (00..23)

%I - Hour of the day, 12-hour clock (01..12)

%j - Day of the year (001..366)

%k - hour, 24-hour clock, blank-padded ( 0..23)

%l - hour, 12-hour clock, blank-padded ( 0..12)

%L - Millisecond of the second (000..999)

%m - Month of the year (01..12)

%M - Minute of the hour (00..59)

%n - Newline (
)

%N - Fractional seconds digits, default is 9 digits (nanosecond)

%3N millisecond (3 digits)
%6N microsecond (6 digits)
%9N nanosecond (9 digits)

%p - Meridian indicator ("AM" or "PM")

%P - Meridian indicator ("am" or "pm")

%r - time, 12-hour (same as %I:%M:%S %p)

%R - time, 24-hour (%H:%M)

%s - Number of seconds since 1970年01月01日 00:00:00 UTC.

%S - Second of the minute (00..60)

%t - Tab character (\t)

%T - time, 24-hour (%H:%M:%S)

%u - Day of the week as a decimal, Monday being 1. (1..7)

%U - Week number of the current year, starting with the first Sunday as the first day of the first week (00..53)

%v - VMS date (%e-%b-%Y)

%V - Week number of year according to ISO 8601 (01..53)

%W - Week number of the current year, starting with the first Monday as the first day of the first week (00..53)

%w - Day of the week (Sunday is 0, 0..6)

%x - Preferred representation for the date alone, no time

%X - Preferred representation for the time alone, no date

%y - Year without a century (00..99)

%Y - Year with century

%z - Time zone as hour offset from UTC (e.g. +0900)

%Z - Time zone name

%% - Literal "%" character

t = Time.now #=> 2007年11月19日 08:37:48 -0600 t.strftime("Printed on %m/%d/%Y") #=> "Printed on 11/19/2007" t.strftime("at %I:%M%p") #=> "at 08:37AM"

Always a String

szeryf · Feb 25, 2009

Remember that even if you ask for one field that is a number, a String will be returned:

Time.now.strftime("%j") #=> "055"

OUTDATED!!!

joshuapinter · Apr 3, 2019

Man, this stuff is so outdated. Be very careful using anything from here. A lot has changed since Ruby 1.9.

You'll want to look at the updated docs, like here for Ruby 2.5.1:

https://ruby-doc.org/core-2.5.1/Time.html#method-i-strftime

They really should just take this site down if they're not going to keep it updated. Probably does more harm than good now.