Number API

clamp Clamp

Clamps a number to a closed interval.

Signature

export function clamp(value: number, minimum: number, maximum: number): number;

Example

import { clamp } from "@fast-china/utils";

const result = clamp(1, 1, 10);
console.log(result); // 1

Input

Input	Type	Required / default	Description
value	number	Required	Number to clamp.
minimum	number	Required	Inclusive lower bound.
maximum	number	Required	Inclusive upper bound.

Returns

Value	Type	Description
result	number	Value satisfying minimum <= result <= maximum.

inRange Range

Checks whether a number lies within an interval.

Signature

export function inRange(value: number, minimum: number, maximum: number, includeMaximum = false): boolean;

Example

import { inRange } from "@fast-china/utils";

const result = inRange(1, 1, 10, false);
console.log(result); // true

Input

Input	Type	Required / default	Description
value	number	Required	Number to check.
minimum	number	Required	Inclusive lower bound.
maximum	number	Required	Upper bound.
includeMaximum	unknown	Optional; defaults to false	Whether the upper bound is inclusive; defaults to the half-open interval [minimum, maximum).

Returns

Value	Type	Description
result	boolean	true when the number satisfies the interval bounds.

roundTo Round

Rounds to a decimal precision.

Signature

export function roundTo(value: number, digits = 0): number;

Example

import { roundTo } from "@fast-china/utils";

const result = roundTo(1, 0);
console.log(result); // 1

Input

Input	Type	Required / default	Description
value	number	Required	Finite number.
digits	unknown	Optional; defaults to 0	Decimal places from -15 to 15; negative values mean tens, hundreds, and so on.

Returns

Value	Type	Description
result	number	Number rounded using Math.round semantics.

sum Sum

Sums finite numbers.

Signature

export function sum(values: readonly number[]): number;

Example

import { sum } from "@fast-china/utils";

const result = sum([1, 2, 3]);
console.log(result); // 6

Input

Input	Type	Required / default	Description
values	readonly number[]	Required	Number array; not mutated.

Returns

Value	Type	Description
result	number	Arithmetic sum; empty input returns 0.

average Average

Calculates the arithmetic mean of finite numbers.

Signature

export function average(values: readonly number[]): number | undefined;

Example

import { average } from "@fast-china/utils";

const result = average([1, 2, 3]);
console.log(result); // 2

Input

Input	Type	Required / default	Description
values	readonly number[]	Required	Number array; not mutated.

Returns

Value	Type	Description
result	number | undefined	Empty arrays or arrays containing only holes return undefined; holes do not contribute to the denominator.

lerp Interpolate

Linearly interpolates between two numbers.

Signature

export function lerp(start: number, end: number, amount: number): number;

Example

import { lerp } from "@fast-china/utils";

const result = lerp(0, 10, 1);

Input

Input	Type	Required / default	Description
start	number	Required	Start at amount = 0.
end	number	Required	End at amount = 1.
amount	number	Required	Interpolation or extrapolation ratio.

Returns

Value	Type	Description
result	number	Linear result.

formatBytes Format

Nonnegative fractional byte counts are supported: formatBytes(0.5) returns "0.5 B", not a larger unit.

Formats nonnegative byte counts using SI or IEC units.

Signature

export function formatBytes(bytes: number, options: FormatBytesOptions = {}): string;

Example

import { formatBytes } from "@fast-china/utils";

const result = formatBytes(1_536, { base: 1024, decimals: 1 });

Input

Input	Type	Required / default	Description
bytes	number	Required	Nonnegative finite byte count.
options	FormatBytesOptions	Optional; defaults to {}	Base, decimal precision, and locale options.

Returns

Value	Type	Description
result	string	For example, 1.5 KiB.

randomInt Random

Generates a random integer in a half-open interval.

Signature

export function randomInt(minimum: number, maximumExclusive: number): number;

Example

import { randomInt } from "@fast-china/utils";

const result = randomInt(1, 10);

Input

Input	Type	Required / default	Description
minimum	number	Required	Inclusive safe-integer lower bound.
maximumExclusive	number	Required	Exclusive safe-integer upper bound; interval width is at most 2^32.

Returns

Value	Type	Description
result	number	Random integer in [minimum, maximumExclusive).