Source: helper.js

  1. /**
  2.  * @file Helper functions.
  3.  * @version March 26, 2017
  4.  *
  5.  * @author Olivier Pirson --- http://www.opimedia.be/
  6.  * @license GPLv3 --- Copyright (C) 2017 Olivier Pirson
  7.  */
  9. /**
  10.  * Returns true iff arrays are equal.
  11.  *
  12.  * @param {Array} arrayA
  13.  * @param {Array} arrayB
  14.  * @param {function} compareFct: function (a, b) --> number
  15.  *
  16.  * @returns {Boolean}
  17.  */
  18. function arrayIsEquals(arrayA, arrayB, compareFct=compare) {
  19.     assert(arrayA instanceof Array, arrayA);
  20.     assert(arrayB instanceof Array, arrayB);
  21.     assert(typeof compareFct === "function", compareFct);
  23.     if (arrayA.length !== arrayB.length) {
  24.         return false;
  25.     }
  26.     else {
  27.         for (let i = 0; i < arrayA.length; ++i) {
  28.             if (compareFct(arrayA[i], arrayB[i]) !== 0) {
  29.                 return false;
  30.             }
  31.         }
  33.         return true;
  34.     }
  35. }
  38. /**
  39.  * Remove from the array
  40.  * the first item equals to value according to compareFct.
  41.  *
  42.  * Returns true iff one item was removed.
  43.  *
  44.  * @param {Array} array
  45.  * @param value
  46.  * @param {function} compareFct: function (a, b) --> number
  47.  *
  48.  * @returns {Boolean}
  49.  */
  50. function arrayRemoveFirst(array, value, compareFct=compare) {
  51.     assert(array instanceof Array, array);
  52.     assert(typeof compareFct === "function", compareFct);
  54.     for (let i = 0; i < array.length; ++i) {
  55.         if (compareFct(value, array[i]) === 0) {
  56.             array.splice(i, 1);
  58.             return true;
  59.         }
  60.     }
  62.     return false;
  63. }
  66. /**
  67.  * Shuffle the array (in place)
  68.  * by Knuth algorithm.
  69.  *
  70.  * @param {Array} array
  71.  */
  72. function arrayShuffle(array) {
  73.     "use strict";
  75.     assert(array instanceof Array, array);
  77.     for (let i = 0; i < array.length; ++i) {
  78.         const j = getRandomInteger(0, array.length);
  79.         const tmp = array[i];
  81.         array[i] = array[j];
  82.         array[j] = tmp;
  83.     }
  84. }
  87. /**
  88.  * If a < 0 then return -1,
  89.  * if a = 0 then return  0,
  90.  * if a > 0 then return  1.
  91.  *
  92.  * @param a object that can be compared with <
  93.  * @param b object that can be compared with <
  94.  *
  95.  * @returns {integer} -1, 0, 1
  96.  */
  97. function compare(a, b) {
  98.     "use strict";
  100.     return (b < a
  101.             ? 1
  102.             : (a < b
  103.                ? -1
  104.                : 0));
  105. }
  108. /**
  109.  * Add the CSS class name to a HTML element (if doesn't exist yet).
  110.  *
  111.  * @param {HTMLElement} htmlElement
  112.  * @param {String} name !== ""
  113.  */
  114. function cssAddClass(htmlElement, name) {
  115.     "use strict";
  117.     assert(htmlElement instanceof HTMLElement, htmlElement);
  119.     assert(typeof name === "string", name);
  120.     assert(name !== "", name);
  122.     const classes = (typeof htmlElement.className === "string"
  123.                      ? htmlElement.className.split(/\s+/)
  124.                      : []);
  126.     for (let i = 0; i < classes.length; ++i) {
  127.         if (classes[i] === name) {
  128.             return;
  129.         }
  130.     }
  131.     classes.push(name);
  133.     htmlElement.className = classes.join(" ");
  134. }
  137. /**
  138.  * Returns true iff the HTML element has the CSS class name.
  139.  *
  140.  * @param {HTMLElement} htmlElement
  141.  * @param {String} name !== ""
  142.  *
  143.  * @returns {Boolean}
  144.  */
  145. function cssHasClass(htmlElement, name) {
  146.     "use strict";
  148.     assert(htmlElement instanceof HTMLElement, htmlElement);
  150.     assert(typeof name === "string", name);
  151.     assert(name !== "", name);
  153.     const classes = new Set(typeof htmlElement.className === "string"
  154.                             ? htmlElement.className.split(/\s+/)
  155.                             : []);
  157.     return classes.has(name);
  158. }
  161. /**
  162.  * If the HTML element has the CSS class name
  163.  * then remove it,
  164.  * else add it.
  165.  *
  166.  * @param {HTMLElement} htmlElement
  167.  * @param {String} name !== ""
  168.  */
  169. function cssInvertClass(htmlElement, name) {
  170.     "use strict";
  172.     assert(htmlElement instanceof HTMLElement, htmlElement);
  174.     assert(typeof name === "string", name);
  175.     assert(name !== "", name);
  177.     cssSetClass(htmlElement, name, !cssHasClass(htmlElement, name));
  178. }
  181. /**
  182.  * Remove the CSS class name to a HTML element (if exist).
  183.  *
  184.  * @param {HTMLElement} htmlElement
  185.  * @param {String} name !== ""
  186.  */
  187. function cssRemoveClass(htmlElement, name) {
  188.     "use strict";
  190.     assert(htmlElement instanceof HTMLElement, htmlElement);
  192.     assert(typeof name === "string", name);
  193.     assert(name !== "", name);
  195.     const classes = (typeof htmlElement.className === "string"
  196.                      ? htmlElement.className.split(/\s+/)
  197.                      : []);
  199.     for (let i = 0; i < classes.length; ++i) {
  200.         if (classes[i] === name) {
  201.             classes.splice(i, 1);
  202.         }
  203.     }
  205.     htmlElement.className = classes.join(" ");
  206. }
  209. /**
  210.  * Add or remove a CSS class to a HTML element.
  211.  *
  212.  * @param {HTMLElement} htmlElement
  213.  * @param {String} name !== ""
  214.  * @param {Boolean} add
  215.  */
  216. function cssSetClass(htmlElement, name, add) {
  217.     "use strict";
  219.     assert(htmlElement instanceof HTMLElement, htmlElement);
  221.     assert(typeof name === "string", name);
  222.     assert(name !== "", name);
  224.     assert(typeof add === "boolean", add);
  226.     if (add) {
  227.         cssAddClass(htmlElement, name);
  228.     }
  229.     else {
  230.         cssRemoveClass(htmlElement, name);
  231.     }
  232. }
  235. /**
  236.  * Returns a number between min (included) and max (excluded),
  237.  * choiced randomly.
  238.  *
  239.  * @param {Number} min
  240.  * @param {Number} max
  241.  *
  242.  * @returns {Number}
  243.  */
  244. function getRandom(min, max) {
  245.     "use strict";
  247.     assert(typeof min === "number", min);
  248.     assert(typeof max === "number", max);
  249.     assert(min < max, min, max);
  251.     return Math.random()*(max - min) + min;
  252. }
  255. /**
  256.  * Returns false or true,
  257.  * choiced randomly.
  258.  *
  259.  * @returns {Boolean}
  260.  */
  261. function getRandomBoolean() {
  262.     "use strict";
  264.     return (getRandomInt(0, 2) !== 0);
  265. }
  268. /**
  269.  * Returns a integer between min (included) and max (excluded),
  270.  * choiced randomly.
  271.  *
  272.  * @param {Number} min
  273.  * @param {Number} max
  274.  *
  275.  * @returns {integer}
  276.  */
  277. function getRandomInteger(min, max) {
  278.     "use strict";
  280.     assert(typeof min === "number", min);
  281.     assert(typeof max === "number", max);
  282.     assert(min < max, min, max);
  284.     return Math.floor(getRandom(min, max));
  285. }
  288. /**
  289.  * Returns true iff |x - y| <= max(|x|, |y|)*epsilon.
  290.  *
  291.  * Cf. "Relative epsilon comparisons" in
  292.  * https://randomascii.wordpress.com/2012/02/25/comparing-floating-point-numbers-2012-edition/
  293.  *
  294.  * @param {Number} x
  295.  * @param {Number} y
  296.  * @param {Number} epsilon >= 0
  297.  *
  298.  * @returns {Boolean}
  299.  */
  300. function isFloatAlmostEqual(x, y, epsilon=0.0001) {
  301.     assert(typeof x === "number", x);
  302.     assert(typeof y === "number", y);
  304.     assert(typeof epsilon === "number", epsilon);
  305.     assert(epsilon >= 0, epsilon);
  307.     return (Math.abs(x - y) <= Math.max(Math.abs(x), Math.abs(y)) * epsilon);
  308. }
  311. /**
  312.  * Returns true iff |x| <= epsilon.
  313.  *
  314.  * @param {Number} x
  315.  * @param {Number} epsilon >= 0
  316.  *
  317.  * @returns {Boolean}
  318.  */
  319. function isFloat0(x, epsilon=0.000001) {
  320.     assert(typeof x === "number", x);
  322.     assert(typeof epsilon === "number", epsilon);
  323.     assert(epsilon >= 0, epsilon);
  325.     return (Math.abs(x) <= epsilon);
  326. }
  329. /**
  330.  * Returns true iff |x - y| <= epsilon.
  331.  *
  332.  * @param {Number} x
  333.  * @param {Number} y
  334.  * @param {Number} epsilon >= 0
  335.  *
  336.  * @returns {Boolean}
  337.  */
  338. function isFloatEqual(x, y, epsilon=0.000001) {
  339.     assert(typeof x === "number", x);
  340.     assert(typeof y === "number", y);
  342.     assert(typeof epsilon === "number", epsilon);
  343.     assert(epsilon >= 0, epsilon);
  345.     return (Math.abs(x - y) <= epsilon);
  346. }
  349. /**
  350.  * Returns "s" if n >= 2
  351.  * else return "".
  352.  *
  353.  * @param {Number} n
  354.  *
  355.  * @returns {String}
  356.  */
  357. function s(n) {
  358.     "use strict";
  360.     return (n >= 2
  361.             ? "s"
  362.             : "");
  363. }
  366. /**
  367.  * Returns a new set union of setA and setB.
  368.  *
  369.  * @param {Set} setA
  370.  * @param {Set} setB
  371.  *
  372.  * @returns {Set}
  373.  */
  374. function setUnion(setA, setB) {
  375.     "use strict";
  377.     assert(setA instanceof Set, setA);
  378.     assert(setB instanceof Set, setB);
  380.     const union = new Set(setA);
  382.     for (let item of setB) {
  383.         union.add(item);
  384.     }
  386.     return union;
  387. }
  390. /**
  391.  * Returns the insertion point of the value in the array
  392.  * to maintain sorted order according to compareFct.
  393.  *
  394.  * Like
  395.  * https://docs.python.org/3/library/bisect.html#bisect.bisect_left
  396.  *
  397.  * @param {Array} sorted Array according to compareFct
  398.  * @param value
  399.  * @param {function} compareFct: function (a, b) --> boolean
  400.  *
  401.  * @returns {integer} 0 <= integer <= array.length
  402.  */
  403. function sortedArrayBisectionLeft(array, value, compareFct=compare) {
  404.     assert(array instanceof Array, array);
  405.     assert(typeof compareFct === "function", compareFct);
  407.     var first = 0;
  408.     var afterLast = array.length;
  409.     var middle;
  411.     while (first < afterLast) {
  412.         const middle = Math.floor((first + afterLast)/2);
  414.         if (compareFct(array[middle], value) < 0) {
  415.             first = middle + 1;
  416.         }
  417.         else {
  418.             afterLast = middle;
  419.         }
  420.     }
  422.     return first;
  423. }
  426. /**
  427.  * Returns the insertion point of the value in the array
  428.  * to maintain sorted order according to compareFct.
  429.  *
  430.  * Like
  431.  * https://docs.python.org/3/library/bisect.html#bisect.insort_left
  432.  *
  433.  * @param {Array} sorted Array according to compareFct
  434.  * @param value
  435.  * @param {function} compareFct: function (a, b) --> number
  436.  */
  437. function sortedArrayInsert(array, value, compareFct=compare) {
  438.     assert(array instanceof Array, array);
  439.     assert(typeof compareFct === "function", compareFct);
  441.     var first = 0;
  442.     var afterLast = array.length;
  443.     var middle;
  445.     while (first < afterLast) {
  446.         const middle = Math.floor((first + afterLast)/2);
  448.         if (compareFct(array[middle], value) < 0) {
  449.             first = middle + 1;
  450.         }
  451.         else {
  452.             afterLast = middle;
  453.         }
  454.     }
  456.     array.splice(first, 0, value);
  457. }
  460. /**
  461.  * Returns x in a string
  462.  * with left padding to have at least length characters.
  463.  *
  464.  * @param x
  465.  * @param {Number} length > 0
  466.  * @param {String} pad not empty
  467.  */
  468. function strPad(x, length, pad=" ") {
  469.     assert(typeof length === "number", length);
  470.     assert(length > 0, length);
  472.     assert(typeof pad === "string", pad);
  473.     assert(pad !== "");
  475.     x = x.toString();
  477.     if (x.length >= length) {
  478.         return x;
  479.     }
  480.     else {
  481.         const result = pad.repeat(Math.ceil((length - x.length)/pad.length)) + x;
  483.         return result;
  484.     }
  485. }