Class Number

Number helper library.

Methods to make numbers more readable.

Namespace: Cake\I18n
Link: https://book.cakephp.org/4/en/core-libraries/number.html

Constants

  • int
    CURRENCY_ACCOUNTING 
    12

    ICU Constant for accounting format; not yet widely supported by INTL library. This will be able to go away once CakePHP minimum PHP requirement is 7.4.1 or higher. See UNUM_CURRENCY_ACCOUNTING in https://unicode-org.github.io/icu-docs/apidoc/released/icu4c/unum_8h.html

  • string
    DEFAULT_LOCALE 
    'en_US'

    Default locale

  • string
    FORMAT_CURRENCY 
    'currency'

    Format type to format as currency

  • string
    FORMAT_CURRENCY_ACCOUNTING 
    'currency_accounting'

    Format type to format as currency, accounting style (negative numbers in parentheses)

Property Summary

  • $_defaultCurrency protected static
    string|null

    Default currency used by Number::currency()

  • $_defaultCurrencyFormat protected static
    string|null

    Default currency format used by Number::currency()

  • $_formatters protected static
    array<string, array<int, mixed>>

    A list of number formatters indexed by locale and type

Method Summary

  • _setAttributes() protected static

    Set formatter attributes

  • config() public static

    Configure formatters.

  • currency() public static

    Formats a number into a currency format.

  • defaultCurrency() public static deprecated

    Getter/setter for default currency. This behavior is deprecated and will be removed in future versions of CakePHP.

  • format() public static

    Formats a number into the correct locale format

  • formatDelta() public static

    Formats a number into the correct locale format to show deltas (signed differences in value).

  • formatter() public static

    Returns a formatter object that can be reused for similar formatting task under the same locale and options. This is often a speedier alternative to using other methods in this class as only one formatter object needs to be constructed.

  • getDefaultCurrency() public static

    Getter for default currency

  • getDefaultCurrencyFormat() public static

    Getter for default currency format

  • ordinal() public static

    Returns a formatted integer as an ordinal number string (e.g. 1st, 2nd, 3rd, 4th, [...])

  • parseFloat() public static

    Parse a localized numeric string and transform it in a float point

  • precision() public static

    Formats a number with a level of precision.

  • setDefaultCurrency() public static

    Setter for default currency

  • setDefaultCurrencyFormat() public static

    Setter for default currency format

  • toPercentage() public static

    Formats a number into a percentage string.

  • toReadableSize() public static

    Returns a formatted-for-humans file size.

Method Detail

_setAttributes() protected static 

_setAttributes(NumberFormatter $formatter, array<string, mixed> $options = []): NumberFormatter

Set formatter attributes

Parameters

NumberFormatter $formatter

Number formatter instance.

array<string, mixed> $options optional

See Number::formatter() for possible options.

Returns

NumberFormatter

config() public static 

config(string $locale, int $type = NumberFormatter::DECIMAL, array<string, mixed> $options = []): void

Configure formatters.

Parameters

string $locale

The locale name to use for formatting the number, e.g. fr_FR

int $type optional

The formatter type to construct. Defaults to NumberFormatter::DECIMAL.

array<string, mixed> $options optional

See Number::formatter() for possible options.

Returns

void

currency() public static 

currency(string|float $value, string|null $currency = null, array<string, mixed> $options = []): string

Formats a number into a currency format.

Options

  • locale - The locale name to use for formatting the number, e.g. fr_FR
  • fractionSymbol - The currency symbol to use for fractional numbers.
  • fractionPosition - The position the fraction symbol should be placed valid options are 'before' & 'after'.
  • before - Text to display before the rendered number
  • after - Text to display after the rendered number
  • zero - The text to use for zero values, can be a string or a number. e.g. 0, 'Free!'
  • places - Number of decimal places to use. e.g. 2
  • precision - Maximum Number of decimal places to use, e.g. 2
  • pattern - An ICU number pattern to use for formatting the number. e.g #,##0.00
  • useIntlCode - Whether to replace the currency symbol with the international currency code.

Parameters

string|float $value

Value to format.

string|null $currency optional

International currency name such as 'USD', 'EUR', 'JPY', 'CAD'

array<string, mixed> $options optional

Options list.

Returns

string

defaultCurrency() public static 

defaultCurrency(string|false|null $currency = null): string|null

Getter/setter for default currency. This behavior is deprecated and will be removed in future versions of CakePHP.

Parameters

string|false|null $currency optional

Default currency string to be used by {@link currency()} if $currency argument is not provided. If boolean false is passed, it will clear the currently stored value

Returns

string|null

format() public static 

format(string|int|float $value, array<string, mixed> $options = []): string

Formats a number into the correct locale format

Options:

  • places - Minimum number or decimals to use, e.g 0
  • precision - Maximum Number of decimal places to use, e.g. 2
  • pattern - An ICU number pattern to use for formatting the number. e.g #,##0.00
  • locale - The locale name to use for formatting the number, e.g. fr_FR
  • before - The string to place before whole numbers, e.g. '['
  • after - The string to place after decimal numbers, e.g. ']'

Parameters

string|int|float $value

A floating point number.

array<string, mixed> $options optional

An array with options.

Returns

string

formatDelta() public static 

formatDelta(string|float $value, array<string, mixed> $options = []): string

Formats a number into the correct locale format to show deltas (signed differences in value).

Options

  • places - Minimum number or decimals to use, e.g 0
  • precision - Maximum Number of decimal places to use, e.g. 2
  • locale - The locale name to use for formatting the number, e.g. fr_FR
  • before - The string to place before whole numbers, e.g. '['
  • after - The string to place after decimal numbers, e.g. ']'

Parameters

string|float $value

A floating point number

array<string, mixed> $options optional

Options list.

Returns

string

formatter() public static 

formatter(array<string, mixed> $options = []): NumberFormatter

Returns a formatter object that can be reused for similar formatting task under the same locale and options. This is often a speedier alternative to using other methods in this class as only one formatter object needs to be constructed.

Options

  • locale - The locale name to use for formatting the number, e.g. fr_FR
  • type - The formatter type to construct, set it to currency if you need to format numbers representing money or a NumberFormatter constant.
  • places - Number of decimal places to use. e.g. 2
  • precision - Maximum Number of decimal places to use, e.g. 2
  • pattern - An ICU number pattern to use for formatting the number. e.g #,##0.00
  • useIntlCode - Whether to replace the currency symbol with the international currency code.

Parameters

array<string, mixed> $options optional

An array with options.

Returns

NumberFormatter

getDefaultCurrency() public static 

getDefaultCurrency(): string

Getter for default currency

Returns

string

getDefaultCurrencyFormat() public static 

getDefaultCurrencyFormat(): string

Getter for default currency format

Returns

string

ordinal() public static 

ordinal(float|int $value, array<string, mixed> $options = []): string

Returns a formatted integer as an ordinal number string (e.g. 1st, 2nd, 3rd, 4th, [...])

Options

  • type - The formatter type to construct, set it to currency if you need to format numbers representing money or a NumberFormatter constant.

For all other options see formatter().

Parameters

float|int $value

An integer

array<string, mixed> $options optional

An array with options.

Returns

string

parseFloat() public static 

parseFloat(string $value, array<string, mixed> $options = []): float

Parse a localized numeric string and transform it in a float point

Options:

  • locale - The locale name to use for parsing the number, e.g. fr_FR
  • type - The formatter type to construct, set it to currency if you need to parse numbers representing money.

Parameters

string $value

A numeric string.

array<string, mixed> $options optional

An array with options.

Returns

float

precision() public static 

precision(string|float $value, int $precision = 3, array<string, mixed> $options = []): string

Formats a number with a level of precision.

Options:

  • locale: The locale name to use for formatting the number, e.g. fr_FR

Parameters

string|float $value

A floating point number.

int $precision optional

The precision of the returned number.

array<string, mixed> $options optional

Additional options

Returns

string

Links

https://book.cakephp.org/4/en/core-libraries/number.html#formatting-floating-point-numbers

setDefaultCurrency() public static 

setDefaultCurrency(string|null $currency = null): void

Setter for default currency

Parameters

string|null $currency optional

Default currency string to be used by {@link currency()} if $currency argument is not provided. If null is passed, it will clear the currently stored value

Returns

void

setDefaultCurrencyFormat() public static 

setDefaultCurrencyFormat(string|null $currencyFormat = null): void

Setter for default currency format

Parameters

string|null $currencyFormat optional

Default currency format to be used by currency() if $currencyFormat argument is not provided. If null is passed, it will clear the currently stored value

Returns

void

toPercentage() public static 

toPercentage(string|float $value, int $precision = 2, array<string, mixed> $options = []): string

Formats a number into a percentage string.

Options:

  • multiply: Multiply the input value by 100 for decimal percentages.
  • locale: The locale name to use for formatting the number, e.g. fr_FR

Parameters

string|float $value

A floating point number

int $precision optional

The precision of the returned number

array<string, mixed> $options optional

Options

Returns

string

Links

https://book.cakephp.org/4/en/core-libraries/number.html#formatting-percentages

toReadableSize() public static 

toReadableSize(string|int $size): string

Returns a formatted-for-humans file size.

Parameters

string|int $size

Size in bytes

Returns

string

Links

https://book.cakephp.org/4/en/core-libraries/number.html#interacting-with-human-readable-values

Property Detail

$_defaultCurrency protected static

Default currency used by Number::currency()

Type

string|null

$_defaultCurrencyFormat protected static

Default currency format used by Number::currency()

Type

string|null

$_formatters protected static

A list of number formatters indexed by locale and type

Type

array<string, array<int, mixed>>

© 2005–present The Cake Software Foundation, Inc.
Licensed under the MIT License.
CakePHP is a registered trademark of Cake Software Foundation, Inc.
We are not endorsed by or affiliated with CakePHP.
https://api.cakephp.org/4.4/class-Cake.I18n.Number.html