1.2.5

◀Back | Minified | Changelog | Cautionlog
2012-05-02

A few semi-minor, but front-facing changes in this one:

String

String#truncate now has sensible defaults as well as different arguments. Previous arguments:

Now are:

Note that split is now true by default, which means that it will behave more like standard truncate methods by splitting to the exact character, even if it means it is the middle of a word. from allows truncation to happen in the middle or even on the left ("middle" is often useful for file URLs where the domain and filename/extension are the most important bits). ellipsis, which doesn't often change, is now the last.

One more minor point to note is that previously the length of ellipsis would count against the length of the truncated string. In others words, if you truncated to 20 characters this would include 3 for the string "...". This is now changed so that the string will be truncated to 20 characters and then ellipsis will be appended. The motivation for this is the use case in which ellipsis can be HTML, in which case the string length (say <a onclick="showMore()">...</a>) would not be an accurate representation of how much space it takes up on the screen, and would be problematic if it counted against the string length.

Having four arguments for a method is less than ideal, but I weighed it against the option of removing an argument in favor of a different method name (in fact the motivation for adding throttle below), and also having an options hash. Ideally, the kind of short, utility methods that Sugar provides should have neither an options hash nor lengthy arguments -- they should be as straightforward and easy to remember as possible. This case, however, was weighed against the confusion that new method names would introduce as well as whether the arguments were likely to stray from their defaults enough to warrant their own method name.

Function

Function#throttle functionality existed previously as Function#debounce with wait parameter set to false. This renaming should make it easier to remember what this method does, as well as bring the naming more in line with Underscore, which may be more familiar. It simply throttles a function to allow it to be executed only once per the designated number of milliseconds. debounce is simliar, but will wait the specified duration before executing.

Note also throttle's similarity to Function#lazy. These 2 methods are in a sense counterparts. lazy will queue calls to a function (up to a limit if one is specified) and space them out so they are only executed once for a given duration. throttle, on the other hand, will only execute a maximum of once for that period without queueing. It is functionally identical to calling lazy with a limit of 1. Both methods have their own use cases and can be quite powerful if applied well.

Other