Relative time: Additional features

[rxaviers]

• PR Add relative time formatting #395 (implementation using value as number unit)

Support relative times:

• in the past , eg "5 days ago";
• in the future, eg "in 5 days";

API

Globalize.formatRelativeTime( value[, unit][, options] )

Examples:

.formatRelativeTime( inTwoDays ); // in 2 days
.formatRelativeTime( twoDaysAgo ); // 2 days ago
.formatRelativeTime( 2, "day" ); // in 2 days
.formatRelativeTime( twoDaysAgo, "hour" ); // 48 hours ago
.formatRelativeTime( -48, "hour" ); // 48 hours ago
.formatRelativeTime( twoDaysAgo, "hour", { form: "short" } ); // 48 hr. ago
.formatRelativeTime({ from: christmas2001, to: newyear2002 }, "day" ); // in 7 days

Value: Object with from and to keys and Date instance values, or a Date instance (considered to be the to value and from defaults to now (new Date())), or a Number (positive numbers represent future, negative numbers represent past).

Unit: Optional when value is a Date instance or an object of Date instances. Required when value is a Number. Possible values are (year, quarter, month, week, day, hour, minute, and second), e.g., "in 30 days", "in 4 weeks", or "in 1 month", ... Defaults to automatic detection when using Date instances, therefore implementing a simple approximation algorithm [1]. But, delegating any more complex things to a specific date manipulation library such as moment.js.

Options:

• form (short, narrow), eg. "in 30 days", "in 4 wk.", or "in 1 mo."...

1:

• "1 second ago" .. "59 seconds ago"; (1 .. 59 s)
• "1 minute ago" .. "59 minutes ago"; (60 .. 60*60 s)
• "1 hour ago" .. "59 hours ago";
• "1 day ago" .. "59 days ago";
• "1 week ago" .. "59 weeks ago";
• "1 month ago" .. "59 months ago";
• "1 year ago" .. "59 years ago";

(analogous for future)

CLDR

Relative time fields can be found on /dateFields.json.

• http://www.unicode.org/reports/tr35/tr35-dates.html#Calendar_Fields
• http://www.unicode.org/reports/tr35/tr35-dates.html#Date_Field_Symbol_Table

Other

References:

• Ecma proposal Relative time/dates tc39/ecma402#35
• twitter-cldr
• Rails;
• Wikipedia [1] [2];

This issue succeeds #205 (discussion to get to the API above). For absolute durations, see .formatUnit() in #252.

[rxaviers]

On CLDR v26, different widths/forms appeared: short and narrow. So, I've updated the API accordingly.

I've also (a) made the API more similar to .formatUnit(), i.e., making unit an argument and having options.form to modify the default width/form; and (b) allowed value to be a Number, whose sign represents the past/future direction (according to #389 (comment)).

[rxaviers]

Ecma proposal:

• Relative time/dates tc39/ecma402#35