Bagikan melalui

Pemformatan komposit

Fitur pemformatan komposit .NET mengambil daftar objek dan string format komposit sebagai input. String format komposit terdiri dari teks tetap yang bercampur dengan placeholder yang diindeks, 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 dievaluasi dengan nilai ekspresi dan disertakan dalam string hasil ketika string tersebut diberikan. Untuk informasi selengkapnya, lihat interpolasi String (Referensi C#) dan string terinterpolasi (Referensi Dasar Visual).

Metode berikut mendukung fitur pemformatan komposit:

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 lebih potongan teks tetap yang dicampur 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 Format berikut:

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

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

Teks tetap Name = dan , hours = . Item format adalah {0}, yang indeksnya 0 sesuai dengan string literal "Fred", dan {1:hh}, yang indeks 1 sesuai dengan nilai DateTime.Now.

Sintaksis item format

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

{index[,width][:formatString]}

Kurung kurawal yang serasi ({ dan }) harus ada.

Komponen indeks

Komponen wajib index , yang juga disebut penentu parameter, adalah angka mulai dari 0 yang mengidentifikasi item yang sesuai dalam daftar objek. Artinya, item format yang penentu parameternya 0 memformat objek pertama dalam daftar. Item format yang penentu parameternya 1 memformat 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 "0x{0:X} {0:E} {0:N}", seperti yang ditunjukkan contoh berikut:

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 runtime jika penentu parameter menunjuk item di luar batas daftar objek.

Komponen Lebar

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

Contoh berikut mendefinisikan dua array, satu yang berisi nama karyawan dan yang lain yang berisi jam kerja mereka selama dua minggu. Format string komposit meratakan nama secara rata kiri dalam bidang 20 karakter dan jam kerja mereka secara rata kanan 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 opsional formatString 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 objek DateTime.
  • String format untuk enumerasi dapat digunakan 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 artikel antarmuka IFormattable dan ICustomFormatter.

Tipe 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

Format Numerik Kustom
Guid Guid.ToString(String)
TimeSpan String Format Rentang Waktu Standar

String Format Rentang Waktu Kustom

Kurung kurawal pelepasan

Kurung kurawal buka dan tutup diartikan sebagai tanda mulai dan akhir dari item format. Untuk menampilkan kurung kurawal pembuka atau kurung kurawal penutup secara harfiah, Anda harus menggunakan urutan pelarian. 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 di-escape dengan item format diparsing secara berbeda antara .NET dan .NET Framework.

.JARING

Kurung kurawal dapat diloloskan di sekitar item format. Misalnya, pertimbangkan item format {{{0:D}}}, 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 sesuai urutan ditemukan. Menginterpretasikan kurung kurawal berlapis tidak didukung.

Cara interpretasi kurung kurawal yang diabaikan dapat menyebabkan hasil yang tidak terduga. Misalnya, pertimbangkan item format {{{0:D}}}, 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) 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 harfiah D}.
  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 agar tidak salah menafsirkan kurung kurawal yang di-escape dan item format adalah dengan memformat kurung kurawal dan item format secara terpisah. Artinya, dalam operasi format pertama, tampilkan kurung kurawal pembuka secara 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 argumen IFormatProvider yang nilainya tidak null, runtime memanggil metode IFormatProvider.GetFormat untuk meminta implementasi ICustomFormatter. Jika metode dapat mengembalikan implementasi ICustomFormatter, metode tersebut di-cache selama panggilan metode pemformatan komposit.

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

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

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

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

  4. Metode ToString tanpa parameter dari tipe tersebut, yang baik menggantikan Object.ToString() atau mewarisi perilaku dari kelas dasarnya, dipanggil. Dalam hal ini, string format yang ditentukan oleh komponen formatString 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 ToString objek. 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 di bulan Mei, dalam budaya bahasa Inggris AS nilai dari kedua string dalam contoh sebelumnya adalah Thursday May.

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

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

// 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 lebar 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

  • Last updated on