Kelas System.FlagsAttribute

  • Artikel

Artikel ini menyediakan keterangan tambahan untuk dokumentasi referensi untuk API ini.

Atribut FlagsAttribute menunjukkan bahwa enumerasi dapat diperlakukan sebagai bidang bit; yaitu, sekumpulan bendera.

Bidang bit umumnya digunakan untuk daftar elemen yang mungkin terjadi dalam kombinasi, sedangkan konstanta enumerasi umumnya digunakan untuk daftar elemen yang saling eksklusif. Oleh karena itu, bidang bit dirancang untuk dikombinasikan dengan operasi bitwise OR untuk menghasilkan nilai yang tidak disebutkan namanya, sedangkan konstanta enumerasi tidak. Bahasa bervariasi dalam penggunaan bidang bit dibandingkan dengan konstanta enumerasi.

Atribut FlagsAttribute

AttributeUsageAttribute diterapkan ke kelas ini, dan propertinya Inherited menentukan false. Atribut ini hanya dapat diterapkan ke enumerasi.

Panduan untuk FlagsAttribute dan enum

  • FlagsAttribute Gunakan atribut kustom untuk enumerasi hanya jika operasi bitwise (AND, OR, EXCLUSIVE OR) akan dilakukan pada nilai numerik.

  • Tentukan konstanta enumerasi dalam kekuatan dua, yaitu, 1, 2, 4, 8, dan sebagainya. Ini berarti bendera individu dalam konstanta enumerasi gabungan tidak tumpang tindih.

  • Pertimbangkan untuk membuat konstanta enumerasi untuk kombinasi bendera yang umum digunakan. Misalnya, jika Anda memiliki enumerasi yang digunakan untuk operasi I/O file yang berisi konstanta enumerasi dan Write = 2, pertimbangkan untuk membuat konstanta Read = 1ReadWrite = Read OR Writeenumerasi , yang menggabungkan Read bendera dan Write . Selain itu, operasi bitwise OR yang digunakan untuk menggabungkan bendera mungkin dianggap sebagai konsep lanjutan dalam beberapa keadaan yang seharusnya tidak diperlukan untuk tugas sederhana.

  • Berhati-hatilah jika Anda menentukan angka negatif sebagai konstanta enumerasi bendera karena banyak posisi bendera mungkin diatur ke 1, yang mungkin membuat kode Anda membingungkan dan mendorong kesalahan pengkodean.

  • Cara mudah untuk menguji apakah bendera diatur dalam nilai numerik adalah dengan melakukan operasi BITWISE AND antara nilai numerik dan konstanta enumerasi bendera, yang menetapkan semua bit dalam nilai numerik ke nol yang tidak sesuai dengan bendera, lalu menguji apakah hasil operasi tersebut sama dengan konstanta enumerasi bendera.

  • Gunakan None sebagai nama konstanta enumerasi bendera yang nilainya nol. Anda tidak dapat menggunakan None konstanta enumerasi dalam operasi BITWISE AND untuk menguji bendera karena hasilnya selalu nol. Namun, Anda dapat melakukan perbandingan logis, bukan bitwise, antara nilai numerik dan None konstanta enumerasi untuk menentukan apakah bit dalam nilai numerik diatur.

    Jika Anda membuat enumerasi nilai alih-alih enumerasi bendera, masih ada baiknya untuk membuat None konstanta enumerasi. Alasannya adalah bahwa secara default memori yang digunakan untuk enumerasi diinisialisasi ke nol oleh runtime bahasa umum. Akibatnya, jika Anda tidak menentukan konstanta yang nilainya nol, enumerasi akan berisi nilai ilegal saat dibuat.

    Jika ada kasus default yang jelas yang perlu diwakili aplikasi Anda, pertimbangkan untuk menggunakan konstanta enumerasi yang nilainya nol untuk mewakili default. Jika tidak ada kasus default, pertimbangkan untuk menggunakan konstanta enumerasi yang nilainya nol yang berarti kasus yang tidak diwakili oleh konstanta enumerasi lainnya.

  • Jangan mendefinisikan nilai enumerasi semata-mata untuk mencerminkan status enumerasi itu sendiri. Misalnya, jangan tentukan konstanta enumerasi yang hanya menandai akhir enumerasi. Jika Anda perlu menentukan nilai terakhir enumerasi, periksa nilai tersebut secara eksplisit. Selain itu, Anda dapat melakukan pemeriksaan rentang untuk konstanta pertama dan terakhir yang dijumlahkan jika semua nilai dalam rentang valid.

  • Jangan tentukan konstanta enumerasi yang dicadangkan untuk digunakan di masa mendatang.

  • Saat Anda menentukan metode atau properti yang mengambil konstanta enumerasi sebagai nilai, pertimbangkan untuk memvalidasi nilai. Alasannya adalah Anda dapat melemparkan nilai numerik ke jenis enumerasi bahkan jika nilai numerik tersebut tidak ditentukan dalam enumerasi.

Contoh

Contoh berikut mengilustrasikan penggunaan FlagsAttribute atribut dan menunjukkan efek pada ToString metode penggunaan FlagsAttribute pada Enum deklarasi.

using System;

class Example
{
    // Define an Enum without FlagsAttribute.
    enum SingleHue : short
    {
        None = 0,
        Black = 1,
        Red = 2,
        Green = 4,
        Blue = 8
    };

    // Define an Enum with FlagsAttribute.
    [Flags]
    enum MultiHue : short
    {
        None = 0,
        Black = 1,
        Red = 2,
        Green = 4,
        Blue = 8
    };

    static void Main()
    {
        // Display all possible combinations of values.
        Console.WriteLine(
             "All possible combinations of values without FlagsAttribute:");
        for (int val = 0; val <= 16; val++)
            Console.WriteLine("{0,3} - {1:G}", val, (SingleHue)val);

        // Display all combinations of values, and invalid values.
        Console.WriteLine(
             "\nAll possible combinations of values with FlagsAttribute:");
        for (int val = 0; val <= 16; val++)
            Console.WriteLine("{0,3} - {1:G}", val, (MultiHue)val);
    }
}
// The example displays the following output:
//       All possible combinations of values without FlagsAttribute:
//         0 - None
//         1 - Black
//         2 - Red
//         3 - 3
//         4 - Green
//         5 - 5
//         6 - 6
//         7 - 7
//         8 - Blue
//         9 - 9
//        10 - 10
//        11 - 11
//        12 - 12
//        13 - 13
//        14 - 14
//        15 - 15
//        16 - 16
//
//       All possible combinations of values with FlagsAttribute:
//         0 - None
//         1 - Black
//         2 - Red
//         3 - Black, Red
//         4 - Green
//         5 - Black, Green
//         6 - Red, Green
//         7 - Black, Red, Green
//         8 - Blue
//         9 - Black, Blue
//        10 - Red, Blue
//        11 - Black, Red, Blue
//        12 - Green, Blue
//        13 - Black, Green, Blue
//        14 - Red, Green, Blue
//        15 - Black, Red, Green, Blue
//        16 - 16

open System

// Define an Enum without FlagsAttribute.
type SingleHue =
    | None = 0
    | Black = 1
    | Red = 2
    | Green = 4
    | Blue = 8

// Define an Enum with FlagsAttribute.
[<Flags>]
type MultiHue =
    | None = 0
    | Black = 1
    | Red = 2
    | Green = 4
    | Blue = 8

// Display all possible combinations of values.
printfn "All possible combinations of values without FlagsAttribute:"
for i = 0 to 16 do
    printfn $"{i,3} - {enum<SingleHue> i:G}"

// Display all combinations of values, and invalid values.
printfn "\nAll possible combinations of values with FlagsAttribute:"
for i = 0 to 16 do
    printfn $"{i,3} - {enum<MultiHue> i:G}"

// The example displays the following output:
//       All possible combinations of values without FlagsAttribute:
//         0 - None
//         1 - Black
//         2 - Red
//         3 - 3
//         4 - Green
//         5 - 5
//         6 - 6
//         7 - 7
//         8 - Blue
//         9 - 9
//        10 - 10
//        11 - 11
//        12 - 12
//        13 - 13
//        14 - 14
//        15 - 15
//        16 - 16
//
//       All possible combinations of values with FlagsAttribute:
//         0 - None
//         1 - Black
//         2 - Red
//         3 - Black, Red
//         4 - Green
//         5 - Black, Green
//         6 - Red, Green
//         7 - Black, Red, Green
//         8 - Blue
//         9 - Black, Blue
//        10 - Red, Blue
//        11 - Black, Red, Blue
//        12 - Green, Blue
//        13 - Black, Green, Blue
//        14 - Red, Green, Blue
//        15 - Black, Red, Green, Blue
//        16 - 16

Module Example
   ' Define an Enum without FlagsAttribute.
   Enum SingleHue As Short
      None = 0
      Black = 1
      Red = 2
      Green = 4
      Blue = 8
   End Enum

   ' Define an Enum with FlagsAttribute.
   <Flags()> 
   Enum MultiHue As Short
      None = 0
      Black = 1
      Red = 2
      Green = 4
      Blue = 8
   End Enum

   Sub Main()
      ' Display all possible combinations of values.
      Console.WriteLine(
           "All possible combinations of values without FlagsAttribute:")
      For val As Integer = 0 To 16
         Console.WriteLine("{0,3} - {1:G}", val, CType(val, SingleHue))
     Next 
     Console.WriteLine()
     
     ' Display all combinations of values, and invalid values.
     Console.WriteLine( 
          "All possible combinations of values with FlagsAttribute:")
     For val As Integer = 0 To 16
        Console.WriteLine( "{0,3} - {1:G}", val, CType(val, MultiHue))
     Next 
   End Sub 
End Module 
' The example displays the following output:
'       All possible combinations of values without FlagsAttribute:
'         0 - None
'         1 - Black
'         2 - Red
'         3 - 3
'         4 - Green
'         5 - 5
'         6 - 6
'         7 - 7
'         8 - Blue
'         9 - 9
'        10 - 10
'        11 - 11
'        12 - 12
'        13 - 13
'        14 - 14
'        15 - 15
'        16 - 16
'       
'       All possible combinations of values with FlagsAttribute:
'         0 - None
'         1 - Black
'         2 - Red
'         3 - Black, Red
'         4 - Green
'         5 - Black, Green
'         6 - Red, Green
'         7 - Black, Red, Green
'         8 - Blue
'         9 - Black, Blue
'        10 - Red, Blue
'        11 - Black, Red, Blue
'        12 - Green, Blue
'        13 - Black, Green, Blue
'        14 - Red, Green, Blue
'        15 - Black, Red, Green, Blue
'        16 - 16

Contoh sebelumnya mendefinisikan dua enumerasi terkait warna, SingleHue dan MultiHue. Yang terakhir memiliki FlagsAttribute atribut ; yang pertama tidak. Contoh menunjukkan perbedaan perilaku ketika rentang bilangan bulat, termasuk bilangan bulat yang tidak mewakili nilai yang mendasar dari jenis enumerasi, ditransmisikan ke jenis enumerasi dan representasi stringnya ditampilkan. Misalnya, perhatikan bahwa 3 tidak dapat direpresentasikan sebagai SingleHue nilai karena 3 bukan nilai yang mendasar dari anggota mana punSingleHue, sedangkan FlagsAttribute atribut memungkinkan untuk mewakili 3 sebagai MultiHue nilai .Black, Red

Contoh berikut mendefinisikan enumerasi lain dengan FlagsAttribute atribut dan menunjukkan cara menggunakan operator logis bitwise dan kesetaraan untuk menentukan apakah satu atau beberapa bidang bit diatur dalam nilai enumerasi. Anda juga dapat menggunakan Enum.HasFlag metode untuk melakukannya, tetapi itu tidak ditunjukkan dalam contoh ini.

using System;

[Flags]
public enum PhoneService
{
    None = 0,
    LandLine = 1,
    Cell = 2,
    Fax = 4,
    Internet = 8,
    Other = 16
}

public class Example1
{
    public static void Main()
    {
        // Define three variables representing the types of phone service
        // in three households.
        var household1 = PhoneService.LandLine | PhoneService.Cell |
                         PhoneService.Internet;
        var household2 = PhoneService.None;
        var household3 = PhoneService.Cell | PhoneService.Internet;

        // Store the variables in an array for ease of access.
        PhoneService[] households = { household1, household2, household3 };

        // Which households have no service?
        for (int ctr = 0; ctr < households.Length; ctr++)
            Console.WriteLine("Household {0} has phone service: {1}",
                              ctr + 1,
                              households[ctr] == PhoneService.None ?
                                  "No" : "Yes");
        Console.WriteLine();

        // Which households have cell phone service?
        for (int ctr = 0; ctr < households.Length; ctr++)
            Console.WriteLine("Household {0} has cell phone service: {1}",
                              ctr + 1,
                              (households[ctr] & PhoneService.Cell) == PhoneService.Cell ?
                                 "Yes" : "No");
        Console.WriteLine();

        // Which households have cell phones and land lines?
        var cellAndLand = PhoneService.Cell | PhoneService.LandLine;
        for (int ctr = 0; ctr < households.Length; ctr++)
            Console.WriteLine("Household {0} has cell and land line service: {1}",
                              ctr + 1,
                              (households[ctr] & cellAndLand) == cellAndLand ?
                                 "Yes" : "No");
        Console.WriteLine();

        // List all types of service of each household?//
        for (int ctr = 0; ctr < households.Length; ctr++)
            Console.WriteLine("Household {0} has: {1:G}",
                              ctr + 1, households[ctr]);
        Console.WriteLine();
    }
}
// The example displays the following output:
//    Household 1 has phone service: Yes
//    Household 2 has phone service: No
//    Household 3 has phone service: Yes
//
//    Household 1 has cell phone service: Yes
//    Household 2 has cell phone service: No
//    Household 3 has cell phone service: Yes
//
//    Household 1 has cell and land line service: Yes
//    Household 2 has cell and land line service: No
//    Household 3 has cell and land line service: No
//
//    Household 1 has: LandLine, Cell, Internet
//    Household 2 has: None
//    Household 3 has: Cell, Internet

open System

[<Flags>]
type PhoneService =
    | None = 0
    | LandLine = 1
    | Cell = 2
    | Fax = 4
    | Internet = 8
    | Other = 16

// Define three variables representing the types of phone service
// in three households.
let household1 = 
    PhoneService.LandLine ||| PhoneService.Cell ||| PhoneService.Internet

let household2 = 
    PhoneService.None

let household3 = 
    PhoneService.Cell ||| PhoneService.Internet

// Store the variables in a list for ease of access.
let households =
    [ household1; household2; household3 ]

// Which households have no service?
for i = 0 to households.Length - 1 do
    printfn $"""Household {i + 1} has phone service: {if households[i] = PhoneService.None then "No" else "Yes"}"""
printfn ""

// Which households have cell phone service?
for i = 0 to households.Length - 1 do
    printfn $"""Household {i + 1} has cell phone service: {if households[i] &&& PhoneService.Cell = PhoneService.Cell then "Yes" else "No"}"""
printfn ""

// Which households have cell phones and land lines?
let cellAndLand = 
    PhoneService.Cell ||| PhoneService.LandLine

for i = 0 to households.Length - 1 do
    printfn $"""Household {i + 1} has cell and land line service: {if households[i] &&& cellAndLand = cellAndLand then "Yes" else "No"}"""
printfn ""

// List all types of service of each household?//
for i = 0 to households.Length - 1 do
    printfn $"Household {i + 1} has: {households[i]:G}"

// The example displays the following output:
//    Household 1 has phone service: Yes
//    Household 2 has phone service: No
//    Household 3 has phone service: Yes
//
//    Household 1 has cell phone service: Yes
//    Household 2 has cell phone service: No
//    Household 3 has cell phone service: Yes
//
//    Household 1 has cell and land line service: Yes
//    Household 2 has cell and land line service: No
//    Household 3 has cell and land line service: No
//
//    Household 1 has: LandLine, Cell, Internet
//    Household 2 has: None
//    Household 3 has: Cell, Internet

<Flags()>
Public Enum PhoneService As Integer
   None = 0
   LandLine = 1
   Cell = 2
   Fax = 4
   Internet = 8
   Other = 16
End Enum

Module Example1
   Public Sub Main()
      ' Define three variables representing the types of phone service
      ' in three households.
      Dim household1 As PhoneService = PhoneService.LandLine Or
                                       PhoneService.Cell Or
                                       PhoneService.Internet
      Dim household2 As PhoneService = PhoneService.None
      Dim household3 As PhoneService = PhoneService.Cell Or
                                       PhoneService.Internet

      ' Store the variables in an array for ease of access.
      Dim households() As PhoneService = { household1, household2,
                                           household3 }

      ' Which households have no service?
      For ctr As Integer = 0 To households.Length - 1
         Console.WriteLine("Household {0} has phone service: {1}",
                           ctr + 1,
                           If(households(ctr) = PhoneService.None,
                              "No", "Yes"))
      Next
      Console.WriteLine()
      
      ' Which households have cell phone service?
      For ctr As Integer = 0 To households.Length - 1
         Console.WriteLine("Household {0} has cell phone service: {1}",
                           ctr + 1,
                           If((households(ctr) And PhoneService.Cell) = PhoneService.Cell,
                              "Yes", "No"))
      Next
      Console.WriteLine()
      
      ' Which households have cell phones and land lines?
      Dim cellAndLand As PhoneService = PhoneService.Cell Or PhoneService.LandLine
      For ctr As Integer = 0 To households.Length - 1
         Console.WriteLine("Household {0} has cell and land line service: {1}",
                           ctr + 1,
                           If((households(ctr) And cellAndLand) = cellAndLand,
                              "Yes", "No"))
      Next
      Console.WriteLine()
      
      ' List all types of service of each household?'
      For ctr As Integer = 0 To households.Length - 1
         Console.WriteLine("Household {0} has: {1:G}",
                           ctr + 1, households(ctr))
      Next
      Console.WriteLine()
   End Sub
End Module
' The example displays the following output:
'    Household 1 has phone service: Yes
'    Household 2 has phone service: No
'    Household 3 has phone service: Yes
'
'    Household 1 has cell phone service: Yes
'    Household 2 has cell phone service: No
'    Household 3 has cell phone service: Yes
'
'    Household 1 has cell and land line service: Yes
'    Household 2 has cell and land line service: No
'    Household 3 has cell and land line service: No
'
'    Household 1 has: LandLine, Cell, Internet
'    Household 2 has: None
'    Household 3 has: Cell, Internet