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, vous pouvez formater les nombres, les montants de devises et les pourcentages, en fonctions des conventions locales. NumberFormatter prend en compte les conventions, ce qui fait que vous devez créer un nouvel objet NumberFormatter, pour chaque convention. Les méthodes de NumberFormatter, formatent des types primitifs comme des nombres décimaux, et produit une chaîne de caractères.

Pour les monnaies, vous pouvez 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, quelqu'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, vous devez 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 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_ACCOUNTING; 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_HALFEVEN; 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 __construct(string $locale, int $style, ?string $pattern = null) public static create(string $locale, int $style, ?string $pattern = null): ?NumberFormatter public formatCurrency(float $amount, string $currency): string|false public format(int|float $num, int $type = NumberFormatter::TYPE_DEFAULT): string|false public getAttribute(int $attribute): int|float|false public getErrorCode(): int public getErrorMessage(): string public getLocale(int $type = ULOC_ACTUAL_LOCALE): string|false public getPattern(): string|false public getSymbol(int $symbol): string|false public getTextAttribute(int $attribute): string|false public parseCurrency(string $string, string &$currency, int &$offset = null): float|false public parse(string $string, int $type = NumberFormatter::TYPE_DOUBLE, int &$offset = null): int|float|false public setAttribute(int $attribute, int|float $value): bool public setPattern(string $pattern): bool public setSymbol(int $symbol, string $value): bool public setTextAttribute(int $attribute, string $value): bool }

Constantes pré-définies

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

NumberFormatter::PATTERN_DECIMAL

Format décimal défini par un modèle

NumberFormatter::DECIMAL

Format décimal

NumberFormatter::CURRENCY

Format monétaire

NumberFormatter::PERCENT

Format pourcentage

NumberFormatter::SCIENTIFIC

Format scientifique

NumberFormatter::SPELLOUT

Format littéral, basé sur des règles

NumberFormatter::ORDINAL

Format ordinal, basé sur des règles

NumberFormatter::DURATION

Format de durée, basé sur des règles

NumberFormatter::PATTERN_RULEBASED

Format de modèle, basé sur des règles

NumberFormatter::CURRENCY_ACCOUNTING

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

Format par défaut pour les conventions locales

NumberFormatter::IGNORE

Alias de PATTERN_DECIMAL

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

NumberFormatter::TYPE_DEFAULT

Dérive le type depuis le type de variable

NumberFormatter::TYPE_INT32

Formate / analyse un entier 32 bits

NumberFormatter::TYPE_INT64

Formate / analyse un entier 64 bits

NumberFormatter::TYPE_DOUBLE

Formate / analyse un nombre décimal

NumberFormatter::TYPE_CURRENCY

Formate / analyse une valeur monétaire

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

NumberFormatter::PARSE_INT_ONLY

Analyse uniquement les entiers.

NumberFormatter::GROUPING_USED

Séparateur de groupes.

NumberFormatter::DECIMAL_ALWAYS_SHOWN

Affiche toujours une virgule décimale.

NumberFormatter::MAX_INTEGER_DIGITS

Nombre maximal de chiffres.

NumberFormatter::MIN_INTEGER_DIGITS

Nombre minimal de chiffres.

NumberFormatter::INTEGER_DIGITS

Nombre de chiffres.

NumberFormatter::MAX_FRACTION_DIGITS

Nombre maximal de décimales.

NumberFormatter::MIN_FRACTION_DIGITS

Nombre minimal de décimales.

NumberFormatter::FRACTION_DIGITS

Nombre de décimales.

NumberFormatter::MULTIPLIER

Multiplicateur.

NumberFormatter::GROUPING_SIZE

Taille de regroupement.

NumberFormatter::ROUNDING_MODE

Mode d'arrondi.

NumberFormatter::ROUNDING_INCREMENT

Incrément d'arrondi.

NumberFormatter::FORMAT_WIDTH

La largeur de complément pour le formattage d'un nombre.

NumberFormatter::PADDING_POSITION

La position à laquelle le complément se fait. Voyez les constantes de complément pour avoir les différentes valeurs possibles.

NumberFormatter::SECONDARY_GROUPING_SIZE

Taille secondaire de groupement.

NumberFormatter::SIGNIFICANT_DIGITS_USED

Utilise les chiffres significatifs.

NumberFormatter::MIN_SIGNIFICANT_DIGITS

Nombre minimum de chiffres significatifs.

NumberFormatter::MAX_SIGNIFICANT_DIGITS

Nombre maximum de chiffres significatifs.

NumberFormatter::LENIENT_PARSE

Mode d'analyse utilisé par les formats à règles.

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

NumberFormatter::POSITIVE_PREFIX

Préfixe positif.

NumberFormatter::POSITIVE_SUFFIX

Suffixe positif.

NumberFormatter::NEGATIVE_PREFIX

Préfixe négatif.

NumberFormatter::NEGATIVE_SUFFIX

Suffixe négatif.

NumberFormatter::PADDING_CHARACTER

Le caractère à utiliser pour compléter les formats jusqu'à la taille.

NumberFormatter::CURRENCY_CODE

Le code de devise ISO.

NumberFormatter::DEFAULT_RULESET

Le jeu de règles par défaut. Il est uniquement utilisable avec les formatteurs à règles.

NumberFormatter::PUBLIC_RULESETS

Le jeu de règles publiques. Ceci est uniquement disponible avec les formatteurs à 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 ';'.

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

NumberFormatter::DECIMAL_SEPARATOR_SYMBOL

Le séparateur décimal.

NumberFormatter::GROUPING_SEPARATOR_SYMBOL

Le séparateur de groupes.

NumberFormatter::PATTERN_SEPARATOR_SYMBOL

Le modèle de séparateur.

NumberFormatter::PERCENT_SYMBOL

Le signe de pourcentage.

NumberFormatter::ZERO_DIGIT_SYMBOL

Zéro.

NumberFormatter::DIGIT_SYMBOL

Un caractère représentant un chiffre dans un modèle.

NumberFormatter::MINUS_SIGN_SYMBOL

Le signe moins.

NumberFormatter::PLUS_SIGN_SYMBOL

Le signe plus.

NumberFormatter::CURRENCY_SYMBOL

Le symbole de devise.

NumberFormatter::INTL_CURRENCY_SYMBOL

Le symbole international de devise.

NumberFormatter::MONETARY_SEPARATOR_SYMBOL

Le séparateur monétaire.

NumberFormatter::EXPONENTIAL_SYMBOL

Le symbole d'exponentiel.

NumberFormatter::PERMILL_SYMBOL

Le symbol par mille.

NumberFormatter::PAD_ESCAPE_SYMBOL

Le caractère de protection des symboles.

NumberFormatter::INFINITY_SYMBOL

Le symbole de l'infini.

NumberFormatter::NAN_SYMBOL

Le symbole "n'est pas un nombre".

NumberFormatter::SIGNIFICANT_DIGIT_SYMBOL

Le symbole des chiffres significatifs.

NumberFormatter::MONETARY_GROUPING_SEPARATOR_SYMBOL

Le séparateur de groupes monétaires.

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

NumberFormatter::ROUND_CEILING

Mode d'arrondi vers l'infini positif.

NumberFormatter::ROUND_DOWN

Mode d'arrondi vers zéro.

NumberFormatter::ROUND_FLOOR

Mode d'arrondi vers l'infini négatif.

NumberFormatter::ROUND_HALFDOWN

Mode d'arrondi vers le plus proche entier, a moins qu'ils soient équidistants : arrondi inférieur dans ce cas.

NumberFormatter::ROUND_HALFEVEN

Mode d'arrondi vers le plus proche entier, a moins qu'ils soient équidistants : arrondi vers le nombre pair dans ce cas.

NumberFormatter::ROUND_HALFUP

Mode d'arrondi vers le plus proche entier, a moins qu'ils soient équidistants : arrondi supérieur dans ce cas.

NumberFormatter::ROUND_UP

Mode d'arrondi qui éloigne de zéro.

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

NumberFormatter::PAD_AFTER_PREFIX

Caractères de compléments ajoutés après le préfixe.

NumberFormatter::PAD_AFTER_SUFFIX

Caractères de compléments ajoutés après le suffixe.

NumberFormatter::PAD_BEFORE_PREFIX

Caractères de compléments ajoutés avant le préfixe.

NumberFormatter::PAD_BEFORE_SUFFIX

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 de ICU

Sommaire

• NumberFormatter::create — Crée un formateur de nombre
• NumberFormatter::formatCurrency — Formate une valeur monétaire
• NumberFormatter::format — Formate un nombre
• 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::parseCurrency — Analyse un nombre monétaire
• NumberFormatter::parse — Analyse un nombre
• 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