Partilhar via

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

Um tipo de enumeração (ou tipo de enum) é 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 enum:

enum Season
{
    Spring,
    Summer,
    Autumn,
    Winter
}

Por padrão, os valores constantes associados dos membros enum são do tipo int, eles começam com zero e aumentam em um 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 constantes associados, como mostra o exemplo a seguir:

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

Não se 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 enum correspondente.

Conversões implícitas a partir de zero

C# permite conversões implícitas do valor 0 literal para qualquer tipo de enum e de const valores iguais a zero. Esse comportamento pode levar a resultados inesperados quando um enum 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 e port2 são atribuídos o valor 0, mas GpioPort não tem nenhum membro com esse valor. O Enum.IsDefined método confirma que estes são valores de enum inválidos.

Esta conversão implícita existe porque o padrão de 0 bits é o padrão para todos os tipos de struct, incluindo todos os tipos de enum. No entanto, ele pode introduzir bugs em seu código. Para evitar estes problemas:

  • Você quase sempre deve definir um membro com valor 0 em seus enums.
  • Use Enum.IsDefined para validar valores de enum ao converter de tipos numéricos.
  • Tenha cuidado ao usar parâmetros numéricos que podem ser implicitamente convertidos em tipos de enum.

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 bandeiras de bits.

Tipos de enumeração como marcadores de bits

Se você quiser que um tipo de enumeração represente uma combinação de opções, defina membros enum para essas opções de modo que uma escolha individual seja um campo bit. Ou seja, os valores associados desses membros enum devem ser as potências de dois. Em seguida, poderá usar os operadores lógicos bitwise | ou & para combinar escolhas ou intersectar combinações de escolhas, respectivamente. Para indicar que um tipo de enumeração declara campos de bits, 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 a seção Membros não exclusivos e o atributo Flags da página de referência da System.Enum API.

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

O System.Enum tipo é a classe base abstrata de todos os tipos de enumeração. Ele fornece vários 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 (que é conhecida como a restrição de enum) para especificar que um parâmetro type é 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 type é 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 converter um valor de um enum para o seu tipo subjacente, o resultado será o valor inteiro associado de um membro do enum.

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 enum com determinado valor associado.

Para qualquer tipo de enumeração, existem conversões de embrulhamento e desembrulhamento para e de o tipo System.Enum, respectivamente.

Especificação da linguagem C#

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

Ver também

  • Last updated on