A Quick Guide to Ruby's Time and DateTime Classes


Ruby has three main classes for handling date and time: Date, Time, and DateTime. The DateTime class is a subclass of Date and is used to handle date, hour, minute, second, and offset. However, The Ruby documentation also recommends using the Time class instead of DateTime.

The DateTime class is still available in Ruby for backward compatibility, but developers are encouraged to use the Time class for new projects and to migrate existing code to use the Time class.

DateTime in Ruby

DateTime in Ruby is a class that can handle date, hour, minute, second, and offset. It is a subclass of the Date class. The DateTime class can be used to represent a specific point in time with a specified offset from UTC.

require 'date'

datetime = DateTime.new(2023, 1, 1, 12, 0, 0, '-05:00')
# <DateTime: 2023-01-01T12:00:00-05:00 ((2459946j,61200s,0n),-18000s,2299161j)

In the above example, we are using the new method, passing in the year, month, day, hour, minute, second, and offset as arguments.

An offset refers to the difference between the local time and the Coordinated Universal Time (UTC).

Time class in Ruby

There are various methods to create a Time object with the Time class.

t = Time.new(2024, 3, 11, 2, 2, 2, '+02:00')
# => 2024-03-11 02:02:02 +0200

Here also we can pass date, hour, minute, second, and offset. But in the Time class we can pass the timezone object well for the offset value. Let’s see the below example.

require 'tzinfo'

# Define a timezone object
tz = TZInfo::Timezone.get('Europe/Berlin') # Example timezone

time_with_timezone = Time.new(2002, 10, 31, 2, 2, 2, tz)
# => 2024-03-11 02:02:02 +0100

We can also create a new Time using Time.at which takes the number of seconds since the Unix Epoch. The Unix Epoch refers to a specific point in time used as a reference for measuring time in Unix-like operating systems and many programming languages. It is defined as 00:00:00 UTC on January 1, 1970.

# => 2024-04-15 13:52:27 +0530

Please go through the docs to read more about Time class.

Let’s examine when it’s appropriate to use the Time and DateTime class

The DateTime class is considered deprecated because it does not consider leap seconds and does not track any summertime rules.

It means that it does not account for the extra second that is occasionally added to Coordinated Universal Time (UTC) to adjust for the Earth’s uneven rotation, and it does not adjust for daylight saving time (DST) changes.

The lack of leap seconds can be an issue for certain applications where precise timing is required. For example, in financial transactions and scientific research calculations.

The lack of summertime rule tracking can also be a limitation in certain applications where DST changes need to be considered.

However, DateTime has some advantages over the Time class in Ruby.

The DateTime class is aware of calendar reforms, while the Time class implements a proleptic Gregorian calendar and has no concept of calendar reform. This means that DateTime can accurately convert dates in historical contexts, while Time may not be able to. To understand more about this please go through this gist.

We can conclude that when handling current dates, it’s preferable to utilize the Time class, whereas the DateTime class is more suitable for managing historical dates.

Need help on your Ruby on Rails or React project?

Join Our Newsletter