Sdílet prostřednictvím

System.FlagsAttribute třída

Tento článek obsahuje doplňující poznámky k referenční dokumentaci pro toto rozhraní API.

Atribut FlagsAttribute označuje, že výčet může být považován za bitové pole. To znamená sada příznaků.

Bitová pole se obecně používají pro seznamy prvků, které mohou nastat v kombinaci, zatímco výčtové konstanty se obvykle používají pro seznamy vzájemně se vylučujících prvků. Bitová pole jsou proto navržena tak, aby byla kombinována s bitovou operací OR za účelem generování nepojmenovaných hodnot, zatímco výčtové konstanty tuto možnost nemají. Jazyky se liší v jejich používání bitových polí v porovnání s výčtovými konstantami.

Atributy atributu Flags

AttributeUsageAttribute je použit pro tuto třídu a jeho Inherited vlastnost určuje false. Tento atribut lze použít pouze u výčtů.

Pokyny pro FlagsAttribute a výčtový typ

  • Použijte vlastní atribut FlagsAttribute pro výčet pouze v případě, že má být na číselné hodnotě provedena bitová operace (AND, OR, EXCLUSIVE OR).

  • Definujte konstanty výčtu v mocninách dvou, tj. 1, 2, 4, 8 atd. To znamená, že jednotlivé příznaky v kombinovaných výčtových konstantách se nepřekrývají.

  • Zvažte vytvoření výčtové konstanty pro běžně používané kombinace příznaků. Pokud máte například výčet používaný pro vstupně-výstupní operace souborů, které obsahují výčtové konstanty Read = 1 a Write = 2, zvažte vytvoření výčtové konstanty ReadWrite = Read OR Write, která kombinuje Read a Write příznaky. Kromě toho může být bitová operace OR použitá na kombinaci příznaků v některých případech považována za pokročilý koncept, který by pro jednoduché úlohy neměl být potřebný.

  • Dbejte opatrnosti, pokud definujete záporné číslo jako konstantu vyjádřenou příznakem, protože mnoho pozic příznaků může být nastaveno na hodnotu 1, což může způsobit, že kód bude matoucí a může vést k chybám kódování.

  • Pohodlný způsob, jak otestovat, zda je příznak nastaven v číselné hodnotě, je provést bitovou operaci AND mezi číselnou hodnotou a příznakem výčtu konstanty, která nastaví všechny bity v číselné hodnotě na nulu, která neodpovídá příznaku, a pak otestujte, zda výsledek této operace je roven výčtu příznaku konstanty.

  • Jako název konstanty enumerovaného příznaku použijte None, jehož hodnota je nula. K otestování příznaku nelze použít None výčtovou konstantu v bitové operaci AND, protože výsledek je vždy nula. Můžete ale provést logické, nikoli bitové porovnání mezi číselnou hodnotou a None výčtovou konstantou, abyste zjistili, zda jsou některé bity v číselné hodnotě nastaveny.

    Pokud místo výčtu příznaků vytvoříte výčet hodnot, je stále vhodné vytvořit výčtovou konstantu None . Důvodem je to, že ve výchozím nastavení je paměť používaná pro výčet inicializována na nulu modulem CLR (Common Language Runtime). Pokud tedy nedefinujete konstantu, jejíž hodnota je nula, bude výčet při vytváření obsahovat neplatnou hodnotu.

    Pokud existuje jasný výchozí případ, který vaše aplikace potřebuje reprezentovat, zvažte použití výčtové konstanty, jejíž hodnota je nula, aby představovala výchozí hodnotu. Pokud neexistuje žádný výchozí případ, zvažte použití výčtové konstanty, jejíž hodnota je nula, což znamená, že případ, který není reprezentován žádnou z ostatních výčtových konstant.

  • Nedefinujte hodnotu výčtu výhradně pro zrcadlení stavu samotné výčtu. Například nedefinujte výčtovou konstantu, která pouze označuje konec výčtu. Pokud potřebujete určit poslední hodnotu výčtu, zkontrolujte tuto hodnotu explicitně. Kromě toho můžete provést kontrolu rozsahu první a poslední výčtové konstanty, pokud jsou všechny hodnoty v rozsahu platné.

  • Nezadávejte výčtové konstanty, které jsou vyhrazeny pro budoucí použití.

  • Při definování metody nebo vlastnosti, která přebírá výčtovou konstantu jako hodnotu, zvažte ověření hodnoty. Důvodem je, že číselnou hodnotu můžete přetypovat na typ výčtu, i když tato číselná hodnota není definována ve výčtu.

Příklady

Následující příklad znázorňuje použití atributu FlagsAttribute a ukazuje účinek na ToString metodu použití FlagsAttribute na Enum deklaraci.

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

Předchozí příklad definuje dva výčty SingleHue související s barvou a MultiHue. Ten druhý má atribut FlagsAttribute; ten první ho nemá. Příklad ukazuje rozdíl v chování v případě, že rozsah celých čísel, včetně celých čísel, které nepředstavují podkladové hodnoty typu výčtu, jsou přetypovány na typ výčtu a jejich řetězcové reprezentace zobrazené. Všimněte si například, že 3 nelze reprezentovat jako SingleHue hodnotu, protože 3 není podkladovou hodnotou žádného SingleHue člena, zatímco FlagsAttribute atribut umožňuje reprezentovat hodnotu 3 jako MultiHue hodnotu Black, Red.

Následující příklad definuje další výčet s atributem FlagsAttribute a ukazuje, jak používat bitové logické operátory a operátory rovnosti k určení, zda jsou v hodnotě výčtu nastavena jedna nebo více bitových polí. Můžete k tomu také použít metodu Enum.HasFlag , která se ale v tomto příkladu nezobrazuje.

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