[Toon-members] TooN/doc vectordoc.h

[Tom Drummond]

CVSROOT:        /cvsroot/toon
Module name:    TooN
Changes by:     Tom Drummond <twd20>    09/04/02 03:56:39

Modified files:
        doc            : vectordoc.h 

Log message:
        work on bringing documentation up to date for Vector
        still more do to

CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/TooN/doc/vectordoc.h?cvsroot=toon&r1=1.8&r2=1.9

Patches:
Index: vectordoc.h
===================================================================
RCS file: /cvsroot/toon/TooN/doc/vectordoc.h,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -b -r1.8 -r1.9
--- vectordoc.h 11 Mar 2007 21:47:33 -0000      1.8
+++ vectordoc.h 2 Apr 2009 03:56:38 -0000       1.9
@@ -1,3 +1,4 @@
+// -*- c++ -*-
 /*
     Copyright (c) 2005 Paul Smith
 
@@ -24,20 +25,19 @@
 namespace TooN
 {
 
-/// An object to create a Vector from a list of numbers. See the detailed 
documentation
-/// for Vector for information on usage.
-struct make_Vector
-{
-       /// Overloaded operator to allow this object to interpret a list of 
numbers after it
-       /// as elements for a vector.
-       VectorCreator operator,(const T& t);
-};
+       /// A symbolic constant used as the size argument for dynamically sized 
vectors and matrices
+       const int Dynamic=1;
+
+       /// A series of overloaded functions to create a Vector from a list of 
numbers. See the detailed documentation
+       /// for Vector for information on usage.
+       Vector<> make_Vector(int, ... , int);
 
+#if 0
 /// Helper function to skip elements when using the <code>operator><<</code> 
initialisation
 /// for Vector. See the detailed documentation for Vector for information on 
usage.
 template <int N>
 ComponentPlaceHolder<N> no_change();
-
+#endif
 
 /**
 @class Vector vectordoc.h TooN/toon.h
@@ -75,48 +75,54 @@
 }
 @endcode
 
-The preferred way of defining a vector is to use make_Vector. The %make_Vector 
object constructs
-a static vector initialised to the size and the contents of the 
comma-separated list following it. 
-This magic is performed by overloading the comma operator, but for this to 
work, the expression
-must be enclosed in brackets (see the examples). The %make_Vector vectors are 
real Vectors and 
-so can be used anywhere where a vector is needed, not just in initialisations. 
For example
+The preferred way of defining a vector is to use make_Vector. The
+%make_Vector function constructs a static vector initialised to the
+size and the contents of the comma-separated list of argments.  The
+%make_Vector vectors are real Vectors and so can be used anywhere
+where a vector is needed, not just in initialisations. For example
+
 @code
 // Create a vector initialised to [1 2 3];
-Vector<3> v = (make_Vector, 1, 2, 3);
+Vector<3> v = make_Vector(1, 2, 3);
 // Calculate the dot product with the vector [4 0 6]
-double dot = v * (make_Vector, 4, 0, 6);
+double dot = v * make_Vector(4, 0, 6);
 @endcode
 Because the %make_Vector syntax creates actual vectors, compile-time checking 
is done to ensure
 that all vectors defined in this way have the correct number of elements.
+**/
 
-An alternative means of assigning values to vectors is to use the overloaded 
<code>operator=</code> function
-with a comma-separated list of doubles (or anything that can be cast to a 
double):
address@hidden
-// Create a vector initialised to [1 2 3];
-Vector<3> v;
-v = 1, 2, 3;
address@hidden
-This is more concise than the %make_Vector syntax, but can only be used for 
assigning values to 
-existing vectors, and only generates a compile-time error if the list is too 
long, not too 
-short (in which case a run-time error is generated instead).
-
-An third means of defining vectors is to use the overloaded 
<code>operator<<</code> function. This 
-allows particular ranges of elements to be modified, since the operator 
sequentially replaces
-elements in order, as the example below shows. The templated no_change() 
object allows runs of
-elements to be skipped.
address@hidden
-// Create a vector initialised to [1 2 3 4];
-Vector<4> v;
-v << 1 << 2 << 3 << 4;
-// Now modify just the first two elements
-v << 5 << 6;   // v is now [5 6 3 4];
-// Now modify the last two
-v << no_change<2>() << 0 << 1;  // v is now [5 6 0 1]
-// Now modify the last middle two
-v << no_change() << 4 << 5;  // v is now [5 4 5 1]   (no_change() is a synonym 
for no_change<1>()
address@hidden
-Compile-time checking is done for attempts to over-fill a matrix. 
 
+// An alternative means of assigning values to vectors is to use the 
overloaded <code>operator=</code> function
+// with a comma-separated list of doubles (or anything that can be cast to a 
double):
+// @code
+// // Create a vector initialised to [1 2 3];
+// Vector<3> v;
+// v = 1, 2, 3;
+// @endcode
+// This is more concise than the %make_Vector syntax, but can only be used for 
assigning values to
+// existing vectors, and only generates a compile-time error if the list is 
too long, not too
+// short (in which case a run-time error is generated instead).
+
+// A third means of defining vectors is to use the overloaded 
<code>operator<<</code> function. This
+// allows particular ranges of elements to be modified, since the operator 
sequentially replaces
+// elements in order, as the example below shows. The templated no_change() 
object allows runs of
+// elements to be skipped.
+// @code
+// // Create a vector initialised to [1 2 3 4];
+// Vector<4> v;
+// v << 1 << 2 << 3 << 4;
+// // Now modify just the first two elements
+// v << 5 << 6;   // v is now [5 6 3 4];
+// // Now modify the last two
+// v << no_change<2>() << 0 << 1;  // v is now [5 6 0 1]
+// // Now modify the last middle two
+// v << no_change() << 4 << 5;  // v is now [5 4 5 1]   (no_change() is a 
synonym for no_change<1>()
+// @endcode
+// Compile-time checking is done for attempts to over-fill a matrix.
+
+
+/**
address@hidden Vector vectordoc.h TooN/toon.h
 \par Dynamically-sized vectors
 
 To create a dynamically sized vector, use:
@@ -130,12 +136,15 @@
   // ...
 }
 @endcode
-Vector<> is actually a synonym for Vector<-1> being a template specialisation 
of Vector<N> with a special implementation.
+Vector<> is actually a synonym for Vector<Dynamic> which is Vector<-1> being a 
template specialisation of Vector<N> with a special implementation.
 
 
 \par Row vectors and column vectors
 
-This library makes no distinction between row vectors and column vectors. 
Vectors that appear on the left of a multiplication are treated as row vectors 
while those that appear on the right are treated as column vectors (thus 
<code>v1*v2</code> means the dot product). This means that sometimes you have 
to be careful to include prarentheses since it is possible to write obscure 
stuff like <code>Vector<4> v4 = v1 * v2 * v3;</code>,
+This library makes no distinction between row vectors and column vectors. 
Vectors that appear on the left of a multiplication are treated as row vectors 
while those that appear on the right are treated as column vectors (thus 
<code>v1*v2</code> means the dot product). This means that sometimes you have 
to be careful to include prarentheses since it is possible to write obscure 
stuff like
address@hidden
+Vector<4> v4 = v1 * v2 * v3;
address@hidden
 which in the absence of any extra parentheses means 'compute the dot product 
between <code>v1</code> and <code>v2</code> and then multiply <code>v3</code> 
by this scalar and assign to <code>v4</code>'.
 
 If the row-column distinction is important, then vectors can be turned into 
matrices with one row or column by using as_row() or as_col():
@@ -147,10 +156,11 @@
 
 @ingroup gLinAlg
 **/
-template<int Size>
-class Vector
-{
-public:
+
+template<int Size=Dynamic, typename Precision=double>
+        class Vector
+        {
+        public:
   /// @name Constructors
   //@{
   
@@ -264,7 +274,7 @@
   double d = a[1];     // now d = 2.0;
   @endcode
   */
-  const double& operator[] (int i) const;
+        const Precision& operator[] (int i) const;
   
   /**
   Access an element from the vector in the usual way.
@@ -276,7 +286,7 @@
   a[1] = 0;        // now a = [1 0 3];
   @endcode
   */
-  double& operator[] (int i);
+        Precision& operator[] (int i);
   
   /// Get the raw double array.
   const double* get_data_ptr() const;
@@ -298,7 +308,7 @@
   Matrix<1,3> m = a.as_row();  // now m = [1 2 3]
   @endcode
   */
-  Matrix<1, Size> as_row();
+        Matrix<1, Size, Precision> as_row();
   
   /**
   Convert this vector into a Size-by-1 matrix, i.e. a matrix which has this
@@ -308,7 +318,7 @@
   Matrix<3,1> m = a.as_col();   // now m = [1 2 3]'
   @endcode
   */
-  Matrix<Size, 1> as_col();
+        Matrix<Size, 1, Precision> as_col();
   
   /**
   Extract a sub-vector. The vector extracted will be begin at element Start
@@ -363,7 +373,7 @@
   template<Start, Length>
   const Vector<Length>& slice() const;
   //@}
-};
+        };
 
 /// @name Input/output
 //@{