Compartir vía


Strings.Format(Object, String) Método

Definición

Devuelve una cadena con formato según las instrucciones contenidas en un formato String expresión.

public static string Format (object? Expression, string? Style = "");
public static string Format (object Expression, string Style = "");
static member Format : obj * string -> string
Public Function Format (Expression As Object, Optional Style As String = "") As String

Parámetros

Expression
Object

Obligatorio. Cualquier expresión válida.

Style
String

Opcional. Un formato válido con nombre o definido por el usuario String expresión.

Devoluciones

Cadena con formato según las instrucciones contenidas en un formato String expresión.

Ejemplos

En este ejemplo se muestran varios usos de la función Format para dar formato a los valores mediante formatos String y formatos definidos por el usuario. Para el separador de fecha (/), separador de hora (:) y los indicadores AM/PM (t y tt), la salida con formato real mostrada por el sistema depende de la configuración regional que usa el código. Cuando se muestran las horas y fechas en el entorno de desarrollo, se usan el formato de hora breve y el formato de fecha corta de la configuración regional del código.

Nota

Para las configuraciones regionales que usan un reloj de 24 horas, los indicadores am/PM (t y tt) no muestran nada.

Dim testDateTime As Date = #1/27/2001 5:04:23 PM#
Dim testStr As String
' Returns current system time in the system-defined long time format.
testStr = Format(Now(), "Long Time")
' Returns current system date in the system-defined long date format.
testStr = Format(Now(), "Long Date")
' Also returns current system date in the system-defined long date 
' format, using the single letter code for the format.
testStr = Format(Now(), "D")

' Returns the value of testDateTime in user-defined date/time formats.
' Returns "5:4:23".
testStr = Format(testDateTime, "h:m:s")
' Returns "05:04:23 PM".
testStr = Format(testDateTime, "hh:mm:ss tt")
' Returns "Saturday, Jan 27 2001".
testStr = Format(testDateTime, "dddd, MMM d yyyy")
' Returns "17:04:23".
testStr = Format(testDateTime, "HH:mm:ss")
' Returns "23".
testStr = Format(23)

' User-defined numeric formats.
' Returns "5,459.40".
testStr = Format(5459.4, "##,##0.00")
' Returns "334.90".
testStr = Format(334.9, "###0.00")
' Returns "500.00%".
testStr = Format(5, "0.00%")

Comentarios

El método String.Format también proporciona una funcionalidad similar.

Si va a dar formato a una cadena numérica no localizada, debe usar un formato numérico definido por el usuario para asegurarse de que obtiene el aspecto que desea.

Si intenta dar formato a un número sin especificar Style, la función Format proporciona funcionalidad similar a la función Str, aunque es consciente internacionalmente. Sin embargo, los números positivos con formato de cadenas que usan la función Format no incluyen un espacio inicial reservado para el signo del valor; los convertidos mediante la función Str conservan el espacio inicial.

Diferentes formatos para valores numéricos diferentes

Una expresión de formato definida por el usuario para números puede tener de una a tres secciones separadas por punto y coma. Si el argumento Style de la función Format contiene uno de los formatos numéricos predefinidos, solo se permite una sección.

Si usa Este es el resultado
Solo una sección La expresión de formato se aplica a todos los valores.
Dos secciones La primera sección se aplica a valores positivos y ceros; el segundo se aplica a valores negativos.
Tres secciones La primera sección se aplica a los valores positivos, el segundo se aplica a valores negativos y el tercero se aplica a ceros.

El ejemplo siguiente tiene dos secciones: la primera define el formato de valores positivos y ceros; la segunda sección define el formato de los valores negativos. Dado que el argumento Style de la función Format toma una cadena, se incluye entre comillas.

Dim style1 As String = "$#,##0;($#,##0)"

Si incluye punto y coma sin nada entre ellos, la sección que falta se imprime con el formato del valor positivo. Por ejemplo, el siguiente formato muestra valores positivos y negativos con el formato en la primera sección y muestra Zero si el valor es cero.

Dim style2 As String = "$#,##0;;\Z\e\r\o"

Formatos numéricos predefinidos

En la tabla siguiente se identifican los nombres de formato numérico predefinidos. Estos se pueden usar por nombre como argumento Style para la función Format:

Nombre de formato Descripción
General Number, Go g Muestra el número sin separador de miles.

Por ejemplo, Format(&H3FA, "g") devuelve 1018.
Currency, Co c Muestra el número con separador de miles, si procede; muestra dos dígitos a la derecha del separador decimal. La salida se basa en la configuración regional del sistema.

Por ejemplo, Format(1234567, "c") devuelve $1,234,567.00.
Fixed, Fo f Muestra al menos un dígito a la izquierda y dos dígitos a la derecha del separador decimal.

Por ejemplo, Format(1234567, "f") devuelve 1234567.00.
Standard, No n Muestra el número con separador de miles, al menos un dígito a la izquierda y dos dígitos a la derecha del separador decimal.

Por ejemplo, Format(1234567, "n") devuelve 1,234,567.00.
Percent Muestra el número multiplicado por 100 con un signo de porcentaje (%) anexado inmediatamente a la derecha; siempre muestra dos dígitos a la derecha del separador decimal.

Por ejemplo, Format(0.4744, "Percent") devuelve 47.44%.
P, o p Muestra el número con separador de milésimas multiplicado por 100 con un signo de porcentaje (%) anexado a la derecha y separados por un solo espacio; siempre muestra dos dígitos a la derecha del separador decimal.

Por ejemplo, Format(0.80345, "p") devuelve 80.35 %.
Scientific Usa notación científica estándar, proporcionando dos dígitos significativos.

Por ejemplo, Format(1234567, "Scientific") devuelve 1.23E+06.
E, o e Usa notación científica estándar, proporcionando seis dígitos significativos.

Por ejemplo, Format(1234567, "e") devuelve 1.234567e+006.
D, o d Muestra el número como una cadena que contiene el valor del número en formato Decimal (base 10). Esta opción se admite solo para tipos enteros (Byte, Short, Integer, Long).

Por ejemplo, Format(&H7F, "d") devuelve 127.
X, o x Muestra el número como una cadena que contiene el valor del número en formato Hexadecimal (base 16). Esta opción se admite solo para tipos enteros (Byte, Short, Integer, Long).

Por ejemplo, Format(127, "x") devuelve 7f.
Yes/No Muestra No si el número es 0; de lo contrario, muestra Yes.

Por ejemplo, Format(0, "Yes/No") devuelve No.
True/False Muestra False si el número es 0; de lo contrario, muestra True.

Por ejemplo, Format(1, "True/False") devuelve True.
On/Off Muestra Off si el número es 0; de lo contrario, muestra On.

Por ejemplo, Format(1, "On/Off") devuelve On.

Notas del desarrollador de dispositivos inteligentes

No se admiten los formatos Yes/No, True/Falsey On/Off.

formatos numéricos de User-Defined

En la tabla siguiente se identifican los caracteres que puede usar para crear formatos de números definidos por el usuario. Se pueden usar para compilar el argumento Style para la función Format:

Carácter Descripción
Ninguno Muestra el número sin formato.
(0) Marcador de posición de dígitos. Muestra un dígito o un cero. Si la expresión tiene un dígito en la posición donde aparece el cero en la cadena de formato, mostrarlo; de lo contrario, muestra un cero en esa posición.

Si el número tiene menos dígitos que ceros (en cualquiera de los lados del decimal) en la expresión de formato, muestra ceros iniciales o finales. Si el número tiene más dígitos a la derecha del separador decimal que ceros a la derecha del separador decimal en la expresión de formato, redondea el número a tantas posiciones decimales como hay ceros. Si el número tiene más dígitos a la izquierda del separador decimal que ceros a la izquierda del separador decimal en la expresión de formato, muestra los dígitos adicionales sin modificaciones.
(#) Marcador de posición de dígitos. Muestra un dígito o nada. Si la expresión tiene un dígito en la posición donde aparece el carácter # en la cadena de formato, lo muestra; de lo contrario, no muestra nada en esa posición.

Este símbolo funciona como el marcador de posición de 0 dígitos, excepto que los ceros iniciales y finales no se muestran si el número tiene menos dígitos que # caracteres en cualquiera de los lados del separador decimal en la expresión de formato.
(.) Marcador de posición decimal. El marcador de posición decimal determina cuántos dígitos se muestran a la izquierda y a la derecha del separador decimal. Si la expresión de formato contiene solo # caracteres a la izquierda de este símbolo; los números menores que 1 comienzan con un separador decimal. Para mostrar un cero inicial mostrado con números fraccionarios, use cero como marcador de posición de primer dígito a la izquierda del separador decimal. En algunas configuraciones regionales, se usa una coma como separador decimal. El carácter real usado como marcador de posición decimal en la salida con formato depende del formato de número reconocido por el sistema. Por lo tanto, debe usar el punto como marcador de posición decimal en los formatos, incluso si está en una configuración regional que usa una coma como marcador de posición decimal. La cadena con formato aparecerá en el formato correcto para la configuración regional.
(%) Marcador de posición de porcentaje. Multiplica la expresión por 100. El carácter de porcentaje (%) se inserta en la posición donde aparece en la cadena de formato.
(,) Separador de miles. El separador de miles separa miles de cientos dentro de un número que tiene cuatro o más lugares a la izquierda del separador decimal. Se especifica el uso estándar del separador de miles si el formato contiene un separador de miles rodeado de marcadores de posición de dígitos (0 o #).

Un separador de miles inmediatamente a la izquierda del separador decimal (si se especifica o no un decimal) o como carácter más a la derecha de la cadena significa "escalar el número dividiéndolo en 1000, redondeando según sea necesario". Los números menores que 1000 pero mayores o iguales a 500 se muestran como 1, y los números menores que 500 se muestran como 0. Dos separadores de miles adyacentes en esta posición escalan por un factor de 1 millón y un factor adicional de 1000 para cada separador adicional.

Varios separadores en cualquier posición que no sea inmediatamente a la izquierda del separador decimal o la posición situada más a la derecha de la cadena se tratan simplemente como especificar el uso de un separador de miles. En algunas configuraciones regionales, se usa un punto como separador de miles. El carácter real que se usa como separador de miles en la salida con formato depende del formato de número reconocido por el sistema. Por lo tanto, debe usar la coma como separador de miles en los formatos aunque esté en una configuración regional que use un punto como separador de miles. La cadena con formato aparecerá en el formato correcto para la configuración regional.

Por ejemplo, considere las tres cadenas de formato siguientes:

- "#,0.", que usa el separador de miles para dar formato al número 100 millones como la cadena "100 000 000".
- "#0,.", que usa el escalado por un factor de mil para dar formato al número 100 millones como la cadena "100000".
- "#,0,.", que usa el separador de miles y escalado en mil para dar formato al número 100 millones como la cadena "100 000".
(:) Separador de tiempo. En algunas configuraciones regionales, se pueden usar otros caracteres para representar el separador de tiempo. El separador de tiempo separa horas, minutos y segundos cuando se da formato a los valores de hora. El carácter real que se usa como separador de hora en la salida con formato viene determinado por la configuración del sistema.
(/) Separador de fecha. En algunas configuraciones regionales, se pueden usar otros caracteres para representar el separador de fecha. El separador de fecha separa el día, el mes y el año en que se da formato a los valores de fecha. El carácter real que se usa como separador de fecha en la salida con formato viene determinado por la configuración del sistema.
(E-``E+``e-``e+) Formato científico. Si la expresión de formato contiene al menos un marcador de posición de dígitos (0 o #) a la izquierda de E-, E+, e-o e+, el número se muestra en formato científico y E o e se inserta entre el número y su exponente. El número de marcadores de posición de dígitos a la izquierda determina el número de dígitos del exponente. Use E- o e- para colocar un signo menos junto a exponentes negativos. Use E+ o e+ para colocar un signo menos junto a exponentes negativos y un signo más junto a exponentes positivos. También debe incluir marcadores de posición de dígitos a la derecha de este símbolo para obtener el formato correcto.
- + $ ( ) Caracteres literales. Estos caracteres se muestran exactamente como se escriben en la cadena de formato. Para mostrar un carácter distinto de uno de los enumerados, precedítelo con una barra diagonal inversa (\) o encierre entre comillas dobles (" ").
(\) Muestra el siguiente carácter en la cadena de formato. Para mostrar un carácter que tiene un significado especial como carácter literal, precedítelo con una barra diagonal inversa (\). No se muestra la barra diagonal inversa. El uso de una barra diagonal inversa es el mismo que incluir el siguiente carácter entre comillas dobles. Para mostrar una barra diagonal inversa, use dos barras diagonales inversas (\\).

Algunos ejemplos de caracteres que no se pueden mostrar como caracteres literales son los caracteres de formato de fecha y formato de hora (a, c, d, h, m, n, p, q, s, t, w, y, /y :), los caracteres de formato numérico (#, 0, %, E, e, coma, y punto) y los caracteres de formato de cadena (@, &, <, >y !).
("``ABC``") Muestra la cadena entre comillas dobles (" "). Para incluir una cadena en el argumento style desde el código, debe usar Chr(34) para incluir el texto (34 es el código de carácter de una comilla (")).

Ejemplo de código heredado

La tabla siguiente contiene algunas expresiones de formato de ejemplo para números. (En estos ejemplos se supone que la configuración regional del sistema es Inglés-EE.UU.) La primera columna contiene las cadenas de formato del argumento Style de la función Format; las demás columnas contienen la salida resultante si los datos con formato tienen el valor proporcionado en los encabezados de columna.

Formato (Style) "5" con formato "-5" con formato "0.5" con formato
Zero-length string ("") 5 -5 0.5
0 5 -5 1
0.00 5.00 -5.00 0.50
#,##0 5 -5 1
$#,##0;($#,##0) $5 ($5) $1
$#,##0.00;($#,##0.00) $5.00 ($5.00) $0.50
0% 500% -500% 50%
0.00% 500.00% -500.00% 50.00%
0.00E+00 5.00E+00 -5.00E+00 5.00E-01
0.00E-00 5.00E00 -5.00E00 5.00E-01

Formatos predefinidos de fecha y hora

En la tabla siguiente se identifican los nombres predefinidos de formato de fecha y hora. Se pueden usar por nombre como argumento de estilo para la función Format:

Nombre de formato Descripción
General Date, o G Muestra una fecha o hora. Por ejemplo, 3/12/2008 11:07:31 AM. La presentación de fechas viene determinada por el valor de referencia cultural actual de la aplicación.
Long Date, Medium Dateo D Muestra una fecha según el formato de fecha larga de la referencia cultural actual. Por ejemplo, Wednesday, March 12, 2008.
Short Date, o d Muestra una fecha con el formato de fecha corta de la referencia cultural actual. Por ejemplo, 3/12/2008.

El carácter d muestra el día en un formato de fecha definido por el usuario.
Long Time, Medium Timeo T Muestra una hora con el formato de tiempo largo de la referencia cultural actual; normalmente incluye horas, minutos, segundos. Por ejemplo, 11:07:31 AM.
Short Time o t Muestra una hora con el formato de tiempo corto de la referencia cultural actual. Por ejemplo, 11:07 AM.

El carácter de t muestra valores AM o PM para configuraciones regionales que usan un reloj de 12 horas en un formato de hora definido por el usuario.
f Muestra la fecha larga y la hora corta según el formato de la referencia cultural actual. Por ejemplo, Wednesday, March 12, 2008 11:07 AM.
F Muestra la fecha larga y la larga hora según el formato de la referencia cultural actual. Por ejemplo, Wednesday, March 12, 2008 11:07:31 AM.
g Muestra la fecha corta y la hora corta según el formato de la referencia cultural actual. Por ejemplo, 3/12/2008 11:07 AM.
M, m Muestra el mes y el día de una fecha. Por ejemplo, March 12.

El carácter M muestra el mes en un formato de fecha definido por el usuario. El carácter m muestra los minutos en un formato de hora definido por el usuario.
R, r Da formato a la fecha según la propiedad RFC1123Pattern. Por ejemplo, Wed, 12 Mar 2008 11:07:31 GMT. La fecha con formato no ajusta el valor de la fecha y hora. Debe ajustar el valor de fecha y hora a GMT antes de llamar a la función Format.
s Da formato a la fecha y hora como índice ordenable. Por ejemplo, 2008-03-12T11:07:31.

El carácter s muestra los segundos en un formato de hora definido por el usuario.
u Da formato a la fecha y hora como un índice ordenable GMT. Por ejemplo, 2008-03-12 11:07:31Z.
U Da formato a la fecha y hora con la fecha y hora largas como GMT. Por ejemplo, Wednesday, March 12, 2008 6:07:31 PM.
Y, y Da formato a la fecha como año y mes. Por ejemplo, March, 2008.

Los caracteres Y y y muestran el año en un formato de fecha definido por el usuario.

Para obtener más información sobre la información de referencia cultural actual de la aplicación, vea Cómo afecta la referencia cultural a las cadenas en Visual Basic.

formatos de fecha y hora de User-Defined

En la tabla siguiente se muestran los caracteres que puede usar para crear formatos de fecha y hora definidos por el usuario. A diferencia de las versiones anteriores de Visual Basic, estos caracteres de formato distinguen mayúsculas de minúsculas.

Carácter Descripción
(:) Separador de tiempo. En algunas configuraciones regionales, se pueden usar otros caracteres para representar el separador de tiempo. El separador de tiempo separa horas, minutos y segundos cuando se da formato a los valores de hora. El carácter real que se usa como separador de hora en la salida con formato viene determinado por el valor de referencia cultural actual de la aplicación.
(/) Separador de fecha. En algunas configuraciones regionales, se pueden usar otros caracteres para representar el separador de fecha. El separador de fecha separa el día, el mes y el año en que se da formato a los valores de fecha. El carácter real que se usa como separador de fecha en la salida con formato viene determinado por la referencia cultural actual de la aplicación.
(%) Se usa para indicar que el carácter siguiente debe leerse como un formato de letra única sin tener en cuenta las letras finales. También se usa para indicar que un formato de letra única se lee como un formato definido por el usuario. Consulte lo siguiente para obtener más detalles.
d Muestra el día como un número sin cero a la izquierda (por ejemplo, 1). Use %d si es el único carácter en el formato numérico definido por el usuario.
dd Muestra el día como un número con un cero a la izquierda (por ejemplo, 01).
ddd Muestra el día como una abreviatura (por ejemplo, Sun).
dddd Muestra el día como un nombre completo (por ejemplo, Sunday).
M Muestra el mes como un número sin cero a la izquierda (por ejemplo, enero se representa como 1). Use %M si es el único carácter en el formato numérico definido por el usuario.
MM Muestra el mes como un número con un cero a la izquierda (por ejemplo, 01/12/01).
MMM Muestra el mes como abreviatura (por ejemplo, Jan).
MMMM Muestra el mes como un nombre de mes completo (por ejemplo, January).
gg Muestra la cadena period/era (por ejemplo, A.D.).
h Muestra la hora como un número sin ceros iniciales mediante el reloj de 12 horas (por ejemplo, 1:15:15 PM). Use %h si es el único carácter en el formato numérico definido por el usuario.
hh Muestra la hora como un número con ceros iniciales mediante el reloj de 12 horas (por ejemplo, 01:15:15 PM).
H Muestra la hora como un número sin ceros iniciales mediante el reloj de 24 horas (por ejemplo, 1:15:15). Use %H si es el único carácter en el formato numérico definido por el usuario.
HH Muestra la hora como un número con ceros iniciales mediante el reloj de 24 horas (por ejemplo, 01:15:15).
m Muestra el minuto como un número sin ceros iniciales (por ejemplo, 12:1:15). Use %m si es el único carácter en el formato numérico definido por el usuario.
mm Muestra el minuto como un número con ceros a la izquierda (por ejemplo, 12:01:15).
s Muestra el segundo como un número sin ceros iniciales (por ejemplo, 12:15:5). Use %s si es el único carácter en el formato numérico definido por el usuario.
ss Muestra el segundo como un número con ceros iniciales (por ejemplo, 12:15:05).
f Muestra fracciones de segundos. Por ejemplo, ff muestra centésimas de segundos, mientras que ffff muestra diez milésimas de segundos. Puede usar hasta siete f símbolos en el formato definido por el usuario. Use %f si es el único carácter en el formato numérico definido por el usuario.
t Utiliza el reloj de 12 horas y muestra una A mayúsculas durante cualquier hora antes del mediodía; muestra una P mayúsculas para cualquier hora entre el mediodía y las 11:59 p.m. Use %t si es el único carácter en el formato numérico definido por el usuario.
tt Para las configuraciones regionales que usan un reloj de 12 horas, muestra una AM mayúsculas con cualquier hora antes del mediodía; muestra una PM mayúsculas con cualquier hora entre el mediodía y las 11:59 p.m.

En el caso de las configuraciones regionales que usan un reloj de 24 horas, no muestra nada.
y Muestra el número de año (0-9) sin ceros iniciales. Use %y si es el único carácter en el formato numérico definido por el usuario.
yy Muestra el año en formato numérico de dos dígitos con un cero inicial, si procede.
yyy Muestra el año en formato numérico de cuatro dígitos.
yyyy Muestra el año en formato numérico de cuatro dígitos.
z Muestra el desplazamiento de zona horaria sin un cero a la izquierda (por ejemplo, -8). Use %z si es el único carácter en el formato numérico definido por el usuario.
zz Muestra el desplazamiento de zona horaria con un cero a la izquierda (por ejemplo, -08)
zzz Muestra el desplazamiento de zona horaria completa (por ejemplo, -08:00)

Ejemplo de código heredado

A continuación se muestran ejemplos de formatos de fecha y hora definidos por el usuario para December 7, 1958, 8:50 PM, 35 seconds:

Formato Muestra
M/d/yy 12/7/58
d-MMM 7-Dec
d-MMMM-yy 7-December-58
d MMMM 7 December
MMMM yy December 58
hh:mm tt 08:50 PM
h:mm:ss t 8:50:35 P
H:mm 20:50
H:mm:ss 20:50:35
M/d/yyyy H:mm 12/7/1958 20:50

Notas del desarrollador de dispositivos inteligentes

La resolución de tiempo mínima para un dispositivo viene determinada por el fabricante del dispositivo. Si la resolución de tiempo del dispositivo es lo suficientemente gruesa, el carácter de formato f devuelve 0 cuando se ejecuta en ese dispositivo.

Se aplica a

Consulte también