Compartilhar via

Tipos de enumeração (referência de C#)

Um tipo de enumeração (ou tipo de enumeração) é um tipo de valor definido por um conjunto de constantes nomeadas do tipo numérico integral subjacente. Para definir um tipo de enumeração, use a enum palavra-chave e especifique os nomes dos membros de enumeração:

enum Season
{
    Spring,
    Summer,
    Autumn,
    Winter
}

Por padrão, os valores constantes associados aos membros de enumeração são do tipo int; eles começam com zero e aumentam em uma unidade seguindo a ordem do texto de definição. Você pode especificar explicitamente qualquer outro tipo numérico integral como um tipo subjacente de um tipo de enumeração. Você também pode especificar explicitamente os valores de constante associados, como mostra o exemplo a seguir:

enum ErrorCode : ushort
{
    None = 0,
    Unknown = 1,
    ConnectionLost = 100,
    OutlierReading = 200
}

Você não pode definir um método dentro da definição de um tipo de enumeração. Para adicionar funcionalidade a um tipo de enumeração, crie um membro de extensão.

O valor padrão de um tipo E de enumeração é o valor produzido pela expressão (E)0, mesmo que zero não tenha o membro de enumeração correspondente.

Conversões implícitas de zero

O C# permite conversões implícitas do valor 0 literal para qualquer tipo de enumeração e de const valores iguais a zero. Esse comportamento pode levar a resultados inesperados quando uma enumeração não inclui um membro com o valor zero:

public enum GpioPort
{
    GpioA = 1,
    GpioB,
    GpioC,
    GpioD
}

public class ZeroConversionExample
{
    public static void Main()
    {
        // This compiles without warning but creates an invalid enum value
        GpioPort port1 = (GpioPort)0;
        Console.WriteLine($"port1: {port1}"); // Output: port1: 0

        // This also compiles due to implicit conversion from zero
        GpioPort port2 = GetPort(0);
        Console.WriteLine($"port2: {port2}"); // Output: port2: 0

        // Check if the enum value is valid
        bool isValid1 = Enum.IsDefined(typeof(GpioPort), port1);
        bool isValid2 = Enum.IsDefined(typeof(GpioPort), port2);
        Console.WriteLine($"port1 is valid: {isValid1}"); // Output: port1 is valid: False
        Console.WriteLine($"port2 is valid: {isValid2}"); // Output: port2 is valid: False

        // Safer approach - validate enum values
        if (Enum.IsDefined(typeof(GpioPort), 0))
        {
            GpioPort safePort = (GpioPort)0;
        }
        else
        {
            Console.WriteLine("Value 0 is not a valid GpioPort");
            // Handle the invalid case appropriately
        }
    }

    public static GpioPort GetPort(GpioPort port)
    {
        return port;
    }
}

No exemplo anterior, ambos port1 recebem port2 o valor 0, mas GpioPort não têm nenhum membro com esse valor. O Enum.IsDefined método confirma que são valores de enumeração inválidos.

Essa conversão implícita existe porque o padrão de 0 bit é o padrão para todos os tipos de struct, incluindo todos os tipos de enumeração. No entanto, ele pode introduzir bugs em seu código. Para evitar esses problemas:

  • Quase sempre você deve definir um membro com valor 0 em suas enumerações.
  • Use Enum.IsDefined para validar valores de enumeração ao converter de tipos numéricos.
  • Tenha cuidado ao usar parâmetros numéricos que podem ser convertidos implicitamente em tipos de enumeração.

Você usa um tipo de enumeração para representar uma escolha de um conjunto de valores mutuamente exclusivos ou uma combinação de opções. Para representar uma combinação de opções, defina um tipo de enumeração como sinalizadores de bit.

Tipos de Enumeração como Sinalizadores de Bit

Se você quiser que um tipo de enumeração represente uma combinação de opções, defina membros de enumeração para essas opções, de modo que uma escolha individual seja um campo de bits. Ou seja, os valores associados desses membros de enumeração devem ser os potências de dois. Em seguida, você pode usar os operadores lógicos bit a bit | ou & para combinar opções ou cruzar combinações de opções, respectivamente. Para indicar que um tipo de enumeração declara campos de bit, aplique o atributo Flags a ele. Como mostra o exemplo a seguir, você também pode incluir algumas combinações típicas na definição de um tipo de enumeração.

[Flags]
public enum Days
{
    None      = 0b_0000_0000,  // 0
    Monday    = 0b_0000_0001,  // 1
    Tuesday   = 0b_0000_0010,  // 2
    Wednesday = 0b_0000_0100,  // 4
    Thursday  = 0b_0000_1000,  // 8
    Friday    = 0b_0001_0000,  // 16
    Saturday  = 0b_0010_0000,  // 32
    Sunday    = 0b_0100_0000,  // 64
    Weekend   = Saturday | Sunday
}

public class FlagsEnumExample
{
    public static void Main()
    {
        Days meetingDays = Days.Monday | Days.Wednesday | Days.Friday;
        Console.WriteLine(meetingDays);
        // Output:
        // Monday, Wednesday, Friday

        Days workingFromHomeDays = Days.Thursday | Days.Friday;
        Console.WriteLine($"Join a meeting by phone on {meetingDays & workingFromHomeDays}");
        // Output:
        // Join a meeting by phone on Friday

        bool isMeetingOnTuesday = (meetingDays & Days.Tuesday) == Days.Tuesday;
        Console.WriteLine($"Is there a meeting on Tuesday: {isMeetingOnTuesday}");
        // Output:
        // Is there a meeting on Tuesday: False

        var a = (Days)37;
        Console.WriteLine(a);
        // Output:
        // Monday, Wednesday, Saturday
    }
}

Para obter mais informações e exemplos, consulte a página de referência da System.FlagsAttribute API e os membros não exclusivos e a seção de atributo Flags da página de referência da System.Enum API.

O tipo System.Enum e a restrição enum

O System.Enum tipo é a classe base abstrata de todos os tipos de enumeração. Ele fornece uma série de métodos para obter informações sobre um tipo de enumeração e seus valores. Para obter mais informações e exemplos, consulte a página de referência da System.Enum API.

Você pode usar System.Enum em uma restrição de classe base (conhecida como restrição de enumeração) para especificar que um parâmetro de tipo é um tipo de enumeração. Qualquer tipo de enumeração também satisfaz a struct restrição, que é usada para especificar que um parâmetro de tipo é um tipo de valor não anulável.

Conversões

Para qualquer tipo de enumeração, existem conversões explícitas entre o tipo de enumeração e seu tipo integral subjacente. Se você converter um valor de enumeração para seu tipo subjacente, o resultado será o valor integral associado de um membro de enumeração.

public enum Season
{
    Spring,
    Summer,
    Autumn,
    Winter
}

public class EnumConversionExample
{
    public static void Main()
    {
        Season a = Season.Autumn;
        Console.WriteLine($"Integral value of {a} is {(int)a}");  // output: Integral value of Autumn is 2

        var b = (Season)1;
        Console.WriteLine(b);  // output: Summer

        var c = (Season)4;
        Console.WriteLine(c);  // output: 4
    }
}

Use o Enum.IsDefined método para determinar se um tipo de enumeração contém um membro de enumeração com o determinado valor associado.

Para qualquer tipo de enumeração, existem as conversões boxing e unboxing de e para o tipo System.Enum, respectivamente.

Especificação da linguagem C#

Para obter mais informações, confira as seguintes seções da especificação da linguagem C#:

Consulte também

  • Last updated on