@modules/utils@0.2.2

Built and signed on GitHub Actions

Built and signed on GitHub Actions

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364
/**
 * @module
 * This module provides functions for working with numbers.
 */

/**
 * @param n
 * @returns boolean indicating whether the number is even
 *
 * @example
 * ```ts
 * isEven(2); // true
 * isEven(3); // false
 * ```
 */
export function isEven(n: number): boolean {
  return n % 2 === 0;
}

/**
 * @param n
 * @returns boolean indicating whether the number is odd
 *
 * @example
 * ```ts
 * isOdd(2); // false
 * isOdd(3); // true
 * ```
 */
export function isOdd(n: number): boolean {
  return !isEven(n);
}

/**
 * @param n
 * @returns boolean indicating whether the number is positive
 *
 * @example
 * ```ts
 * isPositive(2); // true
 * isPositive(-3); // false
 * ```
 */
export function isPositive(n: number): boolean {
  return n > 0;
}

/**
 * @param n
 * @returns boolean indicating whether the number is negative
 *
 * @example
 * ```ts
 * isNegative(2); // false
 * isNegative(-3); // true
 * ```
 */
export function isNegative(n: number): boolean {
  return n < 0;
}

/**
 * @param n
 * @returns boolean indicating whether the number is zero
 *
 * @example
 * ```ts
 * isZero(0); // true
 * isZero(3); // false
 * ```
 */
export function isZero(n: number): boolean {
  return n === 0;
}

/**
 * @param numbers
 * @returns the largest of the given numbers
 *
 * @example
 * ```ts
 * max(2, 3, 4); // 4
 * max(2, 3, 4, 1); // 4
 * ```
 */
export function max(...numbers: number[]): number {
  return numbers.length ? Math.max(...numbers) : NaN;
}

/**
 * @param numbers
 * @returns the smallest of the given numbers
 *
 * @example
 * ```ts
 * min(2, 3, 4); // 2
 * min(2, 3, 4, 1); // 1
 * ```
 */
export function min(...numbers: number[]): number {
  return numbers.length ? Math.min(...numbers) : NaN;
}

/**
 * @param numbers
 * @returns the sum of the given numbers
 *
 * @example
 * ```ts
 * sum(2, 3, 4); // 9
 * sum(2, 3, 4, 1); // 10
 * ```
 */
export function sum(...numbers: number[]): number {
  return numbers.reduce((acc, n) => acc + n, 0);
}

/**
 * @param numbers
 * @returns the average of the given numbers
 *
 * @example
 * ```ts
 * average(2, 3, 4); // 3
 * average(2, 3, 4, 1); // 2.5
 * ```
 */
export function average(...numbers: number[]): number {
  return sum(...numbers) / numbers.length;
}

/**
 * @param numbers
 * @returns the median of the given numbers
 *
 * @example
 * ```ts
 * median(2, 3, 4); // 3
 * median(2, 3, 4, 1); // 2.5
 * ```
 */
export function median(...numbers: number[]): number {
  const sorted = numbers.sort((a, b) => a - b);
  const middle = Math.floor(sorted.length / 2);
  return isEven(sorted.length)
    ? average(sorted[middle - 1], sorted[middle])
    : sorted[middle];
}

/**
 * @param n
 * @returns the factorial of the given number
 *
 * @example
 * ```ts
 * factorial(5); // 120
 * factorial(0); // 1
 * ```
 */
export function factorial(n: number): number {
  return n < 0 ? NaN : n === 0 ? 1 : n * factorial(n - 1);
}

/**
 * @param n
 * @returns the fibonacci number at the given index
 *
 * @example
 * ```ts
 * fibonacci(5); // 5
 * fibonacci(0); // 0
 * ```
 */
export function fibonacci(n: number): number {
  return n < 0 ? NaN : n <= 1 ? n : fibonacci(n - 1) + fibonacci(n - 2);
}

/**
 * @param n
 * @returns boolean indicating whether the number is prime
 *
 * @example
 * ```ts
 * isPrime(2); // true
 * isPrime(4); // false
 * ```
 */
export function isPrime(n: number): boolean {
  if (n < 2) return false;
  for (let i = 2; i <= Math.sqrt(n); i++) {
    if (n % i === 0) return false;
  }
  return true;
}

/**
 * @param n
 * @returns boolean indicating whether the number is perfect
 *
 * @example
 * ```ts
 * isPerfect(6); // true
 * isPerfect(4); // false
 * ```
 */
export function isPerfect(n: number): boolean {
  return n === sum(...getDivisors(n));
}

/**
 * @param n
 * @returns the divisors of the given number
 *
 * @example
 * ```ts
 * getDivisors(6); // [1, 2, 3]
 * getDivisors(4); // [1, 2]
 * ```
 */
export function getDivisors(n: number): number[] {
  const divisors = [];
  for (let i = 1; i <= Math.floor(n / 2); i++) {
    if (n % i === 0) divisors.push(i);
  }
  return divisors;
}

/**
 * @param n
 * @returns the prime factors of the given number
 *
 * @example
 * ```ts
 * getPrimeFactors(6); // [2, 3]
 * getPrimeFactors(4); // [2, 2]
 * ```
 */
export function getPrimeFactors(n: number): number[] {
  const factors = [];
  for (let i = 2; i <= n; i++) {
    while (n % i === 0) {
      factors.push(i);
      n /= i;
    }
  }
  return factors;
}

/**
 * @param n
 * @returns the ordinal of the given number
 *
 * @example
 * ```ts
 * toOrdinal(1); // 1st
 * toOrdinal(2); // 2nd
 * ```
 */
export function toOrdinal(n: number): string {
  const suffixes = ["th", "st", "nd", "rd"];
  const v = n % 100;
  return n + (suffixes[(v - 20) % 10] || suffixes[v] || suffixes[0]);
}

/**
 * @param n
 * @returns the number in words
 *
 * @example
 * ```ts
 * toWords(123); // one two three
 * toWords(456); // four five six
 * ```
 */
export function toWords(n: number): string {
  const words = [
    "zero",
    "one",
    "two",
    "three",
    "four",
    "five",
    "six",
    "seven",
    "eight",
    "nine",
  ];
  return n.toString().split("").map((d) => words[parseInt(d)]).join(" ");
}

/**
 * @param min
 * @param max
 * @returns a random number between the given range
 *
 * @example
 * ```ts
 * random(1, 10); // 5.12342
 */
export function random(min = 0, max = 1): number {
  return Math.random() * (max - min) + min;
}

/**
 * @param min
 * @param max
 * @returns a random integer between the given range
 *
 * @example
 * ```ts
 * randomInt(1, 10); // 5
 */
export function randomInt(min = 0, max = 1): number {
  return Math.floor(random(min, max));
}

/**
 * @param n
 * @param m
 * @returns the modulo of the given numbers
 *
 * @example
 * ```ts
 * mod(5, 3); // 2
 * mod(-5, 3); // 1
 * ```
 */
export function mod(n: number, m: number): number {
  return ((n % m) + m) % m;
}

/**
 * @param n
 * @param minN
 * @param maxN
 * @returns the clamped number
 *
 * @example
 * ```ts
 * clamp(5, 1, 10); // 5
 * clamp(0, 1, 10); // 1
 * clamp(15, 1, 10); // 10
 * ```
 */
export function clamp(n: number, minN: number, maxN: number): number {
  return min(max(n, minN), maxN);
}

/**
 * @param n
 * @param start
 * @param end
 * @returns boolean indicating whether the number is in the range
 *
 * @example
 * ```ts
 * inRange(5, 1, 10); // true
 * inRange(0, 1, 10); // false
 * inRange(15, 1, 10); // false
 * ```
 */
export function inRange(n: number, start: number, end: number): boolean {
  return start <= n && n < end;
}