Mercurial > octave-nkf

changeset 14169:c0ca47ab7641 stable

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
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	Sat Jan 07 12:44:34 2012 -0500
+++ b/doc/interpreter/expr.txi	Sun Jan 08 15:24:53 2012 -0500
@@ -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	Sat Jan 07 12:44:34 2012 -0500
+++ b/src/data.cc	Sun Jan 08 15:24:53 2012 -0500
@@ -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	Sat Jan 07 12:44:34 2012 -0500
+++ b/src/help.cc	Sun Jan 08 15:24:53 2012 -0500
@@ -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 ("./",