/*! ****************************************************************************
\ingroup IN_OUT_GROUP
\fn  int writebin(void* x, int n, int dtype, char* fn)

\brief
Сохранить данные в бинарный файл

Функция сохраняет реальный или комплексный вектор данных 
размера `[n x 1]` в бинарный файл `fn`.  \n \n

Файл является универсальным для хранения как одномерных, 
так и двумерных массивов и имеет следующий формат:  \n \n
\verbatim

type   4 байта типа int.
       Может принимать значение:
       DAT_DOUBLE,  если x указатель на вектор вещественных чисел;
       DAT_COMPLEX, если x указатель на вектор комплексных чисел.
      
n      4 байта типа int.
       Количество строк данных.

m      4 байта типа int. 
       Количество столбцов данных. 
       При сохранении вектора всегда равно 1.
    
data   Данные в бинарном виде.
       Размер данных: 
       n * sizeof(double),    если dtype==DAT_DOUBLE;
       n * sizeof(complex_t), если dtype==DAT_COMPLEX.
\endverbatim

Файл может быть использован для верификации алгоритмов сторонними пакетами,
такими как GNU Octave, Matlab, Python и т.д. \n \n

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

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

\param[in] dtype
Тип данных. \n

Может принимать значения: \n 
`DAT_DOUBLE` -- вещественные данные; \n
`DAT_COMPLEX` -- комплексные данные. \n 
\n

\param[in] fn
Имя файла. \n 
\n

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

\note 
Данная функция производит запись в файл без потери точности, 
поэтому рекомендуется использовать ее для верификации данных DSPL. \n 
\n


Функция для чтения бинарного файла в GNU Octave и Matlab:
\code{.m}
function [dat, n, m] = readbin(fn)
  fid = fopen(fn);
  if(~fid)
    error('cannot to open file');
  end
  type = fread(fid, 1, 'int32');  
  n    = fread(fid, 1, 'int32');
  m    = fread(fid, 1, 'int32');
  
  if(type==0)
    dat = fread(fid, [n*m, 1], 'double');
  end
  
  if(type==1)
    y = fread(fid, [n*m*2, 1], 'double');
    dat = y(1:2:end) + 1i * y(2:2:end);
  end
  
  dat = reshape(dat, n, m);
  
  fclose(fid);
end
\endcode

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







/*! ****************************************************************************
\ingroup IN_OUT_GROUP
\fn  int writetxt(double* x, double* y, int n, char* fn)

\brief
Сохранить вещественные данные в текстовый файл

Функция сохраняет вещественные данные в текстовый файл `fn`. \n

Файл имеет следующий формат: \n

\verbatim
x[0]    y[0]
x[1]    y[1]
...     ...
x[n-1]  y[n-1]
\endverbatim  

Файл может быть использован для построения графика сторонней программой,
например пакетом GNUPLOT (см. раздел \ref PLOT_GROUP). \n

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

\param[in] y
Указатель на второй вектор.  \n
Размер вектора  `[n x 1]`.  \n
Может быть `NULL`.  \n
Файл будет содержать только один столбец соответствующий 
вектору `x` если `y == NULL`. \n 
\n

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

\param[in] fn 
Имя файла. \n 
\n


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

\note 
Данная функция производит округление данных при записи в файл. 
Поэтому не рекомендуется использовать ее для верификации данных DSPL.

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





/*! ****************************************************************************
\ingroup IN_OUT_GROUP
\fn  int writetxt_3d(double* x, int nx, double* y, int ny, double* z, char* fn)

\brief
Сохранить данные для построения 3D графика

Функция сохраняет вещественные данные в текстовый файл `fn` 
для построения 3D поверхности. \n

Функция \f$ z(x,y)\f$ описывается матрицей значений `z[x[n], y[n]]` 
как это показано на рисунке

\image html writetxt_3d_matrix.png

Матрица `z` хранится в памяти по столбцам, как это показано красной стрелкой. \n

Файл имеет следующий формат: \n

\verbatim
x[0]    y[0]    z[0, 0]
x[1]    y[0]    z[1, 0]
x[2]    y[0]    z[2, 0]
...     ...     ...
x[nx-1] y[0]    z[nx-1, 0]

x[0]    y[1]    z[0, 1]
x[1]    y[1]    z[1, 1]
x[2]    y[1]    z[2, 1]
...     ...     ...
x[nx-1] y[1]    z[nx-1, 1]

...     ...     ...
...     ...     ...
...     ...     ...

x[0]    y[ny-1] z[0, ny-1]
x[1]    y[ny-1] z[1, ny-1]
x[2]    y[ny-1] z[2, ny-1]
...     ...     ...
x[nx-1] y[ny-1] z[nx-1, ny-1]
\endverbatim  
Таким образом, каждое значение матрицы `z` записано отдельной строкой со
соответствующими значениями `x` и `y`. Столбцы матрицы отделены пустой строкой.

Файл может быть использован для построения графика сторонней программой,
например пакетом GNUPLOT (см. раздел \ref PLOT_GROUP). Также данный формат
поддерживается пакетами pgfplot3d издательской системы Latex. \n

\param[in] x
Указатель на вектор значений оси `x`.  \n
Размер вектора `[nx x 1]`. \n 
\n

\param[in] nx
Размер вектора оси `x`. \n 
\n


\param[in] y
Указатель на второй вектор значений оси `y`.  \n
Размер вектора  `[ny x 1]`.  \n
\n

\param[in] ny
Размер вектора оси `y`. \n 
\n

\param[in] z
Указатель на матрицу значений функции `z(x, y)`. \n 
\n

\param[in] fn 
Имя файла. \n 
\n


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

Пример использования функции и посторения 3D поверхности приведен
в следующем листинге:

\include writetxt_3d_test.c

Данная программа рассчитывает и строит поверхность функции

\f[
z(x,y) = x \exp(-x^2 -y^2)
\f]

В каталоге `dat` будет создан файл `data3d.txt`.\n
Кроме того программа GNUPLOT произведет построение 3D поверхности 
по сохраненным в файл данным:

\image html writetxt_3d.png


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





/*! ****************************************************************************
\ingroup IN_OUT_GROUP
\fn  int writetxt_int(int* x, int* y, int n, char* fn)

\brief
Сохранить целочисленные данные в текстовый файл

Функция сохраняет целочисленные данные в текстовый файл `fn`. \n

Файл имеет следующий формат: \n

\verbatim
x[0]    y[0]
x[1]    y[1]
...     ...
x[n-1]  y[n-1]
\endverbatim  

Файл может быть использован для построения графика сторонней программой,
например пакетом GNUPLOT (см. раздел \ref PLOT_GROUP). \n

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

\param[in] y
Указатель на второй вектор.  \n
Размер вектора  `[n x 1]`.  \n
Может быть `NULL`.  \n
Файл будет содержать только один столбец соответствующий 
вектору `x` если `y == NULL`. \n 
\n

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

\param[in] fn 
Имя файла. \n 
\n

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

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