Clase System.FlagsAttribute
En este artículo se proporcionan comentarios adicionales a la documentación de referencia de esta API.
El FlagsAttribute atributo indica que una enumeración se puede tratar como un campo de bits; es decir, un conjunto de marcas.
Los campos de bits se usan generalmente para listas de elementos que pueden producirse en combinación, mientras que las constantes de enumeración se usan generalmente para listas de elementos mutuamente excluyentes. Por lo tanto, los campos de bits están diseñados para combinarse con una operación bit a bit OR para generar valores sin nombre, mientras que las constantes enumeradas no son. Los lenguajes varían en su uso de campos de bits en comparación con las constantes de enumeración.
Atributos de FlagsAttribute
AttributeUsageAttribute se aplica a esta clase y su Inherited propiedad especifica false. Este atributo solo se puede aplicar a las enumeraciones.
Directrices para FlagsAttribute y enumeración
Use el FlagsAttribute atributo personalizado para una enumeración solo si se va a realizar una operación bit a bit (AND, OR, EXCLUSIVE OR) en un valor numérico.
Defina constantes de enumeración en potencias de dos, es decir, 1, 2, 4, 8, etc. Esto significa que las marcas individuales de las constantes de enumeración combinadas no se superponen.
Considere la posibilidad de crear una constante enumerada para combinaciones de marcas usadas habitualmente. Por ejemplo, si tiene una enumeración usada para las operaciones de E/S de archivo que contiene las constantes enumeradas
Read = 1yWrite = 2, considere la posibilidad de crear la constanteReadWrite = Read OR Writeenumerada , que combina lasReadmarcas yWrite. Además, la operación OR bit a bit usada para combinar las marcas podría considerarse un concepto avanzado en algunas circunstancias que no deberían ser necesarias para tareas simples.Tenga cuidado si define un número negativo como una constante enumerada de marca porque muchas posiciones de marca pueden establecerse en 1, lo que podría hacer que el código sea confuso y fomentar errores de codificación.
Una manera cómoda de probar si una marca está establecida en un valor numérico es realizar una operación AND bit a bit entre el valor numérico y la constante enumerada de marca, que establece todos los bits del valor numérico en cero que no corresponden a la marca y, a continuación, comprueba si el resultado de esa operación es igual a la constante enumerada de marca.
Use
Nonecomo nombre de la constante enumerada de marca cuyo valor es cero. No se puede usar laNoneconstante enumerada en una operación AND bit a bit para probar una marca porque el resultado siempre es cero. Sin embargo, puede realizar una comparación lógica, no bit a bit, entre el valor numérico y laNoneconstante enumerada para determinar si se establecen los bits del valor numérico.Si crea una enumeración de valores en lugar de una enumeración flags, todavía vale la pena crear una
Noneconstante enumerada. El motivo es que, de forma predeterminada, la memoria usada para la enumeración se inicializa en cero por Common Language Runtime. Por lo tanto, si no define una constante cuyo valor es cero, la enumeración contendrá un valor no válido cuando se cree.Si hay un caso predeterminado obvio que la aplicación debe representar, considere la posibilidad de usar una constante enumerada cuyo valor es cero para representar el valor predeterminado. Si no hay ningún caso predeterminado, considere la posibilidad de usar una constante enumerada cuyo valor es cero, lo que significa que el caso que no está representado por ninguna de las demás constantes enumeradas.
No defina un valor de enumeración únicamente para reflejar el estado de la propia enumeración. Por ejemplo, no defina una constante enumerada que simplemente marque el final de la enumeración. Si necesita determinar el último valor de la enumeración, compruebe explícitamente ese valor. Además, puede realizar una comprobación de intervalo para la primera y última constante enumerada si todos los valores del intervalo son válidos.
No especifique constantes enumeradas reservadas para uso futuro.
Al definir un método o propiedad que toma una constante enumerada como un valor, considere la posibilidad de validar el valor. El motivo es que puede convertir un valor numérico al tipo de enumeración aunque ese valor numérico no esté definido en la enumeración.
Ejemplos
En el ejemplo siguiente se muestra el uso del FlagsAttribute atributo y se muestra el efecto en el ToString método de uso FlagsAttribute en una Enum declaración.
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
En el ejemplo anterior se definen dos enumeraciones relacionadas con el color y SingleHueMultiHue. Este último tiene el FlagsAttribute atributo ; el primero no lo hace. En el ejemplo se muestra la diferencia en el comportamiento cuando un intervalo de enteros, incluidos los enteros que no representan valores subyacentes del tipo de enumeración, se convierten en el tipo de enumeración y se muestran sus representaciones de cadena. Por ejemplo, tenga en cuenta que 3 no se puede representar como un SingleHue valor porque 3 no es el valor subyacente de ningún SingleHue miembro, mientras que el FlagsAttribute atributo permite representar 3 como un MultiHue valor de Black, Red.
En el ejemplo siguiente se define otra enumeración con el FlagsAttribute atributo y se muestra cómo usar operadores lógicos y de igualdad bit a bit para determinar si uno o varios campos de bits se establecen en un valor de enumeración. También puede usar el Enum.HasFlag método para hacerlo, pero eso no se muestra en este ejemplo.
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
