.. highlightlang:: us

.. index:: units

.. _units:

units
=====

.. us.tag units NOTREADYENGLISH units New5511

:ref:`units` returns the unit converter object.

.. function:: oUnit = units()

.. us.return

**Return Value**

Units-Converter-Objekt or the value 0, if the object could not be created.

.. us.comment

**Comment**

When called for the first time, the given Excel file is read and the 
data is saved in an XML file in the user directory. The file name is units.xml.

The Excel file name can be set in the :ref:`tools-formula-configuration` dialog
box. The file name is saved in the registry in the key 
``Settings\unit-converter-file``, see also :ref:`uniplot-registry`.

::

   WriteProfileString("Settings", "unit-converter-file", ...
                   GetRootDirectory() + "Template/units.xlsx");

If you need to add other units or alias values copy the default file into a new
directory and add the new units. Open the :ref:`tools-formula-configuration`
dialog to specify the new file.

Or use the UniPlot command window to set up the new Excel file.

::

   s = GetUserDirectory() + "Template/units.xlsx"
   WriteProfileString("Settings", "unit-converter-file", s);

The active units file can be opened with the following command::

   ShellExecute(units().excel_file)

.. us.example

**Example**

::

   u = units();
   rvScale = units_get_scale(u, "HP", "PS")
   rvScale
       1.0139     0.0000

   rvScale = u.scale("HP", "PS")
   rvScale
       1.0139     0.0000 

.. us.history

**History**

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

   * - Version
     - Description
   * - R2017.6
     - The default units file units.xls has been converted to units.xlsx. The XLS
       file had problems with some ANSI characters.
   * - R2013.11
     - New.

.. seealso::
   :ref:`overview-units`,
   :ref:`units_get_scale`

:sub:`id-680445`