/* libiir/src/libiir++/100_Coeff.h
 * 
 *  Copyright: ©2014, Laurence Withers.
 *  Author: Laurence Withers <l@lwithers.me.uk>
 *  License: GPLv3
 */



/*! \defgroup libiirpp_coeff Coefficient handling

\ingroup libiirpp

A set of coefficients for a single stage %IIR filter is represented by an
instance of the \ref Coeff class. This class is often instantiated through
one of the common filter generator functions (see \ref libiirpp_common_filters).

*/



/*! \brief %IIR filter coefficient set

\ingroup libiirpp_coeff

An instance of this class represents the set of coefficients used to implement
a single-phase %IIR filter. See \ref iir_structure for more information.

*/
class Coeff {
public:
    /*! \brief Constructor with raw coefficients.

    \param nc Number of \a c coefficients, ≥ 1.
    \param c Array of \a c coefficients.
    \param nd Number of \a d coefficients, ≥ 1.
    \param d Array of \a d coefficients.

    */
    Coeff(int nc, const double* c, int nd, const double* d);

    /*! \brief Constructor from C library object.

    \param cc Pointer to existing coefficient object.

    */
    Coeff(const struct iir_coeff_t* cc);

    /*! \brief Copy constructor.

    \param other Object to copy.

    Performs a full deep copy of the set of coefficients from \a other.

    */
    Coeff(const Coeff& other);

    /*! \brief Destructor. */
    virtual ~Coeff();



    /*! \brief Count number of \a c coefficients.

    \returns Number of \a c coefficients, ≥ 1.

    */
    int nc() const;

    /*! \brief Retrieve \a c coefficient by index.

    \param idx Index of coefficient (0 ≤ \a idx < \ref nc()).
    \returns Value of \a c coefficient at index \a idx.

    */
    double c(int idx) const;

    /*! \brief Count number of \a d coefficients.

    \returns Number of \a d coefficients, ≥ 1.

    */
    int nd() const;

    /*! \brief Retrieve \a d coefficient by index.

    \param idx Index of coefficient (0 ≤ \a idx < \ref nd()).
    \returns Value of \a d coefficient at index \a idx.

    */
    double d(int idx) const;



    /*! \brief Evaluate response of filter at given frequency.

    \param freq Frequency (0 ≤ \a freq ≤ 1).
    \returns Complex response of filter at given frequency.

    Returns the steady-state response of the filter to a pure input signal of
    the given frequency. \a freq is expressed as a fraction of the intended
    sampling rate (with 0.5 being the Nyquist frequency).

    */
    std::complex<double> response(double freq) const;

private:
    // allow the Filter class to access cc_ directly
    friend class Filter;

    // our internal representation is the C object
    struct iir_coeff_t* cc_;

    // disallow assignment; object is immutable
    Coeff& operator=(const Coeff& other);
};



/* options for text editors
vim: expandtab:ts=4:sw=4:syntax=cpp.doxygen
*/