# HG changeset patch
# User Rik <rik@octave.org>
# Date 1419778689 28800
# Node ID 51a1d1164449160403c38890fc1c88502feea550
# Parent  aee5fea8a03e410250c7302374d2272926d8671d
Add extra docs about the performance benefits of operator functions (bug #36439).

* func.txi: Document using handles to operator functions rather than anonymous
wrapper functions.

* vectorize.txi: Document using handles to operator functions when using
cellfun, arrayfun, etc.

diff -r aee5fea8a03e -r 51a1d1164449 doc/interpreter/func.txi
--- a/doc/interpreter/func.txi	Fri Dec 26 14:35:46 2014 -0500
+++ b/doc/interpreter/func.txi	Sun Dec 28 06:58:09 2014 -0800
@@ -1389,6 +1389,32 @@
 are passed to @code{betainc} are inherited from the current
 environment.
 
+Note that for performance reasons it is better to use handles to existing
+Octave functions, rather than to define anonymous functions which wrap an
+existing function.  The integration of @code{sin (x)} is 5X faster if the code
+is written as
+
+@example
+quad (@@sin, 0, pi)
+@end example
+
+rather than using the anonymous function @code{@@(x) sin (x)}.  There are many
+operators which have functional equivalents that may be better choices than an
+anonymous function.  Instead of writing
+
+@example
+f = @@(x, y) x + y 
+@end example
+
+this should be coded as
+
+@example
+f = @@plus
+@end example
+
+@xref{Operator Overloading}, for a list of operators which also have a
+functional form.
+
 @node Inline Functions
 @subsection Inline Functions
 
diff -r aee5fea8a03e -r 51a1d1164449 doc/interpreter/vectorize.txi
--- a/doc/interpreter/vectorize.txi	Fri Dec 26 14:35:46 2014 -0500
+++ b/doc/interpreter/vectorize.txi	Sun Dec 28 06:58:09 2014 -0800
@@ -496,6 +496,15 @@
 
 @DOCSTRING(structfun)
 
+Consistent with earlier advice, seek to use Octave built-in functions whenever
+possible for the best performance.  This advice applies especially to the four
+functions above.  For example, when adding two arrays together
+element-by-element one could use a handle to the built-in addition function
+@code{@@plus} or define an anonymous function @code{@@(x,y) x + y}.  But, the
+anonymous function is 60% slower than the first method.
+@xref{Operator Overloading}, for a list of basic functions which might be used
+in place of anonymous ones.
+
 @node Accumulation
 @section Accumulation