Cadenas con formato numérico personalizado

  • Artículo

Actualización: Julio de 2008

Una cadena de formato numérico personalizado, creada por el usuario y formada por uno o varios especificadores de formato numérico personalizado, define cómo debe darse formato a los datos numéricos. Una cadena de formato numérico personalizado se define del mismo modo que cualquier cadena que no sea una cadena de formato numérico estándar.

En la siguiente tabla se describen los especificadores de formato numérico personalizado. Para obtener más información, vea las notas a continuación de la tabla.

Especificador de formato

Nombre

Descripción

0

Marcador de posición cero

Si el valor al que se está dando formato tiene un dígito en la posición donde aparece el "0" en la cadena de formato, se copia ese dígito en la cadena de resultado; de lo contrario, aparecerá un "0" en la cadena de resultado. La posición del "0" que aparece más a la izquierda antes del separador decimal y la del "0" que está más a la derecha después del separador decimal determinan el intervalo de dígitos que están siempre presentes en la cadena de resultado.

El especificador "00" hace que el valor se redondee al dígito más próximo que precede al decimal, donde siempre se utiliza el redondeo para evitar el cero. Por ejemplo, al aplicar el formato a 34.5 con "00" el resultado del valor es 35.

En el ejemplo siguiente se muestran varios valores a los que se les ha aplicado cadenas de formato personalizado que incluyen marcadores de posición cero.

Dim value As Double




value = 123


Console.WriteLine(value.ToString("00000"))


' Displays 00123




value = 1.2


Console.Writeline(value.ToString("0.00", CultureInfo.InvariantCulture))


' Displays 1.20


Console.WriteLine(value.ToString("00.00", CultureInfo.InvariantCulture))


' Displays 01.20


Console.WriteLine(value.ToString("00.00", _


                  CultureInfo.CreateSpecificCulture("da-DK")))


' Displays 01,20




value = .56


Console.WriteLine(value.ToString("0.0", CultureInfo.InvariantCulture))


' Displays 0.6




value = 1234567890


Console.WriteLine(value.ToString("#,#", CultureInfo.InvariantCulture))  


' Displays 1,234,567,890      


Console.WriteLine(value.ToString("#,#", _


                  CultureInfo.CreateSpecificCulture("el-GR")))  


' Displays 1.234.567.890      
double value;




value = 123;


Console.WriteLine(value.ToString("00000"));


// Displays 00123




value = 1.2;


Console.WriteLine(value.ToString("0.00", CultureInfo.InvariantCulture));


// Displays 1.20


Console.WriteLine(value.ToString("00.00", CultureInfo.InvariantCulture));


// Displays 01.20


Console.WriteLine(value.ToString("00.00", 


                  CultureInfo.CreateSpecificCulture("da-DK")));


// Displays 01,20




value = .56;


Console.WriteLine(value.ToString("0.0", CultureInfo.InvariantCulture));


// Displays 0.6




value = 1234567890;


Console.WriteLine(value.ToString("#,#", CultureInfo.InvariantCulture)); 


// Displays 1,234,567,890      


Console.WriteLine(value.ToString("#,#", 


                  CultureInfo.CreateSpecificCulture("el-GR"))); 


// Displays 1.234.567.890

#

Marcador de posición de dígito.

Si el valor al que se está dando formato tiene un dígito en la posición donde aparece '#' en la cadena de formato, ese dígito se copia en la cadena de resultado. En caso contrario, no se almacena nada en esa posición de la cadena de resultado.

Hay que advertir que este especificador nunca muestra el carácter '0' si éste no es un dígito significativo, incluso si '0' es el único dígito de la cadena. Sólo mostrará el carácter '0' si es un dígito significativo del número que se muestra.

La cadena de formato "##" hace que el valor se redondee al dígito más próximo que precede al decimal, donde siempre se utiliza el redondeo para evitar el cero. Por ejemplo, al aplicar el formato a 34.5 con "##" el resultado del valor es 35.

En el ejemplo siguiente se muestran varios valores a los que se les ha aplicado cadenas de formato personalizado que incluyen marcadores de posición de dígitos.

      Dim value As Double




      value = 1.2


      Console.WriteLine(value.ToString("#.##", CultureInfo.InvariantCulture))


      ' Displays 1.2




      value = 123


      Console.WriteLine(value.ToString("#####"))


      ' Displays 123




      value = 123456


      Console.WriteLine(value.ToString("[##-##-##]"))      


       ' Displays [12-34-56]




      value = 1234567890


      Console.WriteLine(value.ToString("#"))


      ' Displays 1234567890


      Console.WriteLine(value.ToString("(###) ###-####"))


      ' Displays (123) 456-7890
      double value;




      value = 1.2;


      Console.WriteLine(value.ToString("#.##", CultureInfo.InvariantCulture));


      // Displays 1.2




      value = 123;


      Console.WriteLine(value.ToString("#####"));


      // Displays 123




      value = 123456;


      Console.WriteLine(value.ToString("[##-##-##]"));      


       // Displays [12-34-56]




      value = 1234567890;


      Console.WriteLine(value.ToString("#"));


      // Displays 1234567890


      Console.WriteLine(value.ToString("(###) ###-####"));


      // Displays (123) 456-7890

.

Separador decimal

El primer carácter '.' de la cadena de formato determina la ubicación del separador decimal en el valor con formato y se omite cualquier carácter '.' adicional.

El carácter real que se utiliza como separador decimal en la cadena de resultado viene determinado por la propiedad NumberDecimalSeparator del objeto NumberFormatInfo que controla la aplicación de formato.

En el ejemplo siguiente se utiliza el especificador de formato del separador decimal para definir la ubicación del separador decimal en varias cadenas de resultado.

      Dim value As Double




      value = 1.2


      Console.Writeline(value.ToString("0.00", CultureInfo.InvariantCulture))


      ' Displays 1.20


      Console.WriteLine(value.ToString("00.00", CultureInfo.InvariantCulture))


      ' Displays 01.20


      Console.WriteLine(value.ToString("00.00", _


                        CultureInfo.CreateSpecificCulture("da-DK")))


      ' Displays 01,20




      value = .086


      Console.WriteLine(value.ToString("#0.##%", CultureInfo.InvariantCulture)) 


      ' Displays 8.6%




      value = 86000


      Console.WriteLine(value.ToString("0.###E+0", CultureInfo.InvariantCulture))


       ' Displays 8.6E+4
      double value;




      value = 1.2;


      Console.WriteLine(value.ToString("0.00", CultureInfo.InvariantCulture));


      // Displays 1.20


      Console.WriteLine(value.ToString("00.00", CultureInfo.InvariantCulture));


      // Displays 01.20


      Console.WriteLine(value.ToString("00.00", 


                        CultureInfo.CreateSpecificCulture("da-DK")));


      // Displays 01,20




      value = .086;


      Console.WriteLine(value.ToString("#0.##%", CultureInfo.InvariantCulture)); 


      // Displays 8.6%




      value = 86000;


      Console.WriteLine(value.ToString("0.###E+0", CultureInfo.InvariantCulture));


       // Displays 8.6E+4

,

Separador de miles y escala numérica

El carácter ',' actúa como especificador de separador de miles y como especificador de escala numérica.

Especificador de separador de miles: si se especifican uno o varios caracteres ',' entre dos marcadores de posición de dígitos (0 ó #) que dan formato a los dígitos enteros de un número, se insertará un carácter separador de grupo entre cada grupo de números en la parte entera del resultado.

Las propiedades NumberGroupSeparator y NumberGroupSizes del objeto NumberFormatInfo actual determinan el carácter utilizado como separador de grupos de números y el tamaño de cada grupo de números. Por ejemplo, si se utiliza la cadena "#,#" y la referencia cultural de todos los idiomas para dar formato al número 1000, el resultado será "1,000".

Especificador de escala numérica: si se especifican uno o varios caracteres ',' inmediatamente a la izquierda del punto decimal explícito o implícito, el número al que hay que dar formato se divide entre 1000 cada vez que se aplica un especificador de escala numérica. Por ejemplo, si se utiliza la cadena "0,," para dar formato al número 100 millones, el resultado será "100".

Puede utilizar especificadores de separador de miles y escala numérica en la misma cadena de formato. Por ejemplo, si se utiliza la cadena "#,0,," y la referencia cultural de todos los idiomas para dar formato al número mil millones, el resultado será "1,000".

En el ejemplo siguiente se muestra el uso de la coma como separador de miles.

Dim value As Double = 1234567890


Console.WriteLine(value.ToString("#,#", CultureInfo.InvariantCulture))


' Displays 1,234,567,890      


Console.WriteLine(value.ToString("#,##0,,", CultureInfo.InvariantCulture))


' Displays 1,235        
double value = 1234567890;


Console.WriteLine(value.ToString("#,#", CultureInfo.InvariantCulture));


// Displays 1,234,567,890      


Console.WriteLine(value.ToString("#,##0,,", CultureInfo.InvariantCulture));


// Displays 1,235

En el ejemplo siguiente se muestra el uso de la coma como especificador de escala numérica.

      Dim value As Double = 1234567890


      Console.WriteLine(value.ToString("#,,", CultureInfo.InvariantCulture))    


      ' Displays 1235   


      Console.WriteLine(value.ToString("#,,,", CultureInfo.InvariantCulture))


       ' Displays 1  


      Console.WriteLine(value.ToString("#,##0,,", CultureInfo.InvariantCulture))       


       ' Displays 1,235
      double value = 1234567890;


      Console.WriteLine(value.ToString("#,,", CultureInfo.InvariantCulture));   


      // Displays 1235   


      Console.WriteLine(value.ToString("#,,,", CultureInfo.InvariantCulture));


       // Displays 1  


      Console.WriteLine(value.ToString("#,##0,,", CultureInfo.InvariantCulture));       


       // Displays 1,235

%

Marcador de posición de porcentaje.

La presencia de un carácter '%' en una cadena de formato hace que se multiplique un número por 100 antes de que se le dé formato. El símbolo adecuado se inserta en el número en la posición en que aparece '%' en la cadena de formato. El carácter de porcentaje que se utiliza depende de la clase NumberFormatInfo actual.

En el ejemplo siguiente se definen varias cadenas de formato personalizado que incluyen el marcador de posición de porcentaje.

Dim value As Double = .086


Console.WriteLine(value.ToString("#0.##%", CultureInfo.InvariantCulture))


' Displays 8.6%      
double value = .086;


Console.WriteLine(value.ToString("#0.##%", CultureInfo.InvariantCulture));


// Displays 8.6%

‰

Marcador de posición de "por mil"

La presencia de un carácter '%' (\u2030) en una cadena de formato hace que un número se multiplique por 1000 antes de que se le dé formato. El símbolo de "por mil" adecuado se inserta en la cadena devuelta, en la ubicación de la cadena de formato en la que aparece el símbolo '‰'. La propiedad NumberFormatInfo.PerMilleSymbol del objeto que proporciona la información de formato específica de la referencia cultural es la que determina el carácter de "por mil" que se utiliza.

En el ejemplo siguiente se define una cadena de formato personalizado que incluye el marcador de posición de "por mil".

Dim value As Double = .00354


Dim perMilleFmt As String = "#0.## " & ChrW(&h2030)


Console.WriteLine(value.ToString(perMilleFmt, CultureInfo.InvariantCulture))


' Displays 3.54 ‰      
double value = .00354;


string perMilleFmt = "#0.## " + '\u2030';


Console.WriteLine(value.ToString(perMilleFmt, CultureInfo.InvariantCulture));


// Displays 3.54‰

E0

E+0

E-0

e0

e+0

e-0

Notación científica

Si alguna de las cadenas "E", "E+", "E-", "e", "e+", o "e-" aparece en la cadena de formato y lleva a continuación por lo menos un carácter '0', entonces se le da formato al número mediante notación científica con una 'E' o una 'e' insertadas entre el número y el exponente. El número de caracteres '0' que sigue al indicador de notación científica determina el número mínimo de dígitos para el exponente. Los formatos 'E+' y 'e+' indican que un carácter de signo (más o menos) debe preceder siempre al exponente. Los formatos 'E', 'E-', 'e' o 'e-' indican que un carácter de signo sólo debe preceder a exponentes negativos.

En el ejemplo siguiente se da formato a varios valores numéricos utilizando los especificadores de notación científica.

Dim value As Double = 86000


Console.WriteLine(value.ToString("0.###E+0", CultureInfo.InvariantCulture))


' Displays 8.6E+4


Console.WriteLine(value.ToString("0.###E+000", CultureInfo.InvariantCulture))


' Displays 8.6E+004


Console.WriteLine(value.ToString("0.###E-000", CultureInfo.InvariantCulture))


' Displays 8.6E004
double value = 86000;


Console.WriteLine(value.ToString("0.###E+0", CultureInfo.InvariantCulture));


// Displays 8.6E+4


Console.WriteLine(value.ToString("0.###E+000", CultureInfo.InvariantCulture));


// Displays 8.6E+004


Console.WriteLine(value.ToString("0.###E-000", CultureInfo.InvariantCulture));


// Displays 8.6E004

\

Carácter de escape

En C# y C++, el carácter de barra invertida hace que el siguiente carácter de la cadena de formato se interprete como una secuencia de escape. Se utiliza con las secuencias tradicionales para la aplicación de formato, como "\n" (nueva línea).

En algunos lenguajes, el carácter de escape debe ir precedido por otro carácter de escape cuando se utiliza como un literal. En caso contrario, el compilador interpreta el carácter como una secuencia de escape. Hay que emplear la cadena "\\" para mostrar '\'.

Hay que tener en cuenta que Visual Basic no admite el carácter de escape; sin embargo ControlChars proporciona la misma funcionalidad.

'ABC'

"ABC"

Cadena literal

Los caracteres situados entre comillas simples o dobles se copian en la cadena de resultado y no afectan al formato.

;

Separador de secciones

El carácter ';' se utiliza para separar secciones para los números positivos, negativos y cero de la cadena de formato. Si hay dos secciones en la cadena de formato personalizado, la sección situada más a la izquierda define el formato los números positivos y cero, mientras que la sección situada más a la derecha define el formato de los números negativos. Si hay tres secciones, la sección situada más a la izquierda define el formato de los números positivos, la sección central define el formato de los números negativos y la sección situada más a la derecha define el formato del número cero.

En el ejemplo siguiente se utiliza el especificador de formato para que el separador de secciones aplique un formato distinto de los números positivos, negativos y cero.

Dim posValue As Double = 1234


Dim negValue As Double = -1234


Dim fmt As String = "##;(##)"


Console.WriteLine(posValue.ToString(fmt))    ' Displays 1234


Console.WriteLine(negValue.ToString(fmt))    ' Displays (1234)
double posValue = 1234;


double negValue = -1234;


string fmt = "##;(##)";


Console.WriteLine(posValue.ToString(fmt));    // Displays 1234


Console.WriteLine(negValue.ToString(fmt));    // Displays (1234)

Otros

Todos los demás caracteres

Cualquier otro carácter se copia en la cadena del resultado y no afecta al formato.

Notas

Infinitos de punto flotante y NaN

Tenga en cuenta que, independientemente de la cadena de formato, si el valor de un tipo de punto flotante Single o Double es infinito positivo, infinito negativo o NaN (Not a Number, no es un número), la cadena con formato será el valor de la propiedad PositiveInfinitySymbol, NegativeInfinitySymbol o NaNSymbol respectiva especificada por el objeto NumberFormatInfo actualmente aplicable.

Configuración del Panel de control

Los valores de configuración del elemento Configuración regional y de idioma del Panel de control influyen en la cadena de resultado generada por una operación de formato. Estos valores de configuración se utilizan para inicializar el objeto NumberFormatInfo asociado a la referencia cultural del subproceso actual, y la referencia cultural del subproceso actual proporciona valores que se utilizan para controlar el formato. Los equipos que utilicen una configuración diferente generarán cadenas de resultado diferentes.

Cadenas de formato de punto fijo y redondeo

Hay que tener en cuenta que, para las cadenas de formato de punto fijo (es decir, las cadenas de formato que no contienen caracteres de formato de notación científica), los números se redondean en tantas cifras decimales como marcadores de posición de dígitos haya a la derecha del separador decimal. Si la cadena de formato no contiene ningún separador decimal, el número se redondea al entero más próximo. Si el número tiene más dígitos que marcadores de posición de dígitos a la izquierda del separador decimal, los dígitos adicionales se copian en la cadena de resultado justo antes del primer marcador de posición de dígitos.

Separadores de sección y formato condicional

Se pueden aplicar diferentes formatos a una cadena basada en que el valor sea positivo, negativo o cero. Para generar este comportamiento, una cadena de formato personalizado puede contener hasta tres secciones separadas por signos de punto y coma. Estas secciones se describen en la siguiente tabla.

Número de secciones

Descripción

Una sección

La cadena de formato se aplica a todos los valores.

Dos secciones

La primera sección se aplica a valores positivos y ceros, y la segunda, sólo a valores negativos.

Si el número al que se va a dar formato es negativo, pero se convierte en cero después de redondear según el formato de la segunda sección, entonces al cero resultante se le da formato según la primera sección.

Tres secciones.

La primera sección se aplica a valores positivos y ceros, la segunda, sólo a valores negativos, y la tercera, a ceros.

La segunda sección se puede dejar vacía (no dejando nada entre los signos de punto y coma) y, en ese caso, la primera sección se aplica a los valores distintos de cero.

Si el número al que se va a dar formato es distinto de cero, pero se convierte en cero después de redondearlo según el formato de la primera o la segunda sección, entonces al cero resultante se le da formato según la tercera sección.

Los separadores de sección omiten cualquier formato preexistente asociado a un número al dar formato al valor final. Por ejemplo, los valores negativos se muestran siempre con signo menos cuando se utilizan separadores de sección. Si se desea que el valor con formato final tenga un signo menos, debe incluir explícitamente el signo menos como parte del especificador de formato personalizado.

En los siguientes fragmentos de código se muestra el uso de los separadores de sección para generar cadenas con formato.

Dim MyPos As Double = 19.95
Dim MyNeg As Double = -19.95
Dim MyZero As Double = 0

' In the U.S. English culture, MyString has the value: $19.95.
Dim MyString As String = MyPos.ToString("$#,##0.00;($#,##0.00);Zero")

' In the U.S. English culture, MyString has the value: ($19.95).
' The minus sign is omitted by default.
MyString = MyNeg.ToString("$#,##0.00;($#,##0.00);Zero")

' In the U.S. English culture, MyString has the value: Zero.
MyString = MyZero.ToString("$#,##0.00;($#,##0.00);Zero")

double MyPos = 19.95, MyNeg = -19.95, MyZero = 0.0;

// In the U.S. English culture, MyString has the value: $19.95.
string MyString = MyPos.ToString("$#,##0.00;($#,##0.00);Zero");

// In the U.S. English culture, MyString has the value: ($19.95).
// The minus sign is omitted by default.
MyString = MyNeg.ToString("$#,##0.00;($#,##0.00);Zero");

// In the U.S. English culture, MyString has the value: Zero.
MyString = MyZero.ToString("$#,##0.00;($#,##0.00);Zero");

Dos ejemplos de formato personalizado

En los siguientes fragmentos de código se muestra el formato numérico personalizado. En ambos casos, el marcador de posición de dígitos (#) de la cadena de formato personalizado muestra los datos numéricos, y el resto de los caracteres se copian en el resultado.

Dim myDouble As Double = 1234567890
Dim myString As String = myDouble.ToString( "(###) ### - ####" )
' The value of myString is "(123) 456 – 7890".

Dim MyInt As Integer = 42
MyString = MyInt.ToString( "My Number = #" )
' In the U.S. English culture, MyString has the value: 
' "My Number = 42".

Double myDouble = 1234567890;
String myString = myDouble.ToString( "(###) ### - ####" );
// The value of myString is "(123) 456 – 7890".

int  MyInt = 42;
MyString = MyInt.ToString( "My Number = #" );
// In the U.S. English culture, MyString has the value: 
// "My Number = 42".

Vea también

Conceptos

Cadenas de formato numérico

Cadenas con formato numérico estándar

Referencia

NumberFormatInfo

Otros recursos

Aplicar formato a tipos

Historial de cambios

Fecha

Historial

Motivo

Julio de 2008

Se agregó el marcador de posición de "por mil".

Corrección de errores de contenido.