@colijnit/sharedcomponents 1.0.54 → 1.0.56

package/projects/sharedcomponents/src/lib/utils/number-utils.ts

@@ -0,0 +1,439 @@
+import {ObjectUtils} from "./object-utils";
+import {CheckWithinSteppedBoundsResult} from "./check-within-stepped-bounds-result";
+import {ArrayUtils} from "./array-utils";
+import {CheckPrecisionAndScaleResult} from "./check-precision-and-scale-result";
+import {isNill} from "./is-nill.function";
+import {notNill} from "./function/not-nill.function";
+
+// Static utility function holder related to numeric variable evaluations and operations.
+export class NumberUtils {
+    // For user-typed number input; supports comma's as decimal delimiter.
+    public static ParseIntNumberInput(arg: any): number {
+        return NumberUtils.ParseInt(NumberUtils._NumberInputToNumberStr(arg));
+    }
+
+    // Parses given argument to an integer, using a native parseInt() function with a radix of 10. Returns NaN if parsing was not possible.
+    public static ParseInt(arg: any): number {
+        if (isNill(arg) || Array.isArray(arg)) {
+            return undefined;
+        }
+
+        return parseInt(arg, 10);
+    }
+
+    // For user-typed number input; supports comma's as decimal delimiter.
+    public static ParseFloatNumberInput(arg: any, decimalPrecision: number = 2): number {
+        return NumberUtils.ParseFloat(NumberUtils._NumberInputToNumberStr(arg), decimalPrecision);
+    }
+
+    public static ParseFloatNumberInputKeepPrecision(arg: any): number {
+        const correctedInputStr: string = NumberUtils._NumberInputToNumberStr(arg);
+        const decimalPrecision: number = this.GetDecimalPlaces(correctedInputStr);
+        return NumberUtils.ParseFloat(correctedInputStr, decimalPrecision);
+    }
+
+    /**
+     * Returns given arg as a float number with given decimal precision, if possible. Returns NaN if parse conversion failed.
+     *
+     * @param {any} arg The argument to parse to a float
+     * @param {number} decimalPrecision The number of decimals, or the precision, the parsed return float should have
+     * @returns {number} NaN if not possible, else the parsed float value
+     */
+    public static ParseFloat(arg: any, decimalPrecision: number = 2): number {
+        if (!ObjectUtils.AllExist(arg, decimalPrecision) || Array.isArray(arg)) {
+            return NaN;
+        }
+
+        if (!NumberUtils.IsInteger(decimalPrecision) || decimalPrecision < 0) {
+            decimalPrecision = 2;
+            // toFixed() can only handle up until 20
+        } else if (decimalPrecision > 20) {
+            decimalPrecision = 20;
+        }
+
+        return parseFloat(parseFloat(arg).toFixed(decimalPrecision));
+    }
+
+    /**
+     * Returns given arg as a float number with given decimal precision, if possible. Returns NaN if parse conversion failed.
+     *
+     * @param arg The argument to parse to a float
+     * @returns {number} The argument as a float with its original decimal precision intact
+     */
+    public static ParseFloatKeepPrecision(arg: any): number {
+        const decimalPrecision: number = this.GetDecimalPlaces(arg);
+        return this.ParseFloat(arg, decimalPrecision);
+    }
+
+    /**
+     * Returns the given argument as a number. Returns given defaultValue if conversion of argument was impossible.
+     * @param arg
+     * @param {number} [defaultValue = 0]
+     * @returns {number}
+     */
+    public static ParseNumberOrDefault(arg: any, defaultValue: number = 0): number {
+        if (Array.isArray(arg)) {
+            return defaultValue;
+        }
+
+        if (!NumberUtils.IsNumber(arg)) {
+            arg = parseFloat(arg);
+            arg = isNaN(arg) ? defaultValue : arg;
+        }
+        return arg;
+    }
+
+    // Returns true iff given argument is an integer number. Returns false on non-numbers or numbers with significant decimals.
+    public static IsInteger(arg: any): boolean {
+        if (isNaN(arg) || Array.isArray(arg)) {
+            return false;
+        }
+        const argAsFloat: number = parseFloat(arg);
+        return ((argAsFloat | 0) === argAsFloat); // returns whether 'arg converted to an integer equals arg'
+    }
+
+    // Returns the number of decimal places of the given number. Returns 0 if no decimals whatsoever could be found on given arg.
+    public static GetDecimalPlaces(arg: any, maxAnswer: number = 1000): number {
+        const match: RegExpMatchArray = ("" + arg).match(/(?:\.(\d+))?(?:[eE]([+-]?\d+))?$/);
+        if (!match) {
+            return 0;
+        }
+
+        let answer: number = Math.max(0,
+            // number of digits right of decimal point.
+            (match[1] ? match[1].length : 0)
+            // adjust for scientific notation
+            - (match[2] ? +match[2] : 0));
+
+        if (answer > maxAnswer) {
+            answer = maxAnswer;
+        }
+
+        return answer;
+    }
+
+    // Parses given numberInput to a number, or returns given defaultValue if parse not possible. Allows ',' char as decimal delimiter.
+    public static ParseNumberInputOrDefault(numberInput: any, defaultValue: number = 0): number {
+        return NumberUtils.ParseNumberOrDefault(NumberUtils._NumberInputToNumberStr(numberInput), defaultValue);
+    }
+
+    // Returns whether the type of given argument is 'number'.
+    public static IsNumber(arg: any): boolean {
+        return typeof arg === "number" && !isNaN(arg);
+    }
+
+    /**
+     * Returns whether given arg is indeed not a number (it's NaN or it has another type than 'number')
+     * Our exact copy of AS Flex'es isNaN(arg) function. Always use this method for copying Flex isNaN(..) occurences into TypeScript.
+     * @param arg
+     * @returns {boolean}
+     * @constructor
+     */
+    public static IsNaN(arg: any): boolean {
+        return isNaN(arg) || !NumberUtils.IsNumber(arg);
+    }
+
+    // Our copy of CoMath.NaN. Returns number, or substitute if NumberUtils.IsNaN(number) holds true.
+    public static NaN(number: any, substitute: number = 0): number {
+        return NumberUtils.IsNaN(number) ? substitute : number;
+    }
+
+    // Returns whether the value is parasable as a number.
+    public static IsParsableNumber(arg: any): boolean {
+        if (Array.isArray(arg)) {
+            return false;
+        }
+
+        return !isNaN(parseFloat(arg));
+    }
+
+    public static IsParsableNumberInput(numberInput: any): boolean {
+        return NumberUtils.IsParsableNumber(NumberUtils._NumberInputToNumberStr(numberInput));
+    }
+
+    /**
+     * Returns whether given arg is parseable as a number, and whether the lengts of its number parse result is equal to its original length.
+     * I.e. this function returns FALSE with given number-parsable strings, but that have non-numeric appendices, eg '2233ff'. That arg
+     * IS number-parseable, but not a strict 'string number', the latter being what this method actually checks for.
+     */
+    public static IsStringNumber(arg: string): boolean {
+        if (!NumberUtils.IsParsableNumber(arg)) {
+            return false;
+        } else {
+            return arg.toString().length === parseFloat(arg).toString().length;
+        }
+    }
+
+    public static IsListOfNumbers(arg: string, separator: string = ","): boolean {
+        const nrs: string[] = arg.split(separator);
+        if (nrs.length === 0) {
+            return false;
+        }
+        return nrs.filter(s => NumberUtils.IsStringNumber(s)).length === nrs.length;
+    }
+
+    // Returns given argument as a string representation of a number parse, e.g. "1" for a number parse result of arg to 1.
+    public static ParseStringNumber(arg: string): number {
+        if (!this.IsStringNumber(arg)) {
+            return NaN;
+        }
+
+        return NumberUtils.ParseFloatKeepPrecision(arg);
+    }
+
+    public static ParseStringNumberDefault(arg: string | any, defaultValue: number = 0): number {
+        return NumberUtils.NaN(NumberUtils.ParseStringNumber(arg), defaultValue);
+    }
+
+    /**
+     * Returns a random integer in range [lowerBound .. upperBound], an inclusive range. Returns NaN if not possible.
+     * Given bounds are truncated first, before serving as the true lower- and upper bounds for the random int.
+     */
+    public static RandomInt(lowerBoundInt: number, upperBoundInt: number): number {
+        if (!NumberUtils.IsNumber(lowerBoundInt) || !NumberUtils.IsNumber(upperBoundInt) || lowerBoundInt > upperBoundInt) {
+            return NaN;
+        }
+
+        lowerBoundInt = Math.trunc(lowerBoundInt);
+        upperBoundInt = Math.trunc(upperBoundInt);
+
+        if (lowerBoundInt === upperBoundInt) {
+            return lowerBoundInt;
+        }
+
+        const delta: number = upperBoundInt - lowerBoundInt;
+        return (Math.round(Math.random() * delta) + lowerBoundInt);
+    }
+
+    // Adds thousands comma's to given value, E.g. '1000' to '1,000'. Returns empty string if value was undefined.
+    public static AddThousandsCommasTo(value: any): string {
+        if (isNill(value)) {
+            return "";
+        }
+
+        return value.toString().replace(/\B(?=(\d{3})+(?!\d))/g, ",");
+    }
+
+    /**
+     * Function used to check wether a given number is composed of another number, power-of-two wise.
+     * Example usage: NumberUtils.NumIsComposedOf(articleListObject.publication, ArticlePublication.Selector).
+     * This would return whether or not that articleListObject was publicated for selector or not, where articleListObject.publication
+     * was possibly a 'COMPOSITE that was made out of (including)' ArticlePublication.Selector.
+     */
+    public static NumIsComposedOfOtherPowTwoNum(bigNrToCheck: number, powTwoNumItShouldBeComposedOf: number): boolean {
+        if (!bigNrToCheck) {
+            return false;
+        } else if (!powTwoNumItShouldBeComposedOf) {
+            return true;
+        } else {
+            return ((bigNrToCheck & powTwoNumItShouldBeComposedOf) === powTwoNumItShouldBeComposedOf);
+        }
+    }
+
+    /**
+     * Returns given nr, or the given default number (default 0) if the nr number was undefined or otherwise not a number.
+     * Same as CoMath.NaN from AS code (used as its substitute in transaction logic)
+     * @param nr
+     * @param defaultNr
+     * @returns {number}
+     */
+    public static NrOrDefault(nr: number, defaultNr: number = 0): number {
+        if (notNill(nr) && NumberUtils.IsNumber(nr)) {
+            return nr;
+        } else {
+            return defaultNr;
+        }
+    }
+
+    /**
+     * Returns whether given nrToCheck is within the given precision and scale limits. Precision and scale, here, are Oracle DB terms.
+     * This function can thus be used to check whether the given number is safe to send to the 'database' beforehand, if we know the
+     * precision and scale of the number in the db declaration.
+     *
+     * I.e. A number declared in the Oracle DB as number(5, 2) has a precision of 5 and a scale of 2.
+     *
+     * @param {number} nrToCheck
+     * @param {number} precision The number of significant digits, including possibly negative scale. E.g. 3 in '123' and 5 in '51.123'
+     * @param {number} [scale = 0] The number of significant digits AFTER the decimal point. E.g. 1 in 5432.1 and 3 in 54000.003
+     * @returns {CheckPrecisionAndScaleResult} Whether given nrToCheck is ok for given precision and scale, and if not, the
+     * nearest number that IS ok for those constraints.
+     */
+    public static CheckPrecisionAndScale(nrToCheck: number, precision: number, scale: number = 0): CheckPrecisionAndScaleResult {
+        // let's say any undefined number is checked OK, and all numbers are checked OK for an undefined precision
+        if (!ObjectUtils.AllExist(nrToCheck, precision, scale)) {
+            return {isOk: true, nearestOkNr: NaN};
+        }
+        // no number can have 0 or less than 0 significant digits, in our universe
+        if (precision < 1 || precision - scale < 1) {
+            return {isOk: false, nearestOkNr: NaN};
+        }
+        // begin check
+        const isNegative: boolean = (nrToCheck < 0);
+        const nrParts: string[] = nrToCheck.toString().split(".");
+        // remove minus sign if negative
+        if (isNegative) {
+            nrParts[0] = nrParts[0].slice(1);
+        }
+        const numCountBeforeDot: number = nrParts[0].length;
+        const allowedNumCountBeforeDot: number = precision - scale;
+        if (numCountBeforeDot <= allowedNumCountBeforeDot) {
+            return {isOk: true, nearestOkNr: nrToCheck};
+        } else {
+            // cut a part from the "before decimal number" so that the number is not too big anymore
+            const numCountToRemove: number = numCountBeforeDot - allowedNumCountBeforeDot;
+            // remove the right-most numbers before the decimal dot
+            nrParts[0] = nrParts[0].slice(0, -1 * numCountToRemove);
+            // add minus sign again if it was negative
+            if (isNegative) {
+                nrParts[0] = "-" + nrParts[0];
+            }
+            // build and return composite number again
+            let nearestOkNr: number;
+            if (nrParts[1]) {
+                nearestOkNr = Number(nrParts[0] + "." + nrParts[1]);
+            } else {
+                nearestOkNr = Number(nrParts[0]);
+            }
+            return {isOk: false, nearestOkNr: nearestOkNr};
+        }
+    }
+
+    /**
+     * Returns whether given x is OK within the given min, max and step boundaries, where it should hold that nrToCheck = min + N * step,
+     * with N integer or 0.
+     * @param {number} nrToCheck Number to check whether it's within the given bounds
+     * @param min Inclusive
+     * @param max Inclusive
+     * @param stepSize
+     * @returns {CheckWithinSteppedBounds} Returns remainder of undefined when nrToCheck was OUTSIDE [min, max], else full result object.
+     */
+    public static CheckWithinSteppedBounds(
+        nrToCheck: number,
+        min: number,
+        max: number,
+        stepSize: number = 1
+    ): CheckWithinSteppedBoundsResult {
+        if (nrToCheck < min || nrToCheck > max) {
+            return {isOk: false, remainder: undefined};
+        }
+
+        // we're in [min, max], but still check if nrToCheck = min + N * step holds (for N integer or 0)
+        let remainder: number = (nrToCheck - min) % stepSize;
+        // correct float for largest precision amongst input numbers
+        remainder = NumberUtils.ParseFloat(remainder, NumberUtils._GetLargestDecimalPrecisionOf(nrToCheck, min, stepSize));
+        return {isOk: (remainder === 0), remainder: remainder};
+    }
+
+    /**
+     * Finds the number closest to the originalNumber, that adheres to the given bounds. That is, for which it holds that
+     * nr = min + N * step with N integer or 0.
+     * @param {number} originalNr Find closest answer to this number
+     * @param min Inclusive
+     * @param max Inclusive
+     * @param stepSize
+     * @returns {boolean} The closest OK number for bounds.
+     */
+    public static GetNearestNumberWithinSteppedBounds(originalNr: number, min: number, max: number, stepSize: number = 1): number {
+        if (originalNr < min) {
+            return min;
+        } else if (originalNr > max) {
+            return NumberUtils.GetTrueSteppedBoundsMax(min, max, stepSize);
+        }
+
+        const boundsCheck: CheckWithinSteppedBoundsResult = NumberUtils.CheckWithinSteppedBounds(originalNr, min, max, stepSize);
+        if (boundsCheck.isOk) {
+            return originalNr;
+        }
+
+        let answer: number;
+
+        const remainder: number = boundsCheck.remainder;
+        if (remainder) {
+            // round up or down?
+            if ((remainder / stepSize) < 0.5) {
+                //  round down, but not below min
+                answer = (originalNr - remainder >= min ? originalNr - remainder : min);
+            } else {
+                // round up, but not above max
+                answer = (originalNr + stepSize - remainder <= max ? originalNr + stepSize - remainder :
+                    NumberUtils.GetTrueSteppedBoundsMax(min, max, stepSize));
+            }
+        } else {
+            // is this real life, why wasn't our stepped bounds check OK?
+            answer = originalNr;
+        }
+
+        // 'correct' float errors
+        answer = NumberUtils.ParseFloat(answer, NumberUtils._GetLargestDecimalPrecisionOf(originalNr, min, max, stepSize));
+        return answer;
+    }
+
+    /**
+     * Returns the true maximum allowed value for the given "stepped bounds": min, stepSize and max, for which it holds that each allowed
+     * value Y = min + stepSize * N, for any INTEGER or 0 N where it also holds, of course, that Y <= max.
+     * @param min
+     * @param max
+     * @param stepSize
+     */
+    public static GetTrueSteppedBoundsMax(min: number, max: number, stepSize: number = 1): number {
+        // solve max integer X in formula min + X * step <= max, and return min + X * stepSize for that X
+        const maxSteps: number = Math.floor((max - min) / stepSize);
+        // 'correct' float errors
+        return NumberUtils.ParseFloat(min + maxSteps * stepSize, NumberUtils._GetLargestDecimalPrecisionOf(min, min, max));
+    }
+
+    // Returns the nearest number, relative to the given originalNr, that is within the given [min, max] inclusive bounds.
+    public static GetNearestNumberWithinBounds(originalNr: number, min: number, max: number): number {
+        let answer: number = originalNr;
+
+        if (originalNr < min) {
+            answer = min;
+        } else if (originalNr > max) {
+            answer = max;
+        }
+
+        return answer;
+    }
+
+    // Returns the string representation of given number. If it's not a number, returns the empty string.
+    public static ToString(nr: number): string {
+        if (!NumberUtils.IsNaN(nr)) {
+            return "" + nr;
+        } else {
+            return "";
+        }
+    }
+
+    public static DecimalsToStepIncrement(numberOfDecimals: number): number {
+        return Math.pow(10, -1 * numberOfDecimals);
+    }
+
+    public static Round(value: number, decimals: number): number {
+        const factor: number = Math.pow(10, decimals);
+        return Math.round(value * factor) / factor;
+    }
+
+    // @returns The inclusive max value
+    public static PrecisionScaleToMaxValue(precision: number, scale: number): number {
+        const oneStep: number = this.DecimalsToStepIncrement(scale);
+        const maxExclusive: number = Math.pow(10, precision - scale);
+        return maxExclusive - oneStep;
+    }
+
+    // @returns the difference between given 2 numbers
+    public static DifferenceBetweenNumbers(numberA: number, numberB: number): number {
+        return Math.abs(numberA - numberB);
+    }
+
+    private static _GetLargestDecimalPrecisionOf(...args: number[]): number {
+        const result = ArrayUtils.GetMaxCalculatedValue(args, (arg: number) => {
+            return NumberUtils.GetDecimalPlaces(arg);
+        });
+        return result;
+    }
+
+    // Returns given number input as a number that's useable by Javascript. Allows for incoming ',' decimal delimiter.
+    private static _NumberInputToNumberStr(numberInput: string): string {
+        return (numberInput + "").replace(",", ".");
+    }
+}