Split filtering/coefficient handling files

Splits the code for handling coefficient objects and handling filter objects
into separate files. This is just to aid documentation and comprehension.

src/libiir/000_TopHeader.h

@@ -15,6 +15,8 @@
 extern "C" {
 #endif
 
+/*! \defgroup libiir C library */
+
 /* options for text editors
 vim: expandtab:ts=4:sw=4:syntax=c.doxygen
 */

src/libiir/100_coeff.c

@@ -0,0 +1,113 @@
+/* libiir/src/libiir/100_coeff.c
+ * 
+ *  Copyright: ©2010–2014, Laurence Withers.
+ *  Author: Laurence Withers <l@lwithers.me.uk>
+ *  License: GPLv3
+*/
+
+
+
+/* struct iir_coeff_t
+ *  Holds a general IIR filter (i.e. the set of coefficients that define it).
+ *  nc >= 1 and nd >= 1.
+ */
+struct iir_coeff_t {
+    int nc, nd;
+    double* c, * d;
+};
+
+
+
+/* iir_coeff_new()
+ *  Allocates a new set of coefficient objects.
+ */
+struct iir_coeff_t*
+iir_coeff_new(int nc, const double* c, int nd, const double* d)
+{
+    struct iir_coeff_t* coeff;
+
+    if(nc < 1 || nd < 1) {
+        errno = EINVAL;
+        return 0;
+    }
+
+    coeff = malloc(sizeof(struct iir_coeff_t));
+    coeff->nc = nc;
+    coeff->nd = nd;
+    coeff->c = malloc(sizeof(double) * nc);
+    coeff->d = malloc(sizeof(double) * nd);
+    memcpy(coeff->c, c, sizeof(double) * nc);
+    memcpy(coeff->d, d, sizeof(double) * nd);
+
+    return coeff;
+}
+
+
+
+/* iir_coeff_copy()
+ *  Deep copy of coefficient object.
+ */
+struct iir_coeff_t*
+iir_coeff_copy(const struct iir_coeff_t* other)
+{
+    struct iir_coeff_t* coeff;
+
+    coeff = malloc(sizeof(struct iir_coeff_t));
+    coeff->nc = other->nc;
+    coeff->nd = other->nd;
+    coeff->c = malloc(sizeof(double) * coeff->nc);
+    coeff->d = malloc(sizeof(double) * coeff->nd);
+    memcpy(coeff->c, other->c, sizeof(double) * coeff->nc);
+    memcpy(coeff->d, other->d, sizeof(double) * coeff->nd);
+
+    return coeff;
+}
+
+
+
+/* iir_coeff_free()
+ *  Frees memory associated with ‘coeff’.
+ */
+void
+iir_coeff_free(struct iir_coeff_t* coeff)
+{
+    if(!coeff) return;
+    free(coeff->c);
+    free(coeff->d);
+    free(coeff);
+}
+
+
+
+/* iir_coeff_get_*()
+ *  Functions for querying the coefficients that make up an IIR filter.
+ */
+int
+iir_coeff_get_nc(const struct iir_coeff_t* coeff)
+{
+    return coeff->nc;
+}
+
+int
+iir_coeff_get_nd(const struct iir_coeff_t* coeff)
+{
+    return coeff->nd;
+}
+
+double
+iir_coeff_get_c(const struct iir_coeff_t* coeff, int idx)
+{
+    return coeff->c[idx];
+}
+
+double
+iir_coeff_get_d(const struct iir_coeff_t* coeff, int idx)
+{
+    return coeff->d[idx];
+}
+
+
+
+/* options for text editors
+vim: expandtab:ts=4:sw=4
+*/

src/libiir/100_coeff.h

@@ -0,0 +1,126 @@
+/* libiir/src/libiir/100_coeff.h
+ * 
+ *  Copyright: ©2010–2014, Laurence Withers.
+ *  Author: Laurence Withers <l@lwithers.me.uk>
+ *  License: GPLv3
+*/
+
+
+
+/*! \defgroup libiir_coeff Coefficient handling
+
+\ingroup libiir
+
+The functions in this module present an interface for managing the set of
+coefficients of a single IIR filter instance. See \ref iir_structure for
+the definition of a coefficient set. The coefficient sets form the
+basic building block of an IIR filter instance (see \ref libiir_filter),
+which may chain several IIR filters in sequence.
+
+*/
+/*!@{*/
+
+
+
+/* opaque structure */
+struct iir_coeff_t;
+
+
+
+/*! \brief Create IIR coefficient set
+
+\param nc Number of \a c coefficients.
+\param c Array of \a c coefficients.
+\param nd Number of \a d coefficients.
+\param d Array of \a d coefficients.
+\returns Pointer to new general IIR filter object.
+
+This function creates a new set of IIR filter coefficients which may be used to
+create filter instances through \ref iir_filter_new() or chained on to existing
+instances through \ref iir_filter().
+
+See \ref iir_structure for a full explanation of the parameters.
+
+*/
+struct iir_coeff_t* iir_coeff_new(int nc, const double* c, int nd,
+    const double* d)
+#ifndef DOXYGEN
+    __attribute__((malloc,nonnull))
+#endif
+;
+
+
+
+/*! \brief Create copy of a set of IIR coefficients
+
+\param other Set of IIR filter coefficients to copy.
+\returns Pointer to new general IIR filter object.
+
+Performs a deep copy of the set of IIR coefficients contained within \a other.
+
+*/
+struct iir_coeff_t* iir_coeff_copy(const struct iir_coeff_t* other);
+
+
+
+/*! \brief Free IIR coefficient set
+
+\param coeff Pointer to IIR coefficient object. May be 0.
+
+Frees a set of IIR filter coefficients previously allocated through
+\ref iir_coeff_new(). Can be called on a null pointer without consequences.
+Note that \ref iir_filter_new() and \ref iir_filter_chain() actually store a
+copy of the coefficients, so it is possible to free \a coeff even if existing
+filters are still using its coefficient values.
+
+*/
+void iir_coeff_free(struct iir_coeff_t* coeff);
+
+
+
+/*! \brief Query number of C coefficients.
+
+\param coeff Pointer to IIR coefficient object.
+\returns Number of C coefficients (≥1).
+
+*/
+int iir_coeff_get_nc(const struct iir_coeff_t* coeff);
+
+
+
+/*! \brief Query number of D coefficients.
+
+\param coeff Pointer to IIR coefficient object.
+\returns Number of D coefficients (≥1).
+
+*/
+int iir_coeff_get_nd(const struct iir_coeff_t* coeff);
+
+
+
+/*! \brief Get value of C coefficient.
+
+\param coeff Pointer to IIR coefficient object.
+\param idx Index of coefficient (≥0, < \ref iir_coeff_get_nc()).
+\returns C coefficient value.
+
+*/
+double iir_coeff_get_c(const struct iir_coeff_t* coeff, int idx);
+
+
+
+/*! \brief Get value of D coefficient.
+
+\param coeff Pointer to IIR coefficient object.
+\param idx Index of coefficient (≥0, < \ref iir_coeff_get_nd()).
+\returns D coefficient value.
+
+*/
+double iir_coeff_get_d(const struct iir_coeff_t* coeff, int idx);
+
+
+
+/*!@}*/
+/* options for text editors
+vim: expandtab:ts=4:sw=4:syntax=c.doxygen
+*/

src/libiir/200_filter.c

@@ -1,4 +1,4 @@
-/* libiir/src/libiir/200_iir.c
+/* libiir/src/libiir/200_filter.c
  * 
  *  Copyright: ©2010–2014, Laurence Withers.
  *  Author: Laurence Withers <l@lwithers.me.uk>
@@ -7,107 +7,6 @@
 
 
 
-/* struct iir_coeff_t
- *  Holds a general IIR filter (i.e. the set of coefficients that define it).
- *  nc >= 1 and nd >= 1.
- */
-struct iir_coeff_t {
-    int nc, nd;
-    double* c, * d;
-};
-
-
-
-/* iir_coeff_new()
- *  Allocates a new set of coefficient objects.
- */
-struct iir_coeff_t*
-iir_coeff_new(int nc, const double* c, int nd, const double* d)
-{
-    struct iir_coeff_t* coeff;
-
-    if(nc < 1 || nd < 1) {
-        errno = EINVAL;
-        return 0;
-    }
-
-    coeff = malloc(sizeof(struct iir_coeff_t));
-    coeff->nc = nc;
-    coeff->nd = nd;
-    coeff->c = malloc(sizeof(double) * nc);
-    coeff->d = malloc(sizeof(double) * nd);
-    memcpy(coeff->c, c, sizeof(double) * nc);
-    memcpy(coeff->d, d, sizeof(double) * nd);
-
-    return coeff;
-}
-
-
-
-/* iir_coeff_copy()
- *  Deep copy of coefficient object.
- */
-struct iir_coeff_t*
-iir_coeff_copy(const struct iir_coeff_t* other)
-{
-    struct iir_coeff_t* coeff;
-
-    coeff = malloc(sizeof(struct iir_coeff_t));
-    coeff->nc = other->nc;
-    coeff->nd = other->nd;
-    coeff->c = malloc(sizeof(double) * coeff->nc);
-    coeff->d = malloc(sizeof(double) * coeff->nd);
-    memcpy(coeff->c, other->c, sizeof(double) * coeff->nc);
-    memcpy(coeff->d, other->d, sizeof(double) * coeff->nd);
-
-    return coeff;
-}
-
-
-
-/* iir_coeff_free()
- *  Frees memory associated with ‘coeff’.
- */
-void
-iir_coeff_free(struct iir_coeff_t* coeff)
-{
-    if(!coeff) return;
-    free(coeff->c);
-    free(coeff->d);
-    free(coeff);
-}
-
-
-
-/* iir_coeff_get_*()
- *  Functions for querying the coefficients that make up an IIR filter.
- */
-int
-iir_coeff_get_nc(const struct iir_coeff_t* coeff)
-{
-    return coeff->nc;
-}
-
-int
-iir_coeff_get_nd(const struct iir_coeff_t* coeff)
-{
-    return coeff->nd;
-}
-
-double
-iir_coeff_get_c(const struct iir_coeff_t* coeff, int idx)
-{
-    return coeff->c[idx];
-}
-
-double
-iir_coeff_get_d(const struct iir_coeff_t* coeff, int idx)
-{
-    return coeff->d[idx];
-}
-
-
-
 /* struct iir_filter_t
  *  An instantiated IIR filter. This is actually a linked list node, so that we
  *  can create chains of filters. It also has a copy of the coefficients so that

src/libiir/200_filter.h

@@ -1,4 +1,4 @@
-/* libiir/src/libiir/200_iir.h
+/* libiir/src/libiir/200_filter.h
  * 
  *  Copyright: ©2010–2014, Laurence Withers.
  *  Author: Laurence Withers <l@lwithers.me.uk>
@@ -7,11 +7,7 @@
 
 
 
-/*! \defgroup libiir C library */
-
-
-
-/*! \defgroup libiir_iir Basic IIR filtering
+/*! \defgroup libiir_filter Basic IIR filtering
 
 \ingroup libiir
 
@@ -32,104 +28,6 @@ through \ref iir_filter().
 
 
 
-/* opaque structure */
-struct iir_coeff_t;
-
-
-
-/*! \brief Create general IIR filter
-
-\param nc Number of \a c coefficients.
-\param c Array of \a c coefficients.
-\param nd Number of \a d coefficients.
-\param d Array of \a d coefficients.
-\returns Pointer to new general IIR filter object.
-
-This function creates a new general IIR filter object which may be used to
-create filter instances through \ref iir_filter_new() or chained on to existing
-instances through \ref iir_filter().
-
-See \ref iir_structure for a full explanation of the parameters.
-
-*/
-struct iir_coeff_t* iir_coeff_new(int nc, const double* c, int nd,
-    const double* d)
-#ifndef DOXYGEN
-    __attribute__((malloc,nonnull))
-#endif
-;
-
-
-
-/*! \brief Create copy of general IIR filter
-
-\param other Set of IIR filter coefficients to copy.
-\returns Pointer to new general IIR filter object.
-
-Performs a deep copy of the set of IIR coefficients contained within \a other.
-
-*/
-struct iir_coeff_t* iir_coeff_copy(const struct iir_coeff_t* other);
-
-
-
-/*! \brief Free general IIR filter
-
-\param coeff Pointer to IIR filter object. May be 0.
-
-Frees a set of IIR filter coefficients previously allocated through
-\ref iir_coeff_new(). Can be called on a null pointer without consequences.
-Note that \ref iir_filter_new() and \ref iir_filter_chain() actually store a
-copy of the coefficients, so it is possible to free \a coeff even if existing
-filters are still using its coefficient values.
-
-*/
-void iir_coeff_free(struct iir_coeff_t* coeff);
-
-
-
-/*! \brief Query number of C coefficients.
-
-\param coeff Pointer to IIR filter object.
-\returns Number of C coefficients (≥1).
-
-*/
-int iir_coeff_get_nc(const struct iir_coeff_t* coeff);
-
-
-
-/*! \brief Query number of D coefficients.
-
-\param coeff Pointer to IIR filter object.
-\returns Number of D coefficients (≥1).
-
-*/
-int iir_coeff_get_nd(const struct iir_coeff_t* coeff);
-
-
-
-/*! \brief Get value of C coefficient.
-
-\param coeff Pointer to IIR filter object.
-\param idx Index of coefficient (≥0, < \ref iir_coeff_get_nc()).
-\returns C coefficient value.
-
-*/
-double iir_coeff_get_c(const struct iir_coeff_t* coeff, int idx);
-
-
-
-/*! \brief Get value of D coefficient.
-
-\param coeff Pointer to IIR filter object.
-\param idx Index of coefficient (≥0, < \ref iir_coeff_get_nd()).
-\returns D coefficient value.
-
-*/
-double iir_coeff_get_d(const struct iir_coeff_t* coeff, int idx);
-
-
-
 /* opaque structure */
 struct iir_filter_t;