Partager via

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 en fonction des instructions contenues dans un format String expression.

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. Un format nommé ou défini par l’utilisateur valide String expression.

Retours

String

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

Exemples

Cet exemple montre différentes utilisations de la fonction Format pour mettre en forme des valeurs à l’aide de formats String et de 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), la sortie mise en forme réelle affichée par votre système dépend des paramètres régionaux que le code utilise. Lorsque les heures et les dates sont affichées dans l’environnement de développement, le format de temps court et le format de date courte des paramètres régionaux du code sont utilisés.

Note

Pour les paramètres régionaux qui utilisent une horloge de 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 méthode String.Format 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 fonction Format fournit des fonctionnalités similaires à la fonction Str, bien qu’elle soit au niveau international. Toutefois, les nombres positifs mis en forme sous forme de chaînes à l’aide de la fonction Format n’incluent pas d’espace de début réservé pour le signe de la valeur ; ceux convertis à l’aide de la fonction Str 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 un à trois sections séparées par des points-virgules. Si l’argument Style de la fonction Format contient l’un des formats numériques prédéfinis, une seule section est autorisée.

Si vous utilisez Il s’agit du 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 zéros ; la seconde s’applique aux valeurs négatives.
Trois sections La première section s’applique aux valeurs positives, la seconde 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 fonction Format prend une chaîne, il est placé entre guillemets.

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

Si vous incluez des points-virgules avec rien entre eux, la section manquante est imprimée à l’aide du format de la valeur positive. Par exemple, le format suivant affiche des 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 format numérique prédéfinis. Elles peuvent être utilisées par nom comme argument Style pour la fonction Format :

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 un séparateur de milliers, le cas échéant ; affiche deux chiffres à droite du séparateur décimal. La sortie est basée sur les 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 un 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 par un signe de pourcentage (%) ajouté immédiatement à droite ; affiche toujours deux chiffres à droite du séparateur décimal.

Par exemple, Format(0.4744, "Percent") retourne 47.44%.
Pou p Affiche le nombre avec séparateur de millièmes multiplié par 100 par un signe de pourcentage (%) ajouté à droite et séparé par un espace unique ; 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, fournissant deux chiffres significatifs.

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

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

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

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 formats Yes/No, True/Falseet On/Off ne sont pas pris en charge.

formats numériques User-Defined

Le tableau suivant identifie les caractères que vous pouvez utiliser pour créer des formats numériques définis par l’utilisateur. Il peut être utilisé pour générer l’argument Style pour la fonction Format :

Personnage Description
Aucun Affiche le nombre sans mise en forme.
(0) Espace réservé numérique. 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 a moins de chiffres qu’il y a des zéros (sur les deux côtés de la décimale) dans l’expression de format, affiche les zéros de début ou de fin. Si le nombre a plus de chiffres à droite du séparateur décimal qu’il y a des 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 a plus de chiffres à gauche du séparateur décimal qu’il y a des zéros à gauche du séparateur décimal dans l’expression de format, affiche les chiffres supplémentaires sans modification.
(#) Espace réservé numérique. 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 réservé 0 chiffre, sauf que les zéros de début et de fin ne s’affichent pas si le nombre a moins de chiffres qu’il y a # caractères de chaque côté du séparateur décimal dans l’expression de format.
(.) Espace réservé décimal. L’espace réservé décimal détermine le nombre de chiffres affichés à gauche et à droite du séparateur décimal. Si l’expression de format contient uniquement # 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 affiché avec des nombres fractionnaires, utilisez zéro comme espace réservé au premier 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é décimal dans la sortie mise en forme dépend du format numérique reconnu par votre système. Par conséquent, vous devez utiliser la période comme espace réservé décimal dans vos formats même si vous êtes dans des paramètres régionaux qui utilisent une virgule comme espace réservé décimal. La chaîne mise en forme s’affiche au format correct pour les paramètres régionaux.
(%) Espace réservé pour cent. Multiplie l’expression par 100. Le caractère pourcentage (%) est inséré dans la position où il apparaît dans la chaîne de format.
(,) Mille séparateurs. Le séparateur de milliers sépare des milliers de centaines au sein d’un nombre qui a quatre emplacements 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 à chiffres (0 ou #).

Un millier de séparateurs immédiatement à gauche du séparateur décimal (qu’un décimal soit spécifié ou non) ou comme caractère le plus à droite de la chaîne signifie « mettre à l’échelle le nombre en le divisant par 1 000, arrondi selon les besoins ». Les nombres inférieurs à 1 000 mais supérieurs ou égaux à 500 sont affichés en tant que 1, et les nombres inférieurs à 500 sont affichés en tant que 0. Deux séparateurs de milliers adjacents dans cette échelle de position par un facteur de 1 million, et un facteur supplémentaire de 1 000 pour chaque séparateur supplémentaire.

Plusieurs séparateurs dans n’importe quelle position autre que immédiatement à gauche du séparateur décimal ou la position la plus à 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, une période est utilisée comme séparateur de milliers. Le caractère réel utilisé comme séparateur de milliers dans la sortie mise en forme dépend du format numérique reconnu par votre système. Par conséquent, vous devez utiliser la virgule comme séparateur de milliers dans vos formats même si vous êtes dans des paramètres régionaux qui utilisent un point comme séparateur de milliers. La chaîne mise en forme s’affiche au format correct pour 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 comme 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 comme 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 comme chaîne « 100 000 ».
(:) Séparateur de temps. Dans certains paramètres régionaux, d’autres caractères peuvent être utilisés pour représenter le séparateur de temps. Le séparateur de temps sépare les heures, les minutes et les secondes lorsque les valeurs de temps sont mises en forme. Le caractère réel utilisé comme séparateur de temps dans la sortie mise en forme est déterminé par vos paramètres système.
(/) Séparateur de date. Dans 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 où les valeurs de date sont mises en forme. Le caractère réel utilisé comme séparateur de date dans la sortie mise 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 ou e est inséré entre le nombre et son exposant. Le nombre d’espaces réservés à 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 en regard des exposants négatifs et un signe plus en regard des exposants positifs. Vous devez également inclure des espaces réservés à chiffre à droite de ce symbole pour obtenir une mise en forme correcte.
- + $ ( ) Caractères littéraux. Ces caractères sont affichés exactement comme tapés dans la chaîne de format. Pour afficher un caractère autre que l’un de ceux répertoriés, faites-le précéder d’une barre oblique inverse (\) ou placez-le entre guillemets doubles ( » « ).
(\) Affiche le caractère suivant dans la chaîne de format. Pour afficher un caractère qui a une signification spéciale en tant que 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 est identique au caractère suivant entre guillemets doubles. Pour afficher une barre oblique inverse, utilisez deux barres obliques inverses (\\).

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, c, d, h, m, n, p, q, s, t, w, y, /et :), caractères de mise en forme numérique (#, 0, %, E, e, virgule, et point), ainsi que les caractères de mise en forme de chaîne (@, &, <, >et !).
("``ABC``") Affiche la chaîne entre guillemets doubles ( » « ). Pour inclure une chaîne dans l’argument de style à partir du code, vous devez utiliser Chr(34) pour placer le texte (34 est le code 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 des paramètres régionaux de votre système est anglais-États-Unis) La première colonne contient les chaînes de format pour l’argument Style de la fonction Format ; 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) « 5 » mis en forme comme « -5 » mis en forme comme « 0.5 » mis en forme comme
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 format de date et d’heure prédéfinis. Celles-ci peuvent être utilisées par nom comme argument de style pour la fonction Format :

Nom du format Description
General Dateou G Affiche une date et/ou une heure. Par exemple, 3/12/2008 11:07:31 AM. L’affichage de date est déterminé par la valeur de culture actuelle de votre application.
Long Date, Medium Dateou D Affiche une date en fonction du format de date long de votre culture actuelle. Par exemple, Wednesday, March 12, 2008.
Short Dateou d Affiche une date à l’aide du format de date court de votre culture actuelle. Par exemple, 3/12/2008.

Le caractère d affiche le jour dans un format de date défini par l’utilisateur.
Long Time, Medium Timeou T Affiche une heure à l’aide du format de longue durée de votre culture actuelle ; inclut généralement des heures, des minutes, des secondes. Par exemple, 11:07:31 AM.
Short Time ou t Affiche une heure à l’aide du format de temps court de votre culture actuelle. Par exemple, 11:07 AM.

Le caractère t affiche AM ou PM 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 en fonction du format de votre culture actuelle. Par exemple, Wednesday, March 12, 2008 11:07 AM.
F Affiche la date longue et l’heure longue en fonction du format de votre culture actuelle. Par exemple, Wednesday, March 12, 2008 11:07:31 AM.
g Affiche la date courte et l’heure courte en fonction du format de votre culture actuelle. Par exemple, 3/12/2008 11:07 AM.
M, m Affiche le mois et le jour d’une date. Par exemple, March 12.

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

Le caractère s affiche les secondes dans un format de temps défini par l’utilisateur.
u Met en forme la date et l’heure sous forme d’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 comme GMT. Par exemple, Wednesday, March 12, 2008 6:07:31 PM.
Y, y Met en forme la date comme année et mois. Par exemple, March, 2008.

Les caractères Y 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 Comment la culture affecte les chaînes dans Visual Basic.

formats de date/heure User-Defined

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.

Personnage Description
(:) Séparateur de temps. Dans certains paramètres régionaux, d’autres caractères peuvent être utilisés pour représenter le séparateur de temps. Le séparateur de temps sépare les heures, les minutes et les secondes lorsque les valeurs de temps sont mises en forme. Le caractère réel utilisé comme séparateur de temps dans la sortie mise en forme est déterminé par la valeur de culture actuelle de votre application.
(/) Séparateur de date. Dans 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 où les valeurs de date sont mises en forme. Le caractère réel utilisé comme séparateur de date dans la sortie mise en forme est déterminé par la culture actuelle de votre application.
(%) Utilisé pour indiquer que le caractère suivant doit être lu sous la forme d’une lettre unique sans tenir compte des lettres de fin. Également utilisé pour indiquer qu’un format de lettre unique est lu en tant que format défini par l’utilisateur. Pour plus d’informations, consultez ce qui suit.
d Affiche le jour sous la forme d’un nombre sans zéro non significatif (par exemple, 1). Utilisez %d s’il s’agit du seul caractère de votre format numérique défini par l’utilisateur.
dd Affiche le jour sous forme de nombre avec un zéro non significatif (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 non significatif (par exemple, janvier est représenté en tant que 1). Utilisez %M s’il s’agit du seul caractère de votre format numérique défini par l’utilisateur.
MM Affiche le mois sous la forme d’un nombre avec un zéro non significatif (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 de point/ère (par exemple, A.D.).
h Affiche l’heure sous la forme d’un nombre sans zéros non significatifs à l’aide de l’horloge de 12 heures (par exemple, 1:15:15 PM). Utilisez %h s’il s’agit du seul caractère de votre format numérique défini par l’utilisateur.
hh Affiche l’heure sous la forme d’un nombre avec des zéros non significatifs à l’aide de l’horloge de 12 heures (par exemple, 01:15:15 PM).
H Affiche l’heure sous la forme d’un nombre sans zéros non significatifs à l’aide de l’horloge de 24 heures (par exemple, 1:15:15). Utilisez %H s’il s’agit du seul caractère de votre format numérique défini par l’utilisateur.
HH Affiche l’heure sous la forme d’un nombre avec des zéros non significatifs à l’aide de l’horloge de 24 heures (par exemple, 01:15:15).
m Affiche la minute sous la forme d’un nombre sans zéros non significatifs (par exemple, 12:1:15). Utilisez %m s’il s’agit du seul caractère de votre format numérique défini par l’utilisateur.
mm Affiche la minute sous la forme d’un nombre avec des zéros non significatifs (par exemple, 12:01:15).
s Affiche le deuxième sous la forme d’un nombre sans zéros non significatifs (par exemple, 12:15:5). Utilisez %s s’il s’agit du seul caractère de votre format numérique défini par l’utilisateur.
ss Affiche le deuxième sous la forme d’un nombre avec des zéros non significatifs (par exemple, 12:15:05).
f Affiche des fractions de secondes. Par exemple, ff affiche des centièmes de secondes, tandis que ffff affiche dix millièmes de secondes. Vous pouvez utiliser jusqu’à sept symboles f dans votre format défini par l’utilisateur. Utilisez %f s’il s’agit du seul caractère de votre format numérique défini par l’utilisateur.
t Utilise l’horloge de 12 heures et affiche un A en majuscules pour une heure avant midi ; affiche un P en majuscules pendant une heure comprise entre midi et 11:59 P.M. Utilisez %t s’il s’agit du seul caractère de votre format numérique défini par l’utilisateur.
tt Pour les paramètres régionaux qui utilisent une horloge de 12 heures, affiche un AM majuscule avec une heure avant midi ; affiche un PM majuscule avec une heure comprise entre midi et 11h59.

Pour les paramètres régionaux qui utilisent une horloge de 24 heures, n’affiche rien.
y Affiche le numéro d’année (0-9) sans zéros non significatifs. Utilisez %y s’il s’agit du seul caractère de 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 non significatif (par exemple, -8). Utilisez %z s’il s’agit du seul caractère de votre format numérique défini par l’utilisateur.
zz Affiche le décalage de fuseau horaire avec un zéro non significatif (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 minimale de temps pour un appareil est déterminée par le fabricant de l’appareil. Si la résolution temporelle de l’appareil est suffisamment grossière, le caractère de format f retourne 0 lors de l’exécution sur cet appareil.

S’applique à

Voir aussi