1.3.4
◀Back | Minified | Changelog | Cautionlog2012-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:
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
- Fixed issue with
Array.create
not properly creating arrays. Date#setWeekday
now returns a timestamp like native methods.Date#clone
will now preserve the utc flag.- Fixed issue with DateRanges going into an infinite loop when traversing DST timezones.
- Various date parsing fixes.
timers
object is now exposed on functions.Function#debounce
now properly sets the timer on the debounced function.Function#bind
no longer overwrites native implementations.