System.FlagsAttribute-klasse

Het FlagsAttribute kenmerk geeft aan dat een opsomming kan worden behandeld als een bitveld, dat wil gezegd een set vlaggen.

Bitvelden worden over het algemeen gebruikt voor lijsten met elementen die in combinatie kunnen optreden, terwijl opsommingsconstanten over het algemeen worden gebruikt voor lijsten met wederzijds exclusieve elementen. Daarom zijn bitvelden ontworpen om te worden gecombineerd met een bitwise OR bewerking om niet-benoemde waarden te genereren, terwijl geïnventareerde constanten niet zijn. Talen verschillen in het gebruik van bitvelden in vergelijking met opsommingsconstanten.

Kenmerken van de FlagsAttribute

AttributeUsageAttribute wordt toegepast op deze klasse en de Inherited eigenschap geeft aan false. Dit kenmerk kan alleen worden toegepast op opsommingen.

Richtlijnen voor FlagsAttribute en enum

• Gebruik het FlagsAttribute aangepaste kenmerk alleen voor een opsomming als een bitwise bewerking (AND, OR, EXCLUSIVE OR) moet worden uitgevoerd op een numerieke waarde.

• Opsommingsconstanten definiëren in machten van twee, dat wil gezegd: 1, 2, 4, 8, enzovoort. Dit betekent dat de afzonderlijke vlaggen in gecombineerde opsommingsconstanten elkaar niet overlappen.

• Overweeg om een geïnventariseerd constante te maken voor veelgebruikte vlagcombinaties. Als u bijvoorbeeld een opsomming hebt die wordt gebruikt voor bestands-I/O-bewerkingen die de geïnventareerde constanten Read = 1 bevatten, Write = 2kunt u overwegen om de geïnventareerde constante ReadWrite = Read OR Writete maken, waarin de Read en Write vlaggen worden gecombineerd. Bovendien kan de bitsgewijze OR-bewerking die wordt gebruikt om de vlaggen te combineren, worden beschouwd als een geavanceerd concept in sommige omstandigheden dat niet vereist mag zijn voor eenvoudige taken.

• Wees voorzichtig als u een negatief getal definieert als een markeringsconstante, omdat veel vlagposities kunnen worden ingesteld op 1, waardoor uw code verwarrend kan zijn en coderingsfouten kan stimuleren.

• Een handige manier om te testen of een vlag is ingesteld in een numerieke waarde, is door een bitsgewijze AND-bewerking uit te voeren tussen de numerieke waarde en de opsommingsconstante van de vlag, waarmee alle bits in de numerieke waarde worden ingesteld op nul die niet overeenkomen met de vlag, en vervolgens testen of het resultaat van die bewerking gelijk is aan de vlag-opsommingsconstante.

• Gebruik None deze naam als de naam van de vlag-opsommingsconstante waarvan de waarde nul is. U kunt de None geïnventareerde constante in een bitwise AND-bewerking niet gebruiken om te testen op een vlag, omdat het resultaat altijd nul is. U kunt echter een logische, niet een bitgewijze vergelijking uitvoeren tussen de numerieke waarde en de None opgesomde constante om te bepalen of bits in de numerieke waarde zijn ingesteld.

  Als u een opsomming van waarden maakt in plaats van een opsomming van vlaggen, is het nog steeds de moeite waard om een None geïnventariseerd constante te maken. De reden hiervoor is dat het geheugen dat voor de opsomming wordt gebruikt, standaard wordt geïnitialiseerd tot nul door de algemene taalruntime. Als u dus geen constante definieert waarvan de waarde nul is, bevat de opsomming een ongeldige waarde wanneer deze wordt gemaakt.

  Als er een duidelijk standaardscenario is dat uw toepassing moet vertegenwoordigen, kunt u overwegen een opgesomde constante te gebruiken waarvan de waarde nul is om de standaardwaarde weer te geven. Als er geen standaardcase is, kunt u overwegen een opgesomde constante te gebruiken waarvan de waarde nul is, wat betekent dat de case die niet wordt weergegeven door een van de andere opgesomde constanten.

• Definieer niet alleen een opsommingswaarde om de status van de opsomming zelf te spiegelen. Definieer bijvoorbeeld geen opsommingsconstante die alleen het einde van de opsomming markeert. Als u de laatste waarde van de opsomming wilt bepalen, controleert u expliciet op die waarde. Daarnaast kunt u een bereikcontrole uitvoeren op de eerste en laatste opsommingsconstante als alle waarden binnen het bereik geldig zijn.

• Geef geen geïnventareerde constanten op die zijn gereserveerd voor toekomstig gebruik.

• Wanneer u een methode of eigenschap definieert die een geïnventareerde constante als een waarde gebruikt, kunt u overwegen om de waarde te valideren. De reden hiervoor is dat u een numerieke waarde kunt casten naar het opsommingstype, zelfs als die numerieke waarde niet is gedefinieerd in de opsomming.

Voorbeelden

Het volgende voorbeeld illustreert het gebruik van het FlagsAttribute kenmerk en toont het effect op de ToString methode om FlagsAttribute te gebruiken in een Enum declaratie.

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

In het voorgaande voorbeeld worden twee kleurgerelateerde opsommingen gedefinieerd, SingleHue en MultiHue. De laatste heeft het FlagsAttribute kenmerk; de vroegere niet. In het voorbeeld ziet u het verschil in gedrag wanneer een bereik met gehele getallen, inclusief getallen die geen onderliggende waarden van het opsommingstype zijn, worden omgezet naar het opsommingstype en hun tekenreeksweergaven worden weergegeven. Houd er bijvoorbeeld rekening mee dat 3 niet kan worden weergegeven als een SingleHue waarde omdat 3 niet de onderliggende waarde van een SingleHue lid is, terwijl het FlagsAttribute kenmerk het mogelijk maakt om 3 weer te geven als een MultiHue waarde van Black, Red.

In het volgende voorbeeld wordt een andere opsomming gedefinieerd met het FlagsAttribute kenmerk en ziet u hoe u bitgewijze logische operatoren en gelijkheidsoperators gebruikt om te bepalen of een of meer bitvelden zijn ingesteld in een opsommingswaarde. U kunt ook de Enum.HasFlag methode gebruiken om dat te doen, maar dat wordt niet weergegeven in dit voorbeeld.

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 {ctr + 1} has phone service:" +
                $"{(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 {ctr + 1} has cell phone service: " +
                $"{((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 {ctr + 1} has cell and land line service: " +
                $"{((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 {ctr + 1} has: {households[ctr]:G}");
        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