Ignore:
Timestamp:
Feb 3, 2008, 2:53:29 AM (15 years ago)
Author:
Peter
Message:

documentation for VectorConstView? and changing name of view functions in matrix

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/yat/utility/VectorConstView.h

    r1027 r1028  
    1010  Copyright (C) 2006 Jari Häkkinen, Markus Ringnér
    1111  Copyright (C) 2007 Jari Häkkinen, Peter Johansson
     12  Copyright (C) 2008 Peter Johansson
    1213
    1314  This file is part of the yat library, http://trac.thep.lu.se/trac/yat
    … …  
    4748
    4849  /**
    49      @brief This is the yat interface to GSL vector.
     50     @brief Read-only view.
    5051
    51      For time being 'double' is the only type supported.
     52     Wrapper to gsl_vector_const_view
    5253
    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.
     54     With this class you can create a view into const
     55     objects - either a vector or matrix. By design all functionality
     56     in this class is const to guarantee that the viewed object is not
     57     modified.
    5758
    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
     59     \Note that view vectors do not own the underlying data,
     60     and a view is not valid if the vector/matrix owing the data is
     61     deallocated.
    8562  */
    86 
    8763  class VectorConstView : public VectorBase
    8864  {
    … …  
    9066    /**
    9167       \brief The copy constructor.
    92     */ 
    93     VectorConstView(const VectorBase& other);
     68    */
     69    // needed to override compiler generated copy constructor
    9470    VectorConstView(const VectorConstView& other);
    9571
    9672    /**
    97        \brief VectorConstView constructor.
     73       \brief Copy a VectorBase
     74    */
     75    VectorConstView(const VectorBase& other);
    9876
    99        Create a view of VectorConstView \a v, with starting index \a offset,
     77    /**
     78       \brief const view into a vector
     79
     80       Create a const view of VectorBase \a v, with starting index \a offset,
    10081       size \a n, and an optional \a stride.
    101 
    102        A VectorConstView view can be used as any VectorConstView with the difference
    103        that changes made to the view will also change the object that
    104        is viewed. Also, using the copy constructor will create a new
    105        VectorConstView object that is a copy of whatever is viewed. If a copy
    106        of the view is needed then you should use this constructor to
    107        obtain a copy.
    10882
    10983       \note If the object viewed by the view goes out of scope or is
    … …  
    11589    VectorConstView(const VectorBase& v,size_t offset,size_t n,size_t stride=1);
    11690
    117     ///
    118     /// Matrix row/column view constructor.
    119     ///
    120     /// Create a row/column VectorConstView view of matrix \a m, pointing at
    121     /// row/column \a i. The parameter \a row is used to set whether
    122     /// the view should be a row or column view. If \a row is set to
    123     /// true, the view will be a row view (default behaviour), and,
    124     /// naturally, a column view otherwise.
    125     ///
    126     /// A VectorConstView view can be used as any VectorConstView with the difference
    127     /// that changes made to the view will also change the object that
    128     /// is viewed. Also, using the copy constructor will create a new
    129     /// VectorConstView object that is a copy of whatever is viewed. If a copy
    130     /// of the view is needed then you should use the VectorConstView view
    131     /// constructor to obtain a copy.
    132     ///
    133     /// @note If the object viewed by the view goes out of scope or is
    134     /// deleted, the view becomes invalid and the result of further
    135     /// use is undefined.
    136     ///
     91    /**
     92       \brief Matrix row/column view constructor.
     93       
     94       Create a view into a row/column of a matrix.
     95
     96       \param m matrix to view into.
     97       \param i index telling which row/column to view into
     98       \param row if true (defult) created view is a row vector, i.e.,
     99       viewing into row \a i, and, naturally, a column vector
     100       otherwise.
     101
     102       \see matrix::column_const_view(size_t) and
     103       matrix::row_const_view(size_t)
     104
     105       @note If the object viewed by the view goes out of scope or is
     106       deleted, the view becomes invalid and the result of further
     107       use is undefined.
     108    */
    137109    VectorConstView(const matrix& m, size_t i, bool row=true);
    138110
    139     ///
    140     /// The destructor.
    141     ///
     111    /**
     112      The destructor.
     113    */
    142114    ~VectorConstView(void);
    143115
    … …  
    147119    bool isview(void) const;
    148120
    149     /**
    150        \brief The assignment operator.
    151 
    152        \return A const reference to the resulting vector.
    153 
    154        \throw GSL_error if dimensions mis-match.
    155     */
    156     const VectorConstView& operator=(const VectorBase&);
    157     const VectorConstView& operator=(const VectorConstView&);
    158 
    159121  private:
    160     const VectorConstView& assign(const VectorBase& other);
    161122    void delete_allocated_memory(void);
    162123
     124    // Perhaps not needed - only used to create a gsl_vector (that is
     125    // stored in base class). For data access use data in base class
     126    // because this pointer may be NULL.
    163127    gsl_vector_const_view* const_view_;
    164128   
Note: See TracChangeset for help on using the changeset viewer.