# Decimal power

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

Raise a decimal string to an integer power exactly, with optional single rounding to a fixed scale.

**Use when you need to: raise a decimal to a power exactly · exact integer power of a decimal number · 1.05 to the power of 10.**

## Decide before calling

Read the [versioned contract](/v1/tools/decimal-power/versions/1.0.0) and the supported scope below. Reuse `decimal-power@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-power@1.0.0` for raise a decimal to a power exactly. 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

- raise a decimal to a power exactly
- exact integer power of a decimal number
- 1.05 to the power of 10
- compound interest growth factor exact
- decimal exponentiation with rounding
- reciprocal power to n decimal places
- power of a decimal with negative exponent
- square or cube a decimal exactly

## Not supported

- fractional or decimal exponents
- roots of numbers
- logarithms or exponentials with base e
- floating point or scientific notation input

## 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".
- exponent is a JSON integer in -1000..1000; a string, a float, NaN, Infinity or out of range -> invalid_input.
- The power is computed exactly as a rational: base^e for e >= 0, and 1/base^|e| for e < 0. 0^0 is 1; x^0 is 1 for every x; 0^n is 0 for n > 0.
- A negative exponent without scale and rounding -> invalid_input (the reciprocal is generally not a finite decimal).
- Size estimate, checked after the field checks and the scale/rounding pairing and before any arithmetic: let k be the number of digits of the canonical significand of base (fraction digits and the decimal point written out as one integer after stripping trailing FRACTION zeros; integer trailing zeros stay; zero counts as 1 digit). k * |exponent| > 20,000 -> limit_exceeded. Example: "10000000000000000000" (k = 20) with exponent 1000 is allowed, a 21-digit base with exponent 1000 is not.
- 0 to a negative exponent -> not_computable with details.reason "zero_to_negative_power" (checked after the size estimate).
- With no scale, a non-negative exponent must produce a result whose significand power (significand^e) has at most 120 digits; otherwise invalid_input (give a scale). 2^398 (120 digits) succeeds without a scale, 2^399 needs one. The result is canonical (trailing fraction zeros stripped) and exact is true.
- With scale and rounding the exact power is rounded once to scale fraction digits and exact is true iff that changed nothing. A tiny reciprocal such as 10^-1000 at scale 40 is "0.000...0" (40 zeros) with exact false.
- scale and rounding must appear together or not at all; exactly one of them present -> invalid_input.
- 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").
- A result rounded to scale s is written with exactly s fraction digits (no fraction and no point when s is 0); a result with no scale is canonical: trailing fraction zeros are stripped and an integer has no point.
- rounding "unnecessary" with an inexact power -> not_computable with details.reason "rounding_necessary".
- Result size: the written value (sign, digits and point) is at most 20,100 characters. The size estimate bounds a positive-exponent result to about 20,000 integer digits, but a base with fraction digits can still give a longer text, so a result whose written value would exceed 20,100 characters -> limit_exceeded, decided from the size of the exact result (scale digits times |exponent| for an unscaled result, integer digits of the reciprocal for a negative exponent) before the text is built. With the 40-fraction-digit base "0.0000000000000000000000000000000000000001" (k = 1): exponent 502 without a scale is "0." followed by 20,080 fraction digits (20,082 characters) and succeeds; exponent 503 without a scale (20,122 characters) -> limit_exceeded; exponent -502 at scale 0 is 1 followed by 20,080 zeros (20,081 characters) and succeeds; exponent -503 at scale 0 (20,121 characters) -> limit_exceeded.
- 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

- `base` (string, required): min length 1; max length 62; pattern `^-?(0|[1-9][0-9]*)(\.[0-9]+)?$`; Base as a decimal string.
- `exponent` (integer, required): min -1000; max 1000; Integer exponent, -1000 to 1000. A negative exponent requires scale and rounding.
- `scale` (integer, optional): min 0; max 40; Fraction digits of the result. Must be given together with rounding. Required when the exponent is negative or the exact result would exceed 120 digits.
- `rounding` (one of "half_even", "half_up", "half_down", "half_ceiling", "half_floor", "up", "down", "ceiling", "floor", "unnecessary", optional): Rounding mode applied to the exact power. Must be given together with scale.

## Output

- `value` (string, required): min length 1; max length 20100; The power: canonical when no scale was given, otherwise fixed at scale fraction digits.
- `exact` (boolean, required): true when the reported value equals the exact power.

## Limits

- max decimal chars: 62
- max decimal digits: 60
- max fraction digits: 40
- max scale: 40
- max abs exponent: 1000
- max significand digits times exponent: 20000
- max unscaled exact digits: 120
- max result chars: 20100

## Example

Request input:

```json
{
  "base": "1.05",
  "exponent": 10
}
```

Response:

```json
{
  "result": {
    "value": "1.62889462677744140625",
    "exact": true
  }
}
```

## How to call it

### MCP

Connect `https://computefirst.net/mcp` ([setup](/docs#connect)), then call `execute` with:

```json
{
  "id": "decimal-power",
  "version": "1.0.0",
  "input": {
    "base": "1.05",
    "exponent": 10
  }
}
```

### HTTP (no key)

```sh
curl -X POST https://computefirst.net/v1/tools/decimal-power/versions/1.0.0/execute \
  -H "Content-Type: application/json" \
  -d '{"base":"1.05","exponent":10}'
```

The machine-readable contract is at [/v1/tools/decimal-power/versions/1.0.0](/v1/tools/decimal-power/versions/1.0.0).

### CLI

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

Get the client at [/clients/cli/](/clients/cli/).

## Related tools

- [Decimal root](/tools/decimal-root): Real nth root (2 to 100) of a decimal string, correctly rounded once to a fixed scale with an explicit mode.
- [Decimal round](/tools/decimal-round): Round a decimal string with an explicit mode to fraction digits, significant digits or a multiple of an increment.
- [Decimal divide](/tools/decimal-divide): Divide two decimal strings exactly, rounding the quotient once to a fixed scale, and report the exact remainder.
- [Fraction to decimal expand](/tools/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 expression evaluate](/tools/decimal-expression-evaluate): Evaluate a decimal arithmetic expression exactly with variables, abs, min, max and round, rounding once at the end.
- [Decimal multiply](/tools/decimal-multiply): Multiply two decimal strings exactly, optionally rounding the product once to a fixed scale with a chosen mode.