Ignore:
Timestamp:
Feb 7, 2008, 12:56:23 AM (13 years ago)
Author:
Peter
Message:

some dox - refs #256

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/yat/utility/VectorView.h

    r1027 r1046  
    4747
    4848  /**
    49      @brief This is the yat interface to GSL vector.
     49     @brief This is the yat interface to gsl_vector_view.
    5050
    51      For time being 'double' is the only type supported.
     51     This class can be used to create a vector view into a Matrix or a
     52     VectorMutable. Modifying a view will also modify the underlying
     53     data, i.e., the Matrix or VectorMutable that is viewed into. For
     54     that reason all constructors are taking non-const references to
     55     disallow mutable views into a const objects.
    5256
    53      \par File streams:
    54      Reading and writing vectors to file streams are of course
    55      supported. These are implemented without using GSL functionality,
    56      and thus binary read and write to streams are not supported.
     57     The fact that there is no copy constructor with const argument,
     58     but only a so-called move constructor (copying a non-const
     59     reference), implies that temporary objects such as objects
     60     returned from functions can not be copied directly. Instead the
     61     copying is done via a proxy class (see VectorMutable). Also since
     62     we can not bind a temporary to a non-const reference, a
     63     VectorView returned from a function cannot be sent directly to a
     64     function.
     65     For example
     66     @code
     67     Matrix m(10,10);
     68     sum(m.row_view(0));
     69     @endcode
     70     but you need to use create a dummie object
     71     @code
     72     Matrix m(10,10);
     73     VectorView vv = m.row_view(0);
     74     sum(vv);
     75     @endcode
     76     or since sum is a const function, you can use VectorConstView
     77     @code
     78     Matrix m(10,10);
     79     sum(m.row_const_view(0));
     80     @endcode
    5781
    58      \par Vector views:
    59      GSL vector views are supported and these are disguised as
    60      ordinary utility::vectors. A support function is added,
    61      utility::vector::isview(), that can be used to check if a vector
    62      object is a view. Note that view vectors do not own the
    63      underlying data, and a view is not valid if the vector/matrix
    64      owing the data is deallocated.
    65 
    66      \par
    67      Currently there is no restriction on how a vector is used when
    68      the vector is a const view into another vector or matrix. To
    69      avoid unexpected runtime errors, the programmer must declare
    70      const view vectors as 'const' in order to get compile time
    71      diagnostics about improper use of a const view vector object. If
    72      'const' is not used and the const view vector is used erroneously
    73      (such as on the left hand side in assignments), the compiler will
    74      not catch the error and runtime error will occur. assert(3) is
    75      used to catch the runtime error during development. Example on
    76      bad and proper use of const view vectors:
    77      @code
    78   const vector vm(13,1.0);
    79   vector v1(vm,2,4);       // bad code! not const!
    80   v1(0)=-123;              // accepted by compiler, runtime abort will occur
    81                            // or catched by assert depending on compiler flags
    82   const vector v2(vm,2,4); // proper code
    83   v2(0)=-123;              // not acceptable for the compiler
    84      @endcode
     82     Note that VectorView does not own underlying data, and a
     83     VectorView is not valid if Vector/Matrix owning the data is
     84     deallocated.
    8585  */
    86 
    8786  class VectorView : public VectorMutable
    8887  {
     
    9089    /**
    9190       \brief Default constructor.
     91
     92       Creates a view into nothing and behaves like an empty vector.
    9293    */
    9394    VectorView(void);
     
    9596    /**
    9697       \brief The copy constructor.
     98
     99       Modifications to created VectorView will also modify \a
     100       other. Created VectorView is not dependent on \a other, but if
     101       underlying data (Vector or Matrix) is deallocated VectorView is
     102       invalid.
    97103    */
     104    VectorView(VectorView& other);
     105
     106    /**
     107       \brief copy another VectorMutable
     108
     109       \note If the object viewed by the view goes out of scope or is
     110       deleted, the view becomes invalid and the result of further use
     111       is undefined.
     112    */
    98113    VectorView(VectorMutable& other);
    99     VectorView(VectorView& other);
    100114
    101115    /**
    102116       \brief VectorView constructor.
    103117
    104        Create a view of VectorView \a v, with starting index \a offset,
     118       Create a view of VectorMutable \a v, with starting index \a offset,
    105119       size \a n, and an optional \a stride.
    106 
    107        A VectorView view can be used as any VectorView with the difference
    108        that changes made to the view will also change the object that
    109        is viewed. Also, using the copy constructor will create a new
    110        VectorView object that is a copy of whatever is viewed. If a copy
    111        of the view is needed then you should use this constructor to
    112        obtain a copy.
    113120
    114121       \note If the object viewed by the view goes out of scope or is
     
    129136    /// naturally, a column view otherwise.
    130137    ///
    131     /// A VectorView view can be used as any VectorView with the difference
    132     /// that changes made to the view will also change the object that
    133     /// is viewed. Also, using the copy constructor will create a new
    134     /// VectorView object that is a copy of whatever is viewed. If a copy
    135     /// of the view is needed then you should use the VectorView view
    136     /// constructor to obtain a copy.
     138    /// A VectorView view can be used as any VectorMutable with the
     139    /// difference that changes made to the view will also change the
     140    /// object that is viewed.
    137141    ///
    138142    /// @note If the object viewed by the view goes out of scope or is
     
    143147
    144148    /**
     149       \brief create VectorView from proxy class
    145150     */
    146151    VectorView(proxy p);
     
    161166       \return A const reference to the resulting vector.
    162167
     168       \note modifies underlying data.
     169
     170       \throw GSL_error if dimensions mis-match.
     171    */
     172    const VectorView& operator=(const VectorView&);
     173
     174    /**
     175       \brief The assignment operator.
     176
     177       \return A const reference to the resulting vector.
     178
     179       \note modifies underlying data.
     180
    163181       \throw GSL_error if dimensions mis-match.
    164182    */
    165183    const VectorView& operator=(const VectorBase&);
    166     const VectorView& operator=(const VectorView&);
    167184
    168185  private:
     
    171188
    172189    gsl_vector_view* view_;
    173     gsl_vector_const_view* const_view_;
    174    
    175190  };
    176191
Note: See TracChangeset for help on using the changeset viewer.