Features
Arrays
Sugar begins by fixing broken support for standard Javascript 1.6 array methods, such as indexOf, forEach, reduce, etc. These methods are also enhanced to accept arguments that browser native methods won't, such as nested objects, iterating functions, regexes, or strings that provide a shortcut to an iterating function. In such cases, however, browser native methods will always be defered to when possible. Many other methods help make working with arrays easier. More about arrays | Full list of methods.
['a','b','c'].indexOf('c');
['rocksteady','and','bebop'].map('length');
['rocksteady','and','bebop'].sortBy('length');
['rocksteady','and','bebop'].findAll(/o/);
['rocksteady','and','bebop'].first(1);
['rocksteady','and','bebop'].from(1);
['three','two','one'].groupBy('length');
[1,65,2,77,34].average();
[1,2].add([2,3]);
[1,2].subtract([2,3]);
[1,2].intersect([2,3]);
[1,2].union([2,3]);
Strings
Sugar provides methods on strings like from, to, first, last, add, and remove to make modifying strings intuitive and readable, as well as others like each, chars, words, lines, paragraphs which allow iterating over chunks of text. Common escaping methods like escapeURL, escapeHTML, and escapeRegExp provide quick shortcuts for string escaping. Multilingual support is also enhanced with shortcut methods to Unicode script blocks, such as Kanji (Chinese and Japanese), Hiragana (Japanese), Hangul (Korean), Greek, Hebrew, and more. Full list of methods.
'carve me up!'.from(2);
'carve me up!'.to(2);
'carve me up!'.first(2);
'carve me up!'.last(2);
'add me!'.add('to ', 4);
'off'.chars();
'off with her head!'.words();
'off with her head!'.each(/he\S+/g);
'[you] escape <me>'.escapeURL();
'[you] escape <me>'.escapeHTML();
'[you] escape <me>'.escapeRegExp();
'こんにちは'.hasHiragana();
'환영 합니다'.hasHangul();
'Добро пожаловать!'.hasCyrillic();
'welcome'.pad(' ', 1).pad('-', 3);
'hut!'.repeat(3);
'off with her head!'.startsWith(/[a-z]ff/);
Numbers
Basic methods on the Math object exist in Sugar on numbers as shortcut methods. Additional conveniences include number rounding to a specific precison, number padding, and number formatting. Suger also includes methods that bridge the Date class, helping to quickly convert numbers to dates. Full list of methods.
(125.425).round(2);
(125.425).round(-2);
(4235000).format();
(50).pad(5);
(23).ordinalize();
(5).upto(10);
(5).daysAfter('Wednesday');
(5).yearsBefore('2001');
(5).times(function() { /* Run 5 times */ });
Dates
Sugar gives the Date class much love starting with the Date.create method which can understand dates in just about any format in 11 major languages, including relative formats like "1 hour ago". Dates can also be output in any format or language using an easy to understand syntax, with shortcuts to commonly used date formats. Complex date comparison is also possible with methods like is, which understand any format and apply built in precision. More about dates | Full list of methods.
Date.create('2002-06-15');
Date.create('June 15, 2002');
Date.create('today');
Date.create('2 days ago');
Date.create('the last day of 1998');
Date.create('先週金曜日','ja');
Date.create('25 минут назад', 'ru');
Date.create('二十五日', 'zh-CN');
Date.create('il y a une semaine', 'fr');
Date.create().format('{12hr}:{mm}{tt} on {Weekday}');
Date.create().iso();
Date.create('3200 seconds ago').relative();
Date.create('3200 seconds ago').relative('zh-TW');
Date.create('3200 seconds ago').relative('de');
Date.create('3200 seconds ago').relative('ko');
Date.create().is('tuesday');
Date.create().is('the 7th of June');
Date.create().addMonths(2);
Objects
Although Sugar does not interfere with the Object prototype directly, it does provide many shortcuts accessed as Object class methods. One is Object.extended, which creates a hash-like object extended with methods you would expect to find in hashes in other languages. If you prefer not to use these, all methods are also accessible directly on the Object class itself. Also available are type checking methods such as isString, isFunction, etc. More about objects | Full list of methods.
Object.extended({ broken: 'wear' }).keys();
Object.extended({ broken: 'wear' }).values();
Object.keys({ broken: 'wear' });
Object.clone({ broken: 'wear' });
Object.isString('yes, it is');
Object.isFunction(function() {});
Object.fromQueryString(window.location);
Functions
Sugar provides a basic shim for bind to bind scope to functions. Quickly set delays or non-blocking operations with delay and cancel timed operations with cancel. Also included are functions that help with throttling operations: throttle will only fire once for a given duration, lazy will fire all calls to itself, but no more than once for a given duration, and debounce will fire once after a delay when there are many calls in rapid succession. Full list of methods.
(function(a) { /* this = 'wasabi', a = 'bobby' */ }).bind('wasabi', 'bobby')();
(function() { /* delayed 500ms */ }).delay(500);
[1,2,3].each(function() { /* Each iteration will occur 5ms after the previous one */ }.lazy(5));
RegExp
Sugar adds a handful of methods to the RegExp class, and additionally fixes native inconsistencies in splitting on regexes as part of the string class. Full list of methods.
RegExp.escape("oh not /b/, aren't those guys gone?");
/broken/.setFlags('gim');
/broken/im.addFlag('g');
/broken/gi.removeFlag('g');
Opting-In Methods
In trying to extend natives as safely as possible, Sugar will never overwrite methods that have been added by other code. This makes Sugar safe to use alongside other frameworks such as Prototype. However, it may be desirable to override this behavior and allow Sugar to regain control.
For such cases, each built-in class has a sugarRestore() method that will allow any number of methods to revert to Sugar's control. If no method names are passed Sugar will regain control of all methods in that class. Likewise, classes also have a method sugarRevert which will revert (or delete) the methods to restore them to their original state.
Additionally, each built-in class also has an extend() method that allows you to extend built-in types with your own methods!
Finally, calling Object.extend() with no parameters will additionally map all object related methods to the Object.prototype, which is disabled by default. See objects for more about this.
Array.sugarRestore('findAll', 'remove');
String.sugarRestore('from', 'to', 'first', 'last');
Number.sugarRestore('pad');
Object.sugarRevert('isObject');
Number.extend({
add: function(n) {
return this + n;
}
}, true);
(5).add(3);
