Formatos compuestos

  • Artículo

La característica de formato compuesto de .NET 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. Estos elementos de formato corresponden a 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.

Importante

En lugar de usar cadenas de formato compuesto, puede usar cadenas interpoladas si el idioma y la versión que está usando son compatibles con ellos. Una cadena interpolada contiene expresiones interpoladas. Cada expresión interpolada se resuelve con el valor de la expresión y se incluye en la cadena de resultado cuando se asigna la cadena. Para obtener más información, vea Interpolación de cadenas (Referencia de C#) y Cadenas interpoladas (referencia de Visual Basic).

Los métodos siguientes admiten la característica de formato compuesto:

Cadena de formato compuesto

Los métodos compatibles con la característica 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 representación de cadena de cada objeto reemplaza el elemento de formato correspondiente.

Observe el siguiente fragmento de código Format:

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

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

El texto fijo es Name = y , hours = . Los elementos de formato son {0}, cuyo índice es 0 corresponde al objeto name, y {1:hh}, cuyo índice es 1 corresponde al 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, que también se denomina especificador de parámetros, es un número que empieza por 0 que identifica un elemento correspondiente de la lista de objetos. Es decir, el elemento de formato cuyo especificador de parámetros es 0 da formato al primer objeto de la lista. El elemento de formato cuyo especificador de parámetros es 1 da formato al segundo objeto de la lista, etc. En el ejemplo siguiente se incluyen cuatro especificadores de parámetros, numerados del cero al tres, para representar números primos menores que 10:

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

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

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, si quiere aplicar al mismo valor numérico un formato hexadecimal, científico y numérico, puede especificar una cadena de formato compuesto como "0x{0:X} {0:E} {0:N}", como se muestra en el siguiente ejemplo:

string multiple = string.Format("0x{0:X} {0:E} {0:N}",
                                Int64.MaxValue);
Console.WriteLine(multiple);

// The example displays the following output:
//      0x7FFFFFFFFFFFFFFF 9.223372E+018 9,223,372,036,854,775,807.00

Dim multiple As String = String.Format("0x{0:X} {0:E} {0:N}",
                                       Int64.MaxValue)
Console.WriteLine(multiple)

'The example displays the following output
'     0x7FFFFFFFFFFFFFFF 9.223372E+018 9,223,372,036,854,775,807.00

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 {1} {0} {2}. Un objeto al que no hace referencia ningún elemento de formato se omite. Se produce una excepción de tipo FormatException 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 usa 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.

El siguiente ejemplo define dos matrices, que contiene los nombres de empleados y otra contiene las horas que han trabajado en dos semanas. La cadena de formato compuesto alinea a la izquierda los nombres en un campo de 20 caracteres y alinea a la derecha las horas en un campo de 5 caracteres. La cadena de formato estándar "N1" se usa para dar formato a las horas con un dígito fraccionario.

string[] names = { "Adam", "Bridgette", "Carla", "Daniel",
                   "Ebenezer", "Francine", "George" };
decimal[] hours = { 40, 6.667m, 40.39m, 82,
                    40.333m, 80, 16.75m };

Console.WriteLine("{0,-20} {1,5}\n", "Name", "Hours");

for (int counter = 0; counter < names.Length; counter++)
    Console.WriteLine("{0,-20} {1,5:N1}", names[counter], hours[counter]);

// The example displays the following output:
//      Name                 Hours
//      
//      Adam                  40.0
//      Bridgette              6.7
//      Carla                 40.4
//      Daniel                82.0
//      Ebenezer              40.3
//      Francine              80.0
//      George                16.8

Dim names As String() = {"Adam", "Bridgette", "Carla", "Daniel",
                         "Ebenezer", "Francine", "George"}

Dim hours As Decimal() = {40, 6.667D, 40.39D, 82,
                          40.333D, 80, 16.75D}

Console.WriteLine("{0,-20} {1,5}\n", "Name", "Hours")

For counter = 0 To names.Length - 1
    Console.WriteLine("{0,-20} {1,5:N1}", names(counter), hours(counter))
Next

'The example displays the following output
'     Name                 Hours
'     
'     Adam                  40.0
'     Bridgette              6.7
'     Carla                 40.4
'     Daniel                82.0
'     Ebenezer              40.3
'     Francine              80.0
'     George                16.8

Format String (componente)

El componente formatString opcional es una cadena de formato adecuada para el tipo de objeto al que se da formato. Puede especificar:

  • Cadena de formato numérico estándar o personalizado si el objeto correspondiente es un valor numérico.
  • Cadena de formato de fecha y hora estándar o personalizada si el objeto correspondiente es un objeto DateTime.
  • Cadena de formato de enumeración si el objeto correspondiente es un valor de enumeración.

Si no se especifica formatString, se usa el especificador de formato general ("G") para un tipo numérico, de fecha y hora o de enumeración. Si se especifica formatString, son necesarios los dos puntos.

En la tabla siguiente se enumeran los tipos o las categorías de tipos de la biblioteca de clases de .NET que admiten un conjunto predefinido de cadenas de formato, y se proporcionan vínculos a artículos en los que se muestran las cadenas de formato admitidas. La asignación de formato a cadenas es un mecanismo extensible que permite definir cadenas de formato nuevas para todos los tipos existentes y definir un conjunto de cadenas de formato admitidas por un tipo definido por la aplicación.

Para obtener más información, consulte los artículos de interfaz IFormattable y ICustomFormatter.

Tipo o categoría de tipo Vea
Tipos de fecha y hora (DateTime, DateTimeOffset) Cadenas con formato de fecha y hora estándar

Cadenas con formato de fecha y hora personalizado
Tipos de enumeración (todos los tipos derivados de System.Enum) Cadenas de formato de enumeración
Tipos numéricos (BigInteger, Byte, Decimal, Double, Int16, Int32, Int64, SByte, Single, UInt16, UInt32, UInt64) Cadenas con formato numérico estándar

Cadenas con formato numérico personalizado
Guid Guid.ToString(String)
TimeSpan Cadenas de formato TimeSpan estándar

Cadenas de formato TimeSpan personalizado

Llaves de escape

Las llaves de apertura y de cierre se interpretan como el inicio y el final de un elemento de formato. Para que se muestre una llave de apertura o de cierre literal, debe utilizar una secuencia de escape. 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 escape con un elemento de formato se analizan de forma diferente entre .NET y .NET Framework.

.NET

Las llaves se pueden escapar alrededor de un elemento de formato. 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; El elemento de formato se interpreta de la siguiente manera:

  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 interpreta como especificador de formato numérico estándar decimal.
  4. La última llave (}) se interpreta como el final del elemento de formato.
  5. Las dos llaves de cierre finales se escapan y producen una llave de cierre.
  6. Como resultado final, se muestra la cadena literal {6324}.
int value = 6324;
string output = string.Format("{{{0:D}}}", value);

Console.WriteLine(output);
// The example displays the following output:
//       {6324}

Dim value As Integer = 6324
Dim output As String = String.Format("{{{0:D}}}", value)

Console.WriteLine(output)

'The example displays the following output
'      {6324}

.NET Framework

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.
int value = 6324;
string output = string.Format("{{{0:D}}}",
                              value);
Console.WriteLine(output);

// The example displays the following output:
//       {D}

Dim value As Integer = 6324
Dim output As String = String.Format("{{{0:D}}}",
                                     value)
Console.WriteLine(output)

'The example displays the following output:
'      {D}

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, muestra una llave de apertura literal. En la siguiente operación, muestre el resultado del elemento de formato y, en la operación final, muestre una llave de cierre literal. En el ejemplo siguiente se muestra este enfoque:

int value = 6324;
string output = string.Format("{0}{1:D}{2}",
                             "{", value, "}");
Console.WriteLine(output);

// The example displays the following output:
//       {6324}

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}

Orden de procesamiento

Si la llamada al método de formato compuesto incluye un argumento IFormatProvider cuyo valor no es null, el runtime llama al método IFormatProvider.GetFormat para solicitar una implementación de ICustomFormatter. Si el método puede devolver una implementación de ICustomFormatter, se almacena en caché durante la llamada de método de formato compuesto.

Cada valor de la lista de parámetros que se corresponda con un elemento de formato se convierte en una cadena del siguiente modo:

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

  2. Si hay disponible una implementación de ICustomFormatter, el runtime llama al método Format. El tiempo de ejecución pasa el valor del elemento de formato formatString (o null si no está presente) al método. El tiempo de ejecución también pasa la implementación al método IFormatProvider. Si la llamada al método ICustomFormatter.Format devuelve null, la ejecución avanza al siguiente paso. De lo contrario, se devuelve el resultado de la llamada ICustomFormatter.Format.

  3. Si el valor implementa la interfaz IFormattable, se llama al método ToString(String, IFormatProvider) de esta. Si hubiera uno presente en el elemento de formato, se pasa al método el valor formatString. De lo contrario, null no se pasa. El argumento IFormatProvider se determina de la siguiente forma:

  4. Se llama al método sin parámetros ToString del tipo, que reemplaza a Object.ToString() o hereda el comportamiento de su clase base. En este caso, se omite la cadena de formato especificada por el componente formatString en el elemento de formato, si estuviera presente.

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.

string formatString1 = string.Format("{0:dddd MMMM}", DateTime.Now);
string formatString2 = DateTime.Now.ToString("dddd MMMM");

Dim formatString1 As String = String.Format("{0:dddd MMMM}", DateTime.Now)
Dim formatString2 As String = 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 Inglés (Estados Unidos).

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 myNumber como un valor de divisa:

int myNumber = 100;
Console.WriteLine("{0:C}", myNumber);

// The example displays the following output
// if en-US is the current culture:
//        $100.00

Dim myNumber As Integer = 100
Console.WriteLine("{0:C}", myNumber)

'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:

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

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

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.

string firstName = "Fred";
string lastName = "Opals";
int myNumber = 100;

string formatFirstName = string.Format("First Name = |{0,10}|", firstName);
string formatLastName = string.Format("Last Name =  |{0,10}|", lastName);
string formatPrice = string.Format("Price =      |{0,10:C}|", myNumber);
Console.WriteLine(formatFirstName);
Console.WriteLine(formatLastName);
Console.WriteLine(formatPrice);
Console.WriteLine();

formatFirstName = string.Format("First Name = |{0,-10}|", firstName);
formatLastName = string.Format("Last Name =  |{0,-10}|", lastName);
formatPrice = string.Format("Price =      |{0,-10:C}|", myNumber);
Console.WriteLine(formatFirstName);
Console.WriteLine(formatLastName);
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   |

Dim firstName As String = "Fred"
Dim lastName As String = "Opals"
Dim myNumber As Integer = 100

Dim formatFirstName As String = String.Format("First Name = |{0,10}|", firstName)
Dim formatLastName As String = String.Format("Last Name =  |{0,10}|", lastName)
Dim formatPrice As String = String.Format("Price =      |{0,10:C}|", myNumber)
Console.WriteLine(formatFirstName)
Console.WriteLine(formatLastName)
Console.WriteLine(formatPrice)
Console.WriteLine()

formatFirstName = String.Format("First Name = |{0,-10}|", firstName)
formatLastName = String.Format("Last Name =  |{0,-10}|", lastName)
formatPrice = String.Format("Price =      |{0,-10:C}|", myNumber)
Console.WriteLine(formatFirstName)
Console.WriteLine(formatLastName)
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   |

Consulte también