.. highlightlang:: us

.. index:: xml_parse_string

.. _xml_parse_string:

xml_parse_string
================

.. us.tag xml_parse_string NOTREADYENGLISH XML New5200

:ref:`xml_parse_string` converts a valid XML string into a UniScript object.

.. function:: o = xml_parse_string(ssXML)
    o = xml_parse_string(ssXML, nOptions)

.. us.return

**Return Value**

*o* is an XML tree or an Error object (see :ref:`error_create`). *o* contains the
elements *name* and the optional elements *attr*. The child elements are saved in
enumerated keys starting with 1.

::

   xml_parse_string("<a/>")
   [.
      name = "a"
   ]

   xml_parse_string("<a att='1'/>")
   [.
      attr = [.
         att = "1"
      ]
      name = "a"
   ]

   xml_parse_string("<a att='1'>mixed<b>contents</b></a>")
   [.
      [1] = "mixed"
      [2] = [.
         [1] = "contents"
         name = "b"
      ]
      attr = [.
         att = "1"
      ]
      name = "a"
   ]

.. us.params

**Parameters**

.. uparam:: ssXML

   *ssXML* is a valid XML string. 

.. uparam:: nOptions

   *nOptions* is a combination of the following values:

   .. list-table::
      :header-rows: 0

      * - NO_SKIP_WHITESPACE (1)
        - Text elements containing only spaces, new line or tabulator characters
          are **not** ignored (white space).
      * - NO_SHORT_ATTR (2)
        - Informations about the order of attributes are saved in the object.

.. us.comment

**Comment**

The XML declaration at the beginning of the string will be ignored.

.. code-block:: xml

   <?xml version="1.0" encoding="UTF-8" ?>

The input string *ssXML* must contain valid UNICODE characters. 
:ref:`text_file_read` returns for ANSI- and utf-8 coded text files UNICODE 
strings.

.. us.history

**History**

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

   * - Version
     - Description
   * - 5.20
     - New.

.. seealso::
   :ref:`Overview-XML`,
   :ref:`text_file_read`,
   :ref:`xml_save_node`,
   :ref:`xml_simple`

:sub:`id-111701`