Formatos compuestos

La función de formato compuesto de .NET Framework toma una lista de objetos y una cadena de formato compuesto como entrada. Una cadena de formato compuesto está formada por texto fijo combinado con marcadores de posición indizados, que reciben el nombre de elementos de formato, y que se corresponden con los objetos de la lista. La operación de formato genera una cadena de resultado compuesta por el texto fijo original combinado con la representación de cadena de los objetos de la lista.

La característica de formato compuesto es compatible con métodos como Format, AppendFormat y algunas sobrecargas de WriteLine y TextWriter.WriteLine. El método String.Format genera una cadena de resultado con formato; el método AppendFormat anexa una cadena de resultado con formato a un objeto StringBuilder; los métodos Console.WriteLine muestran la cadena de resultado con formato en la consola, y el método TextWriter.WriteLine escribe la cadena de resultado con formato en una secuencia o archivo.

Cadena de formato compuesto

Los métodos compatibles con la función de formato compuesto utilizan como argumentos una cadena de formato compuesto y una lista de objetos. Una cadena de formato compuesto consta de cero o más ejecuciones de texto fijo combinadas con uno o varios elementos de formato. El texto fijo es cualquier cadena que elija y cada elemento de formato se corresponde con un objeto o estructura de conversión boxing de la lista. La función de formato compuesto devuelve una nueva cadena de resultado donde cada elemento de formato se reemplaza por la representación de cadena del objeto correspondiente de la lista.

Observe el siguiente fragmento de código Format.

Dim myName As String = "Fred"
String.Format("Name = {0}, hours = {1:hh}", myName, DateTime.Now)

string myName = "Fred";
String.Format("Name = {0}, hours = {1:hh}", myName, DateTime.Now);

El texto fijo es "Name = " y ", hours = ". Los elementos de formato son "{0}", cuyo índice es 0, que se corresponde con el objeto myName, y "{1:hh}", cuyo índice es 1, que se corresponde con el objeto DateTime.Now.

Sintaxis de elemento de formato

Cada elemento de formato presenta la siguiente sintaxis, formada por los siguientes componentes:

{index[,alignment][:formatString]}

Las llaves ("{" y "}") son necesarias.

Index (Componente)

El componente index obligatorio, denominado también especificador de parámetros, es un número que empieza por 0, que identifica un elemento correspondiente de la lista de objetos. O sea, el elemento de formato cuyo especificador de parámetro es 0 da formato al primer objeto de la lista, el elemento de formato cuyo especificador de parámetro es 1 da formato al segundo objeto de la lista, etc.

Los elementos de formato múltiple se pueden referir al mismo elemento de la lista de objetos mediante la especificación del mismo especificador de parámetro. Por ejemplo, se puede dar formato al mismo valor numérico en formato hexadecimal, científico y de número mediante la especificación de una cadena de formato compuesto como ésta: "{0:X} {0:E} {0:N}".

Cada elemento de formato puede hacer referencia a cualquier objeto de la lista. Por ejemplo, si existen tres objetos, se puede dar formato al segundo, primero y tercer objeto mediante la especificación de una cadena de formato compuesto como ésta: "{1} {0} {2}". Un objeto al que no hace referencia ningún elemento de formato se omite. Se produce una excepción en tiempo de ejecución si un especificador de parámetro designa un elemento fuera de los límites de la lista de objetos.

Alignment (Componente)

El componente opcional alignment es un entero con signo que indica el ancho de campo con formato preferido. Si el valor de alignment es menor que la longitud de la cadena con formato, se omite alignment y se utiliza la longitud de la cadena con formato como el ancho de campo. Los datos con formato del campo están alineados a la derecha si alignment es positivo y, a la izquierda, si alignment es negativo. Si hace falta relleno, se utiliza un espacio en blanco. Si se especifica alignment, es necesaria la coma.

Format String (Componente)

El componente formatString opcional es una cadena de formato adecuada para el tipo de objeto al que se da formato. Especifique una cadena de formato numérico estándar o personalizado si el objeto correspondiente es un valor numérico, una cadena de formato de fecha y hora estándar o personalizado si el objeto correspondiente es un objeto DateTime, o una cadena de formato de enumeración si el objeto correspondiente es un valor de enumeración. Si no se especifica formatString, se utiliza el especificador de formato general ("G") para un tipo numérico, de fecha y hora o de enumeración. Si se especifica formatString, es necesario el punto.

Nota
Para obtener una lista de cadenas de formato numérico estándar y personalizado, vea Cadenas con formato numérico estándar y Cadenas con formato numérico personalizado.Para obtener una lista de cadenas de formato de fecha y hora estándar, vea Cadenas con formato de fecha y hora estándar y Cadenas de formato de fecha y hora personalizadas.

Llaves de escape

Las llaves de apertura y de cierre se interpretan como el inicio y el final de un elemento de formato. Por lo tanto, debe utilizar una secuencia de escape para que se muestre una llave de apertura o de cierre literal. Especifique dos llaves de apertura ("{{") en el texto fijo para que se muestre una llave de apertura ("{"), o dos llaves de cierre ("}}") para que se muestre una llave de cierre ("}"). Las llaves de un elemento de formato se interpretan secuencialmente, en el orden en que se encuentran. No se admite la interpretación de llaves anidadas.

El modo de interpretar las llaves de escape puede dar lugar a resultados inesperados. Tomemos como ejemplo el elemento de formato "{{{0:D}}}", cuyo propósito es mostrar una llave de apertura, un valor numérico con formato de número decimal y una llave de cierre; pero que, en la práctica, se interpreta de la siguiente forma:

1. Las dos primeras llaves de apertura ("{{") son llaves de escape y dan lugar a en una llave de apertura.

2. Los tres caracteres siguientes ("{0:") se interpretan como el inicio de un elemento de formato.

3. El siguiente carácter ("D") se interpretaría como el especificador de formato numérico estándar decimal, pero las dos llaves de escape siguientes ("}}") dan lugar a una única llave. Como la cadena resultante ("D}") no es un especificador de formato numérico estándar, se interpreta como una cadena de formato personalizado que significa que debe mostrarse la cadena literal "D}".

4. La última llave ("}") se interpreta como el final del elemento de formato.

5. Como resultado final, se muestra la cadena literal "{D}". No se muestra el valor numérico al que se debía dar formato.

Una forma de escribir código e impedir que las llaves de escape y los elementos de formato se malinterpreten consiste en dar formato a las llaves y elementos de formato por separado. Es decir, en la primera operación de formato mostrar una llave de apertura literal, en la siguiente operación mostrar el resultado del elemento de formato y, por último, en la operación final mostrar una llave de cierre literal. En el ejemplo siguiente se muestra este enfoque.

Dim value As Integer = 6324
Dim output As String = String.Format("{0}{1:D}{2}", _
                                     "{", value, "}")
Console.WriteLine(output)   
' The example displays the following output:
'       {6324}

int value = 6324;
string output = string.Format("{0}{1:D}{2}", 
                             "{", value, "}");
Console.WriteLine(output);
// The example displays the following output:
//       {6324}                            

Orden de procesamiento

Cada valor de la lista de parámetros que corresponde a un elemento de formato se convierte en una cadena siguiendo los pasos que se describen en la siguiente lista. Si se cumple alguna condición de los tres primeros pasos, se devolverá la representación de cadena del valor en ese paso y no se ejecutarán los pasos subsiguientes.

1. Si el valor al que se va a dar formato es null, se devuelve una cadena vacía ("").

2. Si el método de formato compuesto incluye un parámetro de tipo IFormatProvider que también implementa la interfaz ICustomFormatter, se pasa el valor al método ICustomFormatter.Format.

3. Si el valor implementa la interfaz IFormattable, se llama a su método IFormattable.ToString.

4. Se llama al método ToString del tipo, el cual se reemplaza o se hereda de la clase Object.

La alineación se aplica después de que se hayan realizado los pasos anteriores.

Ejemplos de código

En el ejemplo siguiente se muestra una cadena creada mediante formato compuesto y otra creada mediante el método ToString de un objeto. Los dos tipos de formato producen resultados equivalentes.

Dim FormatString1 As String = String.Format("{0:dddd MMMM}", DateTime.Now)
Dim FormatString2 As String = DateTime.Now.ToString("dddd MMMM") 

string FormatString1 = String.Format("{0:dddd MMMM}", DateTime.Now);
string FormatString2 = DateTime.Now.ToString("dddd MMMM");

Si tomamos como día actual un jueves del mes de mayo, el valor de ambas cadenas del ejemplo anterior será Thursday May para la referencia cultural de Estados Unidos. Referencia cultural para inglés.

Console.WriteLine expone la misma funcionalidad que String.Format. La única diferencia que existe entre estos dos métodos es que String.Format devuelve el resultado como una cadena, mientras que Console.WriteLine escribe el resultado en el flujo de salida asociado al objeto Console. En el ejemplo siguiente se usa el método Console.WriteLine para dar formato al valor de MyInt como un valor de divisa.

Dim MyInt As Integer = 100
Console.WriteLine("{0:C}", MyInt)
' The example displays the following output
' if en-US is the current culture:
'        $100.00

int MyInt = 100;
Console.WriteLine("{0:C}", MyInt);
// The example displays the following output 
// if en-US is the current culture:
//        $100.00

En el siguiente ejemplo se muestra la aplicación de formato a objetos múltiples, incluida la aplicación de formato a un objeto de dos formas diferentes.

Dim myName As String = "Fred"
Console.WriteLine(String.Format("Name = {0}, hours = {1:hh}, minutes = {1:mm}", _
                  myName, DateTime.Now))
' Depending on the current time, the example displays output like the following:
'    Name = Fred, hours = 11, minutes = 30                 

string myName = "Fred";
Console.WriteLine(String.Format("Name = {0}, hours = {1:hh}, minutes = {1:mm}",
      myName, DateTime.Now));
// Depending on the current time, the example displays output like the following:
//    Name = Fred, hours = 11, minutes = 30                 

En el ejemplo siguiente se muestra el uso de la alineación en la aplicación de formato. Los argumentos a los que se da formato se colocan entre caracteres verticales (|) para resaltar la alineación resultante.

Dim myFName As String = "Fred"
Dim myLName As String = "Opals"

Dim myInt As Integer = 100
Dim FormatFName As String = String.Format("First Name = |{0,10}|", myFName)
Dim FormatLName As String = String.Format("Last Name = |{0,10}|", myLName)
Dim FormatPrice As String = String.Format("Price = |{0,10:C}|", myInt)
Console.WriteLine(FormatFName)
Console.WriteLine(FormatLName)
Console.WriteLine(FormatPrice)
Console.WriteLine()

FormatFName = String.Format("First Name = |{0,-10}|", myFName)
FormatLName = String.Format("Last Name = |{0,-10}|", myLName)
FormatPrice = String.Format("Price = |{0,-10:C}|", myInt)
Console.WriteLine(FormatFName)
Console.WriteLine(FormatLName)
Console.WriteLine(FormatPrice)
' The example displays the following output on a system whose current
' culture is en-US:
'          First Name = |      Fred|
'          Last Name = |     Opals|
'          Price = |   $100.00|
'
'          First Name = |Fred      |
'          Last Name = |Opals     |
'          Price = |$100.00   |

string myFName = "Fred";
string myLName = "Opals";
int myInt = 100;
string FormatFName = String.Format("First Name = |{0,10}|", myFName);
string FormatLName = String.Format("Last Name = |{0,10}|", myLName);
string FormatPrice = String.Format("Price = |{0,10:C}|", myInt); 
Console.WriteLine(FormatFName);
Console.WriteLine(FormatLName);
Console.WriteLine(FormatPrice);
Console.WriteLine();

FormatFName = String.Format("First Name = |{0,-10}|", myFName);
FormatLName = String.Format("Last Name = |{0,-10}|", myLName);
FormatPrice = String.Format("Price = |{0,-10:C}|", myInt);
Console.WriteLine(FormatFName);
Console.WriteLine(FormatLName);
Console.WriteLine(FormatPrice);
// The example displays the following output on a system whose current
// culture is en-US:
//          First Name = |      Fred|
//          Last Name = |     Opals|
//          Price = |   $100.00|
//
//          First Name = |Fred      |
//          Last Name = |Opals     |
//          Price = |$100.00   |

Vea también

Referencia

WriteLine

String.Format

Conceptos

Aplicar formato a tipos

Cadenas con formato numérico estándar

Cadenas con formato numérico personalizado

Cadenas con formato de fecha y hora estándar

Cadenas de formato de fecha y hora personalizadas

Cadenas de formato de enumeración

Otros recursos

Cadenas de formato TimeSpan estándar

Cadenas de formato TimeSpan personalizado