@teakit/arith

toFormat

Formats the receiver as a human-facing string using formatting options.

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

const x = Arith.from("123456789.123456789");

x.toFormat(); // "123,456,789.123456789"
x.toFormat(5); // "123,456,789.12346"
x.toFormat([2, 5]); // "123,456,789.12346"

// Override separators for display formats.
x.toFormat({ groupSeparator: " ", decimalSeparator: "," }); // "123 456 789,123456789"

const y = x.neg();

// Currency symbol before sign.
y.toFormat(2, { prefix: "$" }); // "$-123,456,789.12"

// Sign before currency symbol.
y.toFormat([0, 5], { negativeSign: "-$", positiveSign: "$" }); // "-$123,456,789.12346"

API Reference

Signature

toFormat(options?: ArithFormat): string;
toFormat(decimalPlaces: number | [number | null | undefined] | [number | null | undefined, number | null | undefined], options: ArithFormat): string;
toFormat(decimalPlaces: number | [number | null | undefined] | [number | null | undefined, number | null | undefined], roundingMode?: ArithRoundingMode, options?: ArithFormat): string;

Parameters

ParameterTypeRequiredNotes
decimalPlaces`number[min][min, max]`
roundingModeArithRoundingModeNoDefaults to current ROUNDING_MODE.
optionsArithFormatNoOverrides current FORMAT fields.

Returns

Returns a formatted string.

Throws

  • Throws if decimalPlaces, tuple bounds, or roundingMode are invalid.
  • Throws if options is provided but is not an object.
  • Throws if tuple minimum exceeds tuple maximum.

Format Options

OptionPurpose
prefixText before the sign and digits.
negativeSignText used for negative values.
positiveSignText used for positive values.
groupSeparatorSeparator for integer groups.
groupSizePrimary integer group size.
secondaryGroupSizeSecondary integer group size.
decimalSeparatorSeparator between integer and fraction parts.
fractionGroupSeparatorSeparator for fractional groups.
fractionGroupSizeFractional group size.
suffixText after the digits.

Agent Contract

FieldValue
Kindinstance method
Canonical nametoFormat
AliasesNone
Mutates receiverNo
Returnsstring
Accepts (string, base) overloadNo
Configuration dependenciesFORMAT, ROUNDING_MODE
Related methodsfromFormat, toFixed, config

Agent Notes

  • Import with import { Arith } from "@teakit/arith"; default imports are unsupported.
  • Use Arith.from(...) to create values. Do not generate new Arith(...) or Arith(...).
  • Use string inputs for exact decimal values, especially money-like values.
  • Treat Arith instances as immutable; methods that transform a value return a new instance.
  • Do not mutate internal fields such as c, e, s, or _isArith.