> ## Documentation Index
> Fetch the complete documentation index at: https://docs.penbox.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Numbers & calculations

> Arithmetic, formatting, and numeric comparisons in penscript

penscript supports arithmetic, number formatting, and numeric comparisons. These operators are used in computed form fields, premium calculations, validation rules, and automation conditions.

## Addition: `:sum`

Returns the sum of all numbers in a list.

```json theme={null}
{ ":sum": [11, 5, 6, -2] }
// Result: 20
```

Works with variables:

```json theme={null}
{ ":sum": ["{data.amount_1}", "{data.amount_2}", "{data.amount_3}"] }

// Scope: { "data": { "amount_1": 100, "amount_2": 250, "amount_3": 50 } }
// Result: 400
```

Also used for date arithmetic — see the [Dates & time](/penscript/dates) page for details.

## Subtraction: `:substract`

Returns the sequential subtraction of all numbers in a list. The first value is the starting point, and each subsequent value is subtracted from it.

```json theme={null}
{ ":substract": [100, 30] }
// Result: 70

{ ":substract": [100, 20, 5] }
// Result: 75
```

Works with variables:

```json theme={null}
{ ":substract": ["{data.total}", "{data.discount}", "{data.tax}"] }

// Scope: { "data": { "total": 500, "discount": 75, "tax": 25 } }
// Result: 400
```

Also supports date arithmetic — see the [Dates & time](/penscript/dates) page for details.

## Multiplication: `:product`

Returns the product of all numbers in the input array.

```json theme={null}
{ ":product": [5, 3] }
// Result: 15

{ ":product": ["{data.quantity}", "{data.unit_price}"] }
// Scope: { "data": { "quantity": 4, "unit_price": 25 } }
// Result: 100
```

Commonly used inside `:pipe` for sequential transformations:

```json theme={null}
{ ":product": ["@value", 2] }
// Result: double the current @value
```

## Division: `:divide`

Divides the first number by the second.

```json theme={null}
{ ":divide": [100, 4] }
// Result: 25

{ ":divide": ["{data.total}", "{data.count}"] }
// Scope: { "data": { "total": 750, "count": 3 } }
// Result: 250
```

## Power: `:power`

Raises a base to an exponent.

```json theme={null}
{ ":power": [2, 3] }
// Result: 8

{ ":power": [10, 2] }
// Result: 100
```

## Min / Max: `:min`, `:max`

Returns the lowest or highest value from an array.

```json theme={null}
{ ":max": [3, 7, 2, 9, 1] }
// Result: 9

{ ":min": [3, 7, 2, 9, 1] }
// Result: 1
```

Works with variables:

```json theme={null}
{ ":max": ["{data.offer_a}", "{data.offer_b}", "{data.offer_c}"] }
```

## Fixed Decimals: `:to-fixed`

Converts a number to a string with a fixed number of decimal places. Defaults to 2 digits if `:digits` is not specified.

```json theme={null}
{ ":to-fixed": 123.456 }
// Result: "123.46"

{ ":to-fixed": 123.456, ":digits": 1 }
// Result: "123.5"

{ ":to-fixed": 99, ":digits": 2 }
// Result: "99.00"
```

Works with variables:

```json theme={null}
{ ":to-fixed": "{data.price}", ":digits": 2 }

// Scope: { "data": { "price": 49.9 } }
// Result: "49.90"
```

## Type Coercion: `:number`

Converts a value to a number. Useful when form inputs are strings that need to be used in calculations.

```json theme={null}
{ ":number": "123" }
// Result: 123

{ ":number": "45.67" }
// Result: 45.67

{ ":number": "abc" }
// Result: NaN
```

Works with variables:

```json theme={null}
{ ":number": "{data.quantity}" }

// Scope: { "data": { "quantity": "10" } }
// Result: 10
```

## Number Formatting: `:format-number`

Formats a number for display. Use `:digits` to control decimal precision.

```json theme={null}
{
  ":digits": 0,
  ":format-number": {
    ":product": [0.7355, "{data.horses_power}"]
  }
}

// Scope: { "data": { "horses_power": 110 } }
// Result: 81
```

```json theme={null}
{
  ":digits": 2,
  ":format-number": { ":sum": ["{data.subtotal}", "{data.tax}"] }
}

// Scope: { "data": { "subtotal": 99.5, "tax": 20.895 } }
// Result: 120.40
```

## Age Calculation: `:age`

Calculates age in years from a date value. Typically used as an inline pipe (see [Dates & time](/penscript/dates) for the full reference), but also available as an operator in numeric contexts.

```json theme={null}
"{data.birthdate | age}"
// → 34

{
  ":cmp": "{data.birthdate | age}",
  ":gte": 18
}
// → true if the person is 18 or older
```

## Numeric Comparisons

Use `:cmp` with numeric values for conditional logic based on calculations:

```json theme={null}
{
  ":if": { ":cmp": "{data.price}", ":gte": 100 },
  ":then": "Premium tier",
  ":else": "Standard tier"
}

// Scope: { "data": { "price": 110 } }
// Result: "Premium tier"
```

Combining arithmetic with comparison:

```json theme={null}
{
  ":if": {
    ":cmp": { ":sum": ["{data.deductible}", "{data.premium}"] },
    ":gt": 10000
  },
  ":then": "Requires approval",
  ":else": "Auto-approved"
}
```

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Logic & comparisons" icon="code-branch" href="/penscript/logic">
    Conditional logic with numeric results
  </Card>

  <Card title="Dates & time" icon="calendar" href="/penscript/dates">
    Date arithmetic with :sum
  </Card>

  <Card title="Loops & arrays" icon="repeat" href="/penscript/arrays">
    Aggregate calculations on collections
  </Card>

  <Card title="Variables & scope" icon="brackets-curly" href="/penscript/variables">
    Referencing numeric data
  </Card>
</CardGroup>