globalizejs / globalizejs/globalize
Relative time: Additional features
- Dominant language
- JavaScript
- Stars
- 4.8k
- Forks
- 585
- PR merge metrics
- No merged PRs in 30d
Description
- PR #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
``` javascript
Globalize.formatRelativeTime( value[, unit][, options] )
```
Examples:
``` javascript
.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/repos/cldr-aux/json/26/main/en/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 https://github.com/tc39/ecma402/issues/35
- [twitter-cldr](https://github.com/twitter/twitter-cldr-js/)
- [Rails](http://api.rubyonrails.org/classes/ActionView/Helpers/DateHelper.html#method-i-distance_of_time_in_words);
- Wikipedia [[1]](https://github.com/wikimedia/mediawiki-core/blob/master/includes/MWTimestamp.php#L179) [[2]](https://github.com/wikimedia/mediawiki-core/blob/master/languages/Language.php#L2269);
##
This issue succeeds #205 (discussion to get to the API above). For absolute durations, see `.formatUnit()` in #252.
Contributor guide
Assessment
This issue has not been assessed yet.