Variable SafeInt

Type Declaration

• abs: (x: WithSmallInt) => IntersectBrand<SafeInt>

  Returns the absolute value of a safe integer.

  The result is non-negative and keeps the SafeInt brand.

  Example

  const negative = asSafeInt(-900);
  
  const absolute = SafeInt.abs(negative);
  
  assert.isTrue(absolute === 900);
  
  assert.isTrue(SafeInt.is(absolute));
  Copy

• add: (x: WithSmallInt, y: WithSmallInt) => SafeInt

  Adds two safe integers, returning a + b as a SafeInt.

  Example

  const sum = SafeInt.add(asSafeInt(9), asSafeInt(4));
  
  assert.isTrue(sum === 13);
  
  assert.isTrue(SafeInt.is(sum));
  Copy

• div: (x: WithSmallInt, y: ToNonZeroIntWithSmallInt<SafeInt>) => SafeInt

  Divides two safe integers using floor division (⌊a / b⌋): the result is a / b rounded toward negative infinity, as a SafeInt.

  Example

  const quotient = SafeInt.div(asSafeInt(-17), asSafeInt(5));
  
  assert.isTrue(quotient === -4);
  
  assert.isTrue(SafeInt.is(quotient));
  Copy

• fromNumber: (x: number) => SafeInt

  Converts an arbitrary number into a SafeInt, rounding to the nearest integer and saturating the result into the range [MIN_VALUE, MAX_VALUE].

  Unlike asSafeInt, this is total: out-of-range inputs are clamped to the nearest representable SafeInt instead of throwing.

  Example

  const aboveRange = SafeInt.fromNumber(1e20);
  
  const withinRange = SafeInt.fromNumber(123);
  
  const belowRange = SafeInt.fromNumber(-1e20);
  
  assert.isTrue(aboveRange === Number.MAX_SAFE_INTEGER);
  
  assert.isTrue(withinRange === 123);
  
  assert.isTrue(belowRange === Number.MIN_SAFE_INTEGER);
  Copy

• is: (a: number) => a is SafeInt

  Type guard that checks if a value is a safe integer.

  Example

  assert.isTrue(isSafeInt(Number.MAX_SAFE_INTEGER));
  
  assert.isFalse(isSafeInt(Number.MAX_SAFE_INTEGER + 0.5));
  
  assert.isTrue(SafeInt.is(Number.MIN_SAFE_INTEGER));
  Copy

  See

  isSafeInt for usage examples

• Readonlymax: (...values: readonly WithSmallInt<SafeInt>[]) => SafeInt

  Returns the largest of the given safe integers.

  Example

  const largest = SafeInt.max(asSafeInt(25), asSafeInt(-14), asSafeInt(99));
  
  assert.isTrue(largest === 99);
  Copy

• MAX_VALUE: SafeUint

  The largest value representable as SafeInt (the upper saturation target of fromNumber).

• Readonlymin: (...values: readonly WithSmallInt<SafeInt>[]) => SafeInt

  Returns the smallest of the given safe integers.

  Example

  const smallest = SafeInt.min(asSafeInt(25), asSafeInt(-14), asSafeInt(99));
  
  assert.isTrue(smallest === -14);
  Copy

• MIN_VALUE: SafeInt

  The smallest value representable as SafeInt (the lower saturation target of fromNumber).

• mul: (x: WithSmallInt, y: WithSmallInt) => SafeInt

  Multiplies two safe integers, returning a * b as a SafeInt.

  Example

  const product = SafeInt.mul(asSafeInt(-8), asSafeInt(7));
  
  assert.isTrue(product === -56);
  
  assert.isTrue(SafeInt.is(product));
  Copy

• pow: (x: WithSmallInt, y: WithSmallInt) => SafeInt

  Raises a to the power b, returning a ** b as a SafeInt (floored to an integer).

  Example

  const base = asSafeInt(3);
  
  const exponent = asSafeInt(5);
  
  const power = SafeInt.pow(base, exponent);
  
  assert.isTrue(power === 243);
  
  assert.isTrue(SafeInt.is(power));
  Copy

• random: (min?: WithSmallInt<SafeInt>, max?: WithSmallInt<SafeInt>) => SafeInt

  Generates a random SafeInt within the given range.

  The range is inclusive on both ends.

  Example

  const min = asSafeInt(-10);
  
  const max = asSafeInt(10);
  
  const randomValue = SafeInt.random(min, max);
  
  assert.isTrue(SafeInt.is(randomValue));
  
  assert.isTrue(randomValue >= -10 && randomValue <= 10);
  Copy

• sub: (x: WithSmallInt, y: WithSmallInt) => SafeInt

  Subtracts two safe integers, returning a - b as a SafeInt.

  Example

  const difference = SafeInt.sub(asSafeInt(9), asSafeInt(14));
  
  assert.isTrue(difference === -5);
  
  assert.isTrue(SafeInt.is(difference));
  Copy