Ignore:
Timestamp:
Feb 17, 2007, 11:33:44 PM (14 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/vector.h

    r714 r754  
    88  Copyright (C) 2004 Jari Häkkinen, Peter Johansson
    99  Copyright (C) 2005 Jari Häkkinen, Peter Johansson, Markus Ringnér
    10   Copyright (C) 2006 Jari Häkkinen
     10  Copyright (C) 2006, 2007 Jari Häkkinen
    1111
    1212  This file is part of the yat library, http://lev.thep.lu.se/trac/yat
     
    8888  public:
    8989
    90     ///
    91     /// The default constructor.
    92     ///
     90    /**
     91       \brief The default constructor.
     92    */
    9393    vector(void);
    9494
    95     ///
    96     /// Constructor. Allocates memory space for \a n elements, and
    97     /// sets all elements to \a init_value.
    98     ///
     95    /**
     96       \brief Allocates memory space for \a n elements, and sets all
     97       elements to \a init_value.
     98       
     99       \throw GSL_error if memory allocation fails.
     100    */
    99101    vector(size_t n, double init_value=0);
    100102
    101     ///
    102     /// The copy constructor.
    103     ///
    104     /// @note If the object to be copied is a vector view, the values
    105     /// of the view will be copied, i.e. the view is not copied.
    106     ///
     103    /**
     104       \brief The copy constructor.
     105
     106       \note If the object to be copied is a vector view, the values
     107       of the view will be copied, i.e. the view is not copied.
     108
     109       \throw A GSL_error is indirectly thrown if memory allocation
     110       fails.
     111    */
    107112    vector(const vector& other);
    108113
    109     ///
    110     /// Vector view constructor.
    111     ///
    112     /// Create a view of vector \a v, with starting index \a offset,
    113     /// size \a n, and an optional \a stride.
    114     ///
    115     /// A vector view can be used as any vector with the difference
    116     /// that changes made to the view will also change the object that
    117     /// is viewed. Also, using the copy constructor will create a new
    118     /// vector object that is a copy of whatever is viewed. If a copy
    119     /// of the view is needed then you should use this constructor to
    120     /// obtain a copy.
    121     ///
    122     /// @note If the object viewed by the view goes out of scope or is
    123     /// deleted, the view becomes invalid and the result of further
    124     /// use is undefined.
    125     ///
     114    /**
     115       \brief Vector view constructor.
     116
     117       Create a view of vector \a v, with starting index \a offset,
     118       size \a n, and an optional \a stride.
     119
     120       A vector view can be used as any vector with the difference
     121       that changes made to the view will also change the object that
     122       is viewed. Also, using the copy constructor will create a new
     123       vector object that is a copy of whatever is viewed. If a copy
     124       of the view is needed then you should use this constructor to
     125       obtain a copy.
     126
     127       \note If the object viewed by the view goes out of scope or is
     128       deleted, the view becomes invalid and the result of further use
     129       is undefined.
     130
     131       \throw GSL_error if a view cannot be set up.
     132    */
    126133    vector(vector& v, size_t offset, size_t n, size_t stride=1);
    127134
    128     ///
    129     /// Vector const view constructor.
    130     ///
    131     /// Create a view of vector \a v, with starting index \a offset,
    132     /// size \a n, and an optional \a stride.
    133     ///
    134     /// A vector view can be used as any const vector. Using the copy
    135     /// constructor will create a new vector object that is a copy of
    136     /// whatever is viewed. If a copy of the view is needed then you
    137     /// should use this constructor to obtain a copy.
    138     ///
    139     /// @note If the object viewed by the view goes out of scope or is
    140     /// deleted, the view becomes invalid and the result of further
    141     /// use is undefined.
    142     ///
     135    /**
     136       \brief Vector const view constructor.
     137
     138       Create a view of vector \a v, with starting index \a offset,
     139       size \a n, and an optional \a stride.
     140
     141       A vector view can be used as any const vector. Using the copy
     142       constructor will create a new vector object that is a copy of
     143       whatever is viewed. If a copy of the view is needed then you
     144       should use this constructor to obtain a copy.
     145
     146       \note If the object viewed by the view goes out of scope or is
     147       deleted, the view becomes invalid and the result of further use
     148       is undefined.
     149
     150       \throw GSL_error if a view cannot be set up.
     151    */
    143152    vector(const vector& v, size_t offset, size_t n, size_t stride=1);
    144153
     
    186195    vector(const matrix& m, size_t i, bool row=true);
    187196
    188     ///
    189     /// The istream constructor.
    190     ///
    191     /// Either elements should be separated
    192     /// with white space characters (default), or elements should be separated
    193     /// by the delimiter \a sep. When delimiter \a sep is used empty elements
    194     /// are stored as NaN's (except that empty lines are ignored). The
    195     /// end of input to the vector is at end of file marker.
    196     ///
     197    /**
     198       \brief The istream constructor.
     199
     200       Either elements should be separated with white space characters
     201       (default), or elements should be separated by the delimiter \a
     202       sep. When delimiter \a sep is used empty elements are stored as
     203       NaN's (except that empty lines are ignored). The end of input
     204       to the vector is at end of file marker.
     205
     206       \throw GSL_error if memory allocation fails.
     207    */
    197208    explicit vector(std::istream &, char sep='\0')
    198209      throw(utility::IO_error, std::exception);
     
    203214    ~vector(void);
    204215
    205     ///
    206     /// Vector addition, \f$ this_i = this_i + other_i \; \forall i \f$.
    207     ///
    208     /// @return GSL_SUCCESS on normal exit.
    209     ///
    210     // Jari, group as vector_operators
    211     int add(const vector& other);
    212 
    213     ///
    214     /// Add a constant to a vector, \f$ this_i = this_i + term \;
    215     /// \forall i \f$.
    216     ///
    217     /// @return GSL_SUCCESS on normal exit.
    218     ///
    219     // Jari, group as vector_operators
    220     int add(double term);
     216    /**
     217       \brief Vector addition, \f$ this_i = this_i + other_i \;
     218       \forall i \f$.
     219
     220       \throw GSL_error if dimensions mis-match.
     221    */
     222    void add(const vector& other);
     223
     224    /**
     225       \brief Add a constant to a vector, \f$ this_i = this_i + term \;
     226       \forall i \f$.
     227    */
     228    void add(double term);
    221229
    222230    ///
     
    312320    int reverse(void);
    313321
    314     ///
    315     /// Rescale vector, \f$ this_i = this_i * factor \; \forall i \f$.
    316     ///
    317     /// @return GSL_SUCCESS on normal exit.
    318     ///
    319     // Jari, doxygen group as Vector operators
    320     int scale(double factor);
    321 
    322     ///
    323     /// Set element values to values in \a vec. This function is
    324     /// needed for assignment of viewed elements.
    325     ///
    326     /// @return Whatever GSL returns.
    327     ///
    328     /// @note No check on size is done.
    329     ///
    330     /// @see const vector& operator=(const vector&)
    331     ///
    332     int set(const vector& vec);
     322    /**
     323       \brief Rescale vector, \f$ this_i = this_i * factor \; \forall i \f$.
     324    */
     325    void scale(double factor);
     326
     327    /**
     328       \brief Set element values to values in \a vec.
     329
     330       This function is needed for assignment of viewed elements.
     331
     332       \see const vector& operator=(const vector&)
     333
     334       \throw GSL_error if dimensions mis-match.
     335    */
     336    void set(const vector& vec);
    333337
    334338    ///
     
    365369    void sort(void);
    366370
    367     ///
    368     /// Vector subtraction, \f$ this_i = this_i - other_i \; \forall i \f$.
    369     ///
    370     /// @return GSL_SUCCESS on normal exit.
    371     ///
    372     // Jari, doxygen group as Vector operators
    373     int sub(const vector& other);
     371    /**
     372       \brief Vector subtraction, \f$ this_i = this_i - other_i \;
     373       \forall i \f$.
     374
     375       \throw GSL_error if dimensions mis-match.
     376    */
     377    void sub(const vector& other);
    374378
    375379    ///
     
    441445    double operator*(const vector&) const;
    442446
    443     ///
    444     /// The assignment operator. There is no requirements on
    445     /// dimensions, i.e. the vector is remapped in memory if
    446     /// necessary. This implies that in general views cannot be
    447     /// assigned using this operator. Views will be mutated into
    448     /// normal vectors. The only exception to this behaviour on views
    449     /// is when self-assignemnt is done, since self-assignment is
    450     /// ignored.
     447    /**
     448       \brief The assignment operator.
     449
     450       There is no requirements on dimensions, i.e. the vector is
     451       remapped in memory if necessary. This implies that in general
     452       views cannot be assigned using this operator. Views will be
     453       mutated into normal vectors. The only exception to this
     454       behaviour on views is when self-assignemnt is done, since
     455       self-assignment is ignored.
     456
     457       \return A const reference to the resulting vector.
     458
     459       \see void set(const vector&).
     460
     461       \throw A GSL_error is indirectly thrown if memory allocation
     462       fails, or if dimensions mis-match.
     463    */
     464    const vector& operator=(const vector&);
     465
     466    /**
     467       \brief Addition and assign operator.
     468
     469       \return A const reference to the resulting vector.
     470
     471       \throw GSL_error if dimensions mis-match.
     472    */
     473    const vector& operator+=(const vector&);
     474
     475    /**
     476       \brief Subtract and assign operator.
     477
     478       \return A const reference to the resulting vector.
     479
     480       \throw GSL_error if dimensions mis-match.
     481    */
     482    const vector& operator-=(const vector&);
     483
     484    ///
     485    /// Multiply with scalar and assign operator.
    451486    ///
    452487    /// @return A const reference to the resulting vector.
    453488    ///
    454     /// @see int set(const vector&)
    455     ///
    456     const vector& operator=(const vector&);
    457 
    458     ///
    459     /// Addition and assign operator.
    460     ///
    461     /// @return A const reference to the resulting vector.
    462     ///
    463     const vector& operator+=(const vector&);
    464 
    465     ///
    466     /// Subtract and assign operator.
    467     ///
    468     /// @return A const reference to the resulting vector.
    469     ///
    470     const vector& operator-=(const vector&);
    471 
    472     ///
    473     /// Multiply with scalar and assign operator.
    474     ///
    475     /// @return A const reference to the resulting vector.
    476     ///
    477489    const vector& operator*=(const double);
    478490
     
    480492  private:
    481493
    482     ///
    483     /// Create a new copy of the internal GSL vector.
    484     ///
    485     /// Necessary memory for the new GSL vector is allocated and the
    486     /// caller is responsible for freeing the allocated memory.
    487     ///
    488     /// @return A pointer to a copy of the internal GSL vector.
    489     ///
     494    /**
     495       \brief Create a new copy of the internal GSL vector.
     496
     497       Necessary memory for the new GSL vector is allocated and the
     498       caller is responsible for freeing the allocated memory.
     499
     500       \return A pointer to a copy of the internal GSL vector.
     501
     502       \throw GSL_error if memory cannot be allocated for the new
     503       copy, or if dimensions mis-match.
     504    */
    490505    gsl_vector* create_gsl_vector_copy(void) const;
    491506
Note: See TracChangeset for help on using the changeset viewer.