############# Number Helper #############

The Number Helper file contains functions that help you work with numeric data in a locale-aware manner.

.. contents:: :local: :depth: 2

Loading this Helper

This helper is loaded using the following code:

.. literalinclude:: number_helper/001.php

When Things Go Wrong

If PHP's internationalization and localization logic cannot handle a value provided, for the given locale and options, then a BadFunctionCallException() will be thrown.

Available Functions

The following functions are available:

.. php:function:: number_to_size($num[, $precision = 1[, $locale = null]])

:param      mixed     $num: Number of bytes
:param      int       $precision: Floating point precision
:returns:   Formatted data size string, or false if the provided value is not numeric
:rtype:     string

Formats numbers as bytes, based on size, and adds the appropriate
suffix. Examples:

.. literalinclude:: number_helper/002.php

An optional second parameter allows you to set the precision of the result:

.. literalinclude:: number_helper/003.php

An optional third parameter allows you to specify the locale that should
be used when generating the number, and can affect the formatting. If no
locale is specified, the Request will be analyzed and an appropriate
locale taken from the headers, or the app-default:

.. literalinclude:: number_helper/004.php

.. note:: The text generated by this function is found in the following
    language file: *language/<your_lang>/Number.php*

.. php:function:: number_to_amount($num[, $precision = 1[, $locale = null])

:param      mixed     $num: Number to format
:param      int       $precision: Floating point precision
:param      string    $locale: The locale to use for formatting
:returns:   A human-readable version of the string, or false if the provided value is not numeric
:rtype:     string

Converts a number into a human-readable version, like **123.4 trillion**
for numbers up to the quadrillions. Examples:

.. literalinclude:: number_helper/005.php

An optional second parameter allows you to set the precision of the result:

.. literalinclude:: number_helper/006.php

An optional third parameter allows the locale to be specified:

.. literalinclude:: number_helper/007.php

.. php:function:: number_to_currency($num, $currency[, $locale = null[, $fraction = 0]])

:param float $num: Number to format
:param string $currency: The currency type, i.e., USD, EUR, etc
:param string|null $locale: The locale to use for formatting
:param integer $fraction: Number of fraction digits after decimal point
:returns: The number as the appropriate currency for the locale
:rtype: string

Converts a number in common currency formats, like USD, EUR, GBP, etc:

.. literalinclude:: number_helper/008.php

If you don't specify a locale, the Request locale is used.

.. php:function:: number_to_roman($num)

:param int|string $num: The number want to convert
:returns: The roman number converted from given parameter
:rtype: string|null

Converts a number into roman:

.. literalinclude:: number_helper/009.php

This function only handles numbers in the range 1 through 3999.
It will return ``null`` for any value outside that range.