Mercurial > hg > octave-lojdl
changeset 14169:c0ca47ab7641 stable
doc: Better explain which complex result is chosen by .^
* expr.txi: Explain which complex root is chosen and how to choose a
real one if preferred.
* data.cc (power): Ditto.
* help.cc (.^, .**): Ditto. (^, **): Suggest using real-valued functions.
author | Jordi Gutiérrez Hermoso <jordigh@octave.org> |
---|---|
date | Sun, 08 Jan 2012 15:24:53 -0500 |
parents | 7ffd2a0791ef |
children | 2ff75e38c299 |
files | doc/interpreter/expr.txi src/data.cc src/help.cc |
diffstat | 3 files changed, 29 insertions(+), 11 deletions(-) [+] |
line wrap: on
line diff
--- a/doc/interpreter/expr.txi +++ b/doc/interpreter/expr.txi @@ -603,7 +603,11 @@ @opindex .^ Element by element power operator. If both operands are matrices, the number of rows and columns must both agree, or they must be -broadcastable to the same shape. +broadcastable to the same shape. If several complex results are +possible, the one with smallest nonnegative argument (angle) is taken. +This may mean a complex root even if a real root is also possible. Use +@code{realpow}, @code{realsqrt}, @code{cbrt}, or @code{nthroot} if a +real result is preferred. @item -@var{x} @opindex -
--- a/src/data.cc +++ b/src/data.cc @@ -5599,9 +5599,13 @@ "-*- texinfo -*-\n\ @deftypefn {Built-in Function} {} power (@var{x}, @var{y})\n\ Return the element-by-element operation of @var{x} raised to the\n\ -@var{y} power.\n\ +@var{y} power. If several complex results are possible,\n\ +returns the one with smallest nonnegative argument (angle). Use\n\ +@code{realpow}, @code{realsqrt}, @code{cbrt}, or @code{nthroot} if a\n\ +real result is preferred.\n\ +\n\ This function and @w{@xcode{x .^ y}} are equivalent.\n\ -@seealso{mpower}\n\ +@seealso{mpower, realpow, realsqrt, cbrt, nthroot}\n\ @end deftypefn") { return binary_op_defun_body (octave_value::op_el_pow, args);
--- a/src/help.cc +++ b/src/help.cc @@ -239,15 +239,19 @@ pair_type ("**", "-*- texinfo -*-\n\ @deftypefn {Operator} {} **\n\ -Power operator.\n\ -@seealso{power, ^, .**, .^}\n\ +Power operator. This may return complex results for real inputs. Use\n\ +@code{realsqrt}, @code{cbrt}, @code{nthroot}, or @code{realroot} to obtain\n\ +real results when possible.\n\ +@seealso{power, ^, .**, .^, realpow, realsqrt, cbrt, nthroot}\n\ @end deftypefn"), pair_type ("^", "-*- texinfo -*-\n\ @deftypefn {Operator} {} ^\n\ -Power operator.\n\ -@seealso{power, **, .^, .**}\n\ +Power operator. This may return complex results for real inputs. Use\n\ +@code{realsqrt}, @code{cbrt}, @code{nthroot}, or @code{realroot} to obtain\n\ +real results when possible.\n\ +@seealso{power, **, .^, .**, realpow, realsqrt, cbrt, nthroot}\n\ @end deftypefn"), pair_type ("+", @@ -304,15 +308,21 @@ pair_type (".**", "-*- texinfo -*-\n\ @deftypefn {Operator} {} .*\n\ -Element by element power operator.\n\ -@seealso{**, ^, .^, power}\n\ +Element by element power operator. If several complex results are possible,\n\ +returns the one with smallest nonnegative argument (angle). Use\n\ +@code{realpow}, @code{realsqrt}, @code{cbrt}, or @code{nthroot} if a\n\ +real result is preferred.\n\ +@seealso{**, ^, .^, power, realpow, realsqrt, cbrt, nthroot}\n\ @end deftypefn"), pair_type (".^", "-*- texinfo -*-\n\ @deftypefn {Operator} {} .^\n\ -Element by element power operator.\n\ -@seealso{.**, ^, **, power}\n\ +Element by element power operator. If several complex results are possible,\n\ +returns the one with smallest nonnegative argument (angle). Use\n\ +@code{realpow}, @code{realsqrt}, @code{cbrt}, or @code{nthroot} if a\n\ +real result is preferred.\n\ +@seealso{.**, ^, **, power, realpow, realsqrt, cbrt, nthroot}\n\ @end deftypefn"), pair_type ("./",