[Pkg-javascript-commits] [node-keese] 02/05: Imported Upstream version 1.1.1

[Andrew Kelley]

This is an automated email from the git hooks/post-receive script.

andrewrk-guest pushed a commit to branch master
in repository node-keese.

commit fef2795337cf72e35408ab82f28906b08a089693
Author: Andrew Kelley <superjoe30 at gmail.com>
Date:   Sat May 16 20:51:21 2015 +0000

    Imported Upstream version 1.1.1
---
 README.md    | 60 ++++++++++++++++++++++++++++++++++++++++++++++++++++++------
 index.js     | 33 ++++++++++++++++++++++++++++++++-
 package.json |  2 +-
 test.js      | 25 +++++++++++++++++++++++++
 4 files changed, 112 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index 4c12867..518de9d 100644
--- a/README.md
+++ b/README.md
@@ -20,20 +20,26 @@ var smaller = keese(null, something);
 var medium = keese(smaller, bigger);
 // smaller < medium < bigger
 // but no guarantee about middle vs something
+var values = keese(smaller, bigger, 10);
+// values is an array of 10 ascending items between smaller and bigger
 ```
 
 Formally:
 
 ```js
-var middle = keese(low, high);
+var middle = keese(low, high, count);
 ```
 
 Where:
-* `low` and `high` must each either be `== null` or be the result of a previous call to `keese`.
-* If `low` and `high` are both `== null`, then `middle` will be some arbitrary value to get you started.
-* If `low` is `!= null`, then `low` will be `< middle`.
-* If `high` is `!= null`, then `middle` will be `< high`.
-* If `low` and `high` are both `!= null`, then `low < middle < high` (so `low` must be `< high`).
+* `low` and `high` must each either be `== null` or be values from a previous call to `keese`.
+* `count` must be either `== null` or a non-negative integer (type `Number`).
+* If `count == null`:
+  * If `low != null`, then `low < middle`.
+  * If `high != null`, then `middle < high`.
+* If `count != null`, `middle` is an Array of size `count` values, and if `count > 0`:
+  * If `low != null`, then `low < middle[0]`.
+  * If `high != null`, then `middle[middle.length - 1] < high`.
+  * The values in `middle` are in ascending order (i.e. `middle.sort()` will have no effect).
 
 `keese` is a [pure function](http://en.wikipedia.org/wiki/Pure_function).
 
@@ -238,3 +244,45 @@ I believe it is provable that betweening cannot do any better than `O(n)`:
   Therefore, a value obtained through the algorithm above must encode a complete history of each decision.
 * Each of the `n` decisions must occupy a minimum of 1 bit of space in the string, therefore the size of the string is `O(n)`.
 
+
+The Count Parameter
+-------------------
+
+The naive way to generate `n` values at once would be:
+
+```js
+function generateValues(low, high, count) {
+  var result = [];
+  for (var i = 0; i < count; i++) {
+    var value = keese(low, high);
+    result.push(value);
+    low = value;
+  }
+  return result;
+}
+```
+
+This results in values with `O(count)` size (see discussion on algorithmic complexity above).
+A better algorithm would be to fill in an array using a binary-tree descent pattern:
+generate a value for the middle element of the array, and then recurse on each of the left and right remaining spaces.
+
+```js
+function generateValues(low, high, count) {
+  var result = new Array(count);
+  if (count > 0) recurse(low, high, 0, count);
+  return result;
+  function recurse(low_value, high_value, low_index, high_index) {
+    var mid_index = Math.floor((low_index + high_index) / 2);
+    var mid_value = single_keese(low_value, high_value);
+    result[mid_index] = mid_value;
+    if (low_index < mid_index) recurse(low_value, mid_value, low_index, mid_index);
+    if (mid_index + 1 < high_index) recurse(mid_value, high_value, mid_index + 1, high_index);
+  }
+}
+```
+
+This generates values with only `O(log(count))` size.
+This is the optimal algorithmic complexity for such a task.
+
+Since this algorithm is probably useful to many clients and a bit cumbersome to implement yourself,
+keese provides an implementation via the optional `count` parameter to `keese()`.
diff --git a/index.js b/index.js
index 5fdb4d3..7056c8b 100644
--- a/index.js
+++ b/index.js
@@ -14,7 +14,14 @@ var values = (function() {
 })();
 
 module.exports = keese;
-function keese(low, high) {
+function keese(low, high, count) {
+  if (count != null) {
+    return multi_keese(low, high, count);
+  } else {
+    return single_keese(low, high);
+  }
+}
+function single_keese(low, high) {
   if (low == null) {
     if (high == null) {
       // return anything above 0
@@ -33,6 +40,30 @@ function keese(low, high) {
     }
   }
 }
+function multi_keese(low, high, count) {
+  var result = new Array(count);
+  if (count > 0) {
+    if (high == null) {
+      // just allocate straight forward
+      for (var i = 0; i < count; i++) {
+        var value = keese(low, null);
+        result[i] = value;
+        low = value;
+      }
+    } else {
+      // binary tree descent
+      recurse(low, high, 0, count);
+    }
+  }
+  return result;
+  function recurse(low_value, high_value, low_index, high_index) {
+    var mid_index = Math.floor((low_index + high_index) / 2);
+    var mid_value = single_keese(low_value, high_value);
+    result[mid_index] = mid_value;
+    if (low_index < mid_index) recurse(low_value, mid_value, low_index, mid_index);
+    if (mid_index + 1 < high_index) recurse(mid_value, high_value, mid_index + 1, high_index);
+  }
+}
 
 function increment(value) {
   var n = parse(value);
diff --git a/package.json b/package.json
index 9d733f9..e80e289 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "keese",
-  "version": "1.0.4",
+  "version": "1.1.1",
   "description": "Generates arbitrary-precision, comparable values, appropriate for use as sorting keys",
   "main": "index.js",
   "scripts": {
diff --git a/test.js b/test.js
index 45fad54..80e6464 100644
--- a/test.js
+++ b/test.js
@@ -4,6 +4,7 @@ var assert = require('assert');
 
 basicTest();
 overflowTest();
+countTest();
 
 function basicTest() {
   var b = keese(null, null);
@@ -87,3 +88,27 @@ function overflowTest() {
   }
 }
 
+function countTest() {
+  var some_value = keese();
+  runTests(null, null);
+  runTests(some_value, null);
+  runTests(null, some_value);
+  runTests(some_value, keese(some_value));
+  function runTests(low, high) {
+    testSize(0);
+    testSize(1);
+    testSize(2);
+    testSize(3);
+    testSize(1000);
+    function testSize(size) {
+      var array = keese(low, high, size);
+      assert(array.length === size, "array size expected to be: " + size);
+      var previous = low;
+      array.forEach(function(item) {
+        if (previous != null) assert(previous < item, JSON.stringify(previous) + " < " + JSON.stringify(item));
+        previous = item;
+      });
+      if (previous != null && high != null) assert(previous < high, JSON.stringify(previous) + " < " + JSON.stringify(high));
+    }
+  }
+}

-- 
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-javascript/node-keese.git