# La classe NumberFormatter

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

## Introduction

Les programmes stockent et manipulent des nombres en utilisant une représentation locale, binaire et indépendante. Lors de l'affichage d'un nombre, il est converti en une version particulière. Par exemple, un nombre tel que 12345.67 s'écrit "12,345.67" aux USA, "12 345,67" en France et "12.345,67" en Allemagne.

En appelant les méthodes fournies par NumberFormatter, il est possible de formater les nombres, les montants de devises et les pourcentages, en fonction des conventions locales. NumberFormatter prend en compte les conventions, ce qui fait qu'il faut créer un nouvel objet NumberFormatter, pour chaque convention. Les méthodes de NumberFormatter, formatent des types primitifs comme des nombres décimaux, et produisent une chaîne de caractères.

Pour les monnaies, il est possible d'utiliser le format monétaire pour créer un formateur qui retourne une chaîne, avec le symbole de devise approprié. Bien entendu, NumberFormatter ne connait pas les taux de changes, ce qui fait que l'affichage sera fait, quel qu'en soit la devise demandée. Cela signifie que le même nombre aura différentes valeurs monétaires en fonction de la configuration locale. Par exemple, le nombre 9988776.65 s'affichera :

- 9 988 776,65 € en France
- 9.988.776,65 € en Allemagne
- $9,988,776.65 aux USA

Pour formater des pourcentages, il faut créer un formateur local, avec un type de format pourcentage. Avec ce formateur, une fraction décimale telle que 0.75 sera affichée 75%.

Pour des formatages plus complexes, comme des nombres écrits littéralement, des formateurs à règles sont utilisés.

## Synopsis de la classe

class NumberFormatter {
/* Constantes */
public const int PATTERN_DECIMAL;
public const int DECIMAL;
public const int DECIMAL_COMPACT_SHORT;
public const int DECIMAL_COMPACT_LONG;
public const int CURRENCY;
public const int PERCENT;
public const int SCIENTIFIC;
public const int SPELLOUT;
public const int ORDINAL;
public const int DURATION;
public const int PATTERN_RULEBASED;
public const int IGNORE;
public const int CURRENCY_ISO;
public const int CURRENCY_PLURAL;
public const int CURRENCY_ACCOUNTING;
public const int CASH_CURRENCY;
public const int CURRENCY_STANDARD;
public const int DEFAULT_STYLE;
public const int ROUND_CEILING;
public const int ROUND_FLOOR;
public const int ROUND_DOWN;
public const int ROUND_UP;
public const int ROUND_TOWARD_ZERO;
public const int ROUND_AWAY_FROM_ZERO;
public const int ROUND_HALFEVEN;
public const int ROUND_HALFODD;
public const int ROUND_HALFDOWN;
public const int ROUND_HALFUP;
public const int PAD_BEFORE_PREFIX;
public const int PAD_AFTER_PREFIX;
public const int PAD_BEFORE_SUFFIX;
public const int PAD_AFTER_SUFFIX;
public const int PARSE_INT_ONLY;
public const int GROUPING_USED;
public const int DECIMAL_ALWAYS_SHOWN;
public const int MAX_INTEGER_DIGITS;
public const int MIN_INTEGER_DIGITS;
public const int INTEGER_DIGITS;
public const int MAX_FRACTION_DIGITS;
public const int MIN_FRACTION_DIGITS;
public const int FRACTION_DIGITS;
public const int MULTIPLIER;
public const int GROUPING_SIZE;
public const int ROUNDING_MODE;
public const int ROUNDING_INCREMENT;
public const int FORMAT_WIDTH;
public const int PADDING_POSITION;
public const int SECONDARY_GROUPING_SIZE;
public const int SIGNIFICANT_DIGITS_USED;
public const int MIN_SIGNIFICANT_DIGITS;
public const int MAX_SIGNIFICANT_DIGITS;
public const int LENIENT_PARSE;
public const int POSITIVE_PREFIX;
public const int POSITIVE_SUFFIX;
public const int NEGATIVE_PREFIX;
public const int NEGATIVE_SUFFIX;
public const int PADDING_CHARACTER;
public const int CURRENCY_CODE;
public const int DEFAULT_RULESET;
public const int PUBLIC_RULESETS;
public const int DECIMAL_SEPARATOR_SYMBOL;
public const int GROUPING_SEPARATOR_SYMBOL;
public const int PATTERN_SEPARATOR_SYMBOL;
public const int PERCENT_SYMBOL;
public const int ZERO_DIGIT_SYMBOL;
public const int DIGIT_SYMBOL;
public const int MINUS_SIGN_SYMBOL;
public const int PLUS_SIGN_SYMBOL;
public const int CURRENCY_SYMBOL;
public const int INTL_CURRENCY_SYMBOL;
public const int MONETARY_SEPARATOR_SYMBOL;
public const int EXPONENTIAL_SYMBOL;
public const int PERMILL_SYMBOL;
public const int PAD_ESCAPE_SYMBOL;
public const int INFINITY_SYMBOL;
public const int NAN_SYMBOL;
public const int SIGNIFICANT_DIGIT_SYMBOL;
public const int MONETARY_GROUPING_SEPARATOR_SYMBOL;
public const int TYPE_DEFAULT;
public const int TYPE_INT32;
public const int TYPE_INT64;
public const int TYPE_DOUBLE;
public const int TYPE_CURRENCY;
/* Méthodes */
public function __construct(string `$locale`, int `$style`, ?string `$pattern` = `null`)
public static function create(string `$locale`, int `$style`, ?string `$pattern` = `null`): ?NumberFormatter
public function format(int|float `$num`, int `$type` = `NumberFormatter::TYPE_DEFAULT`): string|false
public function formatCurrency(float `$amount`, string `$currency`): string|false
public function getAttribute(int `$attribute`): int|float|false
public function getErrorCode(): int
public function getErrorMessage(): string
public function getLocale(int `$type` = `ULOC_ACTUAL_LOCALE`): string|false
public function getPattern(): string|false
public function getSymbol(int `$symbol`): string|false
public function getTextAttribute(int `$attribute`): string|false
public function parse(string `$string`, int `$type` = `NumberFormatter::TYPE_DOUBLE`, int `&$offset` = `null`): int|float|false
public function parseCurrency(string `$string`, string `&$currency`, int `&$offset` = `null`): float|false
public function setAttribute(int `$attribute`, int|float `$value`): bool
public function setPattern(string `$pattern`): bool
public function setSymbol(int `$symbol`, string `$value`): bool
public function setTextAttribute(int `$attribute`, string `$value`): bool
}

## Constantes pré-définies

## Types de format

Ces styles sont utilisés par numfmt_create() pour définir le type de formateur.

`NumberFormatter::PATTERN_DECIMAL` int
  Format décimal défini par un modèle
`NumberFormatter::DECIMAL` int
  Format décimal
`NumberFormatter::DECIMAL_COMPACT_SHORT` int
  Format décimal exprimé en notation compacte (forme courte), par exemple « 23K », « 45B ». Disponible à partir de PHP 8.5.0 et ICU 56.
`NumberFormatter::DECIMAL_COMPACT_LONG` int
  Format décimal exprimé en notation compacte (forme longue), par exemple « 23 thousand », « 45 billion ». Disponible à partir de PHP 8.5.0 et ICU 56.
`NumberFormatter::CURRENCY` int
  Format monétaire
`NumberFormatter::CURRENCY_ISO` int
  Format monétaire ISO (par exemple, « USD1.00 »). Disponible à partir de PHP 8.5.0.
`NumberFormatter::CURRENCY_PLURAL` int
  Format monétaire pluralisé (par exemple, « 1.00 US dollar » et « 3.00 US dollars »). Disponible à partir de PHP 8.5.0.
`NumberFormatter::CASH_CURRENCY` int
  Symbole monétaire pour l'utilisation en espèces, par exemple « NT$3 » au lieu de « NT$3.23 ». Disponible à partir de PHP 8.5.0 et ICU 54.
`NumberFormatter::CURRENCY_STANDARD` int
  Symbole monétaire, par exemple « $1.00 », utilisant un style non comptable pour les valeurs négatives (par exemple le signe moins). Disponible à partir de PHP 8.5.0 et ICU 56.
`NumberFormatter::PERCENT` int
  Format pourcentage
`NumberFormatter::SCIENTIFIC` int
  Format scientifique
`NumberFormatter::SPELLOUT` int
  Format littéral, basé sur des règles
`NumberFormatter::ORDINAL` int
  Format ordinal, basé sur des règles
`NumberFormatter::DURATION` int
  Format de durée, basé sur des règles
`NumberFormatter::PATTERN_RULEBASED` int
  Format de modèle, basé sur des règles
`NumberFormatter::CURRENCY_ACCOUNTING` int
  Format monétaire pour la comptabilité, par exemple, `($3.00)` pour un montant de devise négatif au lieu de `-$3.00`. Disponible à partir de PHP 7.4.1 et ICU 53.
`NumberFormatter::DEFAULT_STYLE` int
  Format par défaut pour les conventions locales
`NumberFormatter::IGNORE` int
  Alias de PATTERN_DECIMAL

## Spécificateurs de format de nombre

Ces constantes définissent la méthode d'analyse et de formatage des nombres. Elles doivent être utilisées comme arguments des fonctions numfmt_format() et numfmt_parse().

`NumberFormatter::TYPE_DEFAULT` int
  Dérive le type depuis le type de variable
`NumberFormatter::TYPE_INT32` int
  Formate / analyse un entier 32 bits
`NumberFormatter::TYPE_INT64` int
  Formate / analyse un entier 64 bits
`NumberFormatter::TYPE_DOUBLE` int
  Formate / analyse un nombre décimal
`NumberFormatter::TYPE_CURRENCY` int
  Formate / analyse une valeur monétaire. Obsolète à partir de PHP 8.3.0

## Attributs de format de nombre

Attributs de formats de nombre utilisés par numfmt_get_attribute() et numfmt_set_attribute().

`NumberFormatter::PARSE_INT_ONLY` int
  Analyse uniquement les entiers.
`NumberFormatter::GROUPING_USED` int
  Séparateur de groupes.
`NumberFormatter::DECIMAL_ALWAYS_SHOWN` int
  Affiche toujours une virgule décimale.
`NumberFormatter::MAX_INTEGER_DIGITS` int
  Nombre maximal de chiffres.
`NumberFormatter::MIN_INTEGER_DIGITS` int
  Nombre minimal de chiffres.
`NumberFormatter::INTEGER_DIGITS` int
  Nombre de chiffres.
`NumberFormatter::MAX_FRACTION_DIGITS` int
  Nombre maximal de décimales.
`NumberFormatter::MIN_FRACTION_DIGITS` int
  Nombre minimal de décimales.
`NumberFormatter::FRACTION_DIGITS` int
  Nombre de décimales.
`NumberFormatter::MULTIPLIER` int
  Multiplicateur.
`NumberFormatter::GROUPING_SIZE` int
  Taille de regroupement.
`NumberFormatter::ROUNDING_MODE` int
  Mode d'arrondi.
`NumberFormatter::ROUNDING_INCREMENT` int
  Incrément d'arrondi.
`NumberFormatter::FORMAT_WIDTH` int
  La largeur de complément pour le formatage d'un nombre.
`NumberFormatter::PADDING_POSITION` int
  La position à laquelle le complément se fait. Voir les constantes de complément pour avoir les différentes valeurs possibles.
`NumberFormatter::SECONDARY_GROUPING_SIZE` int
  Taille secondaire de groupement.
`NumberFormatter::SIGNIFICANT_DIGITS_USED` int
  Utilise les chiffres significatifs.
`NumberFormatter::MIN_SIGNIFICANT_DIGITS` int
  Nombre minimum de chiffres significatifs.
`NumberFormatter::MAX_SIGNIFICANT_DIGITS` int
  Nombre maximum de chiffres significatifs.
`NumberFormatter::LENIENT_PARSE` int
  Mode d'analyse utilisé par les formats à règles.

## Attributs de texte de format de nombre

Attributs de texte pour les formats de nombres, utilisés par numfmt_get_text_attribute() et numfmt_set_text_attribute().

`NumberFormatter::POSITIVE_PREFIX` int
  Préfixe positif.
`NumberFormatter::POSITIVE_SUFFIX` int
  Suffixe positif.
`NumberFormatter::NEGATIVE_PREFIX` int
  Préfixe négatif.
`NumberFormatter::NEGATIVE_SUFFIX` int
  Suffixe négatif.
`NumberFormatter::PADDING_CHARACTER` int
  Le caractère à utiliser pour compléter les formats jusqu'à la taille.
`NumberFormatter::CURRENCY_CODE` int
  Le code de devise ISO.
`NumberFormatter::DEFAULT_RULESET` int
  Le jeu de règles par défaut. Il est uniquement utilisable avec les formateurs à règles.
`NumberFormatter::PUBLIC_RULESETS` int
  Le jeu de règles publiques. Ceci est uniquement disponible avec les formateurs à règles. C'est un attribut en lecture seule. Les règles publiques sont retournées sous forme d'une seule chaîne, et chaque règle est délimitée par un point-virgule ';'.

## Spécification des Symboles de Format

Les symboles de format utilisés par numfmt_get_symbol() et numfmt_set_symbol().

`NumberFormatter::DECIMAL_SEPARATOR_SYMBOL` int
  Le séparateur décimal.
`NumberFormatter::GROUPING_SEPARATOR_SYMBOL` int
  Le séparateur de groupes.
`NumberFormatter::PATTERN_SEPARATOR_SYMBOL` int
  Le modèle de séparateur.
`NumberFormatter::PERCENT_SYMBOL` int
  Le signe de pourcentage.
`NumberFormatter::ZERO_DIGIT_SYMBOL` int
  Zéro.
`NumberFormatter::DIGIT_SYMBOL` int
  Un caractère représentant un chiffre dans un modèle.
`NumberFormatter::MINUS_SIGN_SYMBOL` int
  Le signe moins.
`NumberFormatter::PLUS_SIGN_SYMBOL` int
  Le signe plus.
`NumberFormatter::CURRENCY_SYMBOL` int
  Le symbole de devise.
`NumberFormatter::INTL_CURRENCY_SYMBOL` int
  Le symbole international de devise.
`NumberFormatter::MONETARY_SEPARATOR_SYMBOL` int
  Le séparateur monétaire.
`NumberFormatter::EXPONENTIAL_SYMBOL` int
  Le symbole d'exponentiel.
`NumberFormatter::PERMILL_SYMBOL` int
  Le symbole par mille.
`NumberFormatter::PAD_ESCAPE_SYMBOL` int
  Le caractère de protection des symboles.
`NumberFormatter::INFINITY_SYMBOL` int
  Le symbole de l'infini.
`NumberFormatter::NAN_SYMBOL` int
  Le symbole "n'est pas un nombre".
`NumberFormatter::SIGNIFICANT_DIGIT_SYMBOL` int
  Le symbole des chiffres significatifs.
`NumberFormatter::MONETARY_GROUPING_SEPARATOR_SYMBOL` int
  Le séparateur de groupes monétaires.

## Modes d'arrondi

Les modes d'arrondi utilisés par les fonctions numfmt_get_attribute() et numfmt_set_attribute() avec l'attribut `NumberFormatter::ROUNDING_MODE`.

`NumberFormatter::ROUND_AWAY_FROM_ZERO`
  Alias de `NumberFormatter::ROUND_UP`.
`NumberFormatter::ROUND_CEILING`
  Mode d'arrondi vers l'infini positif.
`NumberFormatter::ROUND_DOWN` int
  Mode d'arrondi vers zéro.
`NumberFormatter::ROUND_FLOOR` int
  Mode d'arrondi vers l'infini négatif.
`NumberFormatter::ROUND_HALFDOWN` int
  Mode d'arrondi vers le plus proche entier, à moins qu'ils soient équidistants : arrondi inférieur dans ce cas.
`NumberFormatter::ROUND_HALFEVEN` int
  Mode d'arrondi vers le plus proche entier, à moins qu'ils soient équidistants : arrondi vers le nombre pair dans ce cas.
`NumberFormatter::ROUND_HALFODD`
  Mode d’arrondi vers le « voisin impair ».
`NumberFormatter::ROUND_HALFUP`
  Mode d'arrondi vers le plus proche entier, à moins qu'ils soient équidistants : arrondi supérieur dans ce cas.
`NumberFormatter::ROUND_TOWARD_ZERO`
  Alias de `NumberFormatter::ROUND_DOWN`.
`NumberFormatter::ROUND_UP` int
  Mode d'arrondi qui éloigne de zéro.

## Spécificateurs de rembourrage

Valeurs de compléments utilisés par numfmt_get_attribute() et numfmt_set_attribute() avec l'attribut `NumberFormatter::PADDING_POSITION`.

`NumberFormatter::PAD_AFTER_PREFIX` int
  Caractères de compléments ajoutés après le préfixe.
`NumberFormatter::PAD_AFTER_SUFFIX` int
  Caractères de compléments ajoutés après le suffixe.
`NumberFormatter::PAD_BEFORE_PREFIX` int
  Caractères de compléments ajoutés avant le préfixe.
`NumberFormatter::PAD_BEFORE_SUFFIX` int
  Caractères de compléments ajoutés avant le suffixe.

## Voir aussi

- » Documentation de formatage ICU
- » Formateurs de nombres ICU
- » Formateur de nombres décimaux ICU
- » Formateurs à règles d'ICU

## Historique

Version | Description
--- | ---
8.5.0 | Ajout de `NumberFormatter::DECIMAL_COMPACT_SHORT`, `NumberFormatter::DECIMAL_COMPACT_LONG`, `NumberFormatter::CURRENCY_ISO`, `NumberFormatter::CURRENCY_PLURAL`, `NumberFormatter::CASH_CURRENCY`, `NumberFormatter::CURRENCY_STANDARD`.
8.4.0 | Les constantes de classe sont maintenant typées.

## Sommaire

- NumberFormatter::create — Crée un formateur de nombre
- NumberFormatter::format — Formate un nombre
- NumberFormatter::formatCurrency — Formate une valeur monétaire
- NumberFormatter::getAttribute — Lit un attribut
- NumberFormatter::getErrorCode — Lit le dernier code d'erreur du formateur
- NumberFormatter::getErrorMessage — Lit le dernier message d'erreur du formateur
- NumberFormatter::getLocale — Lit la locale du formateur
- NumberFormatter::getPattern — Lit le modèle du formateur
- NumberFormatter::getSymbol — Lit la valeur du symbole
- NumberFormatter::getTextAttribute — Lit un attribut textuel
- NumberFormatter::parse — Analyse un nombre
- NumberFormatter::parseCurrency — Analyse un nombre monétaire
- NumberFormatter::setAttribute — Affecte un attribut du formateur
- NumberFormatter::setPattern — Configure le modèle du formateur
- NumberFormatter::setSymbol — Configure le symbole du formateur
- NumberFormatter::setTextAttribute — Modifie un attribut texte

`↑` and `↓` to navigate • `Enter` to select • `Esc` to close • `/` to open