diff --git a/docs/underscore.array.builders.js.md b/docs/underscore.array.builders.js.md index 8a87b84..28e96f4 100644 --- a/docs/underscore.array.builders.js.md +++ b/docs/underscore.array.builders.js.md @@ -38,6 +38,41 @@ Signature: `_.cat(... elems:Arguments ...)` f(1,2,3); //=> [1,2,3,4,5,6] + +#### chunk + +The `_.chunk` function, by default, accepts an array and a number and splits and returns a new array representing the original array split into some number of arrays of the given size: + + _.chunk([0,1,2,3], 2); + //=> , [[0,1],[2,3]] + +If the original array cannot completely fulfill the chunk scheme then the array returned will drop the undersized final chunk: + + _.chunk([0,1,2,3,4], 2); + //=> , [[0,1],[2,3]] + +You can pass an optional third argument to `_.chunk` to pad out the final array chunk should it fall short. If the value given as the third argument is *not* an array then it is repeated the needed number of times: + + _.chunk([0,1,2,3,4], 3, '_'); + //=> , [[0,1,2],[3,'_','_']] + +If you given an array as the optional third argument then that array is used to pad in-place as needed: + + _.chunk([0,1,2,3,4], 3, ['a', 'b']); + //=> , [[0,1,2],[3,'a','b']] + +#### chunkAll + +The `_.chunkAll` function is similar to `_.chunk` except for the following. First, `_.chunkAll` will never drop short chunks from the end: + + _.chunkAll([0,1,2,3,4], 3); + //=> , [[0,1,2],[3]] + +Also, `_.chunkAll` takes an optional third argument signifying that paritions should be built from skipped regions: + + _.chunkAll(_.range(1), 2, 4); + //=> [[0,1],[4,5],[8,9]] + #### cons @@ -73,41 +108,7 @@ Signature: `_.cons(head:Any, tail:Arguments)` f(1,2,3); //=> [0,1,2,3] -#### partition -The `_.partition` function, by default, accepts an array and a number and splits and returns a new array representing the original array split into some number of arrays of the given size: - - _.partition([0,1,2,3], 2); - //=> , [[0,1],[2,3]] - -If the original array cannot completely fulfill the partition scheme then the array returned will drop the undersized final partition: - - _.partition([0,1,2,3,4], 2); - //=> , [[0,1],[2,3]] - -You can pass an optional third argument to `_.partition` to pad out the final array partition should it fall short. If the value given as the third argument is *not* an array then it is repeated the needed number of times: - - _.partition([0,1,2,3,4], 3, '_'); - //=> , [[0,1,2],[3,'_','_']] - -If you given an array as the optional third argument then that array is used to pad in-place as needed: - - _.partition([0,1,2,3,4], 3, ['a', 'b']); - //=> , [[0,1,2],[3,'a','b']] - -#### partitionAll - -The `_.partitionAll` function is similar to `_.partition` except for the following. First, `_.partionAll` will never drop short partitions from the end: - - _.partitionAll([0,1,2,3,4], 3); - //=> , [[0,1,2],[3]] - -Also, `_.paritionAll` takes an optional third argument signifying that paritions should be built from skipped regions: - - _.partitionAll(_.range(1), 2, 4); - //=> [[0,1],[4,5],[8,9]] - - #### mapcat There are times when a mapping operation produces results contained in arrays, but the final result should be flattened one level. For these circumstances you can use `_.mapcat` to produce results: diff --git a/index.html b/index.html index ae9dab4..a4f2a95 100644 --- a/index.html +++ b/index.html @@ -5,7 +5,7 @@ -
+

Underscore-contrib

The brass buckles on Underscore's utility belt - a contributors' library for Underscore.

@@ -40,19 +40,19 @@

License

Sub-libraries

The _.contrib library currently contains a number of related capabilities, aggregated into the following files.

The links above are to the annotated source code. Full-blown _.contrib documentation is in the works. Contributors welcomed.

array.builders

@@ -69,7 +69,7 @@

cat

//=> [] _.cat([1,2,3]); // 1-arg -//=> [] +//=> [1,2,3] _.cat([1,2,3],[4,5,6]); // 2-args //=> [1,2,3,4,5,6] @@ -86,6 +86,26 @@

cat

f(1,2,3); //=> [1,2,3,4,5,6] +

chunk

+

The _.chunk function, by default, accepts an array and a number and splits and returns a new array representing the original array split into some number of arrays of the given size:

+
_.chunk([0,1,2,3], 2);
+//=> , [[0,1],[2,3]]
+

If the original array cannot completely fulfill the chunk scheme then the array returned will drop the undersized final chunk:

+
_.chunk([0,1,2,3,4], 2);
+//=> , [[0,1],[2,3]]
+

You can pass an optional third argument to _.chunk to pad out the final array chunk should it fall short. If the value given as the third argument is not an array then it is repeated the needed number of times:

+
_.chunk([0,1,2,3,4], 3, '_');
+//=> , [[0,1,2],[3,'_','_']]
+

If you given an array as the optional third argument then that array is used to pad in-place as needed:

+
_.chunk([0,1,2,3,4], 3, ['a', 'b']);
+//=> , [[0,1,2],[3,'a','b']]
+

chunkAll

+

The _.chunkAll function is similar to _.chunk except for the following. First, _.chunkAll will never drop short chunks from the end:

+
_.chunkAll([0,1,2,3,4], 3);
+//=> , [[0,1,2],[3]]
+

Also, _.chunkAll takes an optional third argument signifying that paritions should be built from skipped regions:

+
_.chunkAll(_.range(1), 2, 4);
+//=> [[0,1],[4,5],[8,9]]

cons

Signature: _.cons(head:Any, tail:Array)

The _.cons function provides a way to "construct" a new array by taking some element and putting it at the front of another array.

@@ -110,26 +130,6 @@

cons

f(1,2,3); //=> [0,1,2,3] -

partition

-

The _.partition function, by default, accepts an array and a number and splits and returns a new array representing the original array split into some number of arrays of the given size:

-
_.partition([0,1,2,3], 2);
-//=> , [[0,1],[2,3]]
-

If the original array cannot completely fulfill the partition scheme then the array returned will drop the undersized final partition:

-
_.partition([0,1,2,3,4], 2);
-//=> , [[0,1],[2,3]]
-

You can pass an optional third argument to _.partition to pad out the final array partition should it fall short. If the value given as the third argument is not an array then it is repeated the needed number of times:

-
_.partition([0,1,2,3,4], 3, '_');
-//=> , [[0,1,2],[3,'_','_']]
-

If you given an array as the optional third argument then that array is used to pad in-place as needed:

-
_.partition([0,1,2,3,4], 3, ['a', 'b']);
-//=> , [[0,1,2],[3,'a','b']]
-

partitionAll

-

The _.partitionAll function is similar to _.partition except for the following. First, _.partionAll will never drop short partitions from the end:

-
_.partitionAll([0,1,2,3,4], 3);
-//=> , [[0,1,2],[3]]
-

Also, _.paritionAll takes an optional third argument signifying that paritions should be built from skipped regions:

-
_.partitionAll(_.range(1), 2, 4);
-//=> [[0,1],[4,5],[8,9]]

mapcat

There are times when a mapping operation produces results contained in arrays, but the final result should be flattened one level. For these circumstances you can use _.mapcat to produce results:

var array = [1,2,null,4,undefined,6];
diff --git a/test/array.builders.js b/test/array.builders.js
index de72365..886f225 100644
--- a/test/array.builders.js
+++ b/test/array.builders.js
@@ -52,33 +52,33 @@ $(document).ready(function() {
     deepEqual(a, [1,2,3], 'should not modify the original tail');
   });
 
-  test("partition", function() {
+  test("chunk", function() {
     var a = _.range(4);
     var b = _.range(5);
     var c = _.range(7);
 
-    deepEqual(_.partition(a, 2), [[0,1],[2,3]], 'should partition into the size given');
-    deepEqual(_.partition(b, 2), [[0,1],[2,3]], 'should partition into the size given. Extras are dropped');
+    deepEqual(_.chunk(a, 2), [[0,1],[2,3]], 'should chunk into the size given');
+    deepEqual(_.chunk(b, 2), [[0,1],[2,3]], 'should chunk into the size given. Extras are dropped');
 
-    var result = _.partition(a, 2);
+    var result = _.chunk(a, 2);
     deepEqual(a, _.range(4), 'should not modify the original array');
 
-    deepEqual(_.partition(c, 3, [7,8]), [[0,1,2],[3,4,5],[6,7,8]], 'should allow one to specify a padding array');
-    deepEqual(_.partition(b, 3, 9), [[0,1,2],[3,4,9]], 'should allow one to specify a padding value');
+    deepEqual(_.chunk(c, 3, [7,8]), [[0,1,2],[3,4,5],[6,7,8]], 'should allow one to specify a padding array');
+    deepEqual(_.chunk(b, 3, 9), [[0,1,2],[3,4,9]], 'should allow one to specify a padding value');
   });
 
-  test("partitionAll", function() {
+  test("chunkAll", function() {
     var a = _.range(4);
     var b = _.range(10);
 
-    deepEqual(_.partitionAll(a, 2), [[0,1],[2,3]], 'should partition into the size given');
-    deepEqual(_.partitionAll(b, 4), [[0,1,2,3],[4,5,6,7],[8,9]], 'should partition into the size given, with a small end');
+    deepEqual(_.chunkAll(a, 2), [[0,1],[2,3]], 'should chunk into the size given');
+    deepEqual(_.chunkAll(b, 4), [[0,1,2,3],[4,5,6,7],[8,9]], 'should chunk into the size given, with a small end');
 
-    var result = _.partitionAll(a, 2);
+    var result = _.chunkAll(a, 2);
     deepEqual(a, _.range(4), 'should not modify the original array');
 
-    deepEqual(_.partitionAll(b, 2, 4), [[0,1],[4,5],[8,9]], 'should partition into the size given, with skips');
-    deepEqual(_.partitionAll(b, 3, 4), [[0,1,2],[4,5,6],[8,9]], 'should partition into the size given, with skips and a small end');
+    deepEqual(_.chunkAll(b, 2, 4), [[0,1],[4,5],[8,9]], 'should chunk into the size given, with skips');
+    deepEqual(_.chunkAll(b, 3, 4), [[0,1,2],[4,5,6],[8,9]], 'should chunk into the size given, with skips and a small end');
   });
 
   test("mapcat", function() {
diff --git a/underscore.array.builders.js b/underscore.array.builders.js
index a42163a..bf2a2e6 100644
--- a/underscore.array.builders.js
+++ b/underscore.array.builders.js
@@ -43,11 +43,11 @@
       return _.cat([head], tail);
     },
 
-    // Takes an array and parititions it some number of times into
+    // Takes an array and chunks it some number of times into
     // sub-arrays of size n.  Allows and optional padding array as
-    // the third argument to fill in the tail partition when n is
-    // not sufficient to build paritions of the same size.
-    partition: function(array, n, pad) {
+    // the third argument to fill in the tail chunk when n is
+    // not sufficient to build chunks of the same size.
+    chunk: function(array, n, pad) {
       var p = function(array) {
         if (array == null) return [];
 
@@ -64,11 +64,11 @@
       return p(array);
     },
 
-    // Takes an array and parititions it some number of times into
+    // Takes an array and chunks it some number of times into
     // sub-arrays of size n.  If the array given cannot fill the size
-    // needs of the final partition then a smaller partition is used
+    // needs of the final chunk then a smaller chunk is used
     // for the last.
-    partitionAll: function(array, n, step) {
+    chunkAll: function(array, n, step) {
       step = (step != null) ? step : n;
 
       var p = function(array, n, step) {