自訂數值格式字串
本文內容
更新： 2008 年 7 月
您所建立且由一個或多個自訂數值格式規範所組成的自訂數值格式字串會定義如何格式化數值資料，自訂數值格式字串相當於定義為不是標準數值格式字串 的任何字串。
下表說明自訂數值的格式規範。如需詳細資訊，請參閱表格之後的注意事項。
0
零值預留位置
如果正在格式化的值有數字位於格式字串中出現 '0' 的位置上，那麼那個數字會複製到結果字串，否則 '0' 會出現在結果字串中。小數點前最左邊 '0' 和小數點後最右邊 '0' 的位置決定要一直在輸出字串中出現的位數範圍。
"00" 規範會造成數值捨入至最接近的小數點前面數值，而其中永遠使用遠離零的捨入方式。例如，使用 "00" 格式化 34.5 將會得到值 35。
下列範例顯示幾個使用包含零預留位置的自訂格式字串格式化的值。
Dim value As Double
value = 123
Console.WriteLine(value.ToString("00000" ))
' Displays 00123
value = 1.2
Console.Writeline(value.ToString("0.00" , CultureInfo.InvariantCulture))
' Displays 1.20
Console.WriteLine(value.ToString("00.00" , CultureInfo.InvariantCulture))
' Displays 01.20
Console.WriteLine(value.ToString("00.00" , _
CultureInfo.CreateSpecificCulture("da-DK" )))
' Displays 01,20
value = .56
Console.WriteLine(value.ToString("0.0" , CultureInfo.InvariantCulture))
' Displays 0.6
value = 1234567890
Console.WriteLine(value.ToString("#,#" , CultureInfo.InvariantCulture))
' Displays 1,234,567,890
Console.WriteLine(value.ToString("#,#" , _
CultureInfo.CreateSpecificCulture("el-GR" )))
' Displays 1.234.567.890
double value;
value = 123 ;
Console.WriteLine (value.ToString ("00000" ));
// Displays 00123
value = 1.2 ;
Console.WriteLine (value.ToString ("0.00" , CultureInfo.InvariantCulture ));
// Displays 1.20
Console.WriteLine (value.ToString ("00.00" , CultureInfo.InvariantCulture ));
// Displays 01.20
Console.WriteLine (value.ToString ("00.00" ,
CultureInfo.CreateSpecificCulture ("da-DK" )));
// Displays 01,20
value = .56 ;
Console.WriteLine (value.ToString ("0.0" , CultureInfo.InvariantCulture ));
// Displays 0.6
value = 1234567890 ;
Console.WriteLine (value.ToString ("#,#" , CultureInfo.InvariantCulture ));
// Displays 1,234,567,890
Console.WriteLine (value.ToString ("#,#" ,
CultureInfo.CreateSpecificCulture ("el-GR" )));
// Displays 1.234.567.890
#
數字預留位置
如果正在格式化的值有數字位於格式字串中出現 '#' 的位置上，那麼那個數字會複製到輸出字串。否則，沒有東西會存放在結果字串中的那個位置。
注意，如果它不是有效位數的話，這個規範不會顯示 '0' 字元，即使 '0' 是字串中的唯一數字也一樣。如果是正在顯示的數值的有效位數，會顯示 '0' 字元。
"##" 格式字串會造成數值捨入至最接近的小數點前面數值，而其中永遠使用遠離零的捨入方式。例如，使用 "##" 格式化 34.5 將會得到值 35。
下列範例顯示幾個使用包含數字預留位置的自訂格式字串格式化的值。
Dim value As Double
value = 1.2
Console.WriteLine(value.ToString("#.##" , CultureInfo.InvariantCulture))
' Displays 1.2
value = 123
Console.WriteLine(value.ToString("#####" ))
' Displays 123
value = 123456
Console.WriteLine(value.ToString("[##-##-##]" ))
' Displays [12-34-56]
value = 1234567890
Console.WriteLine(value.ToString("#" ))
' Displays 1234567890
Console.WriteLine(value.ToString("(###) ###-####" ))
' Displays (123) 456-7890
double value;
value = 1.2 ;
Console.WriteLine (value.ToString ("#.##" , CultureInfo.InvariantCulture ));
// Displays 1.2
value = 123 ;
Console.WriteLine (value.ToString ("#####" ));
// Displays 123
value = 123456 ;
Console.WriteLine (value.ToString ("[##-##-##]" ));
// Displays [12-34-56]
value = 1234567890 ;
Console.WriteLine (value.ToString ("#" ));
// Displays 1234567890
Console.WriteLine (value.ToString ("(###) ###-####" ));
// Displays (123) 456-7890
.
小數點
格式字串中第一個 '.' 字元決定格式化的值中小數分隔符號的位置；任何額外 '.' 字元將被忽略。
結果字串中當做小數分隔符號的實際字元由控制格式的 NumberFormatInfo 物件的 NumberDecimalSeparator 屬性來決定。
下列範例使用小數點格式規範來定義小數點在幾個結果字串中的位置。
Dim value As Double
value = 1.2
Console.Writeline(value.ToString("0.00" , CultureInfo.InvariantCulture))
' Displays 1.20
Console.WriteLine(value.ToString("00.00" , CultureInfo.InvariantCulture))
' Displays 01.20
Console.WriteLine(value.ToString("00.00" , _
CultureInfo.CreateSpecificCulture("da-DK" )))
' Displays 01,20
value = .086
Console.WriteLine(value.ToString("#0.##%" , CultureInfo.InvariantCulture))
' Displays 8.6%
value = 86000
Console.WriteLine(value.ToString("0.###E+0" , CultureInfo.InvariantCulture))
' Displays 8.6E+4
double value;
value = 1.2 ;
Console.WriteLine (value.ToString ("0.00" , CultureInfo.InvariantCulture ));
// Displays 1.20
Console.WriteLine (value.ToString ("00.00" , CultureInfo.InvariantCulture ));
// Displays 01.20
Console.WriteLine (value.ToString ("00.00" ,
CultureInfo.CreateSpecificCulture ("da-DK" )));
// Displays 01,20
value = .086 ;
Console.WriteLine (value.ToString ("#0.##%" , CultureInfo.InvariantCulture ));
// Displays 8.6%
value = 86000 ;
Console.WriteLine (value.ToString ("0.###E+0" , CultureInfo.InvariantCulture ));
// Displays 8.6E+4
,
千位分隔符號和數值縮放
',' 字元可當做千位分隔符號規範和數值縮放規範使用。
千位分隔符號規範：如果在兩個採用數字之整數格式的數字替代符號 (Placeholder) (0 或 #) 之間指定一個或多個 ',' 字元，則會在每個數字群組輸出的整數部分之間插入群組分隔符號字元。
目前 NumberFormatInfo 物件的 NumberGroupSeparator 和 NumberGroupSizes 屬性會判斷當做數字群組分隔符號使用的字元，以及每個數字群組的大小。例如，如果使用字串 "#,#" 和不變的文化特性來格式化數字 1000，則輸出為 "1,000"。
數值縮放規範：如果在緊接著明確或隱含小數點的左側指定了一個或多個 ',' 字元，則每次發生數值縮放規範時，要進行格式化的數字會除以 1000。例如，如果使用字串 "0,," 來格式化數字 1 億，則其輸出為 "100"。
您可以在相同的格式字串內使用千位分隔符號和數值縮放規範。例如，如果使用字串 "#,0,," 和不變的文化特性來格式化數字 10 億，則輸出為 "1,000"。
下列範例示範使用逗點做為千位分隔符號。
Dim value As Double = 1234567890
Console.WriteLine(value.ToString("#,#" , CultureInfo.InvariantCulture))
' Displays 1,234,567,890
Console.WriteLine(value.ToString("#,##0,," , CultureInfo.InvariantCulture))
' Displays 1,235
double value = 1234567890 ;
Console.WriteLine (value.ToString ("#,#" , CultureInfo.InvariantCulture ));
// Displays 1,234,567,890
Console.WriteLine (value.ToString ("#,##0,," , CultureInfo.InvariantCulture ));
// Displays 1,235
下列範例示範使用逗點做為數值縮放的規範。
Dim value As Double = 1234567890
Console.WriteLine(value.ToString("#,," , CultureInfo.InvariantCulture))
' Displays 1235
Console.WriteLine(value.ToString("#,,," , CultureInfo.InvariantCulture))
' Displays 1
Console.WriteLine(value.ToString("#,##0,," , CultureInfo.InvariantCulture))
' Displays 1,235
double value = 1234567890 ;
Console.WriteLine (value.ToString ("#,," , CultureInfo.InvariantCulture ));
// Displays 1235
Console.WriteLine (value.ToString ("#,,," , CultureInfo.InvariantCulture ));
// Displays 1
Console.WriteLine (value.ToString ("#,##0,," , CultureInfo.InvariantCulture ));
// Displays 1,235
%
百分比預留位置
格式字串中 '%' 字元的出現會使數值在格式化之前被乘以 100。適當符號會在格式字串中 '%' 出現的位置上插入數值本身。使用的百分比字元取決於目前的 NumberFormatInfo 類別。
下列範例會定義幾個包含百分比預留位置的自訂格式字串。
Dim value As Double = .086
Console.WriteLine(value.ToString("#0.##%" , CultureInfo.InvariantCulture))
' Displays 8.6%
double value = .086 ;
Console.WriteLine (value.ToString ("#0.##%" , CultureInfo.InvariantCulture ));
// Displays 8.6%
‰
千分之一符號預留位置
格式字串中若出現 '‰' 字元 (\u2030)，會使數值在格式化之前先乘以 1000。適當的千分之一符號應插入傳回的字串中，位於格式字串中 '‰' 符號出現的位置。使用的千分之一符號字元是由提供文化特性特定格式資訊之物件的 NumberFormatInfo.PerMilleSymbol 屬性定義的。
下列範例會定義一個包含千分之一符號預留位置的自訂格式字串。
Dim value As Double = .00354
Dim perMilleFmt As String = "#0.## " & ChrW(&h2030)
Console.WriteLine(value.ToString(perMilleFmt, CultureInfo.InvariantCulture))
' Displays 3.54 ‰
double value = .00354 ;
string perMilleFmt = "#0.## " + '\u2030';
Console.WriteLine (value.ToString (perMilleFmt, CultureInfo.InvariantCulture ));
// Displays 3.54‰
E0
E+0
E-0
e0
e+0
e-0
科學標記法
如果字串 'E'、'E+'、'E-'、'e'、'e+' 或 'e-' 的任何一個出現在格式字串中，並有至少一個 '0' 字元緊接其後，那麼數值將使用科學標記法，以 'E' 或 'e' 插入數字和指數之間來格式化。接在科學標記法指標之後的 '0' 字元數目將決定要輸出的指數的最少位數。'E+' 和 'e+' 格式指示正負號字元 (正號或負號) 應該一直在指數前面。"E"、"E-"、"e" 或 "e-" 格式指示正負號字元應該只能放在負數指數前面。
下列範例使用科學記號規範來格式化幾個數值。
Dim value As Double = 86000
Console.WriteLine(value.ToString("0.###E+0" , CultureInfo.InvariantCulture))
' Displays 8.6E+4
Console.WriteLine(value.ToString("0.###E+000" , CultureInfo.InvariantCulture))
' Displays 8.6E+004
Console.WriteLine(value.ToString("0.###E-000" , CultureInfo.InvariantCulture))
' Displays 8.6E004
double value = 86000 ;
Console.WriteLine (value.ToString ("0.###E+0" , CultureInfo.InvariantCulture ));
// Displays 8.6E+4
Console.WriteLine (value.ToString ("0.###E+000" , CultureInfo.InvariantCulture ));
// Displays 8.6E+004
Console.WriteLine (value.ToString ("0.###E-000" , CultureInfo.InvariantCulture ));
// Displays 8.6E004
\
逸出字元
在 C# 和 C++ 中，反斜線字元會造成格式字串中的下一個字元被解譯為逸出序列 (Escape Sequence)。它使用於傳統格式化序列，例如 "\n" (新行)。
某些語言中，逸出字元本身當做常值 (Literal) 時，必須在前面加上逸出字元。否則，編譯器會解譯字元為逸出序列。使用字串 "\\" 來顯示 '\'。
請注意，Visual Basic 中不支援這個逸出字元，不過，ControlChars 提供相同功能。
'ABC'
"ABC"
常值字串
含括在單引號或雙引號中的字元會複製到結果字串，並且不影響格式。
;
區段分隔符號
';' 字元被用來在格式字串中為正數、負數和零值分隔區段。如果自訂格式字串中有兩個區段，最左邊的區段會定義正數和零的格式，而最右邊的區段則定義負數的格式。如果有三個區段，最左邊的區段會定義正數的格式，中間區段定義負數的格式，而最右邊的區段則定義零的格式。
下列範例使用區段分隔符號的格式規範，以不同方式格式化正數、負數和零。
Dim posValue As Double = 1234
Dim negValue As Double = -1234
Dim fmt As String = "##;(##)"
Console.WriteLine(posValue.ToString(fmt)) ' Displays 1234
Console.WriteLine(negValue.ToString(fmt)) ' Displays (1234)
double posValue = 1234 ;
double negValue = -1234 ;
string fmt = "##;(##)" ;
Console.WriteLine (posValue.ToString (fmt)); // Displays 1234
Console.WriteLine (negValue.ToString (fmt)); // Displays (1234)
其他
所有其他字元
其他任何字元都會複製到結果字串，並且不影響格式。
注意
無限浮點數和 NaN
請注意，不管格式字串為何，如果 Single 或 Double 浮點型別為正無限大、負無限大或不是數字 (NaN)，則格式化後的字串分別會是由目前適用之 NumberFormatInfo 物件所指定的 PositiveInfinitySymbol 、NegativeInfinitySymbol 或 NaNSymbol 屬性。
控制台設定值
[控制台] 中 [地區及語言選項] 項目的設定會影響格式化作業所產生的結果字串。這些設定是用來初始化與目前執行緒文化特性相關聯的 NumberFormatInfo 物件，而且目前的執行緒文化特性會提供用來管理格式的值。使用不同設定的電腦將會產生不同的結果字串。
四捨五入和定點格式字串
請注意，如果是定點格式字串 (即不含科學標記法格式字元的格式字串)，則數值會四捨五入成與小數點右邊之數字替代符號一樣多的小數位數。如果格式字串不包含小數點，數值四捨五入至最接近的整數。如果數值有比小數點左邊的數字預留位置還要多的位數，額外位數會緊接第一個數字預留位置之前複製到輸出字串。
區段分隔符號和格式化的條件
各種格式可以根據值是否為正數、負數或零來套用於字串。若要產生這個行為，自訂格式字串可以包含多達三個以分號分隔的區段，下表將說明這些區段。
一個區段
此格式字串適用於所有的值。
兩個區段
第一個區段適用於正數值及零值，第二個區段適用於負數值。
如果要格式化的數值為負數，但依照第二區段的格式四捨五入之後成為零，那麼產生的零會依照第一區段來格式化。
三個區段
第一個區段適用於正數值，第二個區段適用於負數值，而第三個區段則適用於零值。
第二個區段可留白 (分號之間沒有任何內容)，此時第一個區段將套用到所有非零值。
如果要格式化的數值為非零值，但依照第一或第二區段的格式四捨五入之後成為零，那麼產生的零會依照第三區段來格式化。
區段分隔符號會在最終值已格式化時，忽略任何事先存在而與數值相關的格式。例如，負數值在使用區段分隔符號時永遠不以負號來顯示。如果您想要最終的格式化值具有負號，您應該明確包含負號做為自訂格式規範的一部分。
下列程式碼片段將說明如何使用區段分隔符號來產生格式化的字串。
Dim MyPos As Double = 19.95
Dim MyNeg As Double = -19.95
Dim MyZero As Double = 0
' In the U.S. English culture, MyString has the value: $19.95.
Dim MyString As String = MyPos.ToString("$#,##0.00;($#,##0.00);Zero")
' In the U.S. English culture, MyString has the value: ($19.95).
' The minus sign is omitted by default.
MyString = MyNeg.ToString("$#,##0.00;($#,##0.00);Zero")
' In the U.S. English culture, MyString has the value: Zero.
MyString = MyZero.ToString("$#,##0.00;($#,##0.00);Zero")
double MyPos = 19.95, MyNeg = -19.95, MyZero = 0.0;
// In the U.S. English culture, MyString has the value: $19.95.
string MyString = MyPos.ToString("$#,##0.00;($#,##0.00);Zero");
// In the U.S. English culture, MyString has the value: ($19.95).
// The minus sign is omitted by default.
MyString = MyNeg.ToString("$#,##0.00;($#,##0.00);Zero");
// In the U.S. English culture, MyString has the value: Zero.
MyString = MyZero.ToString("$#,##0.00;($#,##0.00);Zero");
兩個自訂格式範例
下列程式碼片段將示範自訂數值的格式化。在這兩個範例中，自訂格式字串內的數字替代符號 (#) 會顯示數值資料，並將所有其他的字元複製到輸出中。
Dim myDouble As Double = 1234567890
Dim myString As String = myDouble.ToString( "(###) ### - ####" )
' The value of myString is "(123) 456 – 7890".
Dim MyInt As Integer = 42
MyString = MyInt.ToString( "My Number = #" )
' In the U.S. English culture, MyString has the value:
' "My Number = 42".
Double myDouble = 1234567890;
String myString = myDouble.ToString( "(###) ### - ####" );
// The value of myString is "(123) 456 – 7890".
int MyInt = 42;
MyString = MyInt.ToString( "My Number = #" );
// In the U.S. English culture, MyString has the value:
// "My Number = 42".
請參閱
概念
數值格式字串
標準數值格式字串
參考
NumberFormatInfo
其他資源
格式化型別
變更記錄
2008 年 7 月
加入千分之一符號預留位置。
內容 Bug 修正。