updated xor128

Author: lorossi

README.md

@@ -8,7 +8,8 @@ Just clone the repo or download the last release.
 
 ## Cool. Do you have some documentation?
 
-[Yes, here.](https://lorossi.github.io/empty-html5-canvas-project/).
+[Yes, here](https://lorossi.github.io/empty-html5-canvas-project/).
+Documentation for the XOR128 random number generator is [here](https://lorossi.github.io/js-XOR128).
 
 Don't have time for that?
 Keep reading for the short version.

js/xor128.js

@@ -1,6 +1,6 @@
 /**
  * XOR128 js implementation
- * @version 1.0.0
+ * @version 1.1.0
  * @author Lorenzo Rossi - https://www.lorenzoros.si - https://github.com/lorossi/
  * @license MIT
  */
@@ -12,17 +12,47 @@ class XOR128 {
    * All parameters are optional, if nothing is passed a random value from
    *  js functions Math.random() will be used
    *
-   * @param {number} [x] first seed
+   * @param {number|Array} [x] first seed or array of seeds. \
+   *  If an array is passed, the first 4 elements will be used as seeds
    * @param {number} [y] second seed
    * @param {number} [z] third seed
    * @param {number} [w] fourth seed
    * @returns {XOR128}
    */
   constructor(x = null, y = null, z = null, w = null) {
-    if (x == null || x == undefined) x = Math.floor(Math.random() * 4294967296);
-    if (y == null || x == undefined) y = Math.floor(Math.random() * 4294967296);
-    if (z == null || x == undefined) z = Math.floor(Math.random() * 4294967296);
-    if (w == null || x == undefined) w = Math.floor(Math.random() * 4294967296);
+    if (x instanceof Array) {
+      if (x.length > 4) throw new Error("XOR128: too many seeds");
+
+      for (let i = x.length; i < 4; i++) x.push(x[i - 1] + 1);
+
+      return new XOR128(x[0], x[1], x[2], x[3]);
+    }
+
+    if (x == null) x = Math.floor(Math.random() * 4294967296);
+
+    if (y == null) {
+      if (x != null) {
+        y = x + 1;
+      } else {
+        y = Math.floor(Math.random() * 4294967296);
+      }
+    }
+
+    if (z == null) {
+      if (y != null) {
+        z = y + 1;
+      } else {
+        z = Math.floor(Math.random() * 4294967296);
+      }
+    }
+
+    if (w == null) {
+      if (z != null) {
+        w = z + 1;
+      } else {
+        w = Math.floor(Math.random() * 4294967296);
+      }
+    }
 
     if (
       typeof x !== "number" ||
@@ -35,6 +65,8 @@ class XOR128 {
     if (x < 1 || y < 1 || z < 1 || w < 1)
       throw new Error("XOR128: seed values must be greater than 0");
 
+    if (arguments.length > 4) throw new Error("XOR128: too many arguments");
+
     this._x = x;
     this._y = y;
     this._z = z;
@@ -59,6 +91,12 @@ class XOR128 {
       a = 0;
     }
 
+    if (a > b)
+      throw new Error("XOR128: first parameter must be smaller than second");
+
+    if (!(typeof a === "number" && typeof b === "number"))
+      throw new Error("XOR128: parameters must be numbers");
+
     const t = this._x ^ ((this._x << 11) >>> 0);
 
     this._x = this._y;
@@ -87,7 +125,34 @@ class XOR128 {
       a = 0;
     }
 
-    return Math.floor(this.random(a, b + 1));
+    return Math.floor(this.random(a, b));
+  }
+
+  /**
+   * Returns a random boolean
+   *
+   * @returns {Boolean} random boolean
+   */
+  random_bool() {
+    return this.random() > 0.5;
+  }
+
+  /**
+   * Returns a random string
+   *
+   * @param {number} [length=10] length of the string
+   * @param {string} [chars="ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789"] characters to use
+   */
+  random_string(
+    length = 10,
+    chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789"
+  ) {
+    let str = "";
+
+    for (let i = 0; i < length; i++)
+      str += chars[this.random_int(0, chars.length)];
+
+    return str;
   }
 
   /**
@@ -110,16 +175,43 @@ class XOR128 {
    * @returns {any} item from input array
    */
   random_from_array(arr) {
+    if (!(arr instanceof Array))
+      throw new Error("XOR128: parameter must be an array");
+
     return arr[this.random_int(0, arr.length)];
   }
 
   /**
-   * Shuffles the provided array without returning it (the original array gets shuffled)
+   * Returns a random char from the provided string
+   *
+   * @param {string} str a string
+   * @returns {string} char from input string
+   */
+  random_from_string(str) {
+    if (typeof str !== "string")
+      throw new Error("XOR128: parameter must be a string");
+
+    return str.charAt(this.random_int(0, str.length));
+  }
+
+  /**
+   * Returns a random item from the provided array or a random char from the provided string
+   *
+   * @returns {any} item from input array or char from input string
+   */
+  pick(x) {
+    if (x instanceof Array) return this.random_from_array(x);
+    else if (typeof x === "string") return this.random_from_string(x);
+    else throw new Error("XOR128: parameter must be an array or a string");
+  }
+
+  /**
+   * Shuffles the provided array (the original array does not get shuffled)
    *
    * @param {Array} arr an array
    */
   shuffle_array(arr) {
-    return arr
+    return [...arr]
       .map((s) => ({ sort: this.random(), value: s }))
       .sort((a, b) => a.sort - b.sort)
       .map((a) => a.value);
@@ -139,4 +231,17 @@ class XOR128 {
       .map((a) => a.value)
       .join("");
   }
+
+  /**
+   * Shuffles and returns an array or a string.
+   *
+   * @param {Array|String} x an array or a string
+   * @returns {any} shuffled array or string
+   */
+  shuffle(x) {
+    if (x instanceof Array) return this.shuffle_array(x);
+    if (typeof x === "string") return this.shuffle_string(x);
+
+    throw new Error("XOR128: parameter must be an array or a string");
+  }
 }