merging changes

source/Ox.js

@@ -150,9 +150,6 @@ Ox.compact <f> Returns an array w/o <code>null</code> or <code>undefined</code>
 @*/
 
 Ox.compact = function(arr) {
-    /***
-    returns an array without null or undefined values
-    ***/
     return Ox.map(arr, function(val) {
         return Ox.isUndefined(val) ? null : val;
     });
@@ -284,7 +281,7 @@ Ox.avg = function(obj) {
 };
 
 /*@
-Ox.clone <f> Returns a (shallow) copy or an object or array
+Ox.clone <f> Returns a (shallow) copy of an object or array
     > (function() { a = ['val']; b = Ox.clone(a); a[0] = null; return b[0]; }())
     'val'
     > (function() { a = {key: 'val'}; b = Ox.clone(a); a.key = null; return b.key; }())
@@ -368,10 +365,10 @@ Ox.every <f> Tests if every element of a collection satisfies a given condition
     > Ox.every([true, true, true])
     true
 @*/
-Ox.every = function(obj, fn) {
+Ox.every = function(col, fn) {
-    return Ox.filter(Ox.values(obj), fn || function(v) {
+    return Ox.filter(Ox.values(col), fn || function(v) {
         return v;
-    }).length == Ox.len(obj);
+    }).length == Ox.len(col);
 };
 
 /*@
@@ -386,10 +383,10 @@ Ox.filter <f> Filters a collection by a given condition
     'foobar'
 @*/
 
-Ox.filter = function(obj, fn) {
+Ox.filter = function(col, fn) {
-    var type = Ox.typeOf(obj),
+    var type = Ox.typeOf(col),
         ret = type == 'array' ? [] : type == 'object' ? {} : '';
-    Ox.forEach(obj, function(v, k) {
+    Ox.forEach(col, function(v, k) {
         if (fn(v, k)) {
             if (type == 'array') {
                 ret.push(v);
@@ -889,6 +886,34 @@ Ox.some = function(obj, fn) {
     return Ox.filter(Ox.values(obj), fn).length > 0;
 };
 
+/*@
+Ox.substr <f> Returns a substring or sub-array
+    Ox.sub behaves like collection[start:stop] in Python
+    (or, for strings, like str.substring() with negative values for stop)
+    > Ox.sub([1, 2, 3], 1, -1)
+    [2]
+    > Ox.sub('foobar', 1)
+    "oobar"
+    > Ox.sub('foobar', -1)
+    "r"
+    > Ox.sub('foobar', 1, 5)
+    "ooba"
+    > Ox.sub('foobar', 1, -1)
+    "ooba"
+    > Ox.sub('foobar', -5, 5)
+    "ooba"
+    > Ox.sub('foobar', -5, -1)
+    "ooba"
+@*/
+Ox.sub = function(col, start, stop) {
+    stop = Ox.isUndefined(stop) ? col.length : stop;
+    start = start < 0 ? col.length + start : start;
+    stop = stop < 0 ? col.length + stop : stop;
+    return Ox.isArray(col) ? Ox.filter(col, function(val, key) {
+        return key >= start && key < stop;
+    }) : col.substring(start, stop);
+}
+
 /*@
 Ox.sum <f> Returns the sum of the values of a collection
     > Ox.sum(1, 2, 3)
@@ -1254,8 +1279,6 @@ Ox.getDaysInMonth <f> Get the number of days in a given month
     29
 @*/
 Ox.getDaysInMonth = function(year, month, utc) {
-    /*
-    */
     year = Ox.makeYear(year);
     month = Ox.isNumber(month) ? month :
         Ox.map(Ox.MONTHS, function(v, i) {
@@ -1264,7 +1287,7 @@ Ox.getDaysInMonth = function(year, month, utc) {
     return new Date(year, month, 0).getDate();
 }
 
-/*
+/*@
 Ox.getDaysInYear <f> Get the number of days in a given year
     > Ox.getDaysInYear(1900)
     365
@@ -1272,7 +1295,7 @@ Ox.getDaysInYear <f> Get the number of days in a given year
     366
     > Ox.getDaysInYear(new Date('01/01/2004'))
     366
-*/
+@*/
 Ox.getDaysInYear = function(year, utc) {
     return 365 + Ox.isLeapYear(Ox.makeYear(year, utc));
 };
@@ -1564,7 +1587,6 @@ Ox.documentReady = (function() {
     var callbacks = [];
     document.onreadystatechange = function() {
         if (document.readyState == 'complete') {
-            //Ox.print('document has become ready', callbacks);
             callbacks.forEach(function(callback) {
                 callback();
             });
@@ -2011,8 +2033,6 @@ Ox.element = function(str) {
         "\u00C2\u00A5\u00E2\u0082\u00AC\u0024"
     @*/
     Ox.encodeUTF8 = function(str) {
-        /*
-        */
         return Ox.map(str, function(chr) {
             var code = chr.charCodeAt(0),
                 str = '';
@@ -2041,8 +2061,6 @@ Ox.element = function(str) {
         '¥€$'
     @*/
     Ox.decodeUTF8 = function(str) {
-        /*
-        */
         var bytes = Ox.map(str, function(v) {
                 return v.charCodeAt(0);
             }),
@@ -2084,15 +2102,18 @@ Ox.element = function(str) {
 //@ Format ---------------------------------------------------------------------
 
 /*@
-Ox.formatArea <f> Formats a number of meters as square kilometers
+Ox.formatArea <f> Formats a number of meters as square meters or kilometers
+    > Ox.formatArea(1000)
+    '1,000 m\u00B2'
     > Ox.formatArea(1000000)
     '1 km\u00B2'
 @*/
 
 Ox.formatArea = function(num, dec) {
     var km = num >= 1000000;
-    return Ox.formatNumber((km ? num / 1000000 : num).toPrecision(8)) +
+    return Ox.formatNumber(
-        ' ' + (km ? 'k' : '') + 'm\u00B2';
+        (km ? num / 1000000 : num).toPrecision(8)
+    ) + ' ' + (km ? 'k' : '') + 'm\u00B2';
 }
 
 /*@
@@ -2276,7 +2297,6 @@ Ox.formatDate = function(date, str, utc) {
     return str;
 };
 
-
 /*@
 Ox.formatDateRange <f> Formats a date range as a string
     A date range is a pair of arbitrary-presicion date strings
@@ -3729,7 +3749,7 @@ Ox.deg = function(rad) {
 
 /*@
 Ox.divideInt <f> Divides a number by another and returns an array of integers
-    <code>Ox.divideInt(num, by)</code> returns an array of "as equal as
+    <code>Ox.divideInt(num, by)</code> returns a sorted array of "as equal as
     possible" integers that has a sum of <code>num</code> and a length of
     <code>by</code>.
     > Ox.divideInt(100, 3)
@@ -3738,14 +3758,12 @@ Ox.divideInt <f> Divides a number by another and returns an array of integers
     [16, 16, 17, 17, 17, 17]
 @*/
 Ox.divideInt = function(num, by) {
-    // fixme: for loops are so C ;)
     var arr = [],
         div = parseInt(num / by),
-        mod = num % by,
+        mod = num % by;
-        i;
+    Ox.loop(by, function(i) {
-    for (i = 0; i < by; i++) {
         arr[i] = div + (i > by - 1 - mod);
-    }
+    });
     return arr;
 }
 
@@ -4103,6 +4121,7 @@ Ox.isValidEmail <f> Tests if a string is a valid e-mail address
     > Ox.isValidEmail("foo@bar..com")
     false
 @*/
+// fixme: rename to isEmail
 Ox.isValidEmail = function(str) {
     return !!/^[0-9A-Z\.\+\-_]+@(?:[0-9A-Z\-]+\.)+[A-Z]{2,6}$/i(str);
 }
@@ -4249,6 +4268,8 @@ Ox.stripTags = function(str) {
 
 /*@
 Ox.substr <f> A better <code>substr</code>
+    Ox.substr behaves like str[start:stop] in Python
+    (or like str.substring() with negative values for stop)
     > Ox.substr('foobar', 1)
     "oobar"
     > Ox.substr('foobar', -1)
@@ -4262,16 +4283,11 @@ Ox.substr <f> A better <code>substr</code>
     > Ox.substr('foobar', -5, -1)
     "ooba"
 @*/
+// deprecated, use Ox.sub()
 Ox.substr = function(str, start, stop) {
-    /***
     // fixme: needed?
-    Ox.substr behaves like str[start:stop] in Python
-    (or like str.substring() with negative values for stop)
-    ***/
     stop = Ox.isUndefined(stop) ? str.length : stop;
     return str.substring(
-        start < 0 ? str.length + start : start,
-        stop < 0 ? str.length + stop : stop
     );
 };
 
@@ -4284,7 +4300,6 @@ Ox.toCamelCase <f> Takes a string with '-', '/' or '_', returns a camelCase stri
     > Ox.toCamelCase('foo_bar_baz')
     'fooBarBaz'
 @*/
-
 Ox.toCamelCase = function(str) {
     return str.replace(/[\-\/_][a-z]/g, function(str) {
         return str[1].toUpperCase();
@@ -4349,7 +4364,7 @@ Ox.trim = function(str) { // is in jQuery, and in JavaScript itself
     Ox.trim(" foo ")
     "foo"
     */
-    return str.replace(/^\s+|\s+$/g, "");
+    return str.replace(/^\s+|\s+$/g, '');
 };
 
 /*@