Caché MultiValue Basic Reference
PWRS
[Home] [Back] [Next]
InterSystems: The power behind what matters   
Class Reference   
Search:    

Returns the elements of a dynamic array raised to a power.
Synopsis
PWRS(dynarray,exponents)
Arguments
dynarray An expression that resolves to a dynamic array of numeric values. Each element in dynarray is raised to the exponent in the corresponding element of the exponents dynamic array. If an element value is 0, the corresponding exponents element must be non-negative. If an element is negative, the corresponding exponents element must be an integer.
exponents The exponents to apply to the dynarray elements. An expression that resolves to a dynamic array of numeric values.
Description
The PWRS function raises each element of dynarray to the power specified by the corresponding element of the exponents dynamic array. Both numeric values can be expressed as either numbers or as strings. Leading plus signs and leading and trailing zeros are ignored. A string is parsed as a number until a non-numeric character is encountered. Thus “7dwarves” is parsed as 7.
If the two dynamic arrays have different numbers of elements, by default the shorter dynamic array) is padded so that the returned dynamic array has the number of elements of the longer dynamic array. If the shorter dynamic array is the value to be raised, it is padded with the required number of elements with the value of 0. If the shorter dynamic array is the exponents, it is padded with the required number of elements with the value of 1. You can also use the REUSE function to define behavior when specifying two dynamic arrays with different numbers of elements.
Note:
In the exponents dynamic array, missing elements and elements with a null string or non-numeric string value are parsed as 1. This parsing differs from the PWR function and other MultiValue numeric functions and operators, which parse non-numerics as 0.
Any non-zero numeric element value raised to an exponent of 0 returns 1. If the corresponding dynarray and exponents elements are both 0, PWRS returns 0 for that element. If the dynarray element is 0 and the corresponding exponents element is a negative number, PWRS generates an <ILLEGAL VALUE> error. If the dynarray element is a negative number and the corresponding exponents element is a fractional number, PWRS generates an <ILLEGAL VALUE> error.
A very large positive exponents element value (such as 135), or a very small dynarray element value (such as .00005) with a corresponding negative exponents element (such as -30) may result in an overflow, generating a <MAXNUMBER> error. A very large negative exponents element value (such as -135), or a very small dynarray element value (such as .00005) with a corresponding positive exponents element (such as 30) may result in an underflow, returning 0.
To return the exponent of a single value raised to a power, use the PWR function or the ** operator.
Example
The following example returns the value of each element in mynums raised to the corresponding element in myexps:
mynums=1:@VM:2:@VM:3:@VM:4:@VM:5
myexps=2:@VM:3:@VM:2:@VM:3:@VM:2
crt PWRS(mynums,myexps)
   ! returns: 1ý8ý9ý64ý25  
See Also