# HG changeset patch
# User Carlo de Falco <address@hidden>
# Date 1384731196 -3600
#      Mon Nov 18 00:33:16 2013 +0100
# Node ID 19bdc1dc10d1d6a4edec71996cda9f31aa6f645d
# Parent  752f6b3587540c23026dacc984a1de16c02227bd
Document calling DEFUN functions in C++.

* standalonebuiltin.cc: new file.
* externa.txi: add a paragraph about calling DEFUN functions in C++.

diff --git a/doc/interpreter/external.txi b/doc/interpreter/external.txi
--- a/doc/interpreter/external.txi
+++ b/doc/interpreter/external.txi
@@ -1773,3 +1773,32 @@
 @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 
address@hidden) accessible in the C++ API. The declarations for all builtin 
+functions are collected in the header file @code{builtin-defun-decls.h}.
+An example of how to call such functions can be seen in the code
+
address@hidden
address@hidden(standalonebuiltin.cc)
address@hidden example
+
address@hidden
+which, again, is compiled and run as a standalone application with
+
address@hidden
address@hidden
+$ 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
+
address@hidden group
address@hidden example
diff --git a/examples/standalonebuiltin.cc b/examples/standalonebuiltin.cc
new file mode 100644
--- /dev/null
+++ b/examples/standalonebuiltin.cc
@@ -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;
+}