From 4ebf6f0df4df15ce96a24a1851e27f4633d1bda5 Mon Sep 17 00:00:00 2001 From: Sergey Bakhurin Date: Sun, 9 Jun 2019 23:58:50 +0300 Subject: [PATCH] addded doc for decimate functions --- dspl/dox/ru/array.dox | 106 ++++++++++++++++++++++++++++++++++++ dspl/src/array.c | 111 ++++++++++++++++++++++++++++++++++---- examples/src/array_test.c | 34 ++++++++++++ include/dspl.h | 4 +- release/include/dspl.h | 4 +- 5 files changed, 244 insertions(+), 15 deletions(-) create mode 100644 examples/src/array_test.c diff --git a/dspl/dox/ru/array.dox b/dspl/dox/ru/array.dox index 408d76b..dad2d25 100644 --- a/dspl/dox/ru/array.dox +++ b/dspl/dox/ru/array.dox @@ -52,3 +52,109 @@ www.dsplib.org + + +/*! **************************************************************************** +\ingroup SPEC_MATH_COMMON_GROUP +\fn int decimate(double* x, int n, int d, double* y, int* cnt) +\brief Децимация вещественного вектора данных + +Функция производит децимацию вещественного вектора `x` в `d` раз.
+В результате выходной вектор `y` содержит значения: +`y(k) = x(k*d), k = 0...n/d-1`
+ +\param[in] x Указатель на вектор входных данных `x`.
+ Размер вектора `[n x 1]`.

+ +\param[in] n Размер входного вектора `x`.

+ +\param[in] d Коэффициент децимации.
+ В результате децимации из вектора `x` будет взять каждый + d-й элемент.

+ +\param[out] y Указатель на децимированный вектор `y`.
+ Размер выходного вектора равен `[n/d x 1]` + будет сохранен по адресу `cnt`.
+ Память должна быть выделена.

+ +\param[out] cnt Указатель переменную, в которую будет сохранен + размер выходного вектора после децимации.
+ Указатель может быть `NULL`, в этом случае + размер вектора `y` не возвращается.

+ +\return +`RES_OK` если функция выполнена успешно.
+ В противном случае \ref ERROR_CODE_GROUP "код ошибки". + +Пример децимации вещественного массива данных в 2 раза: +\code +double x[10] = {1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0}; +double y[5]; +int d = 2; +int cnt; + +decimate(x, 10, d, y, &cnt); +\endcode +в результате в переменную `cnt` будет записан размер 5, +а вектор `y` будет хранить массив данных: +\code +c = [0.0, 2.0, 4.0, 6.0, 8.0] +\endcode + +\author Бахурин Сергей www.dsplib.org +**************************************************************************** */ + + + +/*! **************************************************************************** +\ingroup SPEC_MATH_COMMON_GROUP +\fn int decimate_cmplx(complex_t* x, int n, int d, complex_t* y, int* cnt) +\brief Децимация комплексного вектора данных + +Функция производит децимацию комплексного вектора `x` в `d` раз.
+В результате выходной вектор `y` содержит значения: +`y(k) = x(k*d), k = 0...n/d-1`
+ +\param[in] x Указатель на вектор входных данных `x`.
+ Размер вектора `[n x 1]`.

+ +\param[in] n Размер входного вектора `x`.

+ +\param[in] d Коэффициент децимации.
+ В результате децимации из вектора `x` будет взять каждый + d-й элемент.

+ +\param[out] y Указатель на децимированный вектор `y`.
+ Размер выходного вектора равен `[n/d x 1]` + будет сохранен по адресу `cnt`.
+ Память должна быть выделена.

+ +\param[out] cnt Указатель переменную, в которую будет сохранен + размер выходного вектора после децимации.
+ Указатель может быть `NULL`, в этом случае + размер вектора `y` не возвращается.

+ +\return +`RES_OK` если функция выполнена успешно.
+ В противном случае \ref ERROR_CODE_GROUP "код ошибки". + +Пример децимации комплексного массива данных в 2 раза: +\code +compex_t x[10] = {{0.0, 0.0}, {1.0, 1.0}, {2.0, 2.0}, {3.0, 3.0}, {4.0, 4.0}, + {5.0, 5.0}, {6.0, 6.0}, {7.0, 7.0}, {8.0, 8.0}, {9.0, 9.0}}; +compex_t y[5]; +int d = 2; +int cnt; + +decimate_cmplx(x, 10, d, y, &cnt); +\endcode +в результате в переменную `cnt` будет записан размер 5, +а вектор `y` будет хранить массив данных: +\code +c = [0.0+0.0j, 2.0+2.0j, 4.0+4.0j, 6.0+6.0j, 8.0+8.0j] +\endcode + +\author Бахурин Сергей www.dsplib.org +**************************************************************************** */ + + diff --git a/dspl/src/array.c b/dspl/src/array.c index 6eff87f..dc4af6c 100644 --- a/dspl/src/array.c +++ b/dspl/src/array.c @@ -90,23 +90,67 @@ int DSPL_API concat(void* a, size_t na, void* b, size_t nb, void* c) /****************************************************************************** -decimate real vector +\ingroup SPEC_MATH_COMMON_GROUP +\fn int decimate(double* x, int n, int d, double* y, int* cnt) +\brief Real vector decimation + +Function `d` times decimates real vector `x`.
+Output vector `y` keeps values corresponds to: +`y(k) = x(k*d), k = 0...n/d-1`
+ +\param[in] x Pointer to the input real vector `x`.
+ Vector `x` size is `[n x 1]`.

+ +\param[in] n Size of input vector `x`.

+ +\param[in] d Decimation coefficient.
+ Each d-th vector will be copy from vector `x` to the + output vector `y`.

+ +\param[out] y Pointer to the output decimated vector `y`.
+ Output vector size is `[n/d x 1]` will be copy + to the address `cnt`.
+ +\param[out] cnt Address which will keep decimated vector `y` size.
+ Pointer can be `NULL`, vector `y` will not return + in this case.

+ +\return +`RES_OK` if function calculated successfully.
+Else \ref ERROR_CODE_GROUP "code error". + +Two-times decimation example: +\code +double x[10] = {0.0, 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0}; +double y[5]; +int d = 2; +int cnt; + +decimate(x, 10, d, y, &cnt); +\endcode +As result variable `cnt` will be written value 5 and +vector `y` will keep array: +\code +c = [0.0, 2.0, 4.0, 6.0, 8.0] +\endcode + +\author Sergey Bakhurin www.dsplib.org *******************************************************************************/ -int DSPL_API decimate(double* x, int n, int dec, double* y, int* cnt) +int DSPL_API decimate(double* x, int n, int d, double* y, int* cnt) { int k = 0, i = 0; if(!x || !y) return ERROR_PTR; if(n < 1) return ERROR_SIZE; - if(dec < 1) + if(d < 1) return ERROR_NEGATIVE; k = i = 0; - while(k + dec < n) + while(k + d <= n) { y[i] = x[k]; - k+=dec; + k+=d; i++; } if(cnt) @@ -119,25 +163,70 @@ int DSPL_API decimate(double* x, int n, int dec, double* y, int* cnt) /****************************************************************************** -decimate complex vector +\ingroup SPEC_MATH_COMMON_GROUP +\fn int decimate_cmplx(complex_t* x, int n, int d, complex_t* y, int* cnt) +\brief Complex vector decimation + +Function `d` times decimates a complex vector `x`.
+Output vector `y` keeps values corresponds to: +`y(k) = x(k*d), k = 0...n/d-1`
+ +\param[in] x Pointer to the input complex vector `x`.
+ Vector `x` size is `[n x 1]`.

+ +\param[in] n Size of input vector `x`.

+ +\param[in] d Decimation coefficient.
+ Each d-th vector will be copy from vector `x` to the + output vector `y`.

+ +\param[out] y Pointer to the output decimated vector `y`.
+ Output vector size is `[n/d x 1]` will be copy + to the address `cnt`.
+ Memory must be allocated.

+ +\param[out] cnt Address which will keep decimated vector `y` size.
+ Pointer can be `NULL`, vector `y` will not return + in this case.

+ +\return +`RES_OK` if function calculated successfully.
+Else \ref ERROR_CODE_GROUP "code error". + +Two-times complex vector decimation example: +\code +compex_t x[10] = {{0.0, 0.0}, {1.0, 1.0}, {2.0, 2.0}, {3.0, 3.0}, {4.0, 4.0}, + {5.0, 5.0}, {6.0, 6.0}, {7.0, 7.0}, {8.0, 8.0}, {9.0, 9.0}}; +compex_t y[5]; +int d = 2; +int cnt; + +decimate_cmplx(x, 10, d, y, &cnt); +\endcode +As result variable `cnt` will be written value 5 and +vector `y` will keep array: +\code +c = [0.0+0.0j, 2.0+2.0j, 4.0+4.0j, 6.0+6.0j, 8.0+8.0j] +\endcode + +\author Sergey Bakhurin www.dsplib.org *******************************************************************************/ -int DSPL_API decimate_cmplx(complex_t* x, int n, int dec, - complex_t* y, int* cnt) +int DSPL_API decimate_cmplx(complex_t* x, int n, int d, complex_t* y, int* cnt) { int k = 0, i = 0; if(!x || !y) return ERROR_PTR; if(n < 1) return ERROR_SIZE; - if(dec < 1) + if(d < 1) return ERROR_NEGATIVE; k = i = 0; - while(k + dec < n) + while(k + d < n) { RE(y[i]) = RE(x[k]); IM(y[i]) = IM(x[k]); - k+=dec; + k+=d; i++; } if(cnt) diff --git a/examples/src/array_test.c b/examples/src/array_test.c new file mode 100644 index 0000000..f6052da --- /dev/null +++ b/examples/src/array_test.c @@ -0,0 +1,34 @@ +#include +#include +#include +#include "dspl.h" + +int main() +{ + void* handle; // DSPL handle + handle = dspl_load(); // Load DSPL function + + double a[5] = {0.0, 1.0, 2.0, 3.0, 4.0}; + double b[5] = {5.0, 6.0, 7.0, 8.0, 9.0}; + double c[10], d[5]; + int err, k, n; + + // Concatenate arrays a and b. Result keeps to the array c + err = concat((void*)a, 5*sizeof(double), + (void*)b, 5*sizeof(double), (void*)c); + printf("\n\nconcatenation result: %d\n\narray c = ", err); + for(k = 0; k < 10; k++) + printf("%6.1f", c[k]); + + // Decimate array c 2 times. Result keeps to the array d + err = decimate(c, 10, 2, d, &n); + printf("\n\ndecimation result: %d\n\narray d = ", err); + for (k = 0; k < n; k++) + printf("%6.1f", d[k]); + + dspl_free(handle); // free dspl handle + + return err; +} + + diff --git a/include/dspl.h b/include/dspl.h index ce8a7a6..07ae6a3 100644 --- a/include/dspl.h +++ b/include/dspl.h @@ -357,13 +357,13 @@ DECLARE_FUNC(int, cos_cmplx, complex_t* //------------------------------------------------------------------------------ DECLARE_FUNC(int, decimate, double* x COMMA int n - COMMA int dec + COMMA int d COMMA double* y COMMA int* cnt); //------------------------------------------------------------------------------ DECLARE_FUNC(int, decimate_cmplx, complex_t* x COMMA int n - COMMA int dec + COMMA int d COMMA complex_t* y COMMA int* cnt); //------------------------------------------------------------------------------ diff --git a/release/include/dspl.h b/release/include/dspl.h index ce8a7a6..07ae6a3 100644 --- a/release/include/dspl.h +++ b/release/include/dspl.h @@ -357,13 +357,13 @@ DECLARE_FUNC(int, cos_cmplx, complex_t* //------------------------------------------------------------------------------ DECLARE_FUNC(int, decimate, double* x COMMA int n - COMMA int dec + COMMA int d COMMA double* y COMMA int* cnt); //------------------------------------------------------------------------------ DECLARE_FUNC(int, decimate_cmplx, complex_t* x COMMA int n - COMMA int dec + COMMA int d COMMA complex_t* y COMMA int* cnt); //------------------------------------------------------------------------------