.. highlightlang:: us

.. _xyadddata:

XYAddData
=========

.. index:: XYAddData

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

:ref:`XYAddData` fügt einem Datensatz Daten zu.

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

.. us.return

**Returnwert**

*bool* ist TRUE (1), wenn die Funktion erfolgreich war und
sonst FALSE (0).

.. us.params

**Parameter**

.. uparam:: hData

   *hData* ist die Zugriffsnummer eines Datensatzes.

.. uparam:: rvX

   *rvX* ist ein Vektor mit den X-Koordinaten.

.. uparam:: rvY

   *rvY* ist ein Vektor mit den Y-Koordinaten.

.. uparam:: bExt

   Der Parameter legt fest, ob die Funktion auf die Originaldaten oder die 
   gefilterten Daten zugreift.

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

      * - Wert
        - Beschreibung
      * - -1
        - Falls gefilterte Daten vorhanden sind: Zugriff auf die gefilterten Daten, sonst auf die Originaldaten. Der Defaultwert ist -1.
      * - 0
        - Zugriff auf die Originaldaten.
      * - 1
        - Zugriff auf die gefilterten Daten.

.. uparam:: rvMissingValue

   *rvMissingValue* ist ein Vektor mit einem oder zwei Elementen. Mit dem
   Parameter wird ein ungültige Wert in *rvX* und *rvY* festgelegt. Die 
   ungültigen Werte werden beim Speichern im Datensatz aus den Daten entfernt. 
   Falls *rvMissingValue* nur einen Wert enthält, wird der Wert für die 
   x- und die y-Koordinaten verwendet. Default-Wert ist 1e10.

.. us.comment

**Kommentar**

Mit Hilfe der Funktion :ref:`XYAddData` können sehr große Datensätze erzeugt
werden. Der Datensatz wird mit der Funktion :ref:`TYCreate` oder :ref:`XYCreate`
erzeugt. Danach werden die Daten blockweise dem Datensatz zugefügt. Beim
blockweisen Zufügen müssen nicht alle Datenpunkte als großer Block im
Speicher gehalten werden.

Der erste Aufruf ``XYAddData(hData, rvY)`` fügt einem 1D-Datensatz Daten
zu. Ein 1D-Datensatz sollte mit der Fufnktion :ref:`TYCreate` erzeugt worden sein.
Der zweite Aufruf ``XYAddData(hData, rvX, rvY)`` fügt einem 2D-Datensatz
Daten zu. Ein 2D-Datensatz sollte mit der Funktion :ref:`XYCreate` erzeugt worden
sein.

.. us.example

**Beispiel**

Im folgenden Beispiel erzeugt die Funktion ``WriteTestFile`` eine Binärdatei mit
100000 Punkten. Die Funktion ``Test`` liest die Daten blockweise ein und fügt 
sie einem Datensatz zu. Sie können das Beispiel in in einen UniPlot-Programm-Editor
kopieren und mit über das Menükommando :ref:`uniscriptspeichern/ausfuhren` ausführen.

::

   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");

.. us.history

**History**

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

   * - Version
     - Beschreibung
   * - 5.20.0
     - Neuer Parameter *rvMissingValue*.
   * - 5.3.0
     - 

.. seealso::
   :ref:`uberblick-xy-datensatze`,
   :ref:`XYCreate`,
   :ref:`TYCreate`,
   :ref:`TYAddData`

:sub:`id-259442`