Date And Time Manipulation In Ruby With Code Examples

Date and Time Manipulation in Ruby

The Date/DateTime classes, which are implemented in pure Ruby, and the Time class, which interfaces with the C time library, are the two primary interfaces that Ruby offers for managing and modifying dates and times.

Comparison of Time Implementations

These two objects cannot be combined in arithmetic operations, comparisons, or iterations because they are incompatible.

You can also read TK GUI in Ruby: Creating Your First Graphical User Interface

Creation and Initialization

Current Date and Time

Utilizing the factory methods is the most straightforward approach to producing objects that depict the current moment:

Time: Time.now or its equivalent Time.new gives back the local time right now.

DateTime: Requires require 'date'. DateTime.now returns the current local time.

Code Example: Creating Current and Epoch Times

# Current system time
puts Time.now                # => current date and time

# Time object from seconds since Unix epoch
puts Time.at(0)              # => 1970-01-01 00:00:00 UTC

# Using DateTime
require 'date'
puts DateTime.now            # => current DateTime object

Output

2025-11-20 08:53:47 +0000
1970-01-01 00:00:00 +0000
2025-11-20T08:53:47+00:00

You can also read Ruby GUI Toolkits: GTK, wxRuby And RubyCocoa Explained

Specific Dates and Times

By supplying arguments for the year, month, day, and so forth, you can construct particular time objects.

Time.local / Time.gm: For a particular local time or GMT (UTC), create a Time object. After the year, all arguments are optional and start at zero.

DateTime.civil: A DateTime object is created. Date_of_calendar_reform, timezone_offset, year, month, day, hour, minute, and second are among the arguments. The year 4712 BCE is the default.

Code Example: Creating Specific Times

require 'date'

puts Time.local(1999, 12, 31, 23, 21, 5, 1044)
# => Fri Dec 31 23:21:05 EST 1999

puts Time.gm(2000)
# => Sat Jan 01 00:00:00 UTC 2000

puts DateTime.new(1865, 4, 9).to_s
# => "1865-04-09T00:00:00+00:00"

puts DateTime.civil(1991, 10, 1).to_s
# => "1991-10-01T00:00:00+00:00"

Output

1999-12-31 23:21:05 +0000
2000-01-01 00:00:00 UTC
1865-04-09T00:00:00+00:00
1991-10-01T00:00:00+00:00

You can also read Extending Ruby with C: A Complete Beginner’s Guide

Formatting and Parsing

Formatting (Printing) Dates

You can use the strftime method on both Time and Date objects to print a date in a particular format by passing a format string with directives.

Code Example: Using strftime

require 'time'  # optional, Time class is part of core

# Example 1: Formatting a Time object
puts Time.gm(2006).strftime('The year is %Y!')
# => "The year is 2006!"

# Example 2: Formatting a specific Time object
time = Time.gm(2005, 12, 31, 13, 22, 33)
puts time.strftime('%m/%d/%Y')
# => "12/31/2005"

puts time.strftime('%A, %B %d, %Y')
# => "Saturday, December 31, 2005"

# Example 3: Current time formatting
puts Time.now.strftime("%Y-%m-%d %H:%M:%S")
# => e.g., "2025-11-20 12:34:56"

Output

The year is 2006!
12/31/2005
Saturday, December 31, 2005
2025-11-20 08:58:42

The commands begin with a letter and a percent symbol, such %A for the complete weekday name or %m for the month padded to two digits.

Parsing Dates

You can parse a string fuzzily or precisely to turn it into a date object.

• Fuzzy Parsing: Using heuristics, Date.parse or DateTime.parse tries to infer the string’s format.
• Precise Parsing: You can use DateTime.strptime or Date.strptime with a format string using strftime directives if you know the format.

Code Example: Parsing Dates

require 'date'

# Parsing standard date string
puts Date.parse('Wednesday, January 10, 2001').to_s
# => "2001-01-10"

# Parsing date with time
puts DateTime.parse('02-09-2007 12:30:44 AM').to_s
# => "2007-09-02T00:30:44+00:00"

# Parsing European-style date
european_date = '%d/%m/%y'
puts Date.strptime('2/9/07', european_date).to_s
# => "2007-09-02"

Output

2001-01-10
2007-09-02T00:30:44+00:00
2007-09-02

For common standardized formats (like email or HTTP headers), requiring the 'time' library allows the use of dedicated parsing class methods that return a Time object, such as Time.rfc822 or Time.httpdate.

You can also read Embedding Ruby: Running Ruby Code Inside C & C++ Programs

Date Arithmetic and Duration

Ruby’s time objects are internally stored as numbers, which allows them to implement arithmetic operations.

Adding and Subtracting Time

Time Objects: The number of seconds is increased or decreased when a number is added or subtracted. The interval is returned in seconds when one Time object is subtracted from another.

Date/DateTime Objects: The number of days is added or subtracted when a number is added or subtracted. The interval in days is returned (as a rational integer) when one DateTime object is subtracted from another.

Code Example: Date Arithmetic

require 'date'

# Time arithmetic
y2k = Time.gm(2000, 1, 1)
puts y2k + 1
# => Sat Jan 01 00:00:01 UTC 2000 (1 second later)

day_two = Time.gm(2000, 1, 1)
puts day_two - Time.gm(1999, 12, 31)
# => 86400.0 (seconds in a day)

# DateTime arithmetic
y2k_dt = DateTime.new(2000, 1, 1)
puts (y2k_dt + 1).to_s
# => "2000-01-02T00:00:00+00:00" (1 day later)

puts (y2k_dt + 0.5).to_s
# => "2000-01-01T12:00:00+00:00" (half a day later)

Output

2000-01-01 00:00:01 UTC
86400.0
2000-01-02T00:00:00+00:00
2000-01-01T12:00:00+00:00

Iterating Over Dates

Time objects, like numbers, can be used in ranges.

• In one-day increments, the Date and DateTime ranges iterate.
• One-second increments are used in time ranges.

Code Example: Date Iteration using Ranges

require 'date'

# Iterate over dates
(Date.new(1776, 7, 2)..Date.new(1776, 7, 4)).each do |x|
  puts x
end
# Output:
# 1776-07-02
# 1776-07-03
# 1776-07-04

# Iterate over times by seconds
start_time = Time.at(100)
end_time = Time.at(102)
current = start_time
while current <= end_time
  puts current
  current += 1  # increment by 1 second
end
# Output:
# 1970-01-01 00:01:40 +0000
# 1970-01-01 00:01:41 +0000
# 1970-01-01 00:01:42 +0000

Output

1776-07-02
1776-07-03
1776-07-04
1970-01-01 00:01:40 +0000
1970-01-01 00:01:41 +0000
1970-01-01 00:01:42 +0000

Execution Duration and Timeouts

This Kernel#sleep method is used to halt the execution of a program for a specified amount of time. With the help of the timeout library, timeouts can be applied to lengthy processes.

Code Example: Using sleep and Timeout

# Print current time
puts Time.new  # Prints current time

sleep(10)      # Waits 10 seconds

puts Time.new  # Prints time 10 seconds later

# Example using Timeout
require 'timeout'

begin
  Timeout.timeout(1.5) do
    puts "Sleeping for 1 second within the timeout block"
    sleep(1)
    puts "Block completed successfully"
  end
rescue Timeout::Error
  puts "The block timed out!"
end

Output

2025-11-20 09:05:59 +0000
2025-11-20 09:06:09 +0000
Sleeping for 1 second within the timeout block
Block completed successfully

You can also read What Are The Ruby Version Management With Code Examples