# La clase NumberFormatter

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

## Introducción

Los programas almacenan y operan sobre números utilizando una representación binaria independiente de la configuración regional. Cuando se muestra o imprime un número, éste es convertido a una cadena específica regional. Por ejemplo, el número 12345.67 es "12,345.67" en los Estados Unidos, "12 345,67" en Francia y "12.345,67" en Alemania.

Al invocar a los métodos proporcionados por la clase NumberFormatter, se pueden formatear números, valores monetarios y porcentajes de acuerdo a la configuración regional especificada o predeterminada. NumberFormatter es sensible a la configuración regional, por lo que se necesita crear un nuevo objeto NumberFormatter para cada región. Los métodos de NumberFormatter dan formato a números de tipo primitivo, tales como los de tipo double, e imprimien el número como una cadena específica según la región.

Para los valores monetarios se puede utilizar el tipo de formato de moneda para crear un formateador que devuelva una cadena con el número formateado y el símbolo de moneda apropiada. Por supuesto, la clase NumberFormatter ignora los tipos de cambio monetarios, por lo que el número impreso es el mismo sin tener en cuenta la moneda especificada. Esto significa que el mismo número tiene diferentes valores monetarios dependiendo de la moneda regional. Si el numero fuese el 9988776.65, los resultados serían:

- 9 988 776,65 € en Francia
- 9.988.776,65 € en Alemania
- $9,988,776.65 en los Estados Unidos

Para dar formato a los porcentajes, se debe crear un formateador específico de la región con el tipo de formato de porcentaje. Con este formateador, una fracción decimal como 0.75 será mostrada como 75%.

Para un formateo más complejo, como los números escritos con palabras, se usan los formateadores de números basados en reglas.

## Sinopsis de la Clase

class NumberFormatter {
/* Métodos */
public __construct(string `$locale`, int `$style`, string `$pattern` = ?)
public static create(string `$locale`, int `$style`, string `$pattern` = ?): NumberFormatter
public formatCurrency(float `$value`, string `$currency`): string
public format(number `$value`, int `$type` = ?): string
public getAttribute(int `$attr`): int
public getErrorCode(): int
public getErrorMessage(): string
public getLocale(int `$type` = ?): string
public getPattern(): string
public getSymbol(int `$attr`): string
public getTextAttribute(int `$attr`): string
public parseCurrency(string `$value`, string `&$currency`, int `&$position` = ?): float
public parse(string `$value`, int `$type` = ?, int `&$position` = ?): mixed
public setAttribute(int `$attr`, int `$value`): bool
public setPattern(string `$pattern`): bool
public setSymbol(int `$attr`, string `$value`): bool
public setTextAttribute(int `$attr`, string `$value`): bool
}

## Constantes predefinidas

Estos estilos son utilzados por la función numfmt_create() para definir el tipo del formateador.

`NumberFormatter::PATTERN_DECIMAL` (integer)
  Formato decimal definido por un patrón
`NumberFormatter::DECIMAL` (integer)
  Formato decimal
`NumberFormatter::CURRENCY` (integer)
  Formato de moneda
`NumberFormatter::PERCENT` (integer)
  Formato de porcentaje
`NumberFormatter::SCIENTIFIC` (integer)
  Formato científico
`NumberFormatter::SPELLOUT` (integer)
  Formato basado en reglas de números escritos con palabras
`NumberFormatter::ORDINAL` (integer)
  Formato basado en reglas de números ordinales
`NumberFormatter::DURATION` (integer)
  Formato basado en reglas de duración
`NumberFormatter::PATTERN_RULEBASED` (integer)
  Formato basado en reglas definido por un patrón
`NumberFormatter::DEFAULT_STYLE` (integer)
  Formato predeterminado para la configuración regional
`NumberFormatter::IGNORE` (integer)
  Alias de PATTERN_DECIMAL

Estas constantes definen cómo se procesan o formatean los números. Deberían usarse como argumentos de numfmt_format() y numfmt_parse().

`NumberFormatter::TYPE_DEFAULT` (integer)
  Deriva el tipo de número del tipo de la variable
`NumberFormatter::TYPE_INT32` (integer)
  Formatear/procesar como un valor integer de 32 bits
`NumberFormatter::TYPE_INT64` (integer)
  Formatear/procesar como un valor integer de 64 bits
`NumberFormatter::TYPE_DOUBLE` (integer)
  Formatear/procesar como un valor de coma flotante
`NumberFormatter::TYPE_CURRENCY` (integer)
  FFormatear/procesar como un valor de moneda

Atributos de formato numérico usados por numfmt_get_attribute() y numfmt_set_attribute().

`NumberFormatter::PARSE_INT_ONLY` (integer)
  Procesar sólo los enteros.
`NumberFormatter::GROUPING_USED` (integer)
  Usar un separador de agrupación.
`NumberFormatter::DECIMAL_ALWAYS_SHOWN` (integer)
  Mostrar siempre la coma (punto) decimal.
`NumberFormatter::MAX_INTEGER_DIGITS` (integer)
  Número máximo de dígitos enteros.
`NumberFormatter::MIN_INTEGER_DIGITS` (integer)
  Número mínimo de dígitos enteros.
`NumberFormatter::INTEGER_DIGITS` (integer)
  Dígitos enteros.
`NumberFormatter::MAX_FRACTION_DIGITS` (integer)
  Número máximo de dígitos fraccionarios.
`NumberFormatter::MIN_FRACTION_DIGITS` (integer)
  Número mínimo de dígitos fraccionarios.
`NumberFormatter::FRACTION_DIGITS` (integer)
  Dígitos fraccionarios.
`NumberFormatter::MULTIPLIER` (integer)
  Multiplicador.
`NumberFormatter::GROUPING_SIZE` (integer)
  Tamaño de la agrupación.
`NumberFormatter::ROUNDING_MODE` (integer)
  Modo de redondeo.
`NumberFormatter::ROUNDING_INCREMENT` (integer)
  Incremento del redondeo.
`NumberFormatter::FORMAT_WIDTH` (integer)
  El ancho al que se ajusta la salida de format().
`NumberFormatter::PADDING_POSITION` (integer)
  La posición en la que el relleno tendrá lugar. Véase las constantes de posición de relleno para los posibles valores de los argumentos.
`NumberFormatter::SECONDARY_GROUPING_SIZE` (integer)
  Tamaño de agrupación secundario.
`NumberFormatter::SIGNIFICANT_DIGITS_USED` (integer)
  Utilizar dígitos significativos.
`NumberFormatter::MIN_SIGNIFICANT_DIGITS` (integer)
  Número mínimo de dígitos significativos.
`NumberFormatter::MAX_SIGNIFICANT_DIGITS` (integer)
  Número máximo de dígitos significativos.
`NumberFormatter::LENIENT_PARSE` (integer)
  Modo de proceso poco riguroso usado por los formatos basados en reglas.

Atributos de texto de formato numérico utilizados por numfmt_get_text_attribute() y numfmt_set_text_attribute().

`NumberFormatter::POSITIVE_PREFIX` (integer)
  Prefijo positivo.
`NumberFormatter::POSITIVE_SUFFIX` (integer)
  Sufijo positivo.
`NumberFormatter::NEGATIVE_PREFIX` (integer)
  Prefijo negativo.
`NumberFormatter::NEGATIVE_SUFFIX` (integer)
  Sufijo negativo.
`NumberFormatter::PADDING_CHARACTER` (integer)
  El carácter usado para rellenar el ancho del formato.
`NumberFormatter::CURRENCY_CODE` (integer)
  El código ISO de la moneda.
`NumberFormatter::DEFAULT_RULESET` (integer)
  El conjunto de reglas predeterminadas. Sólo está disponible con formateadores basados en reglas.
`NumberFormatter::PUBLIC_RULESETS` (integer)
  Los conjuntos de reglas públicas. Sólo está disponible con formateadores basados en reglas. Este atributo es de sólo lectura. Los conjuntos de reglas públicas son devueltos como una cadena simple, con cada conjunto de reglas deliminado por ';' (semicolon).

Símbolos de formato numérico utilizados por numfmt_get_symbol() y numfmt_set_symbol().

`NumberFormatter::DECIMAL_SEPARATOR_SYMBOL` (integer)
  El separador decimal.
`NumberFormatter::GROUPING_SEPARATOR_SYMBOL` (integer)
  El separador de agrupación.
`NumberFormatter::PATTERN_SEPARATOR_SYMBOL` (integer)
  El separador de patrones.
`NumberFormatter::PERCENT_SYMBOL` (integer)
  El signo de porcentaje.
`NumberFormatter::ZERO_DIGIT_SYMBOL` (integer)
  Cero.
`NumberFormatter::DIGIT_SYMBOL` (integer)
  Carácter que representa un dígito en el patrón.
`NumberFormatter::MINUS_SIGN_SYMBOL` (integer)
  El símbolo menos.
`NumberFormatter::PLUS_SIGN_SYMBOL` (integer)
  El símbolo más.
`NumberFormatter::CURRENCY_SYMBOL` (integer)
  El símbolo de moneda.
`NumberFormatter::INTL_CURRENCY_SYMBOL` (integer)
  El símbolo internacional de moneda.
`NumberFormatter::MONETARY_SEPARATOR_SYMBOL` (integer)
  El separador monetario.
`NumberFormatter::EXPONENTIAL_SYMBOL` (integer)
  El símbolo exponencial.
`NumberFormatter::PERMILL_SYMBOL` (integer)
  El símbolo por millón.
`NumberFormatter::PAD_ESCAPE_SYMBOL` (integer)
  El carácter de relleno de escape.
`NumberFormatter::INFINITY_SYMBOL` (integer)
  Símbolo de infinito.
`NumberFormatter::NAN_SYMBOL` (integer)
  Símbolo de no-es-un-número (NaN).
`NumberFormatter::SIGNIFICANT_DIGIT_SYMBOL` (integer)
  Símbolo de dígito significativo.
`NumberFormatter::MONETARY_GROUPING_SEPARATOR_SYMBOL` (integer)
  El separador de agrupación monetaria.

Los valores del modo de redondeo utilizados por numfmt_get_attribute() y numfmt_set_attribute() con el atributo `NumberFormatter::ROUNDING_MODE`.

`NumberFormatter::ROUND_CEILING` (integer)
  Modo de redondeo para redondear hacia el infinito positivo.
`NumberFormatter::ROUND_DOWN` (integer)
  Modo de redondeo para redondear hacia cero.
`NumberFormatter::ROUND_FLOOR` (integer)
  Modo de redondeo para redondear hacia el infinito negativo.
`NumberFormatter::ROUND_HALFDOWN` (integer)
  Modo de redondeo para redondear hacia el "vecino más cercano" a menos que ambos vecinos sean equidistantes, en cuyo caso se redondea hacia abajo.
`NumberFormatter::ROUND_HALFEVEN` (integer)
  Modo de redondeo para redondear hacia el "vecino más cercano" a menos que ambos vecinos sean equidistantes, en cuyo caso se redondea hacia el vecino par.
`NumberFormatter::ROUND_HALFUP` (integer)
  Modo de redondeo para redondear hacia el "vecino más cercano" a menos que ambos vecinos sean equidistantes, en cuyo caso se redondea hacia arriba.
`NumberFormatter::ROUND_UP` (integer)
  Modo de redondeo para redondear lejos del cero.

Valores de posición de relleno utilizados por numfmt_get_attribute() y numfmt_set_attribute() con el atributo `NumberFormatter::PADDING_POSITION`.

`NumberFormatter::PAD_AFTER_PREFIX` (integer)
  Los caracteres de relleno se insertan después del prefijo.
`NumberFormatter::PAD_AFTER_SUFFIX` (integer)
  Los caracteres de relleno se insertan después del sufijo.
`NumberFormatter::PAD_BEFORE_PREFIX` (integer)
  Los caracteres de relleno se insertan antes del prefijo.
`NumberFormatter::PAD_BEFORE_SUFFIX` (integer)
  Los caracteres de relleno se insertan antes del sufijo.

## Ver también

- » Documentación de formateo de ICU
- » Formateadores de números de ICU
- » Formateadores decimales de ICU
- » Formateadores de números basados en reglas de ICU

## Tabla de contenidos

- NumberFormatter::create — Crear un formateador de números
- NumberFormatter::formatCurrency — Dar formato a un valor monetario
- NumberFormatter::format — Dar formato a un número
- NumberFormatter::getAttribute — Obtener un atributo
- NumberFormatter::getErrorCode — Obtener el último código de error del formateador
- NumberFormatter::getErrorMessage — Obtener el último mensaje de error del formateador
- NumberFormatter::getLocale — Obtener la configuración regional de un formateador
- NumberFormatter::getPattern — Obtener el patrón del formateador
- NumberFormatter::getSymbol — Obtener el valor de un símbolo
- NumberFormatter::getTextAttribute — Obtiene un atributo de texto
- NumberFormatter::parseCurrency — Procesa un número monetario
- NumberFormatter::parse — Analiza un número
- NumberFormatter::setAttribute — Establecer un atributo
- NumberFormatter::setPattern — Establecer el patrón de un formateador
- NumberFormatter::setSymbol — Establecer un valor de símbolo
- NumberFormatter::setTextAttribute — Set a text attribute