# HG changeset patch
# User Carlo de Falco <cdf@users.sourceforge.net>
# Date 1384762995 -3600
# Node ID 3341d2f1e5db8ad4e14cf31960f2ec739c47d9ac
# Parent  73f46593a51cef6d66e6cb3721506bd252244cf1
Document calling DEFUN functions in C++.

* examples/standalonebuiltin.cc: new file.

* doc/interpreter/external.txi: add a paragraph about calling DEFUN
functions in C++.

diff -r 73f46593a51c -r 3341d2f1e5db doc/interpreter/external.txi
--- a/doc/interpreter/external.txi	Sun Nov 17 23:30:00 2013 -0600
+++ b/doc/interpreter/external.txi	Mon Nov 18 09:23:15 2013 +0100
@@ -1773,3 +1773,37 @@
 @end group
 @end example
 
+It is worth noting that, if only builtin funcions are to be calle from 
+a C++ standalone program, then it does not need to initialize the 
+interpreter to do so. The general rule is that, for a builtin 
+function named @code{function_name} in the interpreter, there will be
+a C++ function named @code{Ffunction_name} (note the prepended capital 
+@code{F}) accessible in the C++ API. The declarations for all builtin 
+functions are collected in the header file @code{builtin-defun-decls.h}.
+This feature should be used with care as the list of built-in functions can change.  
+No guarantees can be made that a function that is currently built in won't be implemented 
+as a .m file or as a dynamically linked function in the future.
+An example of how to call builtin functions from C++ can be seen in the code
+
+@example
+@EXAMPLEFILE(standalonebuiltin.cc)
+@end example
+
+@noindent
+which, again, is compiled and run as a standalone application with
+
+@example
+@group
+$ mkoctfile --link-stand-alone standalonebuiltin.cc -o standalonebuiltin
+$ ./standalonebuiltin 
+This is a matrix:
+ 11 12
+ 21 22
+
+This is the norm of the matrix:
+34.4952
+
+@end group
+@end example
+
+
diff -r 73f46593a51c -r 3341d2f1e5db examples/standalonebuiltin.cc
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/examples/standalonebuiltin.cc	Mon Nov 18 09:23:15 2013 +0100
@@ -0,0 +1,33 @@
+#include <iostream>
+#include <octave/oct.h>
+#include <octave/builtin-defun-decls.h>
+
+int
+main (void)
+{
+
+  int n = 2;
+  Matrix a_matrix = Matrix (n, n);
+
+  for (octave_idx_type i = 0; i < n; i++)
+    for (octave_idx_type j = 0; j < n; j++)
+      a_matrix(i,j) = (i + 1) * 10 + (j + 1);
+
+  std::cout << "This is a matrix:" 
+            << std::endl 
+            << a_matrix
+            << std::endl;
+
+  octave_value_list in;
+  in(0) = a_matrix;
+
+  octave_value_list out = Fnorm (in, 1);
+  double norm_of_the_matrix = out(0).double_value ();
+
+  std::cout << "This is the norm of the matrix:" 
+            << std::endl 
+            << norm_of_the_matrix
+            << std::endl;
+  
+  return 0;
+}