/*! ****************************************************************************
\ingroup TYPES_GROUP
\typedef complex_t
\brief Описание комплексного типа данных.

Комплексный тип данных в библиотеке DSPL-2.0 определен как 
массив из двух элементов типа `double`.
При этом первый элемент массива определяет реальную часть 
комплексного числа, а второй - мнимую.

Например:

\code{.cpp}
    complex_t z;
    z[0] =  1.0;
    z[1] = -2.0;
\endcode 

Переменная `z = 1-2j`, где `j` - мнимая единица.

Для удобства работы с комплексными числами реализованы 
специальные макросы: \ref RE, \ref IM, \ref ABSSQR
***************************************************************************** */









/*! ****************************************************************************
\ingroup TYPES_GROUP
\def ABSSQR(x)
\brief Макрос возвращает квадрат модуля комплексного числа `x`.

Квадрат модуля комплексного числа \f$ x = a + j  b \f$ равен:

\f[
    |x|^2 = x x^* = a^2 + b^2. 
\f]

Например:
\code{.cpp}
    complex_t z;
    double y;
    RE(z) =  1.0;
    IM(z) = -2.0;
    y = ABSSQR(z);
\endcode 

Переменная `z = 1-2j`, где `j` - мнимая единица, а переменная `y = 5`. 
***************************************************************************** */








/*! ****************************************************************************
\ingroup TYPES_GROUP
\def IM(x)
\brief Макрос определяющий мнимую часть комплексного числа.

Например:
\code{.cpp}
    complex_t z;
    RE(z) =  1.0;
    IM(z) = -2.0;        
\endcode 

Переменная `z = 1-2j`, где `j` - мнимая единица.

Аналогично, макрос можно использовать для получения 
мнимой части комплексного числа:
\code{.cpp}
    complex_t z = {3.0, -4.0};
    double    r;
    r = IM(z);
\endcode    
В данном примере переменная `z = 3-4i`, 
а в переменой `r` будет храниться число -4.
***************************************************************************** */










/*! ****************************************************************************
\ingroup TYPES_GROUP
\def RE(x)
\brief Макрос определяющий реальную часть комплексного числа.

Например:
\code{.cpp}
  complex_t z;
  RE(z) =  1.0;
  IM(z) = -2.0;
\endcode 

Переменная `z = 1-2j`, где `j` - мнимая единица.

Аналогично, макрос можно использовать для получения 
реальной части комплексного числа:

\code{.cpp}
  complex_t z = {3.0, -4.0};
  double    r;
  r = RE(z);
\endcode    
В данном примере переменная `z = 3-4i`, а в переменой `r`
будет храниться число 3.
***************************************************************************** */












/*! ****************************************************************************
\ingroup TYPES_GROUP
\fn int cmplx2re(complex_t* x, int n, double* re, double* im)
\brief  Преобразование массива комплексных данных в два массива
        вещественных данных, содержащих реальную и мнимую части 
        исходного массива

Функция заполняет реальные массивы `re` и `im` соответствующими значениями 
реальной и мнимой частей исходного комплексного массива `x`.  \n  


\param[in]  x
Указатель на массив комплексных данных. \n
Размер массива `[n x 1]`.  \n \n

\param[in]  n
Размер массивов входных и выходных данных. \n \n

\param[out] re
Указатель на адрес массива реальной части данных. \n
Размер массива `[n x 1]`.  \n
Память должна быть выделена.  \n \n     

\param[out] im
Указатель на адрес массива мнимой части данных. \n
Размер массива `[n x 1]`.  \n
Память должна быть выделена.  \n \n

\return
`RES_OK` если преобразование произведено успешно.  \n
В противном случае \ref ERROR_CODE_GROUP "код ошибки": \n

Например при выполнении следующего кода 
\code{.cpp}
    complex_t x[3] = {{1.0, 2.0}, {3.0, 4.0}, {5.0, 6.0}};
    double  re[3], im[3];

    cmplx2re(x, 3, re, im);
\endcode 

Элементам массивов `re`  и `im` будут присвоены значения:

\verbatim
re[0] = 1.0; im[0] = 2.0;
re[1] = 3.0; im[1] = 4.0;
re[2] = 5.0; im[2] = 6.0;
\endverbatim

\author
Бахурин Сергей
www.dsplib.org 
***************************************************************************** */















/*! ****************************************************************************
\ingroup TYPES_GROUP
\fn int re2cmplx(double* x, int n, complex_t *y)
\brief Преобразование массива вещественных данных в массив комплексных данных.

Функция заполняет реальные части массива `y` данных соответсвующими значениями 
исходного вещественного массива `x`.  \n  


\param[in]  x
Указатель на массив вещественных данных. \n
Размер массива `[n x 1]`.  \n \n

\param[in]  n
Размер массивов входных и выходных данных. \n \n

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


\return
`RES_OK` если преобразование произведено успешно.  \n
В противном случае \ref ERROR_CODE_GROUP "код ошибки": \n



Например при выполнении следующего кода 
\code{.cpp}
    double x[3] = {1.0, 2.0, 3.0};
    complex_t y[3];

    re2cmplx(x, 3, y);
\endcode 

Значениям `y` будут присвоены значения:

\verbatim
    y[0] = 1+0j;
    y[1] = 2+0j;
    y[2] = 3+0j.
\endverbatim

\author
Бахурин Сергей
www.dsplib.org 
***************************************************************************** */




