.. highlightlang:: us

.. _xyadddata:

XYAddData
=========

.. index:: XYAddData

.. us.tag  XYAddData ENGLISH xy.data Changed400 Changed530 Changed5200

The :ref:`XYAddData` function adds data to an existing dataset.

.. function::  bool = XYAddData(hData, rvX, rvY)
    bool = XYAddData(hData, rvX, rvY, bExt)
    bool = XYAddData(hData, rvX, rvY, bExt, rvMissingValue)

.. us.return

**Return Value**

*bool* is TRUE (1), if the function was successful and otherwise FALSE (0).

.. us.params

**Parameters**

.. uparam:: hData

   *hData* is the handle of a 1D or 2D dataset.

.. uparam:: rvX

   *rvX* is a vector with x-coordinates.

.. uparam:: rvY

   *rvY* is a vector with y-coordinates.

.. uparam:: bExt

   This parameter specifies if the function will access the original data
   or the filtered data.

.. list-table::
   :header-rows: 1

   * - Value
     - Description
   * - -1
     - If filtered data is available it will access filtered data, otherwise it will  access original data. Default value is -1.
   * - 0
     - Access original data.
   * - 1
     - Access filtered data.

.. uparam:: rvMissingValue

   *rvMissingValue* is a real vector with one or two elements. The values specify
   the missing value in *rvX* and *rvY*. All missing values in *rvX* and *rvY*
   will be removed. If *rvMissingValue* contains only one value, it will be used
   to remove missing valued for the x- and y-coordiantes. 
   Default value is 1e10.

.. us.comment

**Comment**

With the help of the :ref:`XYAddData` huge datasets can be handled.
The dataset is created by the function :ref:`TYCreate` or :ref:`XYCreate`.
Then blocks of data can be added to the dataset. The advantage is that not all
data has to be in memory at the same time as a huge block.

The first call ``XYAddData(hData, rvY)`` adds data to a 1D dataset
A 1D dataset should be created with the :ref:`TYCreate` function. A 2D
dataset should be created with the :ref:`XYCreate` function.

All data points equal to *rvMissingValue* will not be added.

.. us.example

**Example**

The following example creates a binary file with a 100000 points
(``WriteTestFile``). The function ``Test`` reads the data block wise and 
adds data to the dataset. To execute the example copy it into an UniPlot
program editor (:ref:`filenew`) and execute it with the 
command :ref:`uniscript-save-execute`.

::

   def WriteTestFile(ssFileName, nPoints)
   {
       ShowWaitCursor(TRUE);
       fp = fopen(ssFileName, "wb");
       x = linspace(0, 100 * PI, nPoints);
       y = sin(x) + rand(1, nPoints) * 0.2;
       fwrite(fp, "float", y)
       fclose(fp);
   }
   def Test(ssFileName)
   {
       hDoc = DocCreate();
       hPage = PageCreate();
       hLayer = LayerCreate();
       DocAddPage(hDoc, hPage);
       PageAddLayer(hPage, hLayer);
       nBlockSize = 10000;
       i = nBlockSize;
       fp = fopen(ssFileName, "rb");
       y = fread(fp, "float", nBlockSize)
       hData = TYCreate("test", y, hDoc);
       LayerAddDataset(hLayer, hData);
       while (1) {
           y = fread(fp, "float", nBlockSize);
           XYAddData(hData, y);
           if (len(y) < nBlockSize) break;
           AppSetStatusBarText(sprintf("Points: %d", i = i + nBlockSize));
       }
       fclose(fp);
       LayerAutoScale(hLayer);
       PageReplot(hPage)
   }
   WriteTestFile("c:/testfile.dat", 100000);
   Test("c:/testfile.dat");

.. seealso::
   :ref:`overview-xy-datasets`,
   :ref:`XYCreate`,
   :ref:`TYCreate`,
   :ref:`TYAddData`

:sub:`id-259442`