[Toon-members] TooN doc/documentation.h internal/allocator.hh ...

[Edward Rosten]

CVSROOT:        /cvsroot/toon
Module name:    TooN
Changes by:     Edward Rosten <edrosten>        10/01/18 15:32:13

Modified files:
        doc            : documentation.h 
        internal       : allocator.hh vector.hh 
        regressions    : vector_resize.cc vector_resize.txt 

Log message:
        vector<Resizable> now resizes on assignment. Safe to use in the STL.
        
        All methods potentially causing resize call try_destructive_resize().
        
        The method is a no-op for static and dynamic vectors, and for assignment
        from non-sized Operator<>s. 

CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/TooN/doc/documentation.h?cvsroot=toon&r1=1.43&r2=1.44
http://cvs.savannah.gnu.org/viewcvs/TooN/internal/allocator.hh?cvsroot=toon&r1=1.36&r2=1.37
http://cvs.savannah.gnu.org/viewcvs/TooN/internal/vector.hh?cvsroot=toon&r1=1.53&r2=1.54
http://cvs.savannah.gnu.org/viewcvs/TooN/regressions/vector_resize.cc?cvsroot=toon&r1=1.1&r2=1.2
http://cvs.savannah.gnu.org/viewcvs/TooN/regressions/vector_resize.txt?cvsroot=toon&r1=1.1&r2=1.2

Patches:
Index: doc/documentation.h
===================================================================
RCS file: /cvsroot/toon/TooN/doc/documentation.h,v
retrieving revision 1.43
retrieving revision 1.44
diff -u -b -r1.43 -r1.44
--- doc/documentation.h 11 Jan 2010 14:59:12 -0000      1.43
+++ doc/documentation.h 18 Jan 2010 15:32:13 -0000      1.44
@@ -62,6 +62,7 @@
  - \ref sInitialize
  - \ref sScalars
  - \ref ssExamples
+ - \ref sSTL
  - \ref sResize
  - \ref sDebug
  - \ref sSlices
@@ -376,6 +377,11 @@
        trying to assign a vector of length 2 to a vector of length 3 is an 
error,
        so it fails. See also \ref sResize
 
+       \subsection sSTL How do I store Dynamic vectors in STL containers.
+
+       As C++ does not yet support move semantics, you can only safely store
+       static and resizable Vectors in STL containers.
+
        \subsection sResize How do I resize a dynamic vector/matrix?
 
        Do you really want to? If you do, then you have to declare it:
@@ -385,16 +391,27 @@
                 v.resize(3);
                 v = makeVector(1, 2, 3);
 
-                v = makeVector(1, 2); //Error!
-       @endcode
-
-       The policy behind the design of TooN is that it is a linear algebra 
library,
-       not a generic container library, so resizable vectors <b>ONLY</b> change
-       their size with a call to <code>.resize()</code>.  Assigning mismatched
-       sizes is a fatal error, just like with static and dynamic vectors. 
Resizing
-       is efficient since it is implemented internally with
-       <code>std::vector</code>.  Note that upon resize, existing data 
elements are
-       retained but new data elements are uninitialized.
+                v = makeVector(1, 2); //resize
+                v = Ones(5); //resize
+                v = Zeros; // no resize
+       @endcode
+
+       The policy behind the design of TooN is that it is a linear algebra
+       library, not a generic container library, so resizable Vectors are only
+       created on request. They provide fewer guarantees than other vectors, so
+       errors are likely to be more subtle and harder to track down.  One of 
the
+       main purposes is to be able to store Dynamic vectors of various sizes in
+       STL containers.
+
+       Assigning vectors of mismatched sizes will cause an automatic resize. 
Likewise
+       assigning from entities like Ones with a size specified will cause a 
resize.
+       Assigning from an entities like Ones with no size specified will not 
cause
+       a resize.
+
+       They can also be resized with an explicit call to .resize().
+       Resizing is efficient since it is implemented internally with
+       <code>std::vector</code>.  Note that upon resize, existing data elements
+       are retained but new data elements are uninitialized.
 
        Currently, resizable matrices are unimplemented.  If you want a 
resizable
        matrix, you may consider using a <code>std::vector</code>, and 
accessing it

Index: internal/allocator.hh
===================================================================
RCS file: /cvsroot/toon/TooN/internal/allocator.hh,v
retrieving revision 1.36
retrieving revision 1.37
diff -u -b -r1.36 -r1.37
--- internal/allocator.hh       14 Oct 2009 11:20:36 -0000      1.36
+++ internal/allocator.hh       18 Jan 2010 15:32:13 -0000      1.37
@@ -108,7 +108,9 @@
 
 
 ///@internal
-///@brief Allocate memory for a Vector.
+///@brief Allocate memory for a static sized Vector.
+///The class switches to heap allocation automatically for large Vectors.
+///Naturally, the vector is not resizable.
 ///@ingroup gInternal
 template<int Size, class Precision> struct VectorAlloc : public 
StaticSizedAllocator<Size, Precision> {
        
@@ -151,8 +153,18 @@
                        return my_data;
                };
 
+               void try_destructive_resize(int)
+               {}
+
+               template<class Op> void try_destructive_resize(const 
Operator<Op>&) 
+               {}
+
 };
 
+///@internal
+///@brief Allocate memory for a dynamic sized Vector.
+///This is not resizable.
+///@ingroup gInternal
 template<class Precision> struct VectorAlloc<Dynamic, Precision> {
        Precision * const my_data;
        const int my_size;
@@ -206,9 +218,20 @@
                {
                        return my_data;
                };
+
+               void try_destructive_resize(int)
+               {}
+
+               template<class Op> void try_destructive_resize(const 
Operator<Op>&) 
+               {}
 };
 
 
+///@internal
+///@brief Allocate memory for a resizable Vector.
+///New elements available after a resize are treated as
+///uninitialized. 
+///@ingroup gInternal
 template<class Precision> struct VectorAlloc<Resizable, Precision> {
        protected: 
                std::vector<Precision> numbers;
@@ -256,6 +279,37 @@
                        return &numbers[0];
                }
 
+       private:
+               //Dymmy class for implementing sfinae
+               //in order to test for a .size() member
+               template<int S> struct SFINAE_dummy{};
+       
+       protected:
+
+               //SFINAE implementation of try_destructive_resize
+               //to avoid calling .size if it does not exist!
+
+               //Force the function TYPE to depend on a property
+               //of the Operator<Op> type, so that it simply does
+               //not exist if the property is missing.
+               //Therefore this method only uses .size() if it exists.
+               template<class Op> 
+               SFINAE_dummy<sizeof(&Operator<Op>::size)> 
try_destructive_resize(const Operator<Op>& op) 
+               {
+                       try_destructive_resize(op.size());
+               }
+               
+               //Catch-all do nothing for operators with no size method.
+               template<class Op>
+               void try_destructive_resize(const Op&)
+               {}
+
+               void try_destructive_resize(int newsize)
+               {
+                       numbers.resize(newsize);
+                       debug_initialize(data(), newsize);
+               }
+
        public:
 
                void resize(int s)
@@ -267,6 +321,10 @@
                }
 };
 
+///@internal
+///@brief Hold a pointer to yield a statically sized slice of a Vector.
+///Not resizable.
+///@ingroup gInternal
 template<int S, class Precision> struct VectorSlice
 {
        int size() const {
@@ -295,9 +353,19 @@
                {
                        return my_data;
                };
+
+               void try_destructive_resize(int)
+               {}
+
+               template<class Op> void try_destructive_resize(const 
Operator<Op>&) 
+               {}
 };
 
-template<class Precision> struct VectorSlice<-1, Precision>
+///@internal
+///@brief Hold a pointer to yield a dynamically sized slice of a Vector.
+///Not resizable.
+///@ingroup gInternal
+template<class Precision> struct VectorSlice<Dynamic, Precision>
 {
        Precision* const my_data;
        const int my_size;
@@ -324,6 +392,12 @@
                {
                        return my_data;
                };
+
+               void try_destructive_resize(int)
+               {}
+
+               template<class Op> void try_destructive_resize(const 
Operator<Op>&) 
+               {}
 };
 
 

Index: internal/vector.hh
===================================================================
RCS file: /cvsroot/toon/TooN/internal/vector.hh,v
retrieving revision 1.53
retrieving revision 1.54
diff -u -b -r1.53 -r1.54
--- internal/vector.hh  27 Oct 2009 16:05:40 -0000      1.53
+++ internal/vector.hh  18 Jan 2010 15:32:13 -0000      1.54
@@ -230,7 +230,10 @@
        /// @{
 
        /// operator = from copy
+       /// A size mismatch is a fatal error, unless the destination
+       /// is resizable.
        inline Vector& operator= (const Vector& from){
+               try_destructive_resize(from.size());
                SizeMismatch<Size,Size>::test(size(), from.size());
                const int s=size();
                for(int i=0; i<s; i++){
@@ -240,8 +243,11 @@
        }
 
        /// operator = another Vector
+       /// A size mismatch is a fatal error, unless the destination
+       /// is resizable.
        template<int Size2, typename Precision2, typename Base2>
        Vector<Size,Precision,Base >& operator= (const Vector<Size2, 
Precision2, Base2>& from){
+               try_destructive_resize(from.size());
                SizeMismatch<Size,Size2>::test(size(), from.size());
                const int s=size();
                for(int i=0; i<s; i++){
@@ -251,8 +257,12 @@
        }
 
        /// assignment from an Operator object
+       /// Assignment from sized operators causes a resize
+       /// of Resizable Vectors. Assignment from unsized
+       /// operators dows not.
        template <class Op>
        inline Vector & operator=(const Operator<Op>& op){
+               try_destructive_resize(op);
                op.eval(*this);
                return *this;
        }

Index: regressions/vector_resize.cc
===================================================================
RCS file: /cvsroot/toon/TooN/regressions/vector_resize.cc,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -b -r1.1 -r1.2
--- regressions/vector_resize.cc        29 Sep 2009 12:47:49 -0000      1.1
+++ regressions/vector_resize.cc        18 Jan 2010 15:32:13 -0000      1.2
@@ -4,25 +4,29 @@
 
 int main()
 {
-       Vector<Resizable> r = makeVector(4);
-       Vector<> v1(makeVector(1, 2));
-
+       Vector<Resizable> r = makeVector(4.);
        cout << r << endl;
        
+       //Test simple resize
+       Vector<> v1(makeVector(1, 2));
        r.resize(v1.size());
        r = v1;
        cout << r << endl;
+
+       //Test automatic resize
        Vector<3> v2 = makeVector(2, 3, 4);
-       r.resize(3);
        r = v2;
        cout << r << endl;
        
+       //Test non-sized operator
        r.resize(10);
        r = Ones;
+       cout << r << endl;
 
+       //Test sized operator
+       r = Zeros(3);
        cout << r << endl;
 
-       r.resize(5);
        r = makeVector(6, 7, 8, 9, 0);
        cout << r << endl;
 

Index: regressions/vector_resize.txt
===================================================================
RCS file: /cvsroot/toon/TooN/regressions/vector_resize.txt,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -b -r1.1 -r1.2
--- regressions/vector_resize.txt       29 Sep 2009 12:47:49 -0000      1.1
+++ regressions/vector_resize.txt       18 Jan 2010 15:32:13 -0000      1.2
@@ -2,5 +2,6 @@
 1 2 
 2 3 4 
 1 1 1 1 1 1 1 1 1 1 
+0 0 0
 6 7 8 9 0 
 5 6