1.3.4

◀Back | Minified | Changelog | Cautionlog
2012-09-13

UTC Dates

These days, nearly all web apps have both a client-side and server-side component. Commonly the server stores dates coordinated in UTC (Universal Time). Javascript dates, on the other hand, are always localized to the the local machine, making handling this discrepancy tricky, or at least a bit of a pain.

Previous versions of Sugar had a toUTC method that performed a very naive operation of subtracting the local timezone's offset to produce a date that would be "pseudo-UTC", that is, still appearing to be a local time (timezones can't be changed in JS) but with the timezone offset subtracted so that the timestamp would match that of a UTC date. The method also set a flag that format would check to output a string format with a zero timezone offset. This system had very limited functionality, as any further manipulation of the date would once again yield a local non-UTC result.

This has now been redesigned. toUTC is deprecated and two different but related methods take its place. First, when parsing utc dates, using Date.utc.create instead of Date.create will now tell Sugar to parse the date as utc based. Date.utc.past and Date.utc.future are likewise available here. This handles the case of parsing a date from utc and returning a localized date.

It is also possible to manipulate dates in Sugar as utc, similar to the way they would be manipulated on the server. To achieve this the instance method utc sets a simple internal flag on the date. From that point forward manipulations to the date will call Javascript native utc method equivalents, and formatting will have a zero timezone offset. Note that the utc method will not modify the date.

The difference between these two methods is important. The most common case is parsing utc dates from the server but using a localized date in the client (displaying to the user, etc). However, there may be more uncommon cases when you want to manipulate the date as UTC as well:

Date.create('October 1st') // October 1st in local time Date.utc.create('October 1st') // October 1st in GMT (UTC) time date.set({ date: 15 }) // Calls .setDate(15) internally date.utc().set({ date: 15 }) // Calls .setUTCDate(15) internally date.format() // Outputs the date as a localized string date.utc().format() // Outputs the date as a string in utc date.utc(false) // turns off the utc flag on the date

Array Matching

Another semi-big refactoring deals with the matching of elements inside an array. Previously Sugar would attempt to recursively match any object in an array by value. This included arrays, primitives, etc, and was opt-out, ensuring that only functions are matched by reference. This has been refactored to effectively opt-in nearly all Javascript native types (except functions) to be matched by value. However it will not opt in any "objects" that are not of class [object Object] and do not have hasOwnProperty.

For user created objects and other JS internals, this has little effect. However it effectively opts-out host objects like dom elements, meaning they will be matched by reference only. This closes a major hole in matching host objects in arrays in Sugar. Previously any div element would be matched by any other div element when attempting to find it in an array, as the stringified value [object HTMLDivElement] would be directly compared. Now, they will be strictly matched by reference, making it possible to use host objects directly in arrays, without the use of a library designed for manipulating collections of elements. Most importantly for Sugar this has been achieved without requiring the complex task of identifying host objects in cross-browser environments.

Other