.. highlightlang:: us

.. index:: format_number

.. _format_number:

format_number
=============

.. us.tag  format_number NOTREADYENGLISH STR Programming.Convert New5400

:ref:`format_number` converts a number to a string. The decimal character and the
thousands separator can be specified.

.. function::  string = format_number(number)
               string = format_number(number, nDecimals)
               string = format_number(number, nDecimals, ssSeparators)

.. us.return

**Return Value**

*string* is a string matrix.

.. us.params

**Parameters**

.. uparam:: number

   *number* is a scalar number of a matrix of numbers.

.. uparam:: nDecimals

   *nDecimals* is a number in the range 0 to 20 and sets the number of decimal
   points. Default value is 4.

   If *nDecimals* is negative (-1 to -20) the "g"-Format is used, see
   :ref:`sprintf`. -6 is equal to %g.

.. uparam:: ssSeparator

   *ssSeparator* is a string with one or two characters. The first character
   is the decimal character. The second character sets the thousands separator.
   Both characters can be set in the windows registry: 
   ``Settings\DecimalSeparator`` and ``Settings\ThousandsSeparator``.
   Default value id ".,".

.. us.example

**Example**

::

   * format_number(1234)
     1234.0000
   * format_number(1234, 2, ".,")
     1,234.00
   * format_number(1234, 2, ",.")
     1.234,00
   * format_number(1234, -2, ".,")
     1.2e+3
   * format_number(1234, -6, ".,")
     1,234
   * format_number(1234567, 0, ". ")
     1 234 567

.. us.history

**History**

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

   * - Version
     - Description
   * - R2012 (5.40.0)
     - New.

.. seealso::
   :ref:`overview-strings`,
   :ref:`sprintf`,
   :ref:`strtol`,
   :ref:`strtod`

:sub:`id-589650`