Add d3.permute.

Makefile

@@ -41,6 +41,7 @@ d3.core.js: \
 	src/core/keys.js \
 	src/core/values.js \
 	src/core/entries.js \
+	src/core/permute.js \
 	src/core/merge.js \
 	src/core/split.js \
 	src/core/collapse.js \
@@ -161,6 +162,7 @@ tests: \
 	tests/test-interpolate.test \
 	tests/test-keys.test \
 	tests/test-nest.test \
+	tests/test-permute.test \
 	tests/test-remove.test \
 	tests/test-rgb.test \
 	tests/test-hsl.test \

d3.js

@@ -168,6 +168,13 @@ d3.entries = function(map) {
   for (var key in map) entries.push({key: key, value: map[key]});
   return entries;
 };
+d3.permute = function(array, indexes) {
+  var permutes = [],
+      i = -1,
+      n = indexes.length;
+  while (++i < n) permutes[i] = array[indexes[i]];
+  return permutes;
+};
 d3.merge = function(arrays) {
   return Array.prototype.concat.apply([], arrays);
 };

src/core/permute.js

@@ -0,0 +1,7 @@
+d3.permute = function(array, indexes) {
+  var permutes = [],
+      i = -1,
+      n = indexes.length;
+  while (++i < n) permutes[i] = array[indexes[i]];
+  return permutes;
+};

tests/test-permute.js

@@ -0,0 +1,38 @@
+require("./../lib/env-js/envjs/node");
+require("./../d3");
+
+var array = [0,1,2];
+
+console.log("permute reverses:");
+console.log("    2,1,0:", d3.permute(array, [2,1,0]) + "");
+console.log("");
+
+console.log("permute does not modify input array:");
+console.log("    0,1,2:", array + "");
+console.log("");
+
+console.log("permute does nothing:");
+console.log("    0,1,2:", d3.permute(array, [0,1,2]) + "");
+console.log("");
+
+console.log("permute duplicates:");
+console.log("    0,0,0:", d3.permute(array, [0,0,0]) + "");
+console.log("");
+
+console.log("permute returns fewer elements:");
+console.log("      2,1:", d3.permute(array, [2,1]) + "");
+console.log("        1:", d3.permute(array, [1]) + "");
+console.log("        0:", d3.permute(array, [0]) + "");
+console.log("         :", d3.permute(array, []) + "");
+console.log("");
+
+console.log("permute returns undefined elements:");
+console.log("       10:", d3.permute(array, [10]) + "");
+console.log("       -1:", d3.permute(array, [-1]) + "");
+console.log("     0,-1:", d3.permute(array, [0,-1]) + "");
+console.log("");
+
+console.log("permute returns more elements:");
+console.log("  0,0,1,2:", d3.permute(array, [0,0,1,2]) + "");
+console.log("  0,1,1,1:", d3.permute(array, [0,1,1,1]) + "");
+console.log("");

tests/test-permute.out

@@ -0,0 +1,27 @@
+permute reverses:
+    2,1,0: 2,1,0
+
+permute does not modify input array:
+    0,1,2: 0,1,2
+
+permute does nothing:
+    0,1,2: 0,1,2
+
+permute duplicates:
+    0,0,0: 0,0,0
+
+permute returns fewer elements:
+      2,1: 2,1
+        1: 1
+        0: 0
+         : 
+
+permute returns undefined elements:
+       10: 
+       -1: 
+     0,-1: 0,
+
+permute returns more elements:
+  0,0,1,2: 0,0,1,2
+  0,1,1,1: 0,1,1,1
+