Strings.Format(Object, String) Метод

Определение

Пространство имен:

Microsoft.VisualBasic

Сборка:

Microsoft.VisualBasic.Core.dll

Исходный код:

Strings.vb

Возвращает строку, отформатированную в соответствии с инструкциями, содержащимися в выражении String формата.

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

Параметры

Expression

Object

Обязательно. Любое допустимое выражение.

Style

String

Необязательный. Допустимое именованное или пользовательское выражение String формата.

Возвращаемое значение

String

Строка отформатирована в соответствии с инструкциями, содержащимися в выражении String формата.

Примеры

В этом примере показано использование функции Format для форматирования значений с помощью форматов String и определяемых пользователем форматов. Для разделителя дат (/), разделителя времени (:) и индикаторов AM/PM (t и tt), фактические отформатированные выходные данные, отображаемые системой, зависят от параметров языкового стандарта, которые использует код. Если время и даты отображаются в среде разработки, используется короткий формат времени и короткий формат даты языкового стандарта кода.

Заметка

Для языковых стандартов, использующих 24-часовые часы, индикаторы AM/PM (t и tt) не отображаются.

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

Комментарии

Метод String.Format также предоставляет аналогичные функциональные возможности.

Если вы форматируете нелокализованную числовую строку, следует использовать определяемый пользователем числовый формат, чтобы обеспечить нужный вид.

Если вы пытаетесь отформатировать число без указания Style, функция Format предоставляет функциональность, аналогичную функции Str, хотя она имеет международное представление. Однако положительные числа, отформатированные как строки с помощью функции Format, не включают в себя начальное пространство, зарезервированное для знака значения; преобразованные с помощью функции Str сохраняют ведущее пространство.

Различные форматы для разных числовых значений

Определяемое пользователем выражение формата для чисел может иметь от одного до трех разделов, разделенных точкой с запятой. Если аргумент Style функции Format содержит один из предопределенных числовых форматов, допускается только один раздел.

Если вы используете	Это результат
Только один раздел	Выражение формата применяется ко всем значениям.
Два раздела	Первый раздел применяется к положительным значениям и нулям; второй применяется к отрицательным значениям.
Три раздела	Первый раздел применяется к положительным значениям, второй применяется к отрицательным значениям, а третий применяется к нулям.

В следующем примере есть два раздела: первый определяет формат положительных значений и нули; Второй раздел определяет формат отрицательных значений. Так как аргумент Style функции Format принимает строку, она заключена кавычками.

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

Если между ними нет запятой, отсутствующий раздел печатается с использованием формата положительного значения. Например, следующий формат отображает положительные и отрицательные значения с помощью формата в первом разделе и отображает Zero, если значение равно нулю.

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

Стандартные числовые форматы

В следующей таблице указаны предопределенные числовые имена форматов. Они могут использоваться в качестве аргумента Style для функции Format:

Имя форматирования	Описание
General Number, Gили g	Отображает число без разделителя тысяч. Например, Format(&H3FA, "g") возвращает 1018.
Currency, Cили c	Отображает число с разделителем тысяч, при необходимости; отображает две цифры справа от десятичного разделителя. Выходные данные основаны на параметрах языкового стандарта системы. Например, Format(1234567, "c") возвращает $1,234,567.00.
Fixed, Fили f	Отображает по крайней мере одну цифру слева и две цифры справа от десятичного разделителя. Например, Format(1234567, "f") возвращает 1234567.00.
Standard, Nили n	Отображает число с разделителем тысяч, по крайней мере одна цифра слева и две цифры справа от десятичного разделителя. Например, Format(1234567, "n") возвращает 1,234,567.00.
Percent	Отображает число, умноженное на 100 с знаком процента (%), добавленным сразу справа; всегда отображает две цифры справа от десятичного разделителя. Например, Format(0.4744, "Percent") возвращает 47.44%.
Pили p	Отображает число с разделителем тысяч, умноженным на 100 с знаком процента (%), добавленным справа и разделенным одним пробелом; всегда отображает две цифры справа от десятичного разделителя. Например, Format(0.80345, "p") возвращает 80.35 %.
Scientific	Использует стандартную научно-нотацию, предоставляя две значимые цифры. Например, Format(1234567, "Scientific") возвращает 1.23E+06.
Eили e	Использует стандартную научное нотацию, предоставляя шесть значимых цифр. Например, Format(1234567, "e") возвращает 1.234567e+006.
Dили d	Отображает число в виде строки, содержащей значение числа в десятичном (базовом формате 10). Этот параметр поддерживается только для целочисленных типов (Byte, Short, Integer, Long) только. Например, Format(&H7F, "d") возвращает 127.
Xили x	Отображает число в виде строки, содержащей значение числа в шестнадцатеричном формате (base 16). Этот параметр поддерживается только для целочисленных типов (Byte, Short, Integer, Long) только. Например, Format(127, "x") возвращает 7f.
Yes/No	Отображает No, если число равно 0; в противном случае отображается Yes. Например, Format(0, "Yes/No") возвращает No.
True/False	Отображает False, если число равно 0; в противном случае отображается True. Например, Format(1, "True/False") возвращает True.
On/Off	Отображает Off, если число равно 0; в противном случае отображается On. Например, Format(1, "On/Off") возвращает On.

Заметки разработчика смарт-устройств

Форматы Yes/No, True/Falseи On/Off не поддерживаются.

числовые форматы User-Defined

В следующей таблице указаны символы, которые можно использовать для создания пользовательских форматов чисел. Их можно использовать для сборки аргумента Style для функции Format:

Характер	Описание
Никакой	Отображает число без форматирования.
(0)	Заполнитель цифр. Отображает цифру или ноль. Если выражение имеет цифру в позиции, где нуль отображается в строке форматирования, отобразите его; в противном случае отображается ноль в этой позиции. Если число имеет меньше цифр, чем нули (на любой стороне десятичного разряда) в выражении форматирования, отображает начальные или конечные нули. Если число имеет больше цифр справа от десятичного разделителя, чем справа от десятичного разделителя справа от десятичного разделителя в выражении форматирования, округляет число до числа десятичных разрядов, так как есть нули. Если число имеет больше цифр слева от десятичного разделителя, чем слева от десятичного разделителя слева от десятичного разделителя в выражении формата, отображает дополнительные цифры без изменения.
(#)	Заполнитель цифр. Отображает цифру или ничего. Если выражение имеет цифру в позиции, где символ # отображается в строке форматирования, отображает его; в противном случае ничего не отображается в этой позиции. Этот символ работает как заполнитель 0 цифр, за исключением того, что начальные и конечные нули не отображаются, если число имеет меньше цифр, чем # символов на обеих сторонах десятичного разделителя в выражении формата.
(.)	Заполнитель десятичных знаков. Заполнитель десятичного разряда определяет, сколько цифр отображается слева и справа от десятичного разделителя. Если выражение формата содержит только # символов слева от этого символа; числа меньше 1 начинаются с десятичного разделителя. Чтобы отобразить начальный ноль, отображаемый дробными числами, используйте ноль в качестве заполнителя первой цифры слева от десятичного разделителя. В некоторых языковых стандартах запятая используется в качестве десятичного разделителя. Фактический символ, используемый в качестве десятичного заполнителя в отформатированных выходных данных, зависит от формата числа, распознанного системой. Таким образом, следует использовать период в качестве десятичного заполнителя в форматах, даже если используется запятая в качестве десятичного заполнителя. Форматированная строка будет отображаться в формате, правильном для языкового стандарта.
(%)	Заполнитель процента. Умножает выражение на 100. Символ процента (%) вставляется в положение, где оно отображается в строке формата.
(,)	Разделитель тысяч. Разделитель тысяч отделяет тысячи от сотен в пределах числа с четырьмя или более местами слева от десятичного разделителя. Стандартное использование разделителя тысяч указывается, если формат содержит разделитель тысяч, окруженный заполнителями цифр (0 или #). Разделитель тысяч сразу слева от десятичного разделителя (независимо от того, задано ли десятичное значение) или как самый правый символ в строке означает "масштабировать число, разделив его на 1000, округляя по мере необходимости". Числа меньше 1000, но больше или равно 500 отображаются как 1, а числа меньше 500 отображаются как 0. Два смежных разделителя тысяч в этом положении масштабируется на 1 миллион и дополнительный фактор 1000 для каждого дополнительного разделителя. Несколько разделителей в любой позиции, отличной от немедленного слева от десятичного разделителя или самой правой позиции в строке, рассматриваются как указание использования разделителя тысяч. В некоторых языковых стандартах период используется в качестве разделителя тысяч. Фактический символ, используемый в качестве разделителя тысяч в отформатированных выходных данных, зависит от формата числа, распознанного системой. Таким образом, следует использовать запятую в качестве разделителя тысяч в форматах, даже если вы находитесь в языковом стандарте, который использует период в качестве разделителя тысяч. Форматированная строка будет отображаться в формате, правильном для языкового стандарта. Например, рассмотрим три следующие строки формата: - "#,0.", который использует разделитель тысяч для форматирования числа 100 миллионов в виде строки "100 000 000". - "#0,.", который использует масштабирование на коэффициенте в одну тысячу для форматирования числа 100 миллионов в виде строки "100000". - "#,0,.", который использует разделитель тысяч и масштабирование на одну тысячу для форматирования числа 100 миллионов в виде строки "100 000".
(:)	Разделитель времени. В некоторых языковых стандартах другие символы могут использоваться для представления разделителя времени. Разделитель времени разделяет часы, минуты и секунды при форматировании значений времени. Фактический символ, используемый в качестве разделителя времени в отформатированных выходных данных, определяется параметрами системы.
(/)	Разделитель дат. В некоторых языковых стандартах другие символы могут использоваться для представления разделителя дат. Разделитель дат отделяет день, месяц и год, когда значения дат форматируются. Фактический символ, используемый в качестве разделителя дат в отформатированных выходных данных, определяется параметрами системы.
(E-``E+``e-``e+)	Научный формат. Если выражение формата содержит по крайней мере один заполнитель цифр (0 или #) слева от E-, E+, e-или e+, число отображается в научном формате и E или e вставляется между числом и его экспонентом. Число заполнителей цифр слева определяет количество цифр в экспоненте. Используйте E- или e-, чтобы поместить знак минуса рядом с отрицательными экспонентами. Используйте E+ или e+, чтобы поместить знак минуса рядом с отрицательными экспонентами и знак плюса рядом с положительными экспонентами. Необходимо также включить заполнители цифр справа от этого символа, чтобы получить правильное форматирование.
- + $ ( )	Литеральные символы. Эти символы отображаются точно так же, как в строке формата. Чтобы отобразить символ, отличный от одного из перечисленных, предшествуйте ему с обратной косой чертой (\) или заключите его в двойные кавычки ("").
(\)	Отображает следующий символ в строке формата. Чтобы отобразить символ с особым значением в качестве литерального символа, предшествуйте ему обратную косую черту (\). Обратная косая черта не отображается. Использование обратной косой черты совпадает с заключением следующего символа в двойные кавычки. Чтобы отобразить обратную косую черту, используйте две обратные косые черты (\\). Примеры символов, которые не могут отображаться в виде литеральных символов, являются символами форматирования даты и времени (a, c, d, h, m, n, p, q, s, t, w, y, /и :), числовые символы форматирования (#, 0, %, E, e, запятая, и символы форматирования строк (@, &, <, >и !).
("``ABC``")	Отображает строку внутри двойных кавычки (" "). Чтобы включить строку в аргумент стиля из кода, необходимо использовать Chr(34), чтобы заключить текст (34 — это код символа для кавычки (")).

Пример устаревшего кода

В следующей таблице содержатся некоторые примеры выражений формата для чисел. (В этих примерах предполагается, что параметр языкового стандарта вашей системы — английский-США) Первый столбец содержит строки форматирования для аргумента Style функции Format; Другие столбцы содержат результирующий результат, если отформатированные данные имеют значение, заданное в заголовках столбцов.

Формат (Style)	Формат "5" в формате	Формат "-5" в формате	Формат "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

Стандартные форматы даты и времени

В следующей таблице указаны предопределенные имена форматов даты и времени. Они могут использоваться в качестве аргумента стиля для функции Format:

Имя форматирования	Описание
General Dateили G	Отображает дату и (или) время. Например, 3/12/2008 11:07:31 AM. Отображение даты определяется текущим значением языка и региональных параметров приложения.
Long Date, Medium Dateили D	Отображает дату в соответствии с форматом длинной даты текущего языка и региональных параметров. Например, Wednesday, March 12, 2008.
Short Dateили d	Отображает дату с использованием короткого формата даты и региональных параметров. Например, 3/12/2008. Символ d отображает день в определяемом пользователем формате даты.
Long Time, Medium Timeили T	Отображает время с использованием длительного формата языка и региональных параметров; обычно включает в себя часы, минуты, секунды. Например, 11:07:31 AM.
Short Time или t	Отображает время, используя короткий формат времени текущего языка и региональных параметров. Например, 11:07 AM. Символ t отображает значения AM или PM для языковых стандартов, использующих 12-часовые часы в пользовательском формате времени.
f	Отображает длинную дату и короткое время в соответствии с форматом текущего языка и региональных параметров. Например, Wednesday, March 12, 2008 11:07 AM.
F	Отображает длинную дату и долгое время в соответствии с форматом текущего языка и региональных параметров. Например, Wednesday, March 12, 2008 11:07:31 AM.
g	Отображает короткую дату и короткое время в соответствии с форматом текущего языка и региональных параметров. Например, 3/12/2008 11:07 AM.
M, m	Отображает месяц и день даты. Например, March 12. Символ M отображает месяц в пользовательском формате даты. Символ m отображает минуты в пользовательском формате времени.
R, r	Форматирует дату в соответствии со свойством RFC1123Pattern. Например, Wed, 12 Mar 2008 11:07:31 GMT. Отформатированная дата не настраивает значение даты и времени. Перед вызовом функции Format необходимо настроить значение даты и времени в GMT.
s	Форматирует дату и время в виде отсортируемых индексов. Например, 2008-03-12T11:07:31. Символ s отображает секунды в пользовательском формате времени.
u	Форматирует дату и время в виде сортируемого индекса GMT. Например, 2008-03-12 11:07:31Z.
U	Форматирует дату и время с длинной датой и временем в формате GMT. Например, Wednesday, March 12, 2008 6:07:31 PM.
Y, y	Форматирует дату в виде года и месяца. Например, March, 2008. Символы Y и y отображают год в пользовательском формате даты.

Дополнительные сведения о текущем языке и региональных параметрах приложения см. в разделе Влияние строк языка и региональных параметров в Visual Basic.

форматы даты и времени User-Defined

В следующей таблице показаны символы, которые можно использовать для создания пользовательских форматов даты и времени. В отличие от более ранних версий Visual Basic, эти символы формата чувствительны к регистру.

Характер	Описание
(:)	Разделитель времени. В некоторых языковых стандартах другие символы могут использоваться для представления разделителя времени. Разделитель времени разделяет часы, минуты и секунды при форматировании значений времени. Фактический символ, используемый в качестве разделителя времени в отформатированных выходных данных, определяется текущим значением языка и региональных параметров приложения.
(/)	Разделитель дат. В некоторых языковых стандартах другие символы могут использоваться для представления разделителя дат. Разделитель дат отделяет день, месяц и год, когда значения дат форматируются. Фактический символ, используемый в качестве разделителя дат в отформатированных выходных данных, определяется текущим языком и региональными параметрами приложения.
(%)	Используется для обозначения того, что следующий символ должен читаться как однобуквенный формат без учета конечных букв. Также используется для указания того, что однобуквенный формат считывается как определяемый пользователем формат. Дополнительные сведения см. в следующих сведениях.
d	Отображает день как число без начального нуля (например, 1). Используйте %d, если это единственный символ в определяемом пользователем числовом формате.
dd	Отображает день как число с начальным нулем (например, 01).
ddd	Отображает день в виде аббревиаций (например, Sun).
dddd	Отображает день в виде полного имени (например, Sunday).
M	Отображает месяц как число без начального нуля (например, январь представлен как 1). Используйте %M, если это единственный символ в определяемом пользователем числовом формате.
MM	Отображает месяц как число с начальным нулем (например, 01/12/01).
MMM	Отображает месяц в виде аббревиаций (например, Jan).
MMMM	Отображает месяц как полное имя месяца (например, January).
gg	Отображает строку периода или эры (например, A.D.).
h	Отображает час в виде числа без начальных нулей, используя 12-часовые часы (например, 1:15:15 PM). Используйте %h, если это единственный символ в определяемом пользователем числовом формате.
hh	Отображает час в виде числа с начальными нулями, используя 12-часовые часы (например, 01:15:15 PM).
H	Отображает час как число без начальных ноль, используя 24-часовые часы (например, 1:15:15). Используйте %H, если это единственный символ в определяемом пользователем числовом формате.
HH	Отображает час в виде числа с начальными нулями, используя 24-часовые часы (например, 01:15:15).
m	Отображает минуту в виде числа без начальных нули (например, 12:1:15). Используйте %m, если это единственный символ в определяемом пользователем числовом формате.
mm	Отображает минуту в виде числа с начальными нулями (например, 12:01:15).
s	Отображает второй в виде числа без начальных нули (например, 12:15:5). Используйте %s, если это единственный символ в определяемом пользователем числовом формате.
ss	Отображает второй в виде числа с начальными нулями (например, 12:15:05).
f	Отображает доли секунд. Например, ff отображает сотые секунды, в то время как ffff отображает десять тысяч секунд. В определяемом пользователем формате можно использовать до семи f символов. Используйте %f, если это единственный символ в определяемом пользователем числовом формате.
t	Использует 12-часовые часы и отображает верхний регистр A в течение любого часа до полудня; отображает верхний регистр P в течение любого часа от полудня до 11:59 вечера. Используйте %t, если это единственный символ в определяемом пользователем числовом формате.
tt	Для языковых стандартов, использующих 12-часовые часы, отображает прописные AM с любым часом до полудня; отображает верхний регистр PM с любым часом от полудня до 11:59 вечера. Для языковых стандартов, использующих 24-часовые часы, не отображается ничего.
y	Отображает число года (0–9) без начальных нулей. Используйте %y, если это единственный символ в определяемом пользователем числовом формате.
yy	Отображает год в двухзначном числовом формате с начальным нулем, если это применимо.
yyy	Отображает год в четырехзначном числовом формате.
yyyy	Отображает год в четырехзначном числовом формате.
z	Отображает смещение часового пояса без начального нуля (например, -8). Используйте %z, если это единственный символ в определяемом пользователем числовом формате.
zz	Отображает смещение часового пояса с начальным нулем (например, -08)
zzz	Отображает полное смещение часового пояса (например, -08:00)

Пример устаревшего кода

Ниже приведены примеры определяемых пользователем форматов даты и времени для December 7, 1958, 8:50 PM, 35 seconds:

Формат	Отображает
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

Заметки разработчика смарт-устройств

Минимальное разрешение времени для устройства определяется производителем устройства. Если разрешение времени для устройства достаточно грубо, символ формата f возвращает значение 0 при запуске на этом устройстве.

См. также раздел

• Format(String, Object)
• Str(Object)
• Сводка