Ignore:
Timestamp:
Feb 17, 2007, 11:33:44 PM (17 years ago)
Author:
Jari Häkkinen
Message:

Addresses #2 and #65. Continued adding GSL_error exceptions, and added doxygen briefs.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/yat/utility/matrix.h

    r737 r754  
    99  Copyright (C) 2005 Jari Häkkinen, Peter Johansson, Markus Ringnér
    1010  Copyright (C) 2006 Jari Häkkinen, Peter Johansson
     11  Copyright (C) 2007 Jari Häkkinen
    1112
    1213  This file is part of the yat library, http://lev.thep.lu.se/trac/yat
    … …  
    8384    matrix(void);
    8485
    85     ///
    86     /// @brief Constructor allocating memory space for \a r times \a c
    87     /// elements, and sets all elements to \a init_value.
    88     ///
     86    /**
     87       \brief Constructor allocating memory space for \a r times \a c
     88       elements, and sets all elements to \a init_value.
     89
     90       \throw GSL_error if memory allocation fails.
     91    */
    8992    matrix(const size_t& r, const size_t& c, double init_value=0);
    9093
    91     ///
    92     /// @brief The copy constructor.
    93     ///
    94     /// @note If the object to be copied is a matrix view, the values
    95     /// of the view will be copied, i.e. the view is not copied.
    96     ///
     94    /**
     95       \brief The copy constructor.
     96
     97       \note If the object to be copied is a matrix view, the values
     98       of the view will be copied, i.e. the view is not copied.
     99
     100       \throw A GSL_error is indirectly thrown if memory allocation
     101       fails.
     102    */
    97103    matrix(const matrix&);
    98104
    99     ///
    100     /// The matrix view constructor.
    101     ///
    102     /// Create a view of matrix \a m, with starting row \a offset_row,
    103     /// starting column \a offset_column, row size \a n_row, and
    104     /// column size \a n_column.
    105     ///
    106     /// A matrix view can be used as any matrix with the difference
    107     /// that changes made to the view will also change the object that
    108     /// is viewed. Also, using the copy constructor will create a new
    109     /// matrix object that is a copy of whatever is viewed. If a copy
    110     /// of the view is needed then you should use this constructor to
    111     /// obtain a copy.
    112     ///
    113     /// @note If the object viewed by the view goes out of scope or is
    114     /// deleted, the view becomes invalid and the result of further
    115     /// use is undefined.
    116     ///
     105    /**
     106       \brief The matrix view constructor.
     107
     108       Create a view of matrix \a m, with starting row \a offset_row,
     109       starting column \a offset_column, row size \a n_row, and column
     110       size \a n_column.
     111
     112       A matrix view can be used as any matrix with the difference
     113       that changes made to the view will also change the object that
     114       is viewed. Also, using the copy constructor will create a new
     115       matrix object that is a copy of whatever is viewed. If a copy
     116       of the view is needed then you should use this constructor to
     117       obtain a copy.
     118
     119       \note If the object viewed by the view goes out of scope or is
     120       deleted, the view becomes invalid and the result of further use
     121       is undefined.
     122
     123       \throw GSL_error if a view cannot be set up.
     124    */
    117125    matrix(matrix& m, size_t offset_row, size_t offset_column, size_t n_row,
    118126           size_t n_column);
    119127
    120     ///
    121     /// The istream constructor.
    122     ///
    123     /// Matrix rows are sepearated with the new line character, and
    124     /// column elements in a row must be separated either with white space
    125     /// characters except the new line (\\n) character (default), or
    126     /// by the delimiter \a sep.
    127     ///. Rows, and
    128     /// columns, are read consecutively and only rectangular matrices
    129     /// are supported. Empty lines are ignored. End of input is at end
    130     /// of file marker.
    131     ///
     128    /**
     129       \brief The istream constructor.
     130
     131       Matrix rows are sepearated with the new line character, and
     132       column elements in a row must be separated either with white
     133       space characters except the new line (\\n) character (default),
     134       or by the delimiter \a sep.  Rows, and columns, are read
     135       consecutively and only rectangular matrices are
     136       supported. Empty lines are ignored. End of input is at end of
     137       file marker.
     138
     139       \throw GSL_error if memory allocation fails.
     140    */
    132141    explicit matrix(std::istream &, char sep='\0')
    133142      throw(utility::IO_error, std::exception);
    134143
    135     ///
    136     /// @brief The destructor.
    137     ///
     144    /**
     145       \brief The destructor.
     146    */
    138147    ~matrix(void);
    139148
    140     ///
    141     /// Elementwise addition of the elements of matrix \a b to the
    142     /// elements of the calling matrix ,\f$ a_{ij} = a_{ij} + b_{ij} \;
    143     /// \forall i,j \f$. The result is stored into the calling matrix.
    144     ///
    145     /// @return Whatever GSL returns.
    146     ///
    147     int add(const matrix& b);
    148 
    149     ///
    150     /// Add the scalar value \a d to the elements of the calling
    151     /// matrix, \f$ a_{ij} = a_{ij} + d \; \forall i,j \f$. The result
    152     /// is stored into the calling matrix.
    153     ///
    154     /// @return Whatever GSL returns.
    155     ///
    156     int add_constant(const double d);
     149    /**
     150       Elementwise addition of the elements of matrix \a b to the
     151       elements of the calling matrix ,\f$ a_{ij} = a_{ij} + b_{ij} \;
     152       \forall i,j \f$. The result is stored into the calling matrix.
     153
     154       \throw GSL_error if dimensions mis-match.
     155    */
     156    void add(const matrix& b);
     157
     158    /**
     159       Add the scalar value \a d to the elements of the calling
     160       matrix, \f$ a_{ij} = a_{ij} + d \; \forall i,j \f$. The result
     161       is stored into the calling matrix.
     162    */
     163    void add(double d);
    157164
    158165    ///
    … …  
    246253    size_t rows(void) const;
    247254
    248     ///
    249     /// Multiply the elements of the calling matrix with a scalar \a
    250     /// d, \f$ a_{ij} = d * a_{ij} \; \forall i,j \f$. The result is
    251     /// stored into the calling matrix.
    252     ///
    253     /// @return Whatever GSL returns.
    254     ///
    255     int scale(const double d);
    256 
    257     ///
    258     /// Set element values to values in \a mat. This function is
    259     /// needed for assignment of viewed elements.
    260     ///
    261     /// @return Whatever GSL returns.
    262     ///
    263     /// @note No check on size is done.
    264     ///
    265     /// @see const matrix& operator=(const matrix&)
    266     ///
    267     int set(const matrix& mat);
     255    /**
     256       Multiply the elements of the calling matrix with a scalar \a d,
     257       \f$ a_{ij} = d * a_{ij} \; \forall i,j \f$. The result is
     258       stored into the calling matrix.
     259    */
     260    void scale(const double d);
     261
     262    /**
     263       \brief Set element values to values in \a mat.
     264
     265       This function is needed for assignment of viewed elements.
     266
     267       \see const matrix& operator=(const matrix&)
     268
     269       \throw GSL_error if dimensions mis-match.
     270    */
     271    void set(const matrix& mat);
    268272
    269273    ///
    … …  
    272276    void set_all(const double value);
    273277
    274     ///
    275     /// Set \a column values to values in \a vec.
    276     ///
    277     /// @return Whatever GSL returns.
    278     ///
    279     /// @note No check on size is done.
    280     ///
    281     int set_column(const size_t column, const vector& vec);
    282 
    283     ///
    284     /// @brief Set \a row values to values in \a vec.
    285     ///
    286     /// @return Whatever GSL returns.
    287     ///
    288     /// @note No check on size is done.
    289     ///
    290     int set_row(const size_t row, const vector& vec);
    291 
    292     ///
    293     /// Subtract the elements of matrix \a b from the elements of the
    294     /// calling matrix ,\f$ a_{ij} = a_{ij} - b_{ij} \; \forall
    295     /// i,j \f$. The result is stored into the calling matrix.
    296     ///
    297     /// @return Whatever GSL returns.
    298     ///
    299     int sub(const matrix& b);
     278    /**
     279       \brief Set \a column values to values in \a vec.
     280
     281       \note No check on size is done.
     282
     283       \throw GSL_error if index is out of range or mis-match in
     284       sizes.
     285    */
     286    void set_column(const size_t column, const vector& vec);
     287
     288    /**
     289       \brief Set \a row values to values in \a vec.
     290
     291       \note No check on size is done.
     292
     293       \throw GSL_error if index is out of range or mis-match in
     294       sizes.
     295    */
     296    void set_row(const size_t row, const vector& vec);
     297
     298    /**
     299       Subtract the elements of matrix \a b from the elements of the
     300       calling matrix ,\f$ a_{ij} = a_{ij} - b_{ij} \; \forall i,j
     301       \f$. The result is stored into the calling matrix.
     302
     303       \throw GSL_error if dimensions mis-match.
     304    */
     305    void sub(const matrix& b);
    300306
    301307    ///
    … …  
    322328    int swap_rows(const size_t i, const size_t j);
    323329
    324     ///
    325     /// @brief Transpose the matrix.
    326     ///
     330    /**
     331       \brief Transpose the matrix.
     332
     333       \throw GSL_error if memory allocation fails for the new
     334       transposed matrix.
     335    */
    327336    void transpose(void);
    328337
    … …  
    356365    bool operator!=(const matrix& other) const;
    357366
    358     ///
    359     /// @brief The assignment operator.
    360     ///
    361     /// There is no requirements on dimensions, i.e. the matrix is
    362     /// remapped in memory if necessary. This implies that in general
    363     /// views cannot be assigned using this operator. Views will be
    364     /// mutated into normal matrices. The only exception to this
    365     /// behaviour on views is when self-assignemnt is done, since
    366     /// self-assignment is ignored.
    367     ///
    368     /// @return A const reference to the resulting matrix.
    369     ///
    370     /// @see int set(const matrix&)
    371     ///
     367    /**
     368       \brief The assignment operator.
     369
     370       There is no requirements on dimensions, i.e. the matrix is
     371       remapped in memory if necessary. This implies that in general
     372       views cannot be assigned using this operator. Views will be
     373       mutated into normal matrices. The only exception to this
     374       behaviour on views is when self-assignemnt is done, since
     375       self-assignment is ignored.
     376
     377       \return A const reference to the resulting matrix.
     378
     379       \see void set(const matrix&).
     380
     381       \throw A GSL_error is indirectly thrown if memory allocation
     382       fails, or if dimensions mis-match.
     383    */
    372384    const matrix& operator=(const matrix& other);
    373385
     386    /**
     387       \brief Add and assign operator.
     388
     389       \return A const reference to the resulting matrix.
     390
     391       \throw GSL_error if dimensions mis-match.
     392    */
     393    const matrix& operator+=(const matrix&);
     394
    374395    ///
    375396    /// @brief Add and assign operator.
    376397    ///
    377     const matrix& operator+=(const matrix&);
    378 
    379     ///
    380     /// @brief Add and assign operator.
    381     ///
    382398    const matrix& operator+=(const double);
    383399
    384     ///
    385     /// @brief Subtract and assign operator.
    386     ///
     400    /**
     401       \brief Subtract and assign operator.
     402
     403       \return A const reference to the resulting matrix.
     404
     405       \throw GSL_error if dimensions mis-match.
     406    */
    387407    const matrix& operator-=(const matrix&);
    388408
    389     ///
    390     /// @brief Multiply and assigment operator.
    391     ///
    392     /// @return Const reference to the resulting matrix.
    393     ///
     409    /**
     410       \brief Multiply and assigment operator.
     411
     412       \return Const reference to the resulting matrix.
     413
     414       \throw GSL_error if memory allocation fails.
     415    */
    394416    const matrix& operator*=(const matrix&);
    395417
    396     ///
    397     /// @brief Multiply and assignment operator
    398     ///
     418    /**
     419       \brief Multiply and assignment operator
     420
     421       \throw GSL_error if memory allocation fails.
     422    */
    399423    const matrix& operator*=(const double);
    400424
    401425  private:
    402426
    403     ///
    404     /// Create a new copy of the internal GSL matrix.
    405     ///
    406     /// Necessary memory for the new GSL matrix is allocated and the
    407     /// caller is responsible for freeing the allocated memory.
    408     ///
    409     /// @return A pointer to a copy of the internal GSL matrix.
    410     ///
     427    /**
     428       \brief Create a new copy of the internal GSL matrix.
     429
     430       Necessary memory for the new GSL matrix is allocated and the
     431       caller is responsible for freeing the allocated memory.
     432
     433       \return A pointer to a copy of the internal GSL matrix.
     434
     435       \throw GSL_error if memory cannot be allocated for the new
     436       copy, or if dimensions mis-match.
     437    */
    411438    gsl_matrix* create_gsl_matrix_copy(void) const;
    412439
Note: See TracChangeset for help on using the changeset viewer.