From 3dda62f8b8d0ba3099b1d674c8697e5715919bce Mon Sep 17 00:00:00 2001
From: Ankit Daftery <ankitdaf@gmail.com>
Date: Fri, 12 Aug 2011 09:26:55 +0000
Subject: [PATCH] Added tutorial for fromdata, i.e. copy free data access

---
 libs/numpy/doc/Jamfile      |  2 +-
 libs/numpy/doc/fromdata.rst | 51 +++++++++++++++++++++++++++++++++++++
 2 files changed, 52 insertions(+), 1 deletion(-)
 create mode 100644 libs/numpy/doc/fromdata.rst

diff --git a/libs/numpy/doc/Jamfile b/libs/numpy/doc/Jamfile
index bf38ffb7..ea99cad1 100644
--- a/libs/numpy/doc/Jamfile
+++ b/libs/numpy/doc/Jamfile
@@ -6,7 +6,7 @@ project user-config : requirements <docutils-cmd>rst2html ;
 import docutils ;
 
 import path ;
-sources = tutorial.rst dtype.rst ndarray.rst ;
+sources = tutorial.rst dtype.rst ndarray.rst fromdata.rst ;
 bases = $(sources:S=) ;
   
 # This is a path relative to the html/ subdirectory where the
diff --git a/libs/numpy/doc/fromdata.rst b/libs/numpy/doc/fromdata.rst
new file mode 100644
index 00000000..2937c78e
--- /dev/null
+++ b/libs/numpy/doc/fromdata.rst
@@ -0,0 +1,51 @@
+How to access data using raw pointers
+=====================================
+
+One of the advantages of the ndarray wrapper is that the same data can be used in both Python and C++ and changes can be made to reflect at both ends.
+The from_data method makes this possible. 
+
+Like before, first get the necessary headers, setup the namespaces and initialize the Python runtime and numpy module::
+
+	#include <boost/numpy.hpp>
+	#include <iostream>
+
+	namespace p = boost::python;
+	namespace np = boost::numpy;
+
+	int main(int argc, char **argv)
+	{
+	  Py_Initialize();
+	  np::initialize();
+
+Create an array in C++ , and pass the pointer to it to the from_data method to create an ndarray::
+
+  int arr[] = {1,2,3,4} ; 
+  np::ndarray py_array = np::from_data(arr, np::dtype::get_builtin<int>() , p::make_tuple(4), p::make_tuple(4), p::object());
+
+Print the source C++ array, as well as the ndarray, to check if they are the same::
+
+  std::cout << "C++ array :" << std::endl ;
+  for (int j=0;j<4;j++)
+  {
+    std::cout << arr[j] << ' ' ;
+  }
+  std::cout << std::endl << "Python ndarray :" << p::extract<char const *>(p::str(py_array)) << std::endl;
+
+Now, change an element in the Python ndarray, and check if the value changed correspondingly in the source C++ array::
+
+  py_array[1] = 5 ; 
+  std::cout << "Is the change reflected in the C++ array used to create the ndarray ? " << std::endl ; 
+  for (int j = 0;j<4 ; j++)
+  {
+    std::cout << arr[j] << ' ' ;
+  }
+
+Next, change an element of the source C++ array and see if it is reflected in the Python ndarray::
+
+  arr[2] = 8 ;
+  std::cout << std::endl << "Is the change reflected in the Python ndarray ?" << std::endl << p::extract<char const *>(p::str(py_array)) << std::endl;
+
+}
+
+As we can see, the changes are reflected across the ends. This happens because the from_data method passes the C++ array by reference to create the ndarray, and thus uses the same locations for storing data.
+