@teakit/arith

allocate

Splits a total into weighted parts while preserving the quantized target total exactly.

import { Arith } from "@teakit/arith";

// Equal weights use stable largest-remainder allocation for tail differences.
const thirds = Arith.allocate("1000000", [1, 1, 1], { decimalPlaces: 2 });
thirds.map((x) => x.toFixed(2)); // ["333333.34", "333333.33", "333333.33"]
Arith.sum(...thirds).toFixed(2); // "1000000.00"

// Business weights may be integers, decimal strings, or Arith instances.
Arith.allocate("100", [50, 30, 20], { decimalPlaces: 2 }).map((x) => x.toFixed(2));
// ["50.00", "30.00", "20.00"]

// Zero weights are allowed, but all weights cannot be zero.
Arith.allocate("10", [1, 0, 1], { decimalPlaces: 2 }).map((x) => x.toFixed(2));
// ["5.00", "0.00", "5.00"]

// Step mode is useful for lot sizes, tick sizes, or minimum share units.
Arith.allocate("10", [1, 1, 1], { step: "0.05" }).map((x) => x.toFixed(2));
// ["3.35", "3.35", "3.30"]

// Negative totals keep the same stable remainder order.
Arith.allocate("-1", [1, 1, 1], { decimalPlaces: 2 }).map((x) => x.toFixed(2));
// ["-0.34", "-0.33", "-0.33"]

// Cloned constructors use their own DECIMAL_PLACES and ROUNDING_MODE defaults.
const Money = Arith.clone({ DECIMAL_PLACES: 2 });
Money.allocate("10", [1, 1, 1]).map((x) => x.toFixed(2));
// ["3.34", "3.33", "3.33"]

API Reference

Signature

interface ArithAllocateOptions {
  decimalPlaces?: number;
  step?: ArithValue;
  roundingMode?: ArithRoundingMode;
}

Arith.allocate(
  total: ArithValue,
  weights: readonly ArithValue[],
  options?: ArithAllocateOptions,
): ArithInstance[];

Parameters

ParameterTypeRequiredNotes
totalArithValueYesFinite total to split. May be positive, negative, or zero.
weightsreadonly ArithValue[]YesNon-empty array of finite non-negative weights. At least one weight must be positive.
options.decimalPlacesnumberNoDecimal-place quantization. Defaults to current DECIMAL_PLACES. Cannot be used with step.
options.stepArithValueNoPositive finite allocation unit. Cannot be used with decimalPlaces.
options.roundingModeArithRoundingModeNoRounds the target total before allocation. Defaults to current ROUNDING_MODE.

Returns

Returns an ArithInstance[] with the same length as weights. The sum of all returned parts equals the quantized target total.

Throws

  • Throws if weights is not a non-empty array.
  • Throws if total is NaN, Infinity, or -Infinity.
  • Throws if any weight is non-finite or negative.
  • Throws if all weights are zero.
  • Throws if decimalPlaces, step, or roundingMode is invalid.
  • Throws if both decimalPlaces and step are provided.

Agent Contract

FieldValue
Kindstatic method
Canonical nameallocate
AliasesNone
Mutates receiverNo
ReturnsArithInstance[]
Accepts (string, base) overloadNo
Configuration dependenciesDECIMAL_PLACES, ROUNDING_MODE, STRICT
Related methodssum, decimalPlaces, toNearest, clone

Agent Notes

  • Use Arith.allocate(total, weights, options?) for deterministic amount, fee, holding, or unit distribution.
  • Do not generate an instance method such as Arith.from(total).allocate(...).
  • Use decimalPlaces for decimal-place money rules and step for lot-size or tick-size rules.
  • Do not pass both decimalPlaces and step.
  • roundingMode only quantizes the target total; remainder distribution always uses stable largest remainder order.
  • Prefer string inputs for exact decimal totals, weights, and steps.