Dates

Sugar makes working with dates easy, and has support for multiple languages.

Installing

Sugar is a library that provides many methods for different native types. A dates-only build can be created at the download page, or using the npm module sugar-date.

Usage

Sugar methods have three different modes of use: Default, Chainable, and Extended. Static and chainable methods go through the Sugar global object, while extended mode maps methods directly to native prototypes. For more information about what this means and which mode to use, see the Getting Started guide.

Parsing

Creating dates in Sugar is handled through the create method. It accepts strings and numbers, as well as other date objects. Date parsing of strings happens automatically, and will use the current locale (English by default) if none is specified. Locale codes can be passed as the second argument.

Sugar supports a wide variety of formats in many different locales. Custom formats can also be added if necessary. For more, see Date Parsing. The box below is a sample of a variety of different English formats that Sugar understands. Click on the links or use the text input:

Manipulating

Dates can easily be manipulated and shifted using the methods set, advance, and rewind. In addition to accepting different forms of input, these methods also optionally can reset units lower than the most specific unit being set. reset will also reset any unit and lower (time is reset by default). Finally the unit add methods are useful for focusing on a single unit.

The following methods all modify the date:

Comparing

Sugar adds methods beginning with the is prefix that allow dates to be compared or tested against different criteria. The is method itself will directly compare dates with a margin of error. When passed a string, it will also intelligently use the precision implied in the input. For example, passing "Oct 21st 2015" will match anything that falls within the entire day, however passing new Date(2015, 9, 21) will match only that exact moment (with an optional margin for error).

Full list of date comparison methods:

Unit Operations

Performing a subtract operation - on two dates will give the relative distance between them in milliseconds, but this is often required to be in a different unit. Sugar provides the methods unitsSince, unitsAgo, unitsUntil, and unitsFromNow to return time differences in any unit required.

Full list of methods:

Formatting

Sugar allows multiple ways to convert dates to a string in different formats. The format method supports two types of tokens: LDML, which are more intuitive and easy to remember, as well as strftime, which are found in a variety of programming languages. In addition to allowing output in a user defined format, four preset format types also exist: short, medium, long, and full. The short format presents only the date in a numeric format. Medium uses a longer, word-based format. Long adds the time to this format. Full adds to this the weekday. The major advantage to these formats is that they exist on all locales and can be quickly used without knowing the details of date formatting in those languages.

Finally, relative date strings can also be output using the methods relative and relativeTo. These methods will automatically choose the appropriate unit, for example minutes for a date less than an hour ago.

Full list of formatting methods:

strftime tokens

LDML tokens

Numbers

The Sugar date module also defines a number of useful methods on numbers, as well. The most handy are the unit shortcuts, which take the number as a unit of time and convert them to milliseconds. Numbers also have the methods unitsBefore, unitsAgo, unitsAfter, and unitsFromNow as shortcuts. Note that these unit methods can also be called in their singular form.

Finally, the duration method will return a string similar to relative, taking the number as millseconds and converting to the unit most appropriate.

Full list of methods mapped to numbers:

Locales

Sugar supports 17 major locales. These can be added separately or included in the build via the downloads page. Locales contain various information including parsing and output of both static and relative formats. Once included, locales can either be set globally via the setLocale method, or passed as a code to methods such as isLastWeek which are locale dependent. Additionally, any method such as create that accepts an options object will accept a locale code in its place.

Locale related methods:

Timezones

As many developers know, Javascript does not natively provide support for handling timezones (all Javascript dates are local to their environment). Handling this properly is complex, and falls outside the scope of Sugar. However, special options are included that allows Sugar to play nicely with other libraries designed for this purpose. Specifically, the newDateInternal option allows dates created internally by Sugar to be transformed to simulate being in a different timezone.

UTC Time

Although Sugar does not handle timezones directly, it does provide a few methods that make working with dates intended to be in UTC easier. First, methods such as create that allow an options object will accept an option fromUTC that indicates that the incoming string is in UTC time. This is most useful when reading in dates from a server, which are often standardized to UTC time.

Additionally, the method setUTC (which also exists as an option of the same name) will set an internal flag on a date telling Sugar to use UTC-based methods such as getUTCHours internally when handling the date. This can be useful if dates need to be output as UTC. Note that native methods like getHours still return local values.

List of UTC related methods:

ISO-8601

Sugar natively supports ISO-8601 as one of its core formats. Most modern browsers can also parse this format, however inconsistencies exist with dates that don't specify a timezone offset (either Z or +-hh:mm). To ensure compatibility, dates such as server timestamps should always supply an offset. If they do not, Sugar will correctly parse these formats as local time (as per ISO-8601), however be aware that this may differ from native parsing (new Date). If UTC time is required, fromUTC will force the date to be parsed as UTC time, and should be used.

Ranges

The Sugar range module provides a lightweight, conventient way to handle a date range that has a distinct start and end. Date ranges can be compared, combined, and iterated over.

The date range is created through the Date.range method, passing a start and end value. These values may be strings, which will be forwarded to the create method, numbers for timestamps, or date objects. The date range constructor also accepts a single string in the forms:

Range methods appear in the API reference and can be included or excluded in custom builds, however they differ from standard Sugar methods in that they are always called as instance methods on range objects, and never as static methods.