THE RUBY WAY, Third Edition (2015)

---

The peculiar-looking code near the end of the method is put there to counteract a long-standing tradition in the underlying time-handling routines. You might expect that trying to create a date of November 31 would result in an error of some kind. You would be mistaken. Most systems would happily (and silently) convert this to December 1. If you are an old-time UNIX hacker, you may think this is a feature; otherwise, you may consider it a bug.

We will not venture an opinion here as to what the underlying library code ought to do or whether Ruby ought to change that behavior. But we don’t want to have this routine perpetuate the tradition. If you are looking for the date of, say, the fifth Friday in November 2014, you will get anil value back (rather than December 5, 2014).

7.6 Converting Between Seconds and Larger Units

Sometimes we want to take a number of seconds and convert to days, hours, minutes, and seconds. This following routine will do just that:

def sec2dhms(secs)
time = secs.round # Get rid of microseconds
sec = time % 60 # Extract seconds
time /= 60 # Get rid of seconds
mins = time % 60 # Extract minutes
time /= 60 # Get rid of minutes
hrs = time % 24 # Extract hours
time /= 24 # Get rid of hours
days = time # Days (final remainder)
[days, hrs, mins, sec] # Return array [d,h,m,s]
end

t = sec2dhms(1000000) # A million seconds is...

puts "#{t[0]} days," # 11 days,
puts "#{t[1]} hours," # 13 hours,
puts "#{t[2]} minutes," # 46 minutes,
puts " and #{t[3]} seconds." # and 40 seconds.

We could, of course, go up to higher units. However, a week is not an overly useful unit, a month is not a well-defined term, and a year is far from being an integral number of days.

We also present here the inverse of that function:

def dhms2sec(days,hrs=0,min=0,sec=0)
days*86400 + hrs*3600 + min*60 + sec
end

7.7 Converting to and from the Epoch

For various reasons, we may want to convert back and forth between the internal (or traditional) measure and the standard date form. Internally, dates are stored as a number of seconds since the epoch.

The Time.at class method creates a new time given the number of seconds since the epoch:

epoch = Time.at(0) # Find the epoch (1 Jan 1970 GMT)
newmil = Time.at(978307200) # Happy New Millennium! (1 Jan 2001)

The inverse is the instance method to_i which converts to an integer:

now = Time.now # 2014-07-23 17:24:26 -0700
sec = now.to_i # 1406161466

If you need microseconds, you can use to_f to convert to a floating point number.

7.8 Working with Leap Seconds: Don’t!

Ah, but my calculations, people say,
Reduced the year to better reckoning? Nay,
’Twas only striking from the calendar
Unborn Tomorrow and dead Yesterday.

—Omar Khayyam, The Rubaiyat (trans. Fitzgerald)

You want to work with leap seconds? Our advice: Don’t.

Leap seconds are very real. One was added to the year 2012, when June 30’s final minute had 61 seconds rather than the usual 60. Although the library routines have for years allowed for the possibility of a 61-second minute, our experience has been that most systems do not keep track of leap seconds. When we say “most,” we mean all the ones we’ve ever checked.

t0 = Time.gm(2012, 6, 30, 23, 59, 59)
puts t0 + 1 # 2012-07-01 00:00:00 UTC

It is (barely) conceivable that Ruby could add a layer of intelligence to correct for this. At the time of this writing, however, there are no plans to add such functionality.

7.9 Finding the Day of the Year

The day number within the year is sometimes called the Julian date; this is not directly related to the Julian calendar, which has gone out of style. Other people insist that this usage is not correct, so we won’t use it from here on.

No matter what you call it, there will be times you want to know what day of the year it is, from 1 to 366. This is easy in Ruby; we use the yday method:

t = Time.now
day = t.yday # 315

7.10 Validating a Date or Time

As we saw in Section 7.5 “Finding the Nth Weekday in a Month,” the standard date/time functions do not check the validity of a date, but “roll it over” as needed. For example, November 31 is translated to December 1.

At times, this may be the behavior you want. If it is not, you will be happy to know that the standard library Date does not regard such a date as valid. We can use this fact to perform validation of a date as we instantiate it:

class Time

def Time.validate(year, month=1, day=1,
hour=0, min=0, sec=0, usec=0)
require "date"

begin
d = Date.new(year,month,day)
rescue
return nil
end
Time.local(year,month,day,hour,min,sec,usec)
end

end

t1 = Time.validate(2014,11,30) # Instantiates a valid object
t2 = Time.validate(2014,11,31) # Returns nil

Here, we have taken the lazy way out; we simply set the return value to nil if the parameters passed in do not form a valid date (as determined by the Date class). We have made this method a class method of Time by analogy with the other methods that instantiate objects.

Note that the Date class can work with dates prior to the epoch. This means that passing in a date such as 31 May 1961 will succeed as far as the Date class is concerned. But when these values are passed into the Time class, an ArgumentError will result. We don’t attempt to catch that exception here because we think it’s appropriate to let it be caught at the same level as (for example) Time.local, in the user code.

Speaking of Time.local, we used that method here; but if we wanted GMT instead, we could have called the gmt method. It would be a good idea to implement both flavors.

7.11 Finding the Week of the Year

The definition of “week number” is not absolute and fixed. Various businesses, coalitions, government agencies, and standards bodies have differing concepts of what it means. This stems, of course, from the fact that the year can start on any day of the week; we may or may not want to count partial weeks, and we may start on Sunday or Monday.

We offer only three alternatives in this section. The first two are made available by the Time method strftime. The %U specifier numbers the weeks starting from Sunday, and the %W specifier starts with Monday.

The third possibility comes from the Date class. It has an accessor called cweek, which returns the week number based on the ISO 8601 definition (which says that week 1 is the week containing the first Thursday of the year).

If none of these three suits you, you may have to “roll your own.” We present these three in a single code fragment:

require "date"

# Let's look at May 1 in the years
# 2005 and 2015.

t1 = Time.local(2005,5,1)
d1 = Date.new(2005,5,1)

week1a = t1.strftime("%U").to_i # 18
week1b = t1.strftime("%W").to_i # 17
week1c = d1.cweek # 17

t2 = Time.local(2015,5,1)
d2 = Date.new(2015,5,1)

week2a = t2.strftime("%U").to_i # 17
week2b = t2.strftime("%W").to_i # 17
week2c = d2.cweek # 18

7.12 Detecting Leap Years

The Date class has two class methods: julian_leap? and gregorian_leap?. Only the latter is of use in recent years. It also has a method called leap?, which is an alias for the gregorian_leap? method.

require "date"
flag1 = Date.julian_leap? 1700 # true
flag2 = Date.gregorian_leap? 1700 # false
flag3 = Date.leap? 1700 # false

Every child knows the first rule for leap years: The year number must be divisible by four. Fewer people know the second rule, that the year number must not be divisible by 100; and fewer still know the exception, that the year can be divisible by 400. In other words, a century year is a leap year only if it is divisible by 400; therefore, 1900 was not a leap year, but 2000 was. (This adjustment is necessary because a year is not exactly 365.25 days, but a little less, approximately 365.2422 days.)

The Time class does not have a method like this, but if we needed one, it would be simple to create:

class Time

def Time.leap? year
if year % 400 == 0
true
elsif year % 100 == 0
false
elsif year % 4 == 0
true
else
false
end

end

I’ve written this to make the algorithm explicit; an easier implementation, of course, would be simply to call the Date.leap? method from this one. I implement this as a class method by analogy with the Date class methods. It could also be implemented as an instance method.

7.13 Obtaining the Time Zone

The accessor zone in the Time class returns a String representation of the time zone name:

z1 = Time.gm(2000,11,10,22,5,0).zone # "UTC"
z2 = Time.local(2000,11,10,22,5,0).zone # "PST"

Unfortunately, times are stored relative to the current time zone, not the one with which the object was created. If necessary, you can do a little arithmetic here.

7.14 Working with Hours and Minutes Only

We may want to work with times of day as strings. Once again, strftime comes to our aid.

We can print the time with hours, minutes, and seconds if we want:

t = Time.now
puts t.strftime("%H:%M:%S") # 22:07:45

We can print hours and minutes only (and, using the trick of adding 30 seconds to the time, we can even round to the nearest minute):

puts t.strftime("%H:%M") # 22:07
puts (t+30).strftime("%H:%M") # 22:08

Finally, if we don’t like the standard 24-hour (or military) clock, we can switch to the 12-hour clock. It’s appropriate to add a meridian indicator then (AM/PM):

puts t.strftime("%I:%M %p") # 10:07 PM

There are other possibilities, of course. Use your imagination.

7.15 Comparing Time Values

The Time class conveniently mixes in the Comparable module so that dates and times may be compared in a straightforward way:

t0 = Time.local(2014,11,10,22,15) # 10 Nov 2014 at 22:15
t1 = Time.local(2014,11,9,23,45) # 9 Nov 2014 at 23:45
t2 = Time.local(2014,11,12,8,10) # 12 Nov 2014 at 8:10
t3 = Time.local(2014,11,11,10,25) # 11 Nov 2014 at 10:25

if t0 > t1 then puts "t0 > t1" end
if t1 != t2 then puts "t1 != t2" end
if t1 <= t2 then puts "t1 <= t2" end
if t3.between?(t1,t2)
puts "t3 is between t1 and t2"
end

# All four if statements test true

7.16 Adding Intervals to Time Values

We can obtain a new time by adding an interval to a specified time; the number is interpreted as a number of seconds:

t0 = Time.now
t1 = t0 + 60 # Exactly one minute past t0
t2 = t0 + 3600 # Exactly one hour past t0
t3 = t0 + 86400 # Exactly one day past t0

The function dhms2sec (defined in Section 7.6, “Converting Between Seconds and Larger Units,” earlier in the chapter) might be helpful here (recall that the hours, minutes, and seconds all default to 0):

t4 = t0 + dhms2sec(5,10) # Ahead 5 days, 10 hours
t5 = t0 + dhms2sec(22,18,15) # Ahead 22 days, 18 hrs, 15 min
t6 = t0 - dhms2sec(7) # Exactly one week ago

Don’t forget that we can move backward in time by subtracting, as seen with t6 in the preceding code example.

7.17 Computing the Difference in Two Time Values

We can find the interval of time between two points in time. Subtracting one Time object from another gives us a number of seconds:

today = Time.local(2014,11,10)
yesterday = Time.local(2014,11,9)
diff = today - yesterday # 86400 seconds

Once again, the function sec2dhms comes in handy (this is defined in Section 7.6, “Converting Between Seconds and Larger Units”):

past = Time.local(2012,9,13,4,15)
now = Time.local(2014,11,10,22,42)
diff = now - past # 68153220.0
unit = sec2dhms(diff)
puts "#{unit[0]} days," # 788 days,
puts "#{unit[1]} hours," # 19 hours,
puts "#{unit[2]} minutes," # 27 minutes,
puts "and #{unit[3]} seconds." # and 0 seconds.

7.18 Working with Specific Dates (Pre-Epoch)

The standard library Date provides a class of the same name for working with dates that precede midnight GMT, January 1, 1970.

Although there is some overlap in functionality with the Time class, there are significant differences. Most notably, the Date class does not handle the time of day at all. Its resolution is a single day. Also, the Date class performs more rigorous error-checking than the Time class; if you attempt to refer to a date such as June 31 (or even February 29 in a non-leap year), you will get an error. The code is smart enough to know the different cutoff dates for Italy and England switching to the Gregorian calendar (in 1582 and 1752, respectively), and it can detect “nonexistent” dates that are a result of this switchover. This standard library is a tangle of interesting and arcane code. We do not have space to document it further here.

7.19 Time, Date, and DateTime

Ruby has three basic classes dealing with dates and times: Time, Date, and DateTime.

• The Time class is mostly a wrapper for the underlying time functions in the C library. These are typically based on the UNIX epoch and therefore cannot represent times before 1970.

• The Date class was created to address this shortcoming of the Time class. It can easily deal with older dates, such as Leonardo da Vinci’s birthday (April 15, 1452), and it is intelligent about the dates of calendar reform. But it has its own shortcoming; for example, it can’t deal with the time of day that Leonardo was born. It deals strictly with dates.

• The DateTime class inherits from Date and tries to be the best of both worlds. It can represent dates as well as Date can, and times as well as Time can. This is often the “right” way to represent a date-time value. The tradeoff made is one of speed, and DateTime can be vastly slower if used extensively for calculations.

But don’t be fooled into thinking that a DateTime is just a Date with an embedded Time. There are, in fact, Time methods missing from DateTime, such as nsec, dst?, utc, and others.

Both the Date and DateTime classes are part of the standard library, and must be loaded with require "date" before they can be used. Once the Date library is loaded, conversions are provided by methods with the highly predictable to_time, to_date, and to_datetimemethods.

7.20 Parsing a Date or Time String

A date and time can be formatted as a string in many different ways because of abbreviations, varying punctuation, different orderings, and so on. Because of the various ways of formatting, writing code to decipher such a character string can be daunting. Consider these examples:

s1 = "9/13/14 2:15am"
s2 = "1961-05-31"
s3 = "11 July 1924"
s4 = "April 17, 1929"
s5 = "20 July 1969 16:17 EDT" # That's one small step...
s6 = "Mon Nov 13 2000"
s7 = "August 24, 79" # Destruction of Pompeii
s8 = "8/24/79"

The Time and Date libraries provide minimal parsing via the parse class method. Unfortunately, those methods assume that two-digit years are in a recent century, thus misplacing the destruction of Pompeii by 1900 years. They also cannot interpret American-style dates, such as those in the preceding s1 and s8 examples.

To solve the century issue, use the second argument to Date.parse. When it is set to false, the century will no longer be guessed:

Date.parse("August 24, 79", false) # 0079-08-24

Keep in mind that the default is to guess the century, which may or may not be the one you intend. Two-digit years up to 69 are interpreted as 20XX, whereas years 70 and above are rendered 19XX.

To parse American-style dates, and in fact a huge range of more exotic formats, use the Chronic gem (installed with gem install chronic). Although it shares the Time limits on two-digit years, it provides fairly exhaustive time parsing.

Chronic.parse "next tuesday"
Chronic.parse "3 weeks ago monday at 5pm"
Chronic.parse "time to go home" # Well, not every possible time

If Chronic can’t understand a time, it will simply return nil instead of raising an exception.

When parsing times, be careful of time zones. CST, for example, has at least five different meanings around the world. See Section 7.22, “Time Zone Conversions,” for more information about how to handle times in multiple time zones.

7.21 Formatting and Printing Time Values

You can obtain the canonical representation of the date and time by calling the to_s method. This is the same as the result you would get if doing a simple puts of a time value.

Similarly, a traditional UNIX format that includes the day of the week is available via the asctime method (“ASCII time”); it has an alias called ctime, for those who already know it by that name.

The strftime method of class Time formats a date and time in almost any form you can think of. Other examples in this chapter have shown the use of the directives %a, %A, %U, %W, %H, %M, %S, %I, and %p; we list here all the remaining directives that strftime recognizes:

%b Abbreviated month name ("Jan")
%B Full month name ("January")
%c Preferred local date/time representation
%d Day of the month (1..31)
%j Day of the year (1..366); so-called "Julian date"
%m Month as a number (1..12)
%w Day of the week as a number (0..6)
%x Preferred representation for date (no time)
%y Two-digit year (no century)
%Y Four-digit year
%Z Time zone name
%% A literal "%" character

For more information, consult a Ruby reference.

7.22 Time Zone Conversions

In plain Ruby, it is only possible to work with two time zones: UTC (or GMT) is one, and the other is whatever time zone you happen to be in.

The utc method converts a time to UTC (changing the receiver in place). There is also an alias named gmtime.

You might expect that it would be possible to convert a time to an array, tweak the time zone, and convert it back. The trouble with this is that all the class methods that create a Time object, such as local and gm (or their aliases mktime and utc), use either your local time zone or UTC.

There is a workaround to get time zone conversions. This does require that you know the time difference in advance. See the following code fragment:

mississippi = Time.local(2014,11,13,9,35) # 9:35 am CST
california = mississippi - 2*3600 # Minus two hours

time1 = mississippi.strftime("%X CST") # 09:35:00 CST
time2 = california.strftime("%X PST") # 07:35:00 PST

The %X directive to strftime that we see here simply uses the hh:mm:ss format as shown.

This kind of conversion is not usable around the world, however, because some zone abbreviations are used by multiple countries in different zones.

If you will be converting between time zones frequently, or simply need to accept and manipulate times that include many time zones, the ActiveSupport gem supplies extensions to Time that add thorough time zone support.

require 'active_support/time'
Time.zone = -8
Time.zone.name # "Pacific Time (US & Canada)"
Time.zone.now # Wed, 25 Jun 2014 12:20:35 PDT -07:00
Time.zone.now.in_time_zone("Hawaii") # 09:20:36 HST -10:00

For more information on how to use ActiveSupport to handle the full range of worldwide time zones, see the gem documentation online, especially the TimeWithZone class.

7.23 Determining the Number of Days in a Month

Although there is no built-in function to do this, it is provided by the days_in_month method added to Time by the ActiveSupport gem. Without ActiveSupport, you can easily write a simple method for this:

require 'date'
def month_days(month,year=Date.today.year)
mdays = [nil,31,28,31,30,31,30,31,31,30,31,30,31]
mdays[2] = 29 if Date.leap?(year)
mdays[month]
end

days = month_days(5) # 31 (May)
days = month_days(2,2000) # 29 (February 2000)
days = month_days(2,2100) # 28 (February 2100)

7.24 Dividing a Month into Weeks

Imagine that you wanted to divide a month into weeks—for example, to print a calendar. The following code does that. The array returned is made up of subarrays, each of size seven (7); Sunday corresponds to the first element of each inner array. Leading entries for the first week and trailing entries for the last week may be nil:

def calendar(month,year)
days = month_days(month,year)
t = Time.mktime(year,month,1)
first = t.wday
list = *1..days
weeks = [[]]
week1 = 7 - first
week1.times { weeks[0] << list.shift }
nweeks = list.size/7 + 1
nweeks.times do |i|
weeks[i+1] ||= []
7.times do
break if list.empty?
weeks[i+1] << list.shift
end
end
pad_first = 7-weeks[0].size
pad_first.times { weeks[0].unshift(nil) }
pad_last = 7-weeks[0].size
pad_last.times { weeks[-1].unshift(nil) }
weeks
end

arr = calendar(12,2008) # [[nil, 1, 2, 3, 4, 5, 6],
# [7, 8, 9, 10, 11, 12, 13],
# [14, 15, 16, 17, 18, 19, 20],
# [21, 22, 23, 24, 25, 26, 27],
# [28, 29, 30, 31, nil, nil, nil]]

To illustrate it a little better, the following method prints out this array of arrays:

def print_calendar(month,year)
weeks = calendar(month,year)
weeks.each do |wk|
wk.each do |d|
item = d.nil? ? " "*4 : " %2d " % d
print item
end
puts
end
puts
end

# Output:
# 1 2 3 4 5 6
# 7 8 9 10 11 12 13
# 14 15 16 17 18 19 20
# 21 22 23 24 25 26 27
# 28 29 30 31

7.25 Conclusion

In this chapter, we have looked at how the Time class works as a wrapper for the underlying C-based functions. We’ve seen its features and its limitations.

We’ve seen the motivation for the Date and DateTime classes and the functionality they provide. We’ve looked at how to convert between these three kinds of objects, and we’ve added a few useful methods of our own.

That ends our discussion of times and dates. Let’s move on to look at arrays, hashes, and other enumerable data structures in Ruby.