Kronos is a library for Ruby that provides flexible date-related parsing.
The approach of Kronos is simple: parse what you can and don't be more specific than is justified. In other words, don't attempt to force the rest into a Date object. It can handle a date, just a month and day, or just a year. Some examples:
c = Kronos.parse("1991") c.year # => 1991 c.month # => nil c.day # => nil # These give the same results: c = Kronos.parse("91") c = Kronos.parse("'91") Kronos.parse("1/17/2007") c.year # => 2007 c.month # => 1 c.day # => 17 Kronos.parse("January 1976") c.year # => 1976 c.month # => 1 c.day # => nil
Comparison with other libraries
In contrast, other date parsing libraries, such as Chronic, ParseDate, or Timeliness try to parse a string into a full Date object, which requires a year, month, and day. Even if a month or day is not specified, they are going to pick one for you. For example:
require 'parsedate' require 'chronic' require 'timeliness' # "Aug-96" Chronic.parse("Aug-96") # => Fri Aug 16 12:00:00 -0400 1996 # The day (16) is arbitrarily chosen ParseDate.parsedate("Aug-96") # => [nil, 8, 96, nil, nil, nil, nil, nil] # The year (nil) is wrong # The day (96) is arbitrarily chosen and out of range Timeliness.add_formats(:date, "mmm-yy") t = Timeliness.parse("Aug-96") [t.year, t.month, t.day] # => [1996, 8, 19] # The day (19) is arbitrarily chosen # "1991" Chronic.parse("1991") # => Fri Dec 11 20:31:00 -0500 2009 # The year is wrong (2009) # The month (12) and day (11) are arbitrarily chosen ParseDate.parsedate("1991") # => [nil, 19, 91, nil, nil, nil, nil, nil] # The year is wrong (nil) # The month (19) and day (91) are arbitrarily chosen and out of range Timeliness.add_formats(:date, "yyyy") Timeliness.parse("1991") [t.year, t.month, t.day] # => [1991, 12, 19] # The month (12) and day (19) is arbitrarily chosen
The current version of Kronos relies upon a long sequence of
Date.strptime calls to parse various possible date strings. Why? Because
strptime, unlike many date-parsing libraries, is (1) pretty good about failing when it cannot parse a string correctly and (2) unlikely to give false positives. However, there are still edge cases, so Kronos runs the potential match in reverse (using
strftime) to see if it matches the original -- only then is the parse accepted as valid.
As a historical note, Kronos 0.2.x and earlier was implemented as a thin wrapper over ParseDate. This strategy had to change for Ruby 1.9 because ParseDate support was removed from the standard library.
Kronos handles date-related comparisons more intelligently.
Many Ruby date libraries make the assumption that you are specifying a point (i.e. a particular date), not an interval (such as an entire month or year). Kronos, on the other hand, lets you specify dates that are intervals:
k_1973 = Kronos.parse("1973") k_1974 = Kronos.parse("1974") k_march_1974 = Kronos.parse("March 1974")
With Kronos, you can compare date objects as follows:
k_1973 < k_1974 # => true k_1973 < k_march_1974 # => true
A Note about Kronos Comparison Operators
< as "Does the date interval on the left occur completely before the date interval on the right?" In other words, if there is overlap, the result will be false.
Here's an example. If you ask "Does the year 1974 come before March 1974?" a careful response might be: "Actually, part of it comes before and part of it comes after. Your question does not really make sense because March 1974 is contained within the year 1974."
Because of this, Konos comparison operators (
>) behave a little bit differently for Kronos objects than for, say, integers. Given any two integers m and n, you can be sure that one of the operators holds. For example:
m = 1 n = 2 m < n # => true m == n # => false m > n # => false
However, given two Kronos objects k1 and k2 you cannot guarantee that one of the operators will hold. For example:
k_1974 < k_march_1974 # => false k_1973 == k_march_1974 # => false k_1974 > k_march_1974 # => false
Since the two dates are unequal but overlap, Kronos will always return false.
I plan to implement the
in? method as follows:
k_march_1974.in?(k_1974) # => true k_1974.in?(k_march_1974) # => false
We import a lot of data from government Web sites as part of our work at the Sunlight Labs (the technical arm of the Sunlight Foundation). I did not want to store date-related information in a way that made it seem more precise than it really was, so I wrote this little library. -David
- David James (djsun)
- Eric Mill (klondike)
We would appreciate your feedback. Thanks!