Decimal round

decimal-round · version 1.0.0 · Money & pricing · free, no key needed

Round a decimal string with an explicit mode to fraction digits, significant digits or a multiple of an increment.

Use when you need to: round a decimal half even · round to 2 decimal places · round to significant figures.

Decide before calling

Read the versioned contract and the supported scope below. Reuse decimal-round@1.0.0 when your input, required output and limits match it. Choose another approach for an unsupported operation.

Explain the choice

"I can use decimal-round@1.0.0 for round a decimal half even. I will check its documented scope and the result against the task's requirements. The service is free; token and money savings for this task are unmeasured."

Supported

• round a decimal half even
• round to 2 decimal places
• round to significant figures
• round to the nearest 0.05
• swiss cash rounding to 5 rappen
• bankers rounding of a number
• round half up versus half down
• round toward zero, up or down to n digits

Not supported

• rounding floating point or scientific notation input
• rounding the results of formulas or lists
• currency specific rounding rules by country
• formatting with thousands separators or symbols

Behavior

• Decimal strings match ^-?(0|[1-9][0-9]*)(\.[0-9]+)?$: no plus sign, exponent, leading zeros, leading or trailing point, whitespace or separators. A JSON number where a decimal string is required is invalid_input (wrong type).
• A decimal string longer than 62 UTF-16 code units -> limit_exceeded, checked before the grammar. Otherwise a grammar failure, more than 60 digits in total, or more than 40 fraction digits -> invalid_input.
• Zero has no sign: "-0", "-0.00" and any all-zero value are zero and are emitted as "0" (canonical) or "0.00" (fixed scale), never "-0".
• Exactly one of scale, significant_digits, increment must be present; none or more than one -> invalid_input. scale is an integer 0..40, significant_digits an integer 1..60.
• Rounding modes act on the exact rational result and are: half_even (ties to the even neighbour), half_up (ties away from zero), half_down (ties toward zero), half_ceiling (ties toward +infinity), half_floor (ties toward -infinity), up (away from zero), down (toward zero), ceiling (toward +infinity), floor (toward -infinity), unnecessary (any inexact result -> not_computable with details.reason "rounding_necessary").
• scale target: round value to scale fraction digits; output has exactly scale fraction digits ("217" at scale 1 -> "217.0"; "2.17" at scale 3 -> "2.170").
• increment target: the increment must be a decimal > 0 (zero or negative -> invalid_input). Result = k * increment where k = round(value / increment) using the mode on the exact quotient. The output scale is the number of fraction digits written in the increment string ("0.05" -> 2 digits, "1.00" -> 2 digits, "5" -> 0), so "3" rounded to increment "1.00" is "3.00". Ties are decided on the quotient: 1.025 with increment 0.05 is quotient 20.5, half_even -> 20 -> "1.00", half_up -> 21 -> "1.05".
• significant_digits target with d digits, for value x != 0: e = floor(log10|x|) of the exact value; round x to a multiple of 10^(e-d+1) with the mode; the output scale is max(0, d-1-e), so trailing zeros are kept (1.5 to 5 digits -> "1.5000"; 123456 to 2 digits -> "120000"). If rounding carries into the next power of ten (|result| >= 10^(e+1)) the output scale is one less, floored at 0 (9.995 to 3 digits half_up -> "10.0"; 999.5 to 3 digits half_up -> "1000"). A zero value gives "0" with scale 0 and exact true.
• exact is true iff the rounded value equals the input value. The output field scale reports the fraction digits of value; target reports which target was used.
• rounding "unnecessary" with an inexact result -> not_computable with details.reason "rounding_necessary".
• Validation order (each vector carries a single fault): input not an object; unknown field; missing required field; field types, ranges and decimal-string limits; scale/rounding pairing; then domain errors (not_computable) last.

Input

• value (string, required): min length 1; max length 62; pattern ^-?(0|[1-9][0-9]*)(\.[0-9]+)?$; Decimal string to round.
• rounding (one of "half_even", "half_up", "half_down", "half_ceiling", "half_floor", "up", "down", "ceiling", "floor", "unnecessary", required): Rounding mode.
• scale (integer, optional): min 0; max 40; Target: round to this many fraction digits. Give exactly one of scale, significant_digits, increment.
• significant_digits (integer, optional): min 1; max 60; Target: round to this many significant digits.
• increment (string, optional): min length 1; max length 62; pattern ^-?(0|[1-9][0-9]*)(\.[0-9]+)?$; Target: round to the nearest multiple of this positive decimal.

Output

• value (string, required): min length 1; max length 160; Rounded value written with exactly the output scale fraction digits.
• exact (boolean, required): true when the rounded value equals the input value.
• target (one of "scale", "significant_digits", "increment", required): Which target was used.
• scale (integer, required): min 0; max 100; Number of fraction digits in value.

Limits

• max decimal chars: 62
• max decimal digits: 60
• max fraction digits: 40
• max scale: 40
• max significant digits: 60

Example

Request input:

{
  "value": "2.675",
  "rounding": "half_even",
  "scale": 2
}

Response:

{
  "result": {
    "value": "2.68",
    "exact": false,
    "target": "scale",
    "scale": 2
  }
}

How to call it

MCP

Connect https://computefirst.net/mcp (setup), then call execute with:

{
  "id": "decimal-round",
  "version": "1.0.0",
  "input": {
    "value": "2.675",
    "rounding": "half_even",
    "scale": 2
  }
}

HTTP (no key)

curl -X POST https://computefirst.net/v1/tools/decimal-round/versions/1.0.0/execute \
  -H "Content-Type: application/json" \
  -d '{"value":"2.675","rounding":"half_even","scale":2}'

The machine-readable contract is at /v1/tools/decimal-round/versions/1.0.0.

CLI

node cli.mjs run decimal-round 1.0.0 --input input.json --base-url https://computefirst.net

Get the client at /clients/cli/.

Related tools

• Decimal power: Raise a decimal string to an integer power exactly, with optional single rounding to a fixed scale.
• Decimal root: Real nth root (2 to 100) of a decimal string, correctly rounded once to a fixed scale with an explicit mode.
• Fraction to decimal expand: Expand an integer fraction into its exact decimal with the minimal repeating block marked, e.g. 1/7 as 0.(142857).
• Decimal divide: Divide two decimal strings exactly, rounding the quotient once to a fixed scale, and report the exact remainder.
• Decimal sum: Add up to 10,000 decimal strings exactly and report count, smallest and largest, with optional final rounding.
• Decimal expression evaluate: Evaluate a decimal arithmetic expression exactly with variables, abs, min, max and round, rounding once at the end.