Pemformatan komposit

Fitur pemformatan komposit .NET mengambil daftar objek dan string format komposit sebagai input. String format komposit terdiri dari teks tetap yang diindeks dengan tempat penampung terindeks, yang disebut item format. Item format ini sesuai dengan objek dalam daftar. Operasi pemformatan menghasilkan string hasil yang terdiri dari teks tetap asli yang diintermiks dengan representasi string objek dalam daftar.

Penting

Alih-alih menggunakan string format komposit, Anda dapat menggunakan string terinterpolasi jika bahasa dan versinya yang Anda gunakan mendukungnya. String terinterpolasi berisi ekspresi terinterpolasi. Setiap ekspresi terinterpolasi diselesaikan dengan nilai ekspresi dan disertakan dalam string hasil saat string ditetapkan. Untuk informasi selengkapnya, lihat Interpolasi string (Referensi C#) dan String terinterpolasi (Referensi Visual Basic).

Metode berikut mendukung fitur pemformatan komposit:

• String.Format, yang mengembalikan string hasil yang diformat.
• StringBuilder.AppendFormat, yang menambahkan string hasil yang diformat ke objek StringBuilder.
• Beberapa kelebihan beban metode Console.WriteLine, yang menampilkan string hasil yang diformat ke konsol.
• Beberapa kelebihan beban metode TextWriter.WriteLine, yang menampilkan string hasil yang diformat ke aliran atau file. Kelas yang berasal dari TextWriter, seperti StreamWriter dan HtmlTextWriter, juga berbagi fungsionalitas ini.
• Debug.WriteLine(String, Object[]), yang menghasilkan pesan yang diformat untuk melacak pendengar.
• Metode Trace.TraceError(String, Object[]), Trace.TraceInformation(String, Object[]), dan Trace.TraceWarning(String, Object[]) yang menghasilkan pesan yang diformat untuk melacak pendengar.
• Metode TraceSource.TraceInformation(String, Object[]), yang menulis metode informasi untuk melacak pendengar.

String format komposit

String format komposit dan daftar objek digunakan sebagai argumen metode yang mendukung fitur pemformatan komposit. String format komposit terdiri dari nol atau beberapa eksekusi teks tetap yang diintermiks dengan satu atau beberapa item format. Teks tetap adalah string apa pun yang Anda pilih, dan setiap item format sesuai dengan objek atau struktur kotak dalam daftar. Representasi string dari setiap objek menggantikan item format yang sesuai.

Pertimbangkan fragmen kode berikut Format :

string.Format("Name = {0}, hours = {1:hh}", "Fred", DateTime.Now);

String.Format("Name = {0}, hours = {1:hh}", "Fred", DateTime.Now)

Teks tetap adalah Name = dan , hours = . Item format adalah {0}, yang indeksnya 0 sesuai dengan objek name, dan {1:hh}, yang indeksnya 1 sesuai dengan objek DateTime.Now.

Format sintaks item

Setiap item format mengambil bentuk berikut dan terdiri dari komponen berikut:

{index[,alignment][:formatString]}

Kurung kurawal yang cocok ({ dan }) diperlukan.

Komponen indeks

Komponen indeks wajib, yang juga disebut penentu parameter, adalah angka mulai dari 0 yang mengidentifikasi item yang sesuai dalam daftar objek. Artinya, item format yang penentu parameternya memformat 0 objek pertama dalam daftar. Item format yang penentu parameternya memformat 1 objek kedua dalam daftar, dan sebagainya. Contoh berikut mencakup empat penentu parameter, bernomor nol hingga tiga, untuk mewakili angka utama kurang dari 10:

string primes = string.Format("Four prime numbers: {0}, {1}, {2}, {3}",
                              2, 3, 5, 7);
Console.WriteLine(primes);

// The example displays the following output:
//      Four prime numbers: 2, 3, 5, 7

Dim primes As String = String.Format("Four prime numbers: {0}, {1}, {2}, {3}",
                                      2, 3, 5, 7)
Console.WriteLine(primes)

'The example displays the following output
'     Four prime numbers 2, 3, 5, 7

Beberapa item format dapat merujuk ke elemen yang sama dalam daftar objek dengan menentukan penentu parameter yang sama. Misalnya, Anda dapat memformat nilai numerik yang sama dalam format heksadesimal, ilmiah, dan angka dengan menentukan string format komposit seperti , seperti "0x{0:X} {0:E} {0:N}"contoh berikut menunjukkan:

string multiple = string.Format("0x{0:X} {0:E} {0:N}",
                                Int64.MaxValue);
Console.WriteLine(multiple);

// The example displays the following output:
//      0x7FFFFFFFFFFFFFFF 9.223372E+018 9,223,372,036,854,775,807.00

Dim multiple As String = String.Format("0x{0:X} {0:E} {0:N}",
                                       Int64.MaxValue)
Console.WriteLine(multiple)

'The example displays the following output
'     0x7FFFFFFFFFFFFFFF 9.223372E+018 9,223,372,036,854,775,807.00

Setiap item format dapat merujuk ke objek apa pun dalam daftar. Misalnya, jika ada tiga objek, Anda dapat memformat objek kedua, pertama, dan ketiga dengan menentukan string format komposit seperti {1} {0} {2}. Objek yang tidak dirujuk oleh item format diabaikan. FormatException dilemparkan pada durasi jika penentu parameter menunjuk item di luar batas daftar objek.

Komponen perataan

Komponen perataan opsional adalah bilangan bulat bertanda yang menunjukkan lebar bidang yang diformat pilihan. Jika nilai perataan kurang dari panjang string yang diformat, perataan diabaikan, dan panjang string yang diformat digunakan sebagai lebar bidang. Data yang diformat di bidang rata kanan jika perataan positif dan rata kiri jika perataan negatif. Jika padding diperlukan, ruang kosong digunakan. Koma diperlukan jika perataan ditentukan.

Contoh berikut mendefinisikan dua array, satu yang berisi nama karyawan dan yang lain yang berisi jam kerja mereka selama dua minggu. String format komposit menyelaraskan nama dalam bidang 20 karakter dan meratakan kanan jamnya dalam bidang 5 karakter. String format standar "N1" memformat jam dengan satu digit pecahan.

string[] names = { "Adam", "Bridgette", "Carla", "Daniel",
                   "Ebenezer", "Francine", "George" };
decimal[] hours = { 40, 6.667m, 40.39m, 82,
                    40.333m, 80, 16.75m };

Console.WriteLine("{0,-20} {1,5}\n", "Name", "Hours");

for (int counter = 0; counter < names.Length; counter++)
    Console.WriteLine("{0,-20} {1,5:N1}", names[counter], hours[counter]);

// The example displays the following output:
//      Name                 Hours
//      
//      Adam                  40.0
//      Bridgette              6.7
//      Carla                 40.4
//      Daniel                82.0
//      Ebenezer              40.3
//      Francine              80.0
//      George                16.8

Dim names As String() = {"Adam", "Bridgette", "Carla", "Daniel",
                         "Ebenezer", "Francine", "George"}

Dim hours As Decimal() = {40, 6.667D, 40.39D, 82,
                          40.333D, 80, 16.75D}

Console.WriteLine("{0,-20} {1,5}\n", "Name", "Hours")

For counter = 0 To names.Length - 1
    Console.WriteLine("{0,-20} {1,5:N1}", names(counter), hours(counter))
Next

'The example displays the following output
'     Name                 Hours
'     
'     Adam                  40.0
'     Bridgette              6.7
'     Carla                 40.4
'     Daniel                82.0
'     Ebenezer              40.3
'     Francine              80.0
'     George                16.8

Memformat komponen string

Komponen formatString opsional adalah string format yang sesuai untuk jenis objek yang sedang diformat. Anda dapat menentukan:

• String format numerik standar atau kustom jika objek yang sesuai adalah nilai numerik.
• String format tanggal dan waktu standar atau kustom jika objek yang sesuai adalah DateTime objek.
• String format enumerasi jika objek yang sesuai adalah nilai enumerasi.

Jika formatString tidak ditentukan, penentu format umum ("G") untuk jenis numerik, tanggal dan waktu, atau enumerasi digunakan. Titik dua diperlukan jika formatString ditentukan.

Tabel berikut ini mencantumkan jenis atau kategori jenis di pustaka kelas .NET yang mendukung serangkaian string format yang telah ditentukan sebelumnya, dan menyediakan tautan ke artikel yang mencantumkan string format yang didukung. Pemformatan string adalah mekanisme yang dapat diperluas yang memungkinkan untuk menentukan string format baru untuk semua jenis yang ada dan untuk menentukan serangkaian string format yang didukung oleh jenis yang ditentukan aplikasi.

Untuk informasi selengkapnya, lihat IFormattable artikel antarmuka dan ICustomFormatter .

Jenis atau kategori jenis	Lihat
Jenis tanggal dan waktu (DateTime, DateTimeOffset)	String Format Tanggal dan Waktu Standar String Format Tanggal dan Waktu Kustom
Jenis enumerasi (semua jenis berasal dari System.Enum)	String format enumerasi
Jenis numerik (BigInteger, Byte, Decimal, Double, Int16, Int32, Int64, SByte, Single, UInt16, UInt32, UInt64)	String Format Numerik Standar String Format Numerik Kustom
Guid	Guid.ToString(String)
TimeSpan	String format TimeSpan kustom String format TimeSpan kustom

Kurung kurawal pelepasan

Kurung kurawal buka dan tutup ditafsirkan sebagai memulai dan mengakhiri item format. Untuk menampilkan kurung kurawal pembuka harfiah atau kurung kurawal penutup, Anda harus menggunakan urutan escape. Tentukan dua kurung kurawal pembuka ({{) dalam teks tetap untuk menampilkan satu kurung kurawal buka ({), atau dua kurung kurawal penutup (}}) untuk menampilkan satu kurung kurawal penutup (}).

Kurung kurawal yang lolos dengan item format diurai secara berbeda antara .NET dan .NET Framework.

.NET

Kurung kurawal dapat diloloskan di sekitar item format. Misalnya, pertimbangkan item {{{0:D}}}format , yang dimaksudkan untuk menampilkan kurung kurawal pembuka, nilai numerik yang diformat sebagai angka desimal, dan kurung kurawal penutup. Item format ditafsirkan dengan cara berikut:

1. Dua kurung kurawal pembuka pertama ({{) lolos dan menghasilkan satu kurung kurawal pembuka.
2. Tiga karakter berikutnya ({0:) ditafsirkan sebagai awal item format.
3. Karakter berikutnya (D) ditafsirkan sebagai penentu format numerik standar desimal.
4. Kurung kurawal berikutnya (}) ditafsirkan sebagai akhir item format.
5. Dua kurung kurawal penutup terakhir lolos dan menghasilkan satu kurung kurawal penutup.
6. Hasil akhir yang ditampilkan adalah string harfiah, {6324}.

int value = 6324;
string output = string.Format("{{{0:D}}}", value);

Console.WriteLine(output);
// The example displays the following output:
//       {6324}

Dim value As Integer = 6324
Dim output As String = String.Format("{{{0:D}}}", value)

Console.WriteLine(output)

'The example displays the following output
'      {6324}

.NET Framework

Kurung kurawal dalam item format ditafsirkan secara berurutan dalam urutan yang ditemui. Menginterpretasikan kurung kurawal berlapis tidak didukung.

Cara kurung kurawal yang diteruskan ditafsirkan dapat menyebabkan hasil yang tidak terduga. Misalnya, pertimbangkan item {{{0:D}}}format , yang dimaksudkan untuk menampilkan kurung kurawal pembuka, nilai numerik yang diformat sebagai angka desimal, dan kurung kurawal penutup. Namun, item format ditafsirkan dengan cara berikut:

1. Dua kurung kurawal pembuka pertama ({{) lolos dan menghasilkan satu kurung kurawal pembuka.
2. Tiga karakter berikutnya ({0:) ditafsirkan sebagai awal item format.
3. Karakter berikutnya (D) akan ditafsirkan sebagai penentu format numerik standar desimal, tetapi dua kurung kurawal yang lolos berikutnya (}}) menghasilkan satu kurung kurawal. Karena string yang dihasilkan (D}) bukan penentu format numerik standar, string yang dihasilkan ditafsirkan sebagai string format kustom yang berarti menampilkan string D}literal .
4. Kurung kurawal terakhir (}) ditafsirkan sebagai akhir item format.
5. Hasil akhir yang ditampilkan adalah string harfiah, {D}. Nilai numerik yang akan diformat tidak ditampilkan.

int value = 6324;
string output = string.Format("{{{0:D}}}",
                              value);
Console.WriteLine(output);

// The example displays the following output:
//       {D}

Dim value As Integer = 6324
Dim output As String = String.Format("{{{0:D}}}",
                                     value)
Console.WriteLine(output)

'The example displays the following output:
'      {D}

Salah satu cara untuk menulis kode Anda untuk menghindari salah menafsirkan kurung kurawal yang lolos dan memformat item adalah dengan memformat kurung kurawal dan memformat item secara terpisah. Artinya, dalam operasi format pertama, menampilkan kurung kurawal pembuka harfiah. Dalam operasi berikutnya, tampilkan hasil item format, dan dalam operasi akhir, tampilkan kurung kurawal penutup harfiah. Contoh berikut mengilustrasikan pendekatan ini:

int value = 6324;
string output = string.Format("{0}{1:D}{2}",
                             "{", value, "}");
Console.WriteLine(output);

// The example displays the following output:
//       {6324}

Dim value As Integer = 6324
Dim output As String = String.Format("{0}{1:D}{2}",
                                     "{", value, "}")
Console.WriteLine(output)

'The example displays the following output:
'      {6324}

Urutan pemrosesan

Jika panggilan ke metode pemformatan komposit menyertakan IFormatProvider argumen yang nilainya tidak null, runtime memanggil metodenya IFormatProvider.GetFormat untuk meminta ICustomFormatter implementasi. Jika metode dapat mengembalikan ICustomFormatter implementasi, metode tersebut di-cache selama panggilan metode pemformatan komposit.

Setiap nilai dalam daftar parameter yang sesuai dengan item format dikonversi menjadi string sebagai berikut:

1. Jika nilai yang akan diformat adalah null, string String.Empty kosong dikembalikan.

2. ICustomFormatter Jika implementasi tersedia, eksekusi memanggil metode Format. Runtime meneruskan nilai item formatString format (atau null jika tidak ada) ke metode . Runtime juga meneruskan IFormatProvider implementasi ke metode . Jika panggilan ke ICustomFormatter.Format metode mengembalikan null, eksekusi berlanjut ke langkah berikutnya. Jika tidak, hasil ICustomFormatter.Format panggilan dikembalikan.

3. Jika nilai mengimplementasikan IFormattable antarmuka, metode antarmuka ToString(String, IFormatProvider) akan dipanggil. Jika ada dalam item format, nilai formatString diteruskan ke metode . Jika tidak, null diteruskan. Argumen IFormatProvider ditentukan sebagai berikut:

   • Untuk nilai numerik, jika metode pemformatan komposit dengan argumen non-null IFormatProvider dipanggil, runtime meminta NumberFormatInfo objek dari metodenya IFormatProvider.GetFormat . Jika tidak dapat menyediakannya, jika nilai argumen adalah null, atau jika metode pemformatan komposit tidak memiliki IFormatProvider parameter, NumberFormatInfo objek untuk budaya saat ini digunakan.

   • Untuk nilai tanggal dan waktu, jika metode pemformatan komposit dengan argumen non-null IFormatProvider dipanggil, runtime meminta DateTimeFormatInfo objek dari metodenya IFormatProvider.GetFormat . Dalam situasi berikut, DateTimeFormatInfo objek untuk budaya saat ini digunakan sebagai gantinya:

     • Metode IFormatProvider.GetFormat ini tidak dapat menyediakan DateTimeFormatInfo objek.
     • Nilai argumen adalah null.
     • Metode pemformatan komposit tidak memiliki IFormatProvider parameter.

   • Untuk objek jenis lain, jika metode pemformatan komposit dipanggil dengan IFormatProvider argumen, nilainya diteruskan langsung ke IFormattable.ToString implementasi. Jika tidak, null diteruskan ke IFormattable.ToString implementasi.

4. Metode tanpa ToString parameter jenis, yang mengambil Object.ToString() alih atau mewarisi perilaku kelas dasarnya, dipanggil. Dalam hal ini, string format yang ditentukan oleh formatString komponen dalam item format, jika ada, diabaikan.

Perataan diterapkan setelah langkah-langkah sebelumnya dilakukan.

Contoh kode

Contoh berikut menunjukkan satu string yang dibuat menggunakan pemformatan komposit dan string lain yang dibuat menggunakan metode objek ToString . Kedua jenis pemformatan menghasilkan hasil yang setara.

string formatString1 = string.Format("{0:dddd MMMM}", DateTime.Now);
string formatString2 = DateTime.Now.ToString("dddd MMMM");

Dim formatString1 As String = String.Format("{0:dddd MMMM}", DateTime.Now)
Dim formatString2 As String = DateTime.Now.ToString("dddd MMMM")

Dengan asumsi bahwa hari ini adalah hari Kamis pada bulan Mei, nilai kedua string dalam contoh sebelumnya ada Thursday May di budaya Inggris AS.

Console.WriteLine mengekspos fungsionalitas yang sama dengan String.Format. Satu-satunya perbedaan antara kedua metode adalah mengembalikan hasilnya sebagai string, sementara String.Format menulis hasilnya ke aliran output yang Console.WriteLine terkait dengan Console objek . Contoh berikut menggunakan Console.WriteLine metode untuk memformat nilai myNumber ke nilai mata uang:

int myNumber = 100;
Console.WriteLine("{0:C}", myNumber);

// The example displays the following output
// if en-US is the current culture:
//        $100.00

Dim myNumber As Integer = 100
Console.WriteLine("{0:C}", myNumber)

'The example displays the following output
'if en-US Is the current culture:
'       $100.00

Contoh berikut menunjukkan pemformatan beberapa objek, termasuk memformat satu objek dengan dua cara berbeda:

string myName = "Fred";
Console.WriteLine(string.Format("Name = {0}, hours = {1:hh}, minutes = {1:mm}",
                                myName, DateTime.Now));

// Depending on the current time, the example displays output like the following:
//        Name = Fred, hours = 11, minutes = 30

Dim myName As String = "Fred"
Console.WriteLine(String.Format("Name = {0}, hours = {1:hh}, minutes = {1:mm}",
                                myName, DateTime.Now))
'Depending on the current time, the example displays output Like the following:
'       Name = Fred, hours = 11, minutes = 30

Contoh berikut menunjukkan penggunaan perataan dalam pemformatan. Argumen yang diformat ditempatkan di antara karakter bilah vertikal (|) untuk menyoroti perataan yang dihasilkan.

string firstName = "Fred";
string lastName = "Opals";
int myNumber = 100;

string formatFirstName = string.Format("First Name = |{0,10}|", firstName);
string formatLastName = string.Format("Last Name =  |{0,10}|", lastName);
string formatPrice = string.Format("Price =      |{0,10:C}|", myNumber);
Console.WriteLine(formatFirstName);
Console.WriteLine(formatLastName);
Console.WriteLine(formatPrice);
Console.WriteLine();

formatFirstName = string.Format("First Name = |{0,-10}|", firstName);
formatLastName = string.Format("Last Name =  |{0,-10}|", lastName);
formatPrice = string.Format("Price =      |{0,-10:C}|", myNumber);
Console.WriteLine(formatFirstName);
Console.WriteLine(formatLastName);
Console.WriteLine(formatPrice);

// The example displays the following output on a system whose current
// culture is en-US:
//     First Name = |      Fred|
//     Last Name =  |     Opals|
//     Price =      |   $100.00|
//
//     First Name = |Fred      |
//     Last Name =  |Opals     |
//     Price =      |$100.00   |

Dim firstName As String = "Fred"
Dim lastName As String = "Opals"
Dim myNumber As Integer = 100

Dim formatFirstName As String = String.Format("First Name = |{0,10}|", firstName)
Dim formatLastName As String = String.Format("Last Name =  |{0,10}|", lastName)
Dim formatPrice As String = String.Format("Price =      |{0,10:C}|", myNumber)
Console.WriteLine(formatFirstName)
Console.WriteLine(formatLastName)
Console.WriteLine(formatPrice)
Console.WriteLine()

formatFirstName = String.Format("First Name = |{0,-10}|", firstName)
formatLastName = String.Format("Last Name =  |{0,-10}|", lastName)
formatPrice = String.Format("Price =      |{0,-10:C}|", myNumber)
Console.WriteLine(formatFirstName)
Console.WriteLine(formatLastName)
Console.WriteLine(formatPrice)

'The example displays the following output on a system whose current
'culture Is en-US:
'    First Name = |      Fred|
'    Last Name =  |     Opals|
'    Price =      |   $100.00|
'
'    First Name = |Fred      |
'    Last Name =  |Opals     |
'    Price =      |$100.00   |

Lihat juga

• WriteLine
• String.Format
• Interpolasi string (C#)
• Interpolasi string (Visual Basic)
• Jenis Pemformatan
• String Format Numerik Standar
• String Format Numerik Kustom
• String Format Tanggal dan Waktu Standar
• String Format Tanggal dan Waktu Kustom
• String format TimeSpan kustom
• String format TimeSpan kustom
• String format enumerasi