Changeset 1046


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

some dox - refs #256

Location:
trunk/yat/utility
Files:
3 edited

Legend:

Unmodified
Added
Removed

  • trunk/yat/utility/VectorBase.h

    r1041 r1046  
    4343namespace yat {
    4444namespace utility {
    45 
     45 
    4646  class matrix;
    4747  class vector;
    … …  
    5050     @brief This is the yat interface to GSL vector.
    5151
    52      For time being 'double' is the only type supported.
    53 
    54      \par File streams:
    55      Reading and writing vectors to file streams are of course
    56      supported. These are implemented without using GSL functionality,
    57      and thus binary read and write to streams are not supported.
    58 
    59      \par Vector views:
    60      GSL vector views are supported and these are disguised as
    61      ordinary utility::vectors. A support function is added,
    62      utility::vector::isview(), that can be used to check if a vector
    63      object is a view. Note that view vectors do not own the
    64      underlying data, and a view is not valid if the vector/matrix
    65      owing the data is deallocated.
    66 
    67      \par
    68      Currently there is no restriction on how a vector is used when
    69      the vector is a const view into another vector or matrix. To
    70      avoid unexpected runtime errors, the programmer must declare
    71      const view vectors as 'const' in order to get compile time
    72      diagnostics about improper use of a const view vector object. If
    73      'const' is not used and the const view vector is used erroneously
    74      (such as on the left hand side in assignments), the compiler will
    75      not catch the error and runtime error will occur. assert(3) is
    76      used to catch the runtime error during development. Example on
    77      bad and proper use of const view vectors:
    78      @code
    79   const vector vm(13,1.0);
    80   vector v1(vm,2,4);       // bad code! not const!
    81   v1(0)=-123;              // accepted by compiler, runtime abort will occur
    82                            // or catched by assert depending on compiler flags
    83   const vector v2(vm,2,4); // proper code
    84   v2(0)=-123;              // not acceptable for the compiler
    85      @endcode
    86   */
    87 
     52     This is an interface class for vectors containing the const
     53     interface. For mutable functionality see VectorMutable.
     54  */
    8855  class VectorBase
    8956  {
    … …  
    12390    bool equal(const VectorBase&, const double precision=0) const;
    12491
    125     ///
    126     /// @return A const pointer to the internal GSL vector,
    127     ///
     92    /**
     93       \return A const pointer to the internal GSL vector,
     94    */
    12895    const gsl_vector* gsl_vector_p(void) const;
    12996
    … …  
    136103    virtual bool isview(void) const=0;
    137104
    138     ///
    139     /// @return the number of elements in the VectorBase.
    140     ///
     105    /**
     106       \return number of elements in the VectorBase.
     107    */
    141108    size_t size(void) const;
    142109
    … …  
    241208     valid and a zero means that the corresponding element is a NaN.
    242209
    243      \note Space for VectorBase \a flag is reallocated to fit the size of
     210     \note Space for vector \a flag is reallocated to fit the size of
    244211     VectorBase \a templat if sizes mismatch.
    245212
    … …  
    261228
    262229  /**
    263       Similar to sort_index but creates a VectorBase with indices to the \a k
    264   smallest elements in \a invec. 
     230      Similar to sort_index but creates a VectorBase with indices to
     231      the \a k smallest elements in \a invec.
    265232  */
    266233  void sort_smallest_index(std::vector<size_t>& sort_index, size_t k,
    … …  
    268235
    269236  /**
    270       Similar to sort_index but creates a VectorBase with indices to the \a k
    271   largest elements in \a invec. 
     237      Similar to sort_index but creates a VectorBase with indices to
     238      the \a k largest elements in \a invec.
    272239  */
    273240  void sort_largest_index(std::vector<size_t>& sort_index, size_t k,

  • trunk/yat/utility/VectorMutable.h

    r1041 r1046  
    4949
    5050  /**
    51      @brief This is the yat interface to GSL vector.
    52 
    53      For time being 'double' is the only type supported.
    54 
    55      \par File streams:
    56      Reading and writing vectors to file streams are of course
    57      supported. These are implemented without using GSL functionality,
    58      and thus binary read and write to streams are not supported.
    59 
    60      \par Vector views:
    61      GSL vector views are supported and these are disguised as
    62      ordinary utility::vectors. A support function is added,
    63      utility::vector::isview(), that can be used to check if a vector
    64      object is a view. Note that view vectors do not own the
    65      underlying data, and a view is not valid if the vector/matrix
    66      owing the data is deallocated.
    67 
    68      \par
    69      Currently there is no restriction on how a vector is used when
    70      the vector is a const view into another vector or matrix. To
    71      avoid unexpected runtime errors, the programmer must declare
    72      const view vectors as 'const' in order to get compile time
    73      diagnostics about improper use of a const view vector object. If
    74      'const' is not used and the const view vector is used erroneously
    75      (such as on the left hand side in assignments), the compiler will
    76      not catch the error and runtime error will occur. assert(3) is
    77      used to catch the runtime error during development. Example on
    78      bad and proper use of const view vectors:
    79      @code
    80   const vector vm(13,1.0);
    81   vector v1(vm,2,4);       // bad code! not const!
    82   v1(0)=-123;              // accepted by compiler, runtime abort will occur
    83                            // or catched by assert depending on compiler flags
    84   const vector v2(vm,2,4); // proper code
    85   v2(0)=-123;              // not acceptable for the compiler
    86      @endcode
     51     @brief This is the mutable interface to GSL vector.
     52
     53     This class contains the mutable interface to vector classes.
     54
     55     The non-mutable interface is inherited from VectorBase. When
     56     dealing with const vectors, it is preferable to use the
     57     VectorBase signature because this allows usage of VectorConstView
     58     too.
    8759  */
    88 
    8960  class VectorMutable : public VectorBase
    9061  {
    … …  
    11081    VectorMutable(const gsl_vector*);
    11182
    112     ///
    113     /// The destructor.
    114     ///
     83    /**
     84      The destructor.
     85    */
    11586    virtual ~VectorMutable(void);
    11687
    117     ///
    118     /// Set all elements to \a value.
    119     ///
     88    /**
     89      Set all elements to \a value.
     90    */
    12091    void all(double value);
    12192
    … …  
    241212    gsl_vector* vec_;
    242213
    243     // Peter document
     214    /**
     215       Proxy class used to allow copy and assignment of VectorView. By
     216       design vectors and matrices are passed as non-const references
     217       in all constructors of VectorView. Because the standard does
     218       not allow temporary objects to be bound to non-const
     219       references, it is not possible to directly construct a
     220       VectorView from a temporary VectorView returned from a
     221       function. Instead this proxy class is created from the
     222       temporary object and then a VectorView can be created from thsi
     223       proxy.
     224
     225       \see VectorView
     226     */
    244227    struct proxy
    245228    {
    … …  
    252235  public:
    253236    /**
     237       conversion operator to protected proxy class.
    254238     */
    255239    operator proxy();
    … …  
    258242
    259243  /**
    260      Randomly shuffles the elements in VectorBase \a invec
     244     Randomly shuffles the elements in VectorMutable \a invec
    261245  */
    262246  void shuffle(VectorMutable& invec);
    263247
    264248  /**
    265      Sort the elements in the VectorBase.
     249     Sort the elements in the VectorMutable.
    266250  */
    267251  void sort(VectorMutable&);

  • 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.