Sugar | Javascript, sweetened.

Creating Manipulating Comparing Formatting Locales

Dates

Try entering a date above. Here are some suggestions:

Creating Dates

The Date.create method is an alternate syntax to new Date() and understands a wide variety of formats. Any Sugar method that accepts dates will also understand these different formats. Aside from the text formats above, timestamps as numbers are also understood, as are other date objects, which return themselves. The method can also accept enumerated params, as with new Date():


Date.create('January 10, 2012');
Date.create('May 1987');
Date.create('tomorrow');
Date.create(1234567899999);
Date.create(new Date());
Date.create(2011, 5, 17, 10, 30);
(5).daysBefore('Monday');
(8).hoursAfter('5:45pm');

Methods that will understand these formats include the following:

Class
Method
Example
Date create 
Date.create('today')
Date is 
date1.is('Jan 25, 1990')
Date isBefore 
date2.isBefore('next week tuesday')
Date isAfter 
date3.isAfter('March 1st')
Date isBetween 
date4.isBetween('January 11th', 'April 22nd')
Date unitSince 
date5.daysSince('2008-05-25')
Date unitUntil 
date6.daysUntil('2008-05-25')
Number unitBefore 
num.daysBefore('2008-05-25')
Number unitAfter 
num.daysAfter('2008-05-25')

Manipulating Dates

Method
Description
set Sets any unit on the date. Accepts a hash, timestamp, or enumerated params. If the second parameter is true it will also reset units that are more specific than those passed.
advance Advances the date into the future. Accepts a hash, timestamp, or enumerated params. All values are relative to the date.
rewind Rewinds the date into the past. Accepts a hash, timestamp, or enumerated params. All values are relative to the date.
addUnit Adds a unit of time to the date.
beginningOfUnit Sets the date to the beginning of that unit. Can be Day/Month/Week/Year.
endOfUnit Sets the date to the end of that unit. Can be Day/Month/Week/Year.
resetTime Resets the time on the date.
toUTC Converts the date to UTC time, effectively subtracting the current timezone offset.
Date.create().set({ day: 17 });
Date.create().set({ month: 2, day: 17 });
Date.create().set({ month: 2, day: 17 }, true);
Date.create().advance({ years: 2 });
Date.create().rewind({ months: 5 });
Date.create().addYears(5);
Date.create().addDays(3);
Date.create().addHours(-11);
Date.create().beginningOfDay();
Date.create().beginningOfWeek();
Date.create().endOfMonth();
Date.create().endOfYear();
Date.create().resetTime();
Date.create().toUTC();

Comparing Dates

Method
Description
is Compares the date to any format passed in. If a date object or timestamp is passed in, the date is tested to the millisecond. If a text format is used, is performs some magic that will use a precision implied in the format used. For example, if '2010' is passed, it will return true for any date between the first and last millisecond of 2010. The second parameter will add a margin of error (in milliseconds).
isAfter Will return true if the date is after the one passed.
isBefore Will return true if the date is before the one passed.
isBetween Will return true if the date is between the two passed.
isFuture Will return true if the date is in the future.
isPast Will return true if the date is in the past.
isYesterday Will return true if the date is yesterday.
isToday Will return true if the date is today.
isTomorrow Will return true if the date is tomorrow.
isWeekday Will return true if the date is Monday - Friday.
isWeekend Will return true if the date is a Saturday or Sunday.
isLastUnit Will return true if the date is last Week/Month/Year.
isThisUnit Will return true if the date is this Week/Month/Year.
isNextUnit Will return true if the date is next Week/Month/Year.
isValid Will return true if the date is valid.
isLeapYear Will return true if the date falls on a leap year.
isUTC Will return true if the date has a zero timezone offset.
Date.create().is('today');
Date.create().is('July');
Date.create().is('2011');
Date.create().isBefore('August');
Date.create().isAfter('April');
Date.create().isBetween('January', 'September');
Date.create('next week').isFuture();
Date.create('next week').isPast();
Date.create('12 hours ago').isYesterday();
Date.create('12 hours from now').isTomorrow();
Date.create().isWeekday();
Date.create().isWeekend();
Date.create('the beginning of the month').isLastWeek();
Date.create('March').isThisMonth();
Date.create('2012').isNextYear();
Date.create('beebop').isValid();
Date.create('this year').isLeapYear();

Formatting Dates

Once you have the date you want, getting it out to the proper format can be a hassle. The format method is designed to help here allowing intuitive tokens to be passed in, with some useful shortcuts. If no format is passed, Sugar will use a common format for the current locale (more on locales below). Tokens that are can be used in a formatting string are:

Token
Meaning
{ms} {milliseconds} {f} {ff} {fff} Millseconds. The {f} style format can pad up to 3 places.
{s} {ss} {seconds} Seconds. {ss} will pad to 2 places.
{m} {mm} {minutes} Minutes. {mm} will pad to 2 places.
{h} {hh} {hours} {12hr} Hours (12 hour). {hh} will pad to 2 places.
{H} {HH} {24hr} Hours (24 hour). {HH} will pad to 2 places.
{d} {dd} {date} Date. {dd} will pad to 2 places.
{dow} {weekday} Day of the week. {dow} is a 3 character abbreviation. If the first letter of any of these tokens is capitalized, the resulting string will also be capitalized.
{ord} The date with an English ordinal suffix (ex. "5th", "3rd", etc)
{M} {MM} Numeric month. {MM}, will pad to 2 places.
{mon} {month} Text month. {mon} is a 3 character abbreviation. If the first letter of any of these tokens is capitalized, the resulting string will also be capitalized.
{yy} {yyyy} {year} Year. If {yy}, will display the last 2 digits only.
{t} {tt} am/pm string. {tt} will be 2 characters. If the first letter of any of these tokens is capitalized, the resulting string will also be capitalized.
{tz} {timezone} {isotz} {isotimezone} Timezone. If iso prefix, will display in ISO format (ex. "+09:00").

Additionally there are a few shortcuts to commonly used formats. These may be passed in as a string or used as a constant directly on the date class. The toISOString method is a direct alias for the ISO8601 format, and additionally will set the date to UTC time. For other formats, you can call the toUTC method on the date first.

Format
Example
Date.RFC1123 Fri, 25 Aug 1978 12:23:44 GMT+0900
Date.RFC1036 Friday, 08-Aug-78 12:23:44 GMT+0900
Date.ISO8601_DATE 1978-08-25
Date.ISO8601_DATETIME 1978-08-25T12:23:44.432Z
Date.create().format();
Date.create().format('{Weekday} {Month} {dd}, {yyyy}');
Date.create().format('{yyyy}-{MM}-{dd}');
Date.create().format('{12hr}:{mm}:{ss} {tt}');
Date.create().format('{yyyy}-{MM}-{dd}T{hh}:{mm}:{ss}');
Date.create().format(Date.RFC1123);
Date.create().format(Date.RFC1036);
Date.create().format(Date.ISO8601_DATETIME);
Date.create().format('RFC1036');
Date.create().toISOString();
Date.create().toUTC().format(Date.RFC1123);

Relative Dates

Sugar also makes getting relative dates easy as well. In addition to standard methods that return the numeric offset, the relative method will produce a localized, relative string with the unit adjusted (more on locales below). Passing a callback fn to relative allows you fine-grained control over the formatting, and is useful for displaying relative or static formats conditionally.

Method
Description
unitsAgo() Returns a number that represents units ago.
unitsFromNow() Returns a number that represents units from now.
relative() Called with no arguments, the relative() method will return a relative date string for the current locale.
relative(fn) Passing a callback to relative allows you more control over the resulting output string. fn is passed 4 arguments: the adjusted value, the adjusted unit index (a value of 0-7 representing milliseconds - years), the non-adjusted offset in ms (negative if the date is in the past), and a locale object. If the callback returns a string with formatting tokens in it, it will parse these out. If it returns nothing or any falsy value, it will remain in relative format. This allows the use of relative and absolute dates conditionally.
format(fn) A callback can also be passed into the format method. This is identical to passing a callback to relative with the exception that returning a falsy value will result in the same format as calling format without any parameters.
Date.create('650 seconds ago').relative();
Date.create('6500 seconds ago').relative();
Date.create('34 hours ago').relative();
Date.create('340 hours ago').relative();
Date.create('monday').relative(function(value, unit, ms, loc) { if(ms.abs() > (1).day()) { // Returns an absolute date, but only if the offset is greater than a day. return '{Weekday} {12hr}:{mm}{tt}'; } });

Date Locales

Sugar now supports 11 major locales out of the box: English (en), French (fr), German (de), Spanish (es), Portuguese (pt), Italian (it), Russian (ru), Japanese (ja), Korean (ko), Simplified Chinese (zh-CN), and Traditional Chinese (zh-TW). Both date parsing and formatting are supported, including support for relative formats. Locales can be set globally, or can be passed in at the moment of date creation or output, allowing mixing and matching of various languages in the page. To improve perfomance, locales are only initialized when first used. In addition to the 11 packaged formats, there is also the ability to extend Sugar with other locales and formats (more on this coming).

Method
Description
Date.setLocale(code) Sets the current locale globally.
Date.getLocale(code) Retreives the localization object for code, or the current locale if none is passed. Augmenting the localization object allows you more control over localizations. Refer to the lib/locales.js file in the Github project to see the kinds of properties that can be set.
Date.create(str, code) Locale codes can also be passed when creating each date object. Most of the date creation methods listed above allow a locale code to be passed as a second parameter. For those methods with a conflicting second parameter, simply create the Date first and pass it in directly.
format(str, code) Passing in a locale code to format will use that localization to output the date. Whan a formatting string is passed, tokens will be populated with the appropriate fields localized. If no format is passed, a common simple format for that locale (date, month, year) will be used.
relative(code) Relative formats can also be localized.
relative(fn, code) Passing a callback to relative allows more control over relative date formatting. fn will receive 4 parameters (see above), the 4th being the localization object for code, or the current locale if none is specified. This object allows access to all the localization information for that locale. If the callback returns a falsy value, the relative format will be used as normal.
Date.setLocale(code, loc) Passing a localization object will extend Sugar with that new locale. Localization objects require a specific set of properties. More on this soon, but for those curious, using getLocale above will get the localization object and give a good idea of what kind of properties need to be passed.
Date.create('2008年11月14日', 'ja');
Date.create('5 años de ahora', 'es');
Date.create('3 октября 2008 года', 'ru');
Date.create('21 octobre 2011', 'fr').format('', 'ko');
Date.create('la settimana prossima', 'it').format('{weekday}', 'pt');
Date.create('580 minutes ago').relative('ko');
Date.create('580 minutes ago').relative('zh-CN');
Date.create('580 minutes ago').relative('zh-TW');
Date.create('580 minutes ago').relative('it');
Date.create('580 minutes ago').relative('es');
Date.create('580 minutes ago').relative('de');

Other Notes

Method
Description
Date.DSTOffset This is a simple property that gets set at initialization which represents the Daylight Savings Time offset in milliseconds.
toUTC Although this method will set the time to UTC, timezones in Javascript are based on the OS, so getTimezoneOffset will always return the same thing. However, this method will set a flag on the date that gets passed to the format method so that the token {tz} will be properly set to UTC. Also note that once a date is set to UTC, it can only be unset by using the clone method.