%\VignetteIndexEntry{STK++ Arrays: User Guide} \documentclass[a4paper,10pt]{article} %------------------------- % preamble for nice lsitings and notes \include{rtkpp-preamble} \geometry{top=3cm, bottom=3cm, left=2cm, right=2cm} %% need no \usepackage{Sweave.sty} <>= library(rtkore) rtkore.version <- packageDescription("rtkore")$Version rtkore.date <- packageDescription("rtkore")$Date @ % Title Page \title{User Guide: \stkpp{} Arrays} \author{Serge Iovleff} \date{\today} % start documentation \begin{document} \SweaveOpts{concordance=TRUE} \maketitle \begin{abstract} This user guide gives a general review of the \stkpp{} arrays and of their usages. After giving a general review of the capability of the library, we detail the various accessors/mutators available. We give a complete list of constructors. We focus on the \code{Array2D} class and give some hints about their capabilities. We then present the different visitors, appliers and functors implemented in \stkpp{} allowing to compute quantities or arrays of interests. We then explain how it is possible to use or modify slices of arrays. Finally we end this document by detailing the way to construct reference arrays. \end{abstract} \section{Introduction} The containers/arrays you use in order to store and process the data in your application greatly influence the speed and the memory usage of your application. \stkpp{} proposes a large choice of containers/arrays and methods that you can used in conjunction with them. There are mainly two kinds of arrays and a wrapper you can use in \stkpp{}: \begin{itemize} \item The \code{Array2D} family classes which are the classes defined in the oldest versions of \stkpp{}, \item the \code{CArray} family classes which have been introduced in version 0.4 of \stkpp{} library. \item For \rtkore{} users, the \code{RVector} and \code{RMatrix} wrap the R \code{SEXP} stucture. \end{itemize} Before explaining the usage and differences between the different arrays, we first introduce some vocabulary. The terminology used in \stkpp{} project for the arrays is the following: \begin{itemize} \item An array is often called a matrix. \item In the case where a matrix has 1 column, such matrix is called column-vector, often abbreviated just as \emph{vector}, \item in the other case, where a matrix has 1 row, it is called row-vector, often abbreviated just as \emph{point}. \end{itemize} The word \emph{point} is borrowed from the statistical vocabulary where a row of a data array is often named a point. The \code{Array2D} classes are very flexible if you need to add, insert, remove, resize,... quickly rows or columns to your container. On the other hand, the storing scheme of the the \code{CArray} classes allow you to used them easily with other linear algebra libraries (e.g. \lapack{}). \section{A detailed introductory example} Consider the following example: \begin{minipage}[t]{0.66\textwidth} \lstinputlisting[style=customcpp,caption=Introductory example]{programs/tutoAccessors.cpp} \end{minipage} \hspace{0.2cm} \begin{minipage}[t]{0.33\textwidth} \addtocounter{lstlisting}{-1} \lstinputlisting[style=customcpp,caption=Output]{programs/tutoAccessors.out} \end{minipage} \subsection{Accessors} The primary coefficient accessors and mutators in \stkpp{} are the overloaded parenthesis operators. For matrices, the row index is always passed first. The \code{operator[]} is also overloaded for index-based access in vectors, but keep in mind that \Cpp{} doesn't allow \code{operator[]} to take more than one argument. The \code{operator[]} is thus restricted to vectors/points/diagonal matrices. For vectors, just pass one index in a bracket. Indexing starts at 0 by default. This behavior can be modify by defining the \ttcode{STKBASEARRAYS} macro at compile time using the directive \ttcode{-DSTKBASEARRAYS=1}. Enabling this macro allow user to get 1 based arrays like in FORTRAN. If you want to build code independent of the first index you should use the \code{beginCols()}, \code{beginRows()}, \code{endRows()}, \code{endCols()}, \code{lastIdxCols()} and \code{lastIdxRows()} methods of the arrays and the \code{begin()}, \code{end()}, \code{lastIdx()} methods of the Points (Row-vectors), Vectors, square matrices and diagonal matrices. Here an example \begin{minipage}[t]{0.66\textwidth} \lstinputlisting[style=customcpp,caption=Accessors]{programs/tutoAccessors2.cpp} \end{minipage} \hspace{0.2cm} \begin{minipage}[t]{0.33\textwidth} \addtocounter{lstlisting}{-1} \lstinputlisting[style=customcpp,caption=Output]{programs/tutoAccessors2.out} \end{minipage} \subsection{Expression template} Assume that \code{c, a, d} are arrays of the same size and consider the line of code \begin{lstlisting}[style=customcpp] c= -a - d + 3.; \end{lstlisting} It is an expression involving matrix operations. All these expressions are encoded in an expression template and are completely inlined at compile time. It means there is no temporary objects created when these expressions are evaluated. \subsection{Constructors} The \code{Array2D} family have only one mandatory template parameter: the type of the data that will be stored. On the other hand arrays in \code{CArray} family have four template parameters: \begin{enumerate} \item the type of the data that will be stored, \item the number of rows (\code{UnknownSize} if it is not known at compile time), \item the number of columns (\code{UnknownSize} if it is not known at compile time), \item the orientation storage scheme of the data (by row or by column). \end{enumerate} Only the first template parameter is mandatory. \begin{minipage}[t]{0.99\textwidth} \lstinputlisting[style=customcpp,caption=Constructors]{programs/tutoConstructors.cpp} \end{minipage} \subsection{Accessing rows/columns/parts of an array} You can access rows, columns and sub-part of \stkpp{} arrays easily. Here is an example: \begin{minipage}[t]{0.66\textwidth} \lstinputlisting[style=customcpp,caption=Example]{programs/tutoSubArrays.cpp} \end{minipage} \hspace{0.2cm} \begin{minipage}[t]{0.33\textwidth} \addtocounter{lstlisting}{-1} \lstinputlisting[style=customcpp,caption=Output]{programs/tutoSubArrays.out} \end{minipage} Applied to a vector/point/diagonal matrix the method sub require only one parameter: the Range of the data we want to access/mutate. In the general case, you can use the following methods in order to access/mutate columns/rows/part of an array: \begin{lstlisting}[style=customcpp,caption=Review of the main accessors] // access to the ith row a.row(i); // access to the element [first, first+size-1] of the ith row a.row(i, Range(first, size)); // access to the jth column a.col(j); // access to the element [first, first+size-1] of the jth columns a.col(j, Range(first, size)); // access to the element [first, first+size-1] of the jth columns a.col(j, Range(first, size)); // Create ranges Range I(3,2), J(4,2); // access to the sub-array formed by the range I,J. a.sub(I, J); // access to the row i, in the range J = 4:5 a(i,J); // access to the column j in the Range I=3:4 a(I,j); // access to a subarray in the range (3:4, 4:5) a(I,J); \end{lstlisting} \subsection{Using references and move} In some cases, you may want to conserve an access to some part of an array for some work. For this purpose, it is possible to create reference array, that is array that wrap (part of) another array \begin{minipage}[t]{0.66\textwidth} \lstinputlisting[style=customcpp,caption=reference and move]{programs/tutoReferenceAndMove.cpp} \end{minipage} \hspace{0.2cm} \begin{minipage}[t]{0.33\textwidth} \addtocounter{lstlisting}{-1} \lstinputlisting[style=customcpp,caption=Output]{programs/tutoReferenceAndMove.out} \end{minipage} The \code{Stat::mean} function return an \code{Array2D} \emph{by value}. In order to avoid a useless copy, we use the \code{move} function. The following piece of code \begin{lstlisting}[style=customcpp] a.move(b); \end{lstlisting} perform the operations: \begin{itemize} \item if \code{a} contains data, the memory is released, \item \code{a} become the owner of the data contain by \code{b}, \item \code{b} become a reference, \item If \code{b} was a reference, then \code{a} is also a reference. \end{itemize} \begin{note} Many more examples can be found in the test files coming with the \stkpp{} library. \end{note} \section{Arrays classes and their constructors} As say in the Introduction, there is two kind of arrays provides by the \stkpp{} library: the arrays part of the \code{Array2D} family and the arrays part of the \code{CArray} family. Constructors depends of the structure of the array you want to obtain. In this part we will review all the existing arrays and the different way to create them. \subsection{Review of the classes} \subsubsection{\ttcode{Array2D} and \ttcode{CArray} classes} The \code{Array2D} and \code{CArray} classes are the most general classes for storing scalars. The values are stored in an array of range \code{[beginRows:endRows)}$\times$\code{[beginCols:endCols)}. \begin{lstlisting}[style=customcpp] template class \code{Array2D}; template< typename Type, int SizeRows_ = UnknownSize, int SizeCols_ = UnknownSize, bool Orient_ = Arrays::by_col_> class CArray; \end{lstlisting} \subsubsection{\ttcode{Array2DVector}, \ttcode{Array2DPoint}, \ttcode{CArrayVector} and \ttcode{CArrayPoint} classes} The \code{Array2DVector}, \code{Array2DPoint}, \code{CArrayVector} and \code{CArrayPoint} classes allow to store scalars in column and row vectors. The values are stored in arrays of range \code{[begin:end)}. \begin{lstlisting}[style=customcpp] template \code{Array2D}Vector; template \code{Array2D}Point; template< typename Type, int SizeRows_=UnknownSize, bool Orient_ = Arrays::by_col_> class CArrayVector; template< typename Type, int SizeCols_=UnknownSize, bool Orient_ = Arrays::by_row_> class CArrayPoint; \end{lstlisting} \begin{note} Only the first template parameter is mandatory. \end{note} \subsubsection{\ttcode{Array2DSquare} and \ttcode{CArraySquare} classes} The \code{Array2DSquare} and \code{CArraySquare} classes are general classes for storing scalars in a square matrix. The values are stored in an array of range \code{[begin:end)}$\times$\code{[begin:end)}. \begin{lstlisting}[style=customcpp] template \code{Array2D}Square; template< typename Type_, int Size_ = UnknownSize, bool Orient_ = Arrays::by_col_> class CArraySquare; \end{lstlisting} \begin{note} Only the first template parameter is mandatory. \end{note} \subsubsection{\ttcode{Array2DDiagonal} class} The \code{Array2DDiagonal} class is a general class for storing scalars in a diagonal matrix. The values are stored in an array of range \code{[begin:end)}$\times$\code{[begin:end)} with zero outside the diagonal. \begin{lstlisting}[style=customcpp] template \code{Array2D}Diagonal; \end{lstlisting} \begin{note} Only the diagonal values are effectively stored in an \code{Array2DDiagonal} array. \end{note} \subsubsection{\ttcode{Array2DUpperTriangular} and \ttcode{Array2DLowerTriangular} classes} The \code{Array2DUpperTriangular} and \code{Array2DLowerTriangular} classes are general classes for storing scalars in triangular matrices. The values are stored in an array of range \code{[beginRows:endRows)}$\times$\code{[beginCols:endCols)} with zero in the respectively lower and upper part of the array. \begin{lstlisting}[style=customcpp] template \code{Array2D}UpperTriangular; template \code{Array2D}LowerTriangular; \end{lstlisting} \begin{note} Only the non-zeros values are effectively stored in the arrays and the upper part (respectively the lower part) is the part of the array such that $j>i$ (resp. $i>j$), where $i$ represents the index of the row and $j$ the index of the column. \end{note} \subsection{Constructors for the \ttcode{Array2D} family containers} \subsubsection{Default constructors} All default constructors create an empty Array of scalar \code{Type} \begin{lstlisting}[style=customcpp] Array2D a; Array2DVector v; Array2DPoint p; Array2DSquare s; Array2DDiagonal d; Array2DLowerTriangular l; Array2DUpperTriangular u; \end{lstlisting} In the following example \begin{lstlisting}[style=customcpp] Array2D a; // a is an empty array of Real (double by default) a.resize(10,10)=0.; // a is now an array of size (10,10) with the value 0. Array2DVector b; // a is an empty column vector of Real b.resize(10)=0.; // b is now an column-vector of size 10 with the value 0. \end{lstlisting} \subsubsection{Constructors with given dimensions} It is possible to declare an array with fixed ranges for the rows and the columns and Optionally an initial value \begin{lstlisting}[style=customcpp] Array2D( Range const& I, Range const& J); Array2D( Range const& I, Range const& J, Type const& v); Array2DVector( Range const& I); Array2DVector( Range const& I, Type const& v); Array2DPoint( Range const& J); Array2DPoint( Range const& J, Type const& v); Array2DSquare( Range const& I); Array2DSquare( Range const& I, Type const& v); Array2DDiagonal( Range const& I); Array2DDiagonal( Range const& I, Type const& v); Array2DLowerTriangular( Range const& I, Range const& J); Array2DLowerTriangular( Range const& I, Range const& J, Type const& v); Array2DUpperTriangular( Range const& I, Range const& J); Array2DUpperTriangular( Range const& I, Range const& J, Type const& v); \end{lstlisting} The following code build an array of \code{Real} (double by default) with rows in the range $2:4$ and columns in the range $0:9$ (this is the default, but could be $1:10$ if the macro STKBASEARRAYS=1 is activated). The array is initialized with the value 2 \begin{lstlisting}[style=customcpp] Array2D a(Range(2,3), 10, 2.); \end{lstlisting} The following code build a vector of \code{Real} (double by default) with columns in the range $0:9$ (this is the default, but could be $1:10$ if the macro \ttcode{STKBASEARRAYS=1} is activated). The array is initialized with the value $2$ \begin{lstlisting}[style=customcpp] Array2DVector a( 10, 2.); \end{lstlisting} \subsubsection{Copy constructors} All arrays have a copy constructor. In the following examples, the resulting array is either a copy of the array \code{T} (if \code{ref == false}) or a reference of the array \code{T} (if \code{ref == true}) \begin{lstlisting}[style=customcpp] Array2D( \code{Array2D} const& T, bool ref=false) a; // a is a physical copy of T Array2DVector( \code{Array2D}Vector const& T, bool ref=false) v; // v is a physical copy of T Array2DPoint( \code{Array2D}Point const& T, bool ref=false); Array2DSquare( \code{Array2D}Square const& T, bool ref=false); Array2DDiagonal( \code{Array2D}Diagonal const& T, bool ref=false); Array2DLowerTriangular( \code{Array2D}LowerTriangular const& T, bool ref=false); Array2DUpperTriangular( \code{Array2D}UpperTriangular const& T, bool ref=false); \end{lstlisting} The following code copy the array \code{a} in a new array \code{b} and create a reference of the rows and columns of \code{c} with range $I$ for the rows and range $J$ for the columns. \begin{lstlisting}[style=customcpp] Array2D a(10, 8); Array2D b(a); // b is now a copy of a // c is a reference, if an element of c is modified, the corresponding element of a is modified Array2D c(a.sub(I,J), true); \end{lstlisting} The following shows how to get a reference on a column and a reference on a row of an \code{Array2D}. \begin{lstlisting}[style=customcpp] Array2D a(10, 8); Array2DVector c(a.col(1), true); // c is now a reference on the column 1 of a Array2DPoint p(a.row(1), true); // p is now a reference on the row 1 of a \end{lstlisting} \begin{warning} It is the responsibility of the user to verify that a reference is valid. \end{warning} \subsection{Constructors for the \ttcode{CArray} family containers} \subsubsection{Default constructors} All default constructors create an empty Array of scalar \code{Type} \begin{lstlisting}[style=customcpp] CArray(); Array2DVector(); CArrayPoint(); CArraySquare(); \end{lstlisting} \begin{note} The only mandatory template argument is \code{Type}. \end{note} Here after are some more examples \begin{lstlisting}[style=customcpp] CArray a; // a is an empty array of Real (double by default) a.resize(10,10) =0.; // a is now an array of size (10,10) with the value 0. CArrayVector b; // a is an empty column vector of Real b.resize(10) =0.; // b is now a column-vector of size 10 with the value 0. \end{lstlisting} \subsubsection{Constructors with given dimensions} It is possible to construct an array with fixed ranges for the rows and the columns and optionally an initial value. \begin{lstlisting}[style=customcpp] CArray( Range const& I, Range const& J); CArray( Range const& I, Range const& J, Type const& v); CArrayVector( Range const& I); CArrayVector( Range const& I, Type const& v); CArrayPoint( Range const& J); CArrayPoint( Range const& J, Type const& v); CArraySquare( Range const& I); CArraySquare( Range const& I, Type const& v); \end{lstlisting} If the dimension is known at compile time, you can use the template arguments \begin{lstlisting}[style=customcpp] CArray a; // uninitialized array of fixed size (10,10) CArray a(0,0,1)); // array of fixed size (10,10) with initial value 1 \end{lstlisting} The following code build an array of \code{Real} (double by default) with rows in the range $2:4$ and columns in the range $0:9$ (this is the default, but could be $1:10$ if the macro \ttcode{STKBASEARRAYS=1} is activated). The array is initialized with the value $2$. \begin{lstlisting}[style=customcpp] CArray a(Range(2,3), 10, 2.); \end{lstlisting} The following code build a vector of \code{Real} (double by default) with columns in the range $0:9$ (this is the default, but could be $1:10$ if the macro \ttcode{STKBASEARRAYS=1} is activated). The array is initialized with the value $2$. \begin{lstlisting}[style=customcpp] CArrayVector a( 10, 2.); \end{lstlisting} \subsubsection{Copy constructors} In the following examples, the resulting array is either a copy of the array \code{T} (if \code{ref == false}) or a reference of the array \code{T} (if \code{ref == true}) \begin{lstlisting}[style=customcpp] CArray( const CArray const& T, bool ref=false); CArrayVector( CArrayVector const& T, bool ref=false); CArrayPoint( CArrayPoint const& T, bool ref=false); CArraySquare( CArraySquare const& T, bool ref=false); \end{lstlisting} The following code copy the array \code{a} in a new array \code{b} and create a reference of the rows and columns of \code{c} with range $I$ for the rows and range $J$ for the columns \begin{lstlisting}[style=customcpp] CArray a(10, 8); CArray b(a); // b is now a copy of a // c is a reference, if an element of c is modified, the corresponding element of a is modified CArray c(a.sub(I,J), true); \end{lstlisting} The following show how to get a reference on a column and a reference on a row of a \code{CArray}. \begin{lstlisting}[style=customcpp] CArray a(10, 8); CArrayVector c(a.col(1), true); // c is now a reference on the column 1 of a CArrayPoint p(a.row(1), true); // p is now a reference on the row 1 of a \end{lstlisting} \section{Using \ttcode{Array2D}} This section explains how you can add and/or remove columns/rows to an array of the \code{Array2D} family and how to merge arrays with the same number of rows without duplicating data. \subsection{General features of the \ttcode{Array2D}} The \code{Array2D} is a family of array/vectors/points proposing much functionality allowing to add/remove rows/columns. It is also possible to resize them in a conservative way. It is also possible to merge them if the dimensions agreed. Each columns in an \code{Array2D} is in a contiguous memory block. Thus, all operations on the columns are fast as it does not involve data copy. This is not the case for the rows. Inserting or appending rows will cause in the worse cases, that is if the number of rows required is greater than the capacities of the columns, a re-allocation of a part (all) the columns. \subsection{Adding rows and columns to \ttcode{Array2D}} All the \code{Array2D} (That is the arrays deriving from the interface class \code{IArray2D}) can add, insert, remove rows or columns to an existing data set. In this first example, we add columns to an \code{Array2D} \begin{minipage}[t]{0.5\textwidth} \lstinputlisting[style=customcpp,caption=Adding columns]{programs/tutoAddingCols.cpp} \end{minipage} \hspace{0.2cm} \begin{minipage}[t]{0.5\textwidth} \addtocounter{lstlisting}{-1} \lstinputlisting[style=customcpp,caption=Output]{programs/tutoAddingCols.out} \end{minipage} And in this second example, we add rows to an \code{Array2D} \begin{minipage}[t]{0.5\textwidth} \lstinputlisting[style=customcpp,caption=Adding rows]{programs/tutoAddingRows.cpp} \end{minipage} \hspace{0.2cm} \begin{minipage}[t]{0.5\textwidth} \addtocounter{lstlisting}{-1} \lstinputlisting[style=customcpp,caption=Output]{programs/tutoAddingRows.out} \end{minipage} \begin{note} It is important to observe that adding/inserting columns to an \code{Array2D} does not produce any copy of the data stored, while the same operations involving the rows of the array will produce data movement. The next graphic give the execution time of the following code \begin{lstlisting}[style=customcpp] A.pushFrontCols(Const::VectorX(m)); A.insertCols(2, 2); A.col(2) = A.col(1).square(); A.col(3) = A.col(1).cube(); A.pushBackCols(2); A.col(5) = A.col(4).square(); A.col(6) = A.col(4).cube(); \end{lstlisting} and of the same code by replacing "Cols" by "Rows". The size of the array \code{A} was $(m,m)$. It is easily observed that adding rows is time consuming. Observe also that a small amount of space is added at the creation of the object and that the usage of the \code{reserve} method can be wise in order to save time. \begin{center} \includegraphics{images/benchAdd.png} \end{center} \end{note} \subsection{Removing Rows and Columns} Rows and columns can be also removed from arrays of the \code{Array2D} family using \code{remove} and \code{popBack} methods. \begin{minipage}[t]{0.5\textwidth} \lstinputlisting[style=customcpp,caption=Removing rows and columns]{programs/tutoRemoveRowsAndCols.cpp} \end{minipage} \hspace{0.2cm} \begin{minipage}[t]{0.5\textwidth} \addtocounter{lstlisting}{-1} \lstinputlisting[style=customcpp,caption=Output]{programs/tutoRemoveRowsAndCols.out} \end{minipage} \subsection{Merging two arrays} It is possible to merge an array with an other array or vector without copying the data using the merge method. \begin{minipage}[t]{0.66\textwidth} \lstinputlisting[style=customcpp,caption=Merge an array with an array and a vector]{programs/tutoMergeArrays2D.cpp} \end{minipage} \hspace{0.2cm} \begin{minipage}[t]{0.33\textwidth} \addtocounter{lstlisting}{-1} \lstinputlisting[style=customcpp,caption=Output]{programs/tutoMergeArrays2D.out} \end{minipage} \section{Using Visitors, Appliers and Functors} This page explains \stkpp{}'s visitors and appliers and how they can be used on the arrays and in expressions. \subsection{Visitors} A visitor is a constant function applied to an expression or array returning a single value. One of the most useful visitor is \code{ExprBase::sum()}, returning the sum of all the coefficients of a given expression or array. Visitors can also be used to obtain the location of an element inside an Expression or Array. This is the case of \code{ExprBase::maxElt(i,j)}, \code{ExprBase::maxElt(i) }, \code{ExprBase::minElt(i,j)} and \code{ExprBase::minElt(i)}, which can be used to find the location of the greatest or smallest coefficient in an Expression or an Array. The \code{minElt} method should not be confounded with the \code{min} method which compute the minimum between two arrays. The next example shows different usage of visitors \begin{minipage}[t]{0.66\textwidth} \lstinputlisting[style=customcpp,caption=Usage of the visitors]{programs/tutoVisitors.cpp} \end{minipage} \hspace{0.2cm} \begin{minipage}[t]{0.33\textwidth} \addtocounter{lstlisting}{-1} \lstinputlisting[style=customcpp,caption=Output]{programs/tutoVisitors.out} \end{minipage} \subsection{Slicing Visitors} A visitor can also be applied on each column/row of an Expression or Array by using global functions in the \code{STK} namespace. All the visitors can be used as slicing visitors except the \code{minElt} with arguments. \begin{minipage}[t]{0.6\textwidth} \lstinputlisting[style=customcpp,caption=Slicing visitors]{programs/tutoSlicingVisitors.cpp} \end{minipage} \hspace{0.2cm} \begin{minipage}[t]{0.39\textwidth} \addtocounter{lstlisting}{-1} \lstinputlisting[style=customcpp,caption=Output]{programs/tutoSlicingVisitors.out} \end{minipage} \subsection{Appliers} An applier is like a visitor except that it can only be applied to arrays as it will modify the content of the array. Slicing appliers does not have any meaning and thus an applier can only be used on a whole expression. If you need to use an applier on a row or column use the \code{col} or \code{row} method. \begin{minipage}[t]{0.5\textwidth} \lstinputlisting[style=customcpp,caption=Appliers]{programs/tutoAppliers.cpp} \end{minipage} \hspace{0.2cm} \begin{minipage}[t]{0.5\textwidth} \addtocounter{lstlisting}{-1} \lstinputlisting[style=customcpp,caption=Output]{programs/tutoAppliers.out} \end{minipage} \subsection{Functors} Functors can fundamentally be used in the same way that slicing visitors. The only difference is that they return an \code{Array2DPoint} if they are applied by column or an \code{Array2DVector} if they are applied by rows. Recall that it is possible to use the \code{move} method in order to store the results of the computation without data copy. All the functors are in the \code{Stat} namespace and compute the usual statistics by columns or rows. If there is the possibility of missing/NaN values add the word Safe to the name of the functor. If the mean by row is needed, just add ByRow to the name of the functor. If you want both add SafeByRow. \begin{minipage}[t]{0.5\textwidth} \lstinputlisting[style=customcpp,caption=Functors]{programs/tutoStatFunctors.cpp} \end{minipage} \hspace{0.2cm} \begin{minipage}[t]{0.5\textwidth} \addtocounter{lstlisting}{-1} \lstinputlisting[style=customcpp,caption=Output]{programs/tutoStatFunctors.out} \end{minipage} \section{Slicing arrays and expressions} This part explains the slicing operations. A slice is a rectangular part of an array or expression. Arrays slices can be used both as \ttcode{rvalue} and as \ttcode{lvalue} while Expression slice can only be used as \ttcode{rvalue}. \subsection{Rows and Columns} Individual columns and rows of arrays and expressions can be accessed using \code{ExprBase::col()} and \code{ExprBase::row()} as \ttcode{rvalue} and using \code{ArrayBase::col()} and \code{ArrayBase::row()} methods as \ttcode{lvalue}. The argument for \code{col()} and \code{row()} is the index of the column or row to be accessed. \begin{minipage}[t]{0.5\textwidth} \lstinputlisting[style=customcpp,caption=Rows and columns slice]{programs/tutoRowsAndCols.cpp} \end{minipage} \hspace{0.2cm} \begin{minipage}[t]{0.5\textwidth} \addtocounter{lstlisting}{-1} \lstinputlisting[style=customcpp,caption=Output]{programs/tutoRowsAndCols.out} \end{minipage} \subsection{sub-Arrays and sub-Vectors} The most general sub operation is named \code{sub()}. There are two versions, one for arrays, an other for vectors. The sub-Arrays and sub-vectors can be employed as \ttcode{rvalue} or \ttcode{lvalue}, meaning you can assign or reference a sub-array or sub-vector. \begin{minipage}[t]{0.5\textwidth} \lstinputlisting[style=customcpp,caption=sub arrays and vectors]{programs/tutoSubArrays.cpp} \end{minipage} \hspace{0.2cm} \begin{minipage}[t]{0.5\textwidth} \addtocounter{lstlisting}{-1} \lstinputlisting[style=customcpp,caption=Output]{programs/tutoSubArrays.out} \end{minipage} \section{Using reference arrays} This part explains how to create reference on existing arrays. \subsection{Creating reference to sub-arrays} Any slice of an existing array can be referenced by an other array and modified using this "reference" container. This is achieved using the copy constructor with reference as \code{true}. \begin{minipage}[t]{0.5\textwidth} \lstinputlisting[style=customcpp,caption=Referencing sub-arrays]{programs/tutoReference.cpp} \end{minipage} \hspace{0.2cm} \begin{minipage}[t]{0.5\textwidth} \addtocounter{lstlisting}{-1} \lstinputlisting[style=customcpp,caption=Output]{programs/tutoReference.out} \end{minipage} This method allows to get a safe access to some sub-part of a big array that you want to modify. \begin{warning} It is the responsibility of the user to verify that a reference is valid. \end{warning} \subsection{Creating reference to raw data} It is possible to map a single pointer \code{Type*} or a double pointer \code{Type**} in respectively \code{CArray} and \code{Array2D} using the dedicated constructors. In this constructor, we wrap the data pointed by \code{q} in an array with rows in the range $I$ and columns in the range $J$. \begin{lstlisting}[style=customcpp,caption=Wrapping raw data in Array2D] Array2D( Type** q, Range const& I, Range const& J); \end{lstlisting} In this example we create an array of size (10,5) and wrap it in an \code{Array2D}. \begin{lstlisting}[style=customcpp,caption=Example of wrapping by Array2D] Real** q = new Real*[10]; for (int j=0; j<10; j++) { q[j] = new Real[5];} //wrap q. Note that q will not be freed when a is deleted Array2D a(q, Range(0,10), Range(0,5)); \end{lstlisting} In this constructor, we wrap the data pointed by \code{q} in an array with rows and columns of size $m$ and $n$. \begin{lstlisting}[style=customcpp,caption=Wrapping raw data in CArray] CArray( Type* q, int m, int n); \end{lstlisting} In this example we create an array of size (10, 5) and wrap it in a \code{CArray}. \begin{lstlisting}[style=customcpp],caption=Example of wrapping by CArray] Real* q = new Real[10]; for (int j=0; j<10; j++) { q[j] = j;} //wrap q in a fixed size array of size (2,5). // Note that q will not be freed when a is deleted CArray a(q, 2, 5); \end{lstlisting} %\bibliographystyle{plain} %\bibliography{rtkore} \end{document}