[Pkg-octave-commit] [SCM] octave-triangular branch, master, updated. 0815cd5456ab65e0f196623742bfdcc3d7e377b4

Fri May 22 02:00:38 UTC 2009

The following commit has been merged in the master branch:
commit 0815cd5456ab65e0f196623742bfdcc3d7e377b4
Author: Rafael Laboissiere <rafael at debian.org>
Date:   Fri May 22 03:59:25 2009 +0200

    Add source for info file inst/doc.info
    
    The file was taken from upstream SVN:
    http://octave.svn.sourceforge.net/viewvc/octave/trunk/octave-forge/extra/triangular/doc/triangular.texi?view=log
    This makes the package DFSG-compliant.

diff --git a/debian/patches/documentation-source.diff b/debian/patches/documentation-source.diff
new file mode 100644
index 0000000..b325bfb
--- /dev/null
+++ b/debian/patches/documentation-source.diff
@@ -0,0 +1,162 @@
+Add source for the info documentation inst/doc.info
+
+ -- Rafael Laboissiere <rafael at debian.org>  Fri, 22 May 2009 03:54:39 +0200
+
+--- /dev/null
++++ b/inst/triangular.texi
+@@ -0,0 +1,155 @@
++\input texinfo
++
++ at setfilename triangular.info
++
++ at settitle
++
++ at titlepage
++ at title  Example C++ User Type for Octave
++ at subtitle June 2007
++ at author David Bateman
++ at page
++ at vskip 0pt plus 1filll
++Copyright @copyright{} 2007
++
++Permission is granted to make and distribute verbatim copies of
++this manual provided the copyright notice and this permission notice
++are preserved on all copies.
++
++Permission is granted to copy and distribute modified versions of this
++manual under the conditions for verbatim copying, provided that the entire
++resulting derived work is distributed under the terms of a permission
++notice identical to this one.
++
++Permission is granted to copy and distribute translations of this manual
++into another language, under the same conditions as for modified versions.
++ at end titlepage
++
++ at contents
++
++ at ifinfo
++ at node Top, User Types in Oct-Files
++ at top
++ at end ifinfo
++
++ at menu
++* User Types in Oct-Files::
++ at end menu
++
++ at node User Types in Oct-Files
++ at chapter User Types in Oct-Files
++
++As Octave is written largely in C++, it can benefit from all of the
++object oriented programming capabilities of the C++ language. This makes
++it easy to add additional types to the Octave scripting language using
++the overloading capabilities of the C++ language.
++
++Any of the existing Octave classes might be used as a basis for a new
++C++ class representing the new type. The basic class for the new user
++type to inherit from is @code{octave_base_value}, that contains all the
++default behaviors for the basic functionality of all Octave classes. 
++
++The following pages includes a simple example of a user type in an
++oct-file. It produces a new type for triangular matrices based on the
++ at code{octave_matrix} class, and overloads certain operators including
++the left division operator, to allow rapid solution of linear equations
++including triangular 
++
++ at example
++ at verbatiminclude uppertri.cc
++ at end example
++
++It should be noted that the above class, is given as an example only, as
++Octave includes the ability to identify triangular matrices and use
++the appropriate method for the left division operator. It is however
++useful as an example.
++
++Before the new user type can be used, it has to be registered as a valid
++Octave type. This is performed by the @code{register_type} method in the
++ at code{install_triangular} function above. The @code{install_triangular}
++function also sets up the overloaded functions in the
++ at code{install_tri_ops} function.  A number of functions are overloaded,
++including the transpose, unary operators and the left division
++operators. Also note that there are three different assignment operators
++defined.
++
++Finally, the constructor functions are locked in to Octave memory with
++the @code{mlock} function. The reason the constructor functions need to
++be locked into memory is that
++
++ at example
++ at group
++a = uppertri (randn (3,3));
++clear uppertri
++disp(a)
++ at end group
++ at end example
++
++ at noindent
++would result in @code{a} being left defined, but the type it refers to
++being cleared from Octave's memory. The next reference to @code{a}, will
++then result in Octave exiting abnormally.
++
++Note that in most ways user types have the same capabilities as any
++other Octave type. There are a few minor points were user types
++differ. Firstly, as the @code{octave_value} class has no knowledge of
++the user type, extracting the user type from the @code{octave_value} or
++setting the @code{octave_value} to the user type is necessarily
++different. Extracting the user type from the @code{octave_value} is done
++with 
++
++ at example
++ at group
++const octave_triangular_matrix ((const octave_triangular_matrix&) 
++        args(0).get_rep();
++ at end group
++ at end example
++
++ at noindent
++and setting the @code{octave_value} is done with
++
++ at example
++ at group
++octave_value retval = new octave_triangular_matrix (@dots{})
++retval.maybe_mutate ();
++ at end group
++ at end example
++
++It should be noted that the normal @code{octave_value} constructors call
++the @code{maybe_mutate} method, that check whether the previous
++operations should result in the type of the returned value being
++changed, using the @code{try_narrowing_conversion} function. The
++constructor functions in the example code, know the type won't change
++and so can ignore te @code{maybe_mutate} functions.
++
++Two other important functions in the above class are the @code{subsref}
++and @code{subsasgn} functions. The @code{subsref} function is used for
++indexed referencing of variable of the user type such as @code{a (1)},
++ at code{a.type} or even @code{a (1).type}. The @code{subsasgn} function is
++similar, but is used for indexed assignments to the user type (ie. when
++the variable is on the left-hand side of the assigment). 
++
++It should be noted that to allow assignments such as
++
++ at example
++ at group
++a = uppertri (@dots{});
++a.type = @dots{};
++ at end group
++ at end example
++
++ at noindent
++to work as expected, then the user type must be declared as a map by
++having the @code{is_map} method return true. The use of  ".type" above
++to reference the type of the triangular matrix, is not necessarily
++recommended, but is rather an indication of how this type of indexing
++might be implemented.
++
++A final important function included in the above class is the
++ at code{numeric_conversion_function}. This returns a pointer to a
++function, that converts the triangular matrix to a normal Octave
++matrix. This allows the operators for normal Octave matrices to be
++applied to the user defined triangular matrices, with the return type
++being a normal Octave matrix type.
++
++ at bye
diff --git a/debian/patches/series b/debian/patches/series
new file mode 100644
index 0000000..2c26f9a
--- /dev/null
+++ b/debian/patches/series
@@ -0,0 +1 @@
+documentation-source.diff

-- 
octave-triangular

