Strings.Format(Object, String) Méthode

  • Référence

Définition

Espace de noms:
Microsoft.VisualBasic
Assembly:
Microsoft.VisualBasic.Core.dll
Assembly:
Microsoft.VisualBasic.dll
Source:
Strings.vb
Source:
Strings.vb
Source:
Strings.vb

Retourne une chaîne mise en forme conformément aux instructions contenues dans une expression String de format.

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

Paramètres

Expression
Object

Obligatoire. Toute expression valide.

Style
String

Optionnel. Expression String de format nommée ou définie par l'utilisateur valide.

Retours

String

Une chaîne mise en forme conformément aux instructions contenues dans une expression String de format.

Exemples

L'exemple suivant illustre différentes utilisations de la fonction Format pour mettre en forme des valeurs utilisant à la fois les formats String et les formats définis par l'utilisateur. Pour le séparateur de date (/), le séparateur d'heure (:) et les indicateurs AM/PM (t et tt), le résultat réel mis en forme affiché par votre système dépend des paramètres régionaux utilisés par le code. Lorsque les heures et les dates sont affichées dans l'environnement de développement, les formats d'heure abrégée et de date courte des paramètres régionaux de code sont utilisés.

Notes

Pour paramètres régionaux configurés avec une horloge au format 24 heures, les indicateurs AM/PM (t et tt) n'affichent rien.

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%")

Remarques

La String.Format méthode fournit également des fonctionnalités similaires.

Si vous mettez en forme une chaîne numérique non localisée, vous devez utiliser un format numérique défini par l’utilisateur pour vous assurer que vous obtenez l’apparence souhaitée.

Si vous essayez de mettre en forme un nombre sans spécifier Style, la Format fonction fournit des fonctionnalités similaires à la Str fonction, bien qu’elle soit internationalement reconnue. Toutefois, les nombres positifs mis en forme en tant que chaînes à l’aide de la Format fonction n’incluent pas d’espace de début réservé au signe de la valeur ; ceux convertis à l’aide de la Str fonction conservent l’espace de début.

Différents formats pour différentes valeurs numériques

Une expression de format définie par l’utilisateur pour les nombres peut avoir de une à trois sections séparées par des points-virgules. Si l’argument Style de la Format fonction contient l’un des formats numériques prédéfinis, une seule section est autorisée.

Si vous utilisez : Voici le résultat :
Une seule section L'expression de format s'applique à toutes les valeurs.
Deux sections La première section s’applique aux valeurs positives et aux zéros. La seconde s’applique aux valeurs négatives.
Trois sections La première section s’applique aux valeurs positives, la deuxième s’applique aux valeurs négatives et la troisième s’applique aux zéros.

L’exemple suivant comporte deux sections : la première définit le format des valeurs positives et des zéros ; la deuxième section définit le format des valeurs négatives. Étant donné que l’argument Style de la Format fonction prend une chaîne, il est entouré de guillemets.

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

Si vous incluez des points-virgules sans valeur entre eux, la section manquante est affichée avec le format de la valeur positive. Par exemple, le format suivant affiche les valeurs positives et négatives à l’aide du format de la première section et affiche Zero si la valeur est égale à zéro.

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

Formats numériques prédéfinis

Le tableau suivant identifie les noms de formats numériques prédéfinis. Ceux-ci peuvent être utilisés par nom comme Style argument pour la Format fonction :

Nom du format Description
General Number, Gou g Affiche le nombre sans séparateur de milliers.

Par exemple, Format(&H3FA, "g") retourne 1018.
Currency, Cou c Affiche le nombre avec séparateur de milliers, le cas échéant ; affiche deux chiffres à droite du séparateur décimal. Le résultat dépend des paramètres régionaux système.

Par exemple, Format(1234567, "c") retourne $1,234,567.00.
Fixed, Fou f Affiche au moins un chiffre à gauche et deux chiffres à droite du séparateur décimal.

Par exemple, Format(1234567, "f") retourne 1234567.00.
Standard, Nou n Affiche le nombre avec le séparateur de milliers, au moins un chiffre à gauche et deux chiffres à droite du séparateur décimal.

Par exemple, Format(1234567, "n") retourne 1,234,567.00.
Percent Affiche le nombre multiplié par 100 avec un signe de pourcentage (%) ajouté de suite à droite ; affiche toujours deux chiffres à droite du séparateur décimal.

Par exemple, Format(0.4744, "Percent") retourne 47.44%.
P ou p Affiche le nombre avec le séparateur des milliers multiplié par 100 avec un symbole de pourcentage (%) ajouté à droite et séparé par un seul espace ; affiche toujours deux chiffres à droite du séparateur décimal.

Par exemple, Format(0.80345, "p") retourne 80.35 %.
Scientific Utilise la notation scientifique standard, en fournissant deux chiffres significatifs.

Par exemple, Format(1234567, "Scientific") retourne 1.23E+06.
E ou e Utilise la notation scientifique standard, en fournissant six chiffres significatifs.

Par exemple, Format(1234567, "e") retourne 1.234567e+006.
D ou d Affiche le nombre sous la forme d'une chaîne qui contient la valeur du nombre au format décimal (base 10). Cette option est prise en charge uniquement pour les types intégraux (Byte, Short, Integer, Long).

Par exemple, Format(&H7F, "d") retourne 127.
X ou x Affiche le nombre sous la forme d'une chaîne qui contient la valeur du nombre au format hexadécimal (base 16). Cette option est prise en charge uniquement pour les types intégraux (Byte, Short, Integer, Long).

Par exemple, Format(127, "x") retourne 7f.
Yes/No Affiche No si le nombre est 0 ; sinon, affiche Yes.

Par exemple, Format(0, "Yes/No") retourne No.
True/False Affiche False si le nombre est 0 ; sinon, affiche True.

Par exemple, Format(1, "True/False") retourne True.
On/Off Affiche Off si le nombre est 0 ; sinon, affiche On.

Par exemple, Format(1, "On/Off") retourne On.

Notes du développeur Smart Device

Les Yes/Noformats , True/Falseet On/Off ne sont pas pris en charge.

User-Defined formats numériques

Le tableau suivant identifie les caractères que vous pouvez utiliser pour créer des formats de nombre définis par l’utilisateur. Vous pouvez les utiliser pour générer l’argument Style de la Format fonction :

Caractère Description
None Affiche le nombre sans mise en forme.
(0) Espace réservé de chiffre. Affiche un chiffre ou un zéro. Si l’expression a un chiffre dans la position où le zéro apparaît dans la chaîne de format, affichez-le ; sinon, affiche un zéro dans cette position.

Si le nombre contient moins de chiffres que de zéros (de part et d’autre du séparateur décimal) dans l’expression de format, affiche des zéros au début ou à la fin. Si le nombre contient plus de chiffres à droite du séparateur décimal qu’il y a de zéros à droite du séparateur décimal dans l’expression de format, arrondit le nombre à autant de décimales qu’il y a de zéros. Si le nombre contient plus de chiffres à gauche du séparateur décimal qu’il y a de zéros à gauche du séparateur décimal dans l’expression de format, affiche les chiffres supplémentaires sans modification.
(#) Espace réservé de chiffre. Affiche un chiffre ou rien. Si l’expression a un chiffre dans la position où le # caractère apparaît dans la chaîne de format, l’affiche ; sinon, n’affiche rien dans cette position.

Ce symbole fonctionne comme l’espace 0 réservé au chiffre, sauf que les zéros de début et de fin ne sont pas affichés si le nombre a moins de chiffres qu’il n’y # a de caractères de chaque côté du séparateur décimal dans l’expression de format.
(.) Espace réservé de décimale. L’espace réservé de décimale détermine le nombre de chiffres affichés à gauche et à droite du séparateur décimal. Si l’expression de format contient uniquement # des caractères à gauche de ce symbole ; les nombres inférieurs à 1 commencent par un séparateur décimal. Pour afficher un zéro non significatif avec les nombres fractionnaires, utilisez zéro comme premier espace réservé de chiffre à gauche du séparateur décimal. Dans certains paramètres régionaux, une virgule est utilisée comme séparateur décimal. Le caractère réel utilisé comme espace réservé de décimale dans le résultat mis en forme dépend du format numérique reconnu par votre système. Ainsi, vous devez utiliser le point comme espace réservé de décimale dans vos formats même si vos paramètres régionaux utilisent une virgule comme espace réservé de décimale. La chaîne mise en forme s’affiche au format correct, selon les paramètres régionaux.
(%) Espace réservé de pourcentage. Multiplie l’expression par 100. Le caractère de pourcentage (%) est inséré à l’emplacement où il apparaît dans la chaîne de format.
(,) Séparateur des milliers. Le séparateur des milliers sépare les milliers des centaines au sein d’un nombre qui a quatre décimales ou plus à gauche du séparateur décimal. L’utilisation standard du séparateur de milliers est spécifiée si le format contient un séparateur de milliers entouré d’espaces réservés de chiffres (0 ou #).

Un séparateur de milliers immédiatement à gauche du séparateur décimal (qu’une décimale soit spécifiée ou non) ou comme caractère le plus à droite dans la chaîne signifie « mettre à l’échelle le nombre en le divisant par 1 000, en l’arrondissant selon les besoins ». Les nombres inférieurs à 1 000 mais supérieurs ou égaux à 500 sont affichés sous la forme 1, et les nombres inférieurs à 500 sont affichés sous la forme 0. Quand deux séparateurs de milliers adjacents figurent à cet emplacement, un facteur d’échelle de 1 million est appliqué. Un facteur supplémentaire de 1 000 est appliqué pour chaque séparateur supplémentaire.

Plusieurs séparateurs à tout emplacement autre qu’immédiatement à gauche du séparateur décimal ou à l’extrême droite de la chaîne sont traités simplement comme spécifiant l’utilisation d’un séparateur de milliers. Dans certains paramètres régionaux, un point est utilisé comme séparateur des milliers. Le caractère réel utilisé pour le séparateur de milliers dans le résultat mis en forme dépend du format numérique reconnu par votre système. Ainsi, vous devez utiliser la virgule comme séparateur de milliers dans vos formats même si vos paramètres régionaux utilisent un point comme séparateur de milliers. La chaîne mise en forme s’affiche au format correct, selon les paramètres régionaux.

Par exemple, considérez les trois chaînes de format suivantes :

- "#,0.", qui utilise le séparateur de milliers pour mettre en forme le nombre 100 millions en tant que chaîne « 100 000 000 ».
- "#0,.", qui utilise la mise à l’échelle d’un facteur de mille pour mettre en forme le nombre 100 millions en tant que chaîne « 100000 ».
- "#,0,.", qui utilise le séparateur de milliers et la mise à l’échelle d’un millier pour mettre en forme le nombre 100 millions en tant que chaîne « 100 000 ».
(:) Séparateur d’heure. Pour certains paramètres régionaux, d’autres caractères peuvent être utilisés pour représenter le séparateur d’heure. Le séparateur d’heure sépare les heures, les minutes et les secondes lors de la mise en forme des valeurs d’heure. Le caractère réel utilisé comme séparateur d’heure dans le résultat mis en forme est déterminé par vos paramètres système.
(/) Séparateur de date. Pour certains paramètres régionaux, d’autres caractères peuvent être utilisés pour représenter le séparateur de date. Le séparateur de date sépare le jour, le mois et l’année lorsque les valeurs de date sont mises en forme. Le caractère réel utilisé comme séparateur de date dans le résultat mis en forme est déterminé par vos paramètres système.
(E-``E+``e-``e+) Format scientifique. Si l’expression de format contient au moins un espace réservé à un chiffre (0 ou #) à gauche de E-, E+, e-ou e+, le nombre est affiché au format scientifique et E est e inséré entre le nombre et son exposant. Le nombre d’espaces réservés de chiffre à gauche détermine le nombre de chiffres dans l’exposant. Utilisez E- ou e- pour placer un signe moins en regard des exposants négatifs. Utilisez E+ ou e+ pour placer un signe moins à côté des exposants négatifs et un signe plus à côté des exposants positifs. Vous devez également inclure des espaces réservés de chiffre à droite de ce symbole pour obtenir la mise en forme correcte.
-+$ ( ) Caractères littéraux. Ces caractères s’affichent exactement tels qu’ils sont tapés dans la chaîne de format. Pour afficher un caractère autre que les caractères listés, faites-le précéder d’une barre oblique inverse (\) ou placez-le entre guillemets doubles (" ").
(\) Affiche le prochain caractère de la chaîne de format. Pour afficher un caractère ayant une signification spéciale sous forme de caractère littéral, faites-le précéder d’une barre oblique inverse (\). La barre oblique inverse elle-même n’est pas affichée. L'utilisation d'une barre oblique inverse équivaut à mettre le caractère suivant entre des guillemets doubles. Pour afficher une barre oblique inverse, utilisez deux barres obliques inverses (\\).

Des exemples de caractères qui ne peuvent pas être affichés en tant que caractères littéraux sont les caractères de mise en forme de date et d’heure (a, tcspqhy/mwdnet :), les caractères de mise en forme numérique (#, 0, %, E, , e, , virgule et point) et les caractères de mise en forme de chaîne (@, &, <>, et ).!
("``ABC``") Affiche la chaîne à l’intérieur des guillemets doubles (" "). Pour inclure une chaîne dans l’argument de style à partir du code, vous devez utiliser Chr(34) pour inclure le texte (34 est le code de caractère d’un guillemet (« )).

Exemple de code hérité

Le tableau suivant contient des exemples d’expressions de format pour les nombres. (Ces exemples supposent tous que le paramètre de paramètres régionaux de votre système est Anglais-États-Unis.) La première colonne contient les chaînes de format de l’argument Style de la Format fonction ; les autres colonnes contiennent la sortie résultante si les données mises en forme ont la valeur donnée dans les en-têtes de colonne.

Format (Style) Résultat mis en forme pour « 5 » Résultat mis en forme pour « -5 » Résultat mis en forme pour « 0.5 »
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

Formats de date/heure prédéfinis

Le tableau suivant identifie les noms de formats de date et heure prédéfinis. Celles-ci peuvent être utilisées par nom comme argument de style pour la Format fonction :

Nom de format Description
General Date ou G Affiche une date et/ou une heure. Par exemple : 3/12/2008 11:07:31 AM. L’affichage de la date est déterminé par les paramètres régionaux actuels de l’application.
Long Date, Medium Dateou D Affiche une date en fonction du format de date longue des paramètres régionaux actuels. Par exemple : Wednesday, March 12, 2008.
Short Date ou d Affiche une date en fonction du format de date courte des paramètres régionaux actuels. Par exemple : 3/12/2008.

Le d caractère affiche le jour dans un format de date défini par l’utilisateur.
Long Time, Medium Timeou T Affiche une heure en fonction du format d’heure longue des paramètres régionaux actuels, qui inclut généralement les heures, les minutes et les secondes. Par exemple : 11:07:31 AM.
Short Time ou t Affiche une heure à l'aide du format d'heure courte des paramètres régionaux définis actuellement. Par exemple : 11:07 AM.

Le t caractère affiche AM ou PM des valeurs pour les paramètres régionaux qui utilisent une horloge de 12 heures dans un format d’heure défini par l’utilisateur.
f Affiche la date longue et l'heure courte d'après le format des paramètres régionaux actuellement définis. Par exemple : Wednesday, March 12, 2008 11:07 AM.
F Affiche la date longue et l'heure longue d'après le format des paramètres régionaux actuellement définis. Par exemple : Wednesday, March 12, 2008 11:07:31 AM.
g Affiche la date courte et l'heure courte d'après le format des paramètres régionaux actuellement définis. Par exemple : 3/12/2008 11:07 AM.
M, m Affiche le mois et le jour d'une date. Par exemple : March 12.

Le M caractère affiche le mois dans un format de date défini par l’utilisateur. Le m caractère affiche les minutes dans un format d’heure défini par l’utilisateur.
R, r Met en forme la date en fonction de la RFC1123Pattern propriété . Par exemple : Wed, 12 Mar 2008 11:07:31 GMT. La date mise en forme n'ajuste pas la valeur de date et d'heure. Vous devez ajuster la valeur Date/Heure à GMT avant d’appeler la Format fonction.
s Met en forme la date et l'heure en tant qu'index triable. Par exemple : 2008-03-12T11:07:31.

Le s caractère affiche les secondes dans un format de temps défini par l’utilisateur.
u Met en forme la date et l'heure en tant qu'index triable GMT. Par exemple : 2008-03-12 11:07:31Z.
U Met en forme la date et l'heure avec la date et l'heure longues d'après GMT. Par exemple : Wednesday, March 12, 2008 6:07:31 PM.
Y, y Met en forme la date en tant qu'année et mois. Par exemple : March, 2008.

Les Y caractères et y affichent l’année dans un format de date défini par l’utilisateur.

Pour plus d’informations sur les informations de culture actuelles de l’application, consultez How Culture Affects Strings in Visual Basic.

User-Defined Formats de date/heure

Le tableau suivant présente les caractères que vous pouvez utiliser pour créer des formats de date/heure définis par l’utilisateur. Contrairement aux versions antérieures de Visual Basic, ces caractères de format respectent la casse.

Caractère Description
(:) Séparateur d’heure. Pour certains paramètres régionaux, d’autres caractères peuvent être utilisés pour représenter le séparateur d’heure. Le séparateur d’heure sépare les heures, les minutes et les secondes lors de la mise en forme des valeurs d’heure. Le caractère réel utilisé comme séparateur d’heure dans le résultat mis en forme est déterminé par les paramètres régionaux actuels de votre application.
(/) Séparateur de date. Pour certains paramètres régionaux, d’autres caractères peuvent être utilisés pour représenter le séparateur de date. Le séparateur de date sépare le jour, le mois et l’année lorsque les valeurs de date sont mises en forme. Le caractère réel utilisé comme séparateur de date dans le résultat mis en forme est déterminé par les paramètres régionaux actuels de votre application.
(%) Utilisé pour indiquer que le caractère suivant doit être lu selon un format à une seule lettre, sans prise en compte des lettres de fin éventuelles. Permet également d’indiquer qu’un format à une seule lettre est lu comme format défini par l’utilisateur. Vous trouverez plus d’informations ci-après.
d Affiche le jour sous la forme d’un nombre sans zéro de début (par exemple, 1). Utilisez %d s’il s’agit du seul caractère dans votre format numérique défini par l’utilisateur.
dd Affiche le jour sous forme de nombre avec un zéro de début (par exemple, 01).
ddd Affiche le jour sous forme d’abréviation (par exemple, Sun).
dddd Affiche le jour sous la forme d’un nom complet (par exemple, Sunday).
M Affiche le mois sous la forme d’un nombre sans zéro (par exemple, janvier est représenté sous la forme 1). Utilisez %M s’il s’agit du seul caractère dans votre format numérique défini par l’utilisateur.
MM Affiche le mois sous forme de nombre avec un zéro de début (par exemple, 01/12/01).
MMM Affiche le mois sous forme d’abréviation (par exemple, Jan).
MMMM Affiche le mois sous la forme d’un nom de mois complet (par exemple, January).
gg Affiche la chaîne point/ère (par exemple, A.D.).
h Affiche l’heure sous forme de nombre sans zéros de début à l’aide de l’horloge de 12 heures (par exemple, 1:15:15 PM). Utilisez %h s’il s’agit du seul caractère dans votre format numérique défini par l’utilisateur.
hh Affiche l’heure sous forme de nombre avec des zéros de début à l’aide de l’horloge de 12 heures (par exemple, 01:15:15 PM).
H Affiche l’heure sous forme de nombre sans zéros de début à l’aide de l’horloge de 24 heures (par exemple, 1:15:15). Utilisez %H s’il s’agit du seul caractère dans votre format numérique défini par l’utilisateur.
HH Affiche l’heure sous forme de nombre avec des zéros de début à l’aide de l’horloge de 24 heures (par exemple, 01:15:15).
m Affiche la minute sous forme de nombre sans zéros de début (par exemple, 12:1:15). Utilisez %m s’il s’agit du seul caractère dans votre format numérique défini par l’utilisateur.
mm Affiche la minute sous forme de nombre avec des zéros de début (par exemple, 12:01:15).
s Affiche le deuxième sous la forme d’un nombre sans zéros (par exemple, 12:15:5). Utilisez %s s’il s’agit du seul caractère dans votre format numérique défini par l’utilisateur.
ss Affiche le deuxième sous la forme d’un nombre avec des zéros de début (par exemple, 12:15:05).
f Affiche des fractions de secondes. Par exemple ff , affiche des centièmes de secondes, tandis qu’il ffff affiche dix millièmes de secondes. Vous pouvez utiliser jusqu’à sept f symboles dans votre format défini par l’utilisateur. Utilisez %f s’il s’agit du seul caractère dans votre format numérique défini par l’utilisateur.
t Utilise l’horloge de 12 heures et affiche une majuscule A pour toute heure avant midi ; affiche une majuscule P pour toute heure comprise entre midi et 23 h 59. Utilisez %t s’il s’agit du seul caractère dans votre format numérique défini par l’utilisateur.
tt Pour les paramètres régionaux qui utilisent une horloge de 12 heures, affiche une majuscule AM avec n’importe quelle heure avant midi ; affiche une majuscule PM avec n’importe quelle heure entre midi et 23 :59.

Pour les paramètres régionaux qui utilisent une horloge de 24 heures, rien ne s'affiche.
y Affiche le numéro de l’année (0-9) sans zéro non significatif. Utilisez %y s’il s’agit du seul caractère dans votre format numérique défini par l’utilisateur.
yy Affiche l’année au format numérique à deux chiffres avec un zéro non significatif, le cas échéant.
yyy Affiche l’année au format numérique à quatre chiffres.
yyyy Affiche l’année au format numérique à quatre chiffres.
z Affiche le décalage de fuseau horaire sans zéro de début (par exemple, -8). Utilisez %z s’il s’agit du seul caractère dans votre format numérique défini par l’utilisateur.
zz Affiche le décalage de fuseau horaire avec un zéro de début (par exemple, -08)
zzz Affiche le décalage de fuseau horaire complet (par exemple, -08:00)

Exemple de code hérité

Voici des exemples de formats de date et d’heure définis par l’utilisateur pour December 7, 1958, 8:50 PM, 35 seconds:

Format Affiche
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

Notes du développeur Smart Device

La résolution de temps minimale d’un appareil est déterminée par le fabricant de l’appareil. Si la résolution de temps de l’appareil est assez grossière, le caractère de f format renvoie 0 lors de l’exécution sur cet appareil.

S’applique à

Voir aussi