
^(+Number1, +Number2, -Result)
-Result is +Number1 ^ +Number2

   Evaluates the expression Number1 "to the power of" Number2 and unifies the
resulting value with Result.



Arguments
   Number1             A number.
   Number2             A number.
   Result              Output: a number.

Type
   Arithmetic

Description

   Evaluates the expression Number1 "to the power of" Number2 and
   unifies the resulting value with Result.

   The result is of type float if any of the arguments is a float. 
   When an integer is raised to the power of a negative integer, the
   result type depends on the value of the global flag prefer_rationals.
   If it is on, it is a rational, otherwise a float.  When the exponent
   is not an integer, the result is of type float.


   This predicate can be used as a function in arithmetic expressions.
   In coroutining mode, if Number1 or Number2 are uninstantiated, the call
   to ^/3 is delayed until these variables are instantiated.




Modes and Determinism
   ^(+, +, -) is det

Exceptions
     4 --- Number1 or Number2 is not instantiated (non-coroutining mode    only).
    24 --- Number1 or Number2 is not of a numeric type.
    20 --- Illegal arithmetic operation:  Number1 is negative and    Number2 is no integral number.
    20 --- Illegal arithmetic operation:  Number1 and Number2 are both    zero.

Examples
   
Success:
    Result is 5 ^ 3.		% gives Result = 125
    Result is -5 ^ 3.		% gives Result = -125
    Result is 5 ^ -2.		% gives Result = 0.04

    Result is 5 ^ 2.2.		% gives Result = 34.493244
    Result is 5.0 ^ 2.		% gives Result = 25.0
    Result is -5.0 ^ 3.		% gives Result = -125.0
    Result is 0.0 ^ 12.3.	% gives Result = 0.0
    Result is 3.3 ^ 0.0.	% gives Result = 1.0
    Result is 0.0 ^ 0.0.	% gives Result = 1.0

Error:
    Result is -5 ^ 0.5.         % arithmetic exception
    Result is -5.0 ^ 3.1.       % arithmetic exception


See Also
   is / 2, get_flag / 2, set_flag / 2
