From 029a064e9ae91adcb46f2a94bddb3f0c20d65fb8 Mon Sep 17 00:00:00 2001 From: Paul Buetow Date: Fri, 22 May 2026 13:08:33 +0300 Subject: doc(rpn): document Power operator's metric behavior MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Task sd: Added detailed comment explaining why Power (^) always returns Cool (unitless): x^n has different physical units than x. Examples included (2hr 3 ^ → 8, not 8hr³). --- internal/rpn/operations_arithmetic.go | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/internal/rpn/operations_arithmetic.go b/internal/rpn/operations_arithmetic.go index dca0afe..7f8df28 100644 --- a/internal/rpn/operations_arithmetic.go +++ b/internal/rpn/operations_arithmetic.go @@ -128,7 +128,16 @@ func (o *Operations) Divide(stack *Stack) error { } // Power pops two values from stack, raises first to power of second (a ^ b), and pushes result. -// Result is unitless (Cool metric). +// +// Result is always Cool (unitless). This is intentional: x^n has different physical +// units than x, so retaining the input metric would be misleading. Examples: +// +// 2hr 3 ^ → 8 (Cool, not 8hr³) +// 100Mbps 2 ^ → 10000 (Cool, not 10000Mbps) +// 3 4 ^ → 81 (Cool) +// +// Scalar exponents (metric=Cool) also produce Cool results. There is no concept of +// "preserving the base metric" for power operations. func (o *Operations) Power(stack *Stack) error { a, b, err := popTwo(stack, "^") if err != nil { -- cgit v1.2.3