Exponentiation (**)

Details

The Exponentiation operator produces the exponentiated value of the left operand raised to the power of the right operand.

• 0**0: Zero raised to the power of zero is 0. However, if either operand is an IEEE double-precision number, (for example, 0**$DOUBLE(0) or $DOUBLE(0)**0) zero raised to the power of zero is 1. For further details, refer to the $DOUBLE function.

• 0**n: 0 raised to the power of any positive number n is 0. This includes 0**$DOUBLE("INF"). Attempting to raise 0 to the power of a negative number results in an error: standard negative numbers generate an <ILLEGAL VALUE> error; $DOUBLE negative numbers generate a <DIVIDE> error.

• num**0: Any non-zero number (positive or negative) raised to the power of zero is 1. This includes $DOUBLE("INF")**0.

• 1**n: 1 raised to the power of any number (positive, negative, or zero) is 1.

• -1**n: -1 raised to the power of zero is 1. -1 raised to the power of 1 or -1 is -1. For exponents larger than 1, see below.

• num**n: A positive number (integer or fractional) raised to any power (integer or fractional, positive or negative) returns a positive number.

• -num**n: A negative number (integer or fractional) raised to the power of an even integer (positive or negative) returns a positive number. A negative number (integer or fractional) raised to the power of an odd integer (positive or negative) returns a negative number.

• -num**.n: Attempting to raise a negative number to the power of a fractional number results in an <ILLEGAL VALUE> error.

• $DOUBLE("INF")**n: An infinite number (positive or negative) raised to the power of 0 is 1. An infinite number (positive or negative) raised to the power of any positive number (integer, fractional, or INF) is INF. An infinite number (positive or negative) raised to the power of any negative number (integer, fractional, or INF) is 0.

• $DOUBLE("NAN"): NAN on either side of the exponentiation operator always returns NAN, regardless of the value of the other operand.

Very large exponents may result in overflow and underflow values:

• num**nnn: A positive or negative number greater than 1 with a large positive exponent value (such as 9**153 or -9.2**152) generates a <MAXNUMBER> error.

• num**-nnn: A positive or negative number greater than 1 with a large negative exponent value (such as 9**-135 or -9.2**-134) returns 0.

• .num**nnn: A positive or negative number less than 1 with a large positive exponent value (such as .22**196 or -.2**184) returns 0.

• .num**-nnn: A positive or negative number less than 1 with a large negative exponent value (such as .22**-196 or -.2**-184) generates a <MAXNUMBER> error.

An exponent that exceeds the maximum value supported by InterSystems IRIS® data platform numbers either issues a <MAXNUMBER> error or automatically converts to an IEEE double-precision floating point number. This automatic conversion is specified by using either the TruncateOverflow()Opens in a new tab method of the %SYSTEM.ProcessOpens in a new tab class on a per-process basis, or the TruncateOverflowOpens in a new tab property of the Config.MiscellaneousOpens in a new tab class on a system-wide basis. For further details, refer to the $DOUBLE function.

Examples

The following examples performs exponentiation on two numeric literals:

 WRITE "9 ** 2 = ",9 ** 2,! // 81
 WRITE "9 ** -2 = ",9 ** -2,! // .01234567901234567901
 WRITE "9 ** 2.5 = ",9 ** 2.5,! // 242.9999999994422343

The following example performs exponentiation on two locally defined variables:

 SET x = 4, y = 3
 WRITE "x ** y = ",x ** y,! // 64

The following example performs string arithmetic. Exponentiation uses any leading numeric characters as the values of the operands and produces a result.

 WRITE "4 apples" ** "3 oranges" // 64

If an operand has no leading numeric characters, Exponentiation assumes its value to be zero.

The following example demonstrates how to use exponentiation to find the square root of a number.

 WRITE 256 ** .5 // 16

Exponentiation can also be performed using the $ZPOWER function.