[Rcpp-commits] r1404 - pkg/RcppGSL/inst/doc/RcppGSL

[noreply at r-forge.r-project.org]

Author: romain
Date: 2010-06-02 16:27:25 +0200 (Wed, 02 Jun 2010)
New Revision: 1404

Modified:
   pkg/RcppGSL/inst/doc/RcppGSL/RcppGSL.Rnw
Log:
first pass at documentation about matrices

Modified: pkg/RcppGSL/inst/doc/RcppGSL/RcppGSL.Rnw
===================================================================
--- pkg/RcppGSL/inst/doc/RcppGSL/RcppGSL.Rnw	2010-06-02 13:48:48 UTC (rev 1403)
+++ pkg/RcppGSL/inst/doc/RcppGSL/RcppGSL.Rnw	2010-06-02 14:27:25 UTC (rev 1404)
@@ -6,6 +6,9 @@
 \setlength{\oddsidemargin}{0pt}
 \setlength{\textwidth}{17cm} % uh-oh, I use letter :)
 \usepackage[authoryear,round,longnamesfirst]{natbib}
+       
+\newcommand{\proglang}[1]{\textsf{#1}}
+\newcommand{\pkg}[1]{{\fontseries{b}\selectfont #1}}
 
 <<echo=FALSE,print=FALSE>>=
 library( "RcppGSL" )
@@ -235,6 +238,7 @@
     _["even"] = v_even,
     _["odd" ] = v_odd
     ) ;
+  // we only need to free v, the views don t own data
   v.free() ;
 
   return res ;
@@ -274,12 +278,72 @@
 in RcppGSL.}
 \end{table}
 
-
 \section{Matrices}
 
-TODO: write content about \texttt{RcppGSL::matrix} and \texttt{RcppGSL::matrix\_view}
+\texttt{GSL} defines a set of matrix data types : \texttt{gsl\_matrix}, 
+\texttt{gsl\_matrix\_int} etc ... for which \pkg{RcppGSL} also defines
+convenience \proglang{C++} wrapper generated by the \texttt{RcppGSL::matrix}
+template.
 
+\subsection{creating matrices}
 
+The \texttt{RcppGSL::matrix} template exposes three constructors. 
+
+<<lang=cpp>>=
+// convert an R matrix to a GSL matrix
+matrix( SEXP x) throw(::Rcpp::not_compatible) 
+
+// encapsulate a GSL matrix pointer
+matrix( gsl_matrix* x)
+
+// create a new matrix with the given number of rows and columns
+matrix( int nrow, int ncol)                 
+@
+
+\subsection{implicit conversion}
+
+\texttt{RcppGSL::matrix} defines implicit conversion to a pointer to
+the associated GSL matrix type, as well as dereferencing operators, making 
+the class \texttt{RcppGSL::matrix} look and feel like a pointer to a GSL
+matrix type.
+
+<<lang=cpp>>=
+	gsltype* data ;
+	operator gsltype*(){ return data ; }        
+	gsltype* operator->() const { return data; }
+	gsltype& operator*() const { return *data; }
+@
+
+\subsection{indexing}
+
+Indexing of GSL matrices is usually the task of the functions
+\texttt{gsl\_matrix\_get}, \texttt{gsl\_matrix\_int\_get}, ... and 
+\texttt{gsl\_matrix\_set}, \texttt{gsl\_matrix\_int\_set}, ... 
+
+\pkg{RcppGSL} takes advantage of both operator overloading and templates
+to make indexing a GSL matrix much more convenient. 
+
+<<lang=cpp>>=
+// create a matrix of size 10x10
+RcppGSL::matrix<int> mat(10,10) ;
+
+// fill the diagonal
+for( int i=0; i<10: i++){
+	mat(i,i) = i ;
+}
+@
+
+\subsection{Methods}
+
+The \texttt{RcppGSL::matrix} type also defines :
+\begin{itemize}
+\item nrow : extract the number of rows
+\item ncol : extract the number of columns
+\item size : extract the number of elements
+\item free : release the memory 
+\end{itemize}
+
+
 \section{References}
 
 \bibliographystyle{abbrvnat}