.. highlightlang:: us

.. index:: units_get_preferred_unit

.. _units_get_preferred_unit:

units_get_preferred_unit
========================

.. us.tag units_get_preferred_unit NOTREADYENGLISH units New5511

:ref:`units_get_preferred_unit` returns the preferred unit for the given
unit or channel name.

.. function:: ssPrefUnit = units_get_preferred_unit(oUnit, ssUnit)
              ssPrefUnit = units_get_preferred_unit(oUnit, ssUnit, ssChannelName)

.. us.return

**Return Value**

*ssPrefUnit* is the preferred unit string or an empty string if the unit
is not found. If *ssChannelName* is specified, the preferred unit will be looked
up from the channel table. If the channel is not available, the preferred
unit is taken from the "Preferred" column in the units table. (see
: ref: `overview`-units).

.. us.params

**Parameters**

.. uparam:: oUnit

   Is the unit converter object, returned by :ref:`units`.

.. uparam:: ssUnit

   *ssUnit* is one of the defined units (see :ref:`overview-units`). Can be an
   empty string, if the *ssChannelName* is given.

.. uparam:: ssChannelName

   *ssChannelName* is one of the channel names from the channel table 
   (see :ref:`overview-units`).

.. us.comment

**Comment**

Can also be invoked in the following form: 
``oUnit.preferred(ssUnit, ssChannelName)``.

.. us.example

**Example**

::

   u = units()
   units_get_preferred_unit(u, "Hp")
   kW

.. us.history

**History**

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

   * - Version
     - Description
   * - R2013.11
     - New.

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

:sub:`id-759758`