# wrDecimal

> Exact decimal arithmetic on strings, with no float on the way. Built on `BigInt`, no dependency.

Source: https://ngwr.dev/reference/utils/wr-decimal  
Kind: Util  
Added in v15.5  
Optional

## Installation

Import the class, and `@use` the entry point in your global styles. Nothing warns you when the `@use` is missing.

```typescript
import { Component } from '@angular/core';
import { WrInputNumber } from 'ngwr/input-number';
import { wrDecimalAdd } from 'ngwr/utils';

@Component({ imports: [WrInputNumber] })
export class MyComponent {}
```

```scss
@use 'ngwr/input-number';
```

## Usage

A decimal is a string: `'0.1'`, `'-1234.56'`. Every helper reads a string, a number or a bigint, and returns the canonical string, or `null` when a side is not a number. Nothing throws. `wr-table` summaries and `wr-input-number` in `mode="decimal"` run on the same core.

```angular-ts
import { wrDecimal, wrDecimalAdd, wrDecimalDivide, wrDecimalRound } from 'ngwr/utils';

wrDecimalAdd('0.1', '0.2');            // '0.3'
wrDecimalAdd('9007199254740993.01', 1); // '9007199254740994.01'
wrDecimalDivide('10', 3, 2);           // '3.33'
wrDecimalRound('1.005', 2);            // '1.01'
wrDecimal('abc');                      // null
```

## Rules

| Input | Result |
| --- | --- |
| `'00.10'`, `' -5. '`, `'.5'` | Canonical: `'0.10'`, `'-5'`, `'0.5'`. Trailing fraction zeros stay. |
| `'9007199254740993.01'` | Every digit kept. A number is read from its shortest form: `0.1` is `'0.1'`. |
| `'1e5'`, `'1.5E-3'` | Read exactly: `'100000'`, `'0.0015'`. An exponent past 1000 is malformed. |
| `''`, `'abc'`, `'1.2.3'`, `'1,5'`, `'Infinity'`, `NaN`, `null` | Malformed: `null`. Never zero, never a throw. |
| Scale of a sum | The wider of the two: `'10.00' + '0.5'` is `'10.50'`. |
| Rounding | Half away from zero: `'2.5'` to `'3'`, `'-2.5'` to `'-3'`. |

## API

| Name | Description | Type | Default |
| --- | --- | --- | --- |
| `wrDecimal` | Reads a value as an exact decimal and returns the canonical string, or `null` when it is not a number. | `(value: unknown) => string \| null` | `-` |
| `wrDecimalAdd` | `a + b` at the wider scale of the two. | `(a: WrDecimalLike, b: WrDecimalLike) => string \| null` | `-` |
| `wrDecimalSubtract` | `a - b` at the wider scale of the two. | `(a: WrDecimalLike, b: WrDecimalLike) => string \| null` | `-` |
| `wrDecimalMultiply` | `a * b`; the scales add. | `(a: WrDecimalLike, b: WrDecimalLike) => string \| null` | `-` |
| `wrDecimalDivide` | `a / b` at exactly `decimals` places, half away from zero. `null` for a zero divisor. | `(a: WrDecimalLike, b: WrDecimalLike, decimals: number) => string \| null` | `-` |
| `wrDecimalCompare` | Orders two decimals by value: `-1`, `0` or `1`. `1.50` and `1.5` are equal. | `(a: WrDecimalLike, b: WrDecimalLike) => -1 \| 0 \| 1 \| null` | `-` |
| `wrDecimalRound` | Sets the scale to exactly `decimals` places: pads with zeros or rounds half away from zero. | `(value: WrDecimalLike, decimals: number) => string \| null` | `-` |
| `WrDecimalLike` | What the helpers read. `null` and `undefined` read as malformed, so data can be passed straight in. | `string \| number \| bigint \| null \| undefined` | `-` |

## See also

- [round](https://ngwr.dev/reference/utils/round) — Rounds a number to a fixed number of decimals.
- [Number Input](https://ngwr.dev/reference/components/input-number) — A number field with stepper buttons and locale formatting.
- [Table](https://ngwr.dev/reference/components/table) — Rows of data with sorting, filtering, paging and custom cells.
- [wrNumber](https://ngwr.dev/reference/pipes/wr-number) — Format a number, percent or price in the app locale.