Enum C#: Value, ToString, Parse, Flags, dan Iterasi

Enum (enumerasi) adalah tipe yang nilainya berupa sekumpulan konstanta bernama yang tetap: status pesanan, hari dalam seminggu, level log. Di baliknya, setiap nama adalah sebuah integer, tetapi sistem tipe mencegah OrderStatus tercampur dengan int biasa atau dengan enum lain.

Mendeklarasikan dan memakai enum

Tuliskan nama-nama member-nya di dalam kurung kurawal. Secara default, yang pertama bernilai 0 dan setiap yang berikutnya bertambah satu:

using System;

enum OrderStatus
{
    Pending,     // 0
    Paid,        // 1
    Shipped,     // 2
    Delivered,   // 3
    Cancelled    // 4
}

class Program
{
    static void Main()
    {
        OrderStatus status = OrderStatus.Paid;
        Console.WriteLine(status);

        status = OrderStatus.Shipped;
        if (status == OrderStatus.Shipped)
            Console.WriteLine("On its way");

        Console.WriteLine(status > OrderStatus.Paid);   // compares the underlying numbers
        Console.WriteLine((int)status);
    }
}

Output:

Paid
On its way
True
2

Enum adalah tipe sungguhan: method yang menerima OrderStatus tidak bisa dipanggil dengan 3 atau dengan LogLevel secara tidak sengaja. Enum adalah tipe value, jadi tidak pernah null dan dibandingkan dengan == berdasarkan nilainya.

Nilai eksplisit dan tipe di baliknya

Kamu bisa menentukan angkanya sendiri. Hal ini penting setiap kali angkanya keluar dari programmu (kolom database, status HTTP, format file), karena mengubah penomoran akan merusak data yang sudah tersimpan:

using System;

enum HttpStatus
{
    Ok = 200,
    Created = 201,
    BadRequest = 400,
    NotFound = 404,
    ServerError = 500
}

enum Priority : byte   // underlying type: byte instead of int
{
    Low = 1,
    Normal = 5,
    High = 10
}

class Program
{
    static void Main()
    {
        int code = (int)HttpStatus.NotFound;       // enum to int
        Console.WriteLine(code);

        var fromDb = (HttpStatus)201;              // int to enum
        Console.WriteLine(fromDb);

        var unknown = (HttpStatus)418;             // no member has 418: still allowed
        Console.WriteLine(unknown);

        Console.WriteLine(sizeof(Priority));
        Console.WriteLine(Enum.GetUnderlyingType(typeof(Priority)).Name);
    }
}

Output:

404
Created
418
1
Byte

Ada dua hal yang perlu diperhatikan. Cast dari int ke enum tidak pernah gagal: (HttpStatus)418 adalah nilai yang valid tetapi tidak punya nama, dan dicetak sebagai angka. Lalu tipe di baliknya bisa berupa tipe integral apa pun (byte, short, long, ...), yang hanya penting untuk kode yang peka terhadap ukuran penyimpanan; int adalah default-nya dan hampir selalu menjadi pilihan yang tepat.

Saat kamu menambahkan member belakangan, tambahkan di akhir atau beri nilai eksplisit. Menyisipkan Refunded di antara Paid dan Shipped diam-diam mengubah angka setiap member setelahnya.

Enum ke string

ToString() mengembalikan nama member-nya, yang juga dipakai oleh Console.WriteLine dan string interpolation. Format string mengubah output-nya:

using System;

enum LogLevel { Debug, Info, Warning, Error }

class Program
{
    static string Label(LogLevel level)
    {
        switch (level)
        {
            case LogLevel.Warning: return "Needs attention";
            case LogLevel.Error: return "Action required";
            default: return "For information";
        }
    }

    static void Main()
    {
        var level = LogLevel.Warning;

        Console.WriteLine(level.ToString());         // name
        Console.WriteLine(level.ToString("D"));      // number
        Console.WriteLine(level.ToString("X"));      // hexadecimal, padded
        Console.WriteLine($"[{level}]");
        Console.WriteLine(nameof(LogLevel.Error));   // compile-time constant
        Console.WriteLine(Enum.GetName(typeof(LogLevel), 3));
        Console.WriteLine(Label(level));
    }
}

Output:

Warning
2
00000002
[Warning]
Error
Error
Needs attention

Nama member adalah identifier, jadi tidak boleh berisi spasi dan tidak diterjemahkan. Untuk teks yang ditampilkan ke pengguna, petakan nilainya sendiri, seperti yang dilakukan Label, atau dengan Dictionary<LogLevel, string>. Sebagian codebase menaruh attribute [Description("Needs attention")] pada setiap member lalu membacanya dengan reflection; halaman reflection dan attribute menunjukkan cara kerja pencarian itu.

String ke enum: Parse dan TryParse

Enum.Parse mengubah nama kembali menjadi nilai dan melempar ArgumentException kalau tidak ada yang cocok. Enum.TryParse mengembalikan false sebagai gantinya, dan itulah yang kamu inginkan untuk input apa pun yang tidak kamu kendalikan:

using System;

enum Size { Small, Medium, Large }

class Program
{
    static void Main()
    {
        var a = (Size)Enum.Parse(typeof(Size), "Large");
        Console.WriteLine(a);

        var b = (Size)Enum.Parse(typeof(Size), "medium", true);   // ignoreCase
        Console.WriteLine(b);

        try
        {
            Enum.Parse(typeof(Size), "Huge");
        }
        catch (ArgumentException)
        {
            Console.WriteLine("Parse threw ArgumentException for Huge");
        }

        foreach (var input in new[] { "small", "XL", "2", "7" })
        {
            Size s;
            bool ok = Enum.TryParse(input, true, out s);
            Console.WriteLine($"{input,-6} parsed={ok,-5} value={s,-6} defined={Enum.IsDefined(typeof(Size), s)}");
        }
    }
}

Output:

Large
Medium
Parse threw ArgumentException for Huge
small  parsed=True  value=Small  defined=True
XL     parsed=False value=Small  defined=True
2      parsed=True  value=Large  defined=True
7      parsed=True  value=7      defined=False

Dua baris terakhir adalah jebakannya. Kedua method menerima string berupa angka, jadi "7" berhasil di-parse menjadi Size yang tidak punya nama. Selain itu, TryParse yang gagal mengisi hasilnya dengan 0, yang di sini adalah Small yang terlihat valid. Saat teksnya berasal dari query string, file konfigurasi, atau form, selalu cek nilai kembaliannya sekaligus Enum.IsDefined:

if (Enum.TryParse(input, true, out Size size) && Enum.IsDefined(typeof(Size), size))
{
    // safe to use size
}

.NET Core 2.0 ke atas menambahkan Enum.Parse<Size>("Large") versi generic yang tidak butuh cast.

Menampilkan semua nilai

Enum.GetValues mengembalikan setiap member, diurutkan berdasarkan nilai numeriknya (dibandingkan sebagai unsigned, jadi member negatif ada di akhir); Enum.GetNames mengembalikan nama-namanya. Begitulah cara kamu mengisi dropdown atau memvalidasi terhadap setiap pilihan:

using System;
using System.Linq;

enum Plan { Free = 0, Starter = 9, Pro = 29, Team = 99 }

class Program
{
    static void Main()
    {
        foreach (Plan p in Enum.GetValues(typeof(Plan)))
            Console.WriteLine($"{p,-8} {(int)p,3} EUR/month");

        Console.WriteLine(string.Join(" | ", Enum.GetNames(typeof(Plan))));

        int paidPlans = Enum.GetValues(typeof(Plan)).Cast<Plan>().Count(p => p != Plan.Free);
        Console.WriteLine($"{paidPlans} paid plans");
    }
}

Output:

Free       0 EUR/month
Starter    9 EUR/month
Pro       29 EUR/month
Team      99 EUR/month
Free | Starter | Pro | Team
3 paid plans

Enum.GetValues(typeof(Plan)) mengembalikan Array biasa, itulah sebabnya ada Cast<Plan>() sebelum LINQ. Di .NET 5 ke atas, Enum.GetValues<Plan>() langsung mengembalikan Plan[] yang bertipe.

Flags: menggabungkan nilai

Sebagian enum menggambarkan sekumpulan pilihan, bukan satu pilihan: izin file, hari buka sebuah toko, saluran notifikasi. Beri setiap member bit-nya sendiri (1, 2, 4, 8, ...), tambahkan None = 0, dan tandai enum-nya dengan [Flags]. Nilainya lalu bisa digabungkan dengan |:

using System;

[Flags]
enum Permissions
{
    None = 0,
    Read = 1,
    Write = 2,
    Delete = 4,
    Share = 8,
    Editor = Read | Write            // named combination
}

class Program
{
    static void Main()
    {
        Permissions user = Permissions.Read | Permissions.Share;
        Console.WriteLine(user);

        user |= Permissions.Write;                  // add
        Console.WriteLine(user);
        Console.WriteLine(user.HasFlag(Permissions.Write));
        Console.WriteLine((user & Permissions.Delete) != 0);

        user &= ~Permissions.Share;                 // remove
        Console.WriteLine(user);
        Console.WriteLine((int)user);

        var parsed = (Permissions)Enum.Parse(typeof(Permissions), "Read, Delete");
        Console.WriteLine(parsed);
        Console.WriteLine(parsed.HasFlag(Permissions.None));   // always true
    }
}

Output:

Read, Share
Editor, Share
True
False
Editor
3
Read, Delete
True

Fungsi setiap operator: | menyalakan bit, & ~X mematikannya, ^ membaliknya, dan (value & X) != 0 atau value.HasFlag(X) mengujinya. HasFlag(X) berarti "semua bit milik X menyala", jadi HasFlag(None) bernilai true untuk setiap nilai, dan HasFlag(Editor) membutuhkan Read dan Write sekaligus.

Perhatikan baris kedua: saat sebuah gabungan bernama mencakup sebagian bit yang menyala, ToString memakainya, jadi Read | Write | Share dicetak sebagai Editor, Share. Ingat hal ini sebelum mem-parse output ToString dengan cara selain Enum.Parse.

Attribute ini tidak mengubah aritmetikanya. Yang diubahnya adalah format: tanpa [Flags], Read | Share dicetak sebagai 9, karena tidak ada satu member pun yang punya nilai itu. Dengan attribute ini, ToString dan Parse sama-sama bekerja dengan bentuk yang dipisahkan koma. Member tetap harus berupa pangkat dua; menulis Read, Write, Delete dengan penomoran default (0, 1, 2) membuat Write | Delete sama dengan 3, nilai yang tidak bermakna.

Switch pada enum

switch adalah cara yang wajar untuk bertindak berdasarkan enum. Sertakan cabang default, karena variabel enum bisa menyimpan nilai tanpa nama:

switch (status)
{
    case OrderStatus.Pending:
    case OrderStatus.Paid:
        return "Preparing";
    case OrderStatus.Shipped:
        return "On the way";
    case OrderStatus.Delivered:
        return "Delivered";
    default:
        return "Unknown";
}

Sejak C# 8, switch expression lebih singkat. Tanpa cabang _, compiler memberi warning: CS8509 saat ada member bernama yang terlewat, dan CS8524 saat semua nama sudah ditangani tetapi nilai tanpa nama seperti (OrderStatus)7 belum:

string text = status switch
{
    OrderStatus.Pending or OrderStatus.Paid => "Preparing",   // 'or' pattern: C# 9
    OrderStatus.Shipped => "On the way",
    OrderStatus.Delivered => "Delivered",
    OrderStatus.Cancelled => "Cancelled",
    _ => throw new ArgumentOutOfRangeException(nameof(status)),
};

Nilai default dan nilai yang tidak terdefinisi

Nilai default setiap enum adalah 0, terlepas dari ada atau tidaknya member dengan nilai itu. Field, elemen array, dan TryParse yang gagal semuanya menghasilkan nilai ini. Rancang dengan memperhitungkan hal itu:

• Jadikan 0 sebagai member "belum diatur" yang bermakna (None, Unknown), bukan pilihan sungguhan. Kalau tidak, field yang belum diinisialisasi diam-diam terbaca sebagai pilihan sungguhan yang pertama.
• Validasi angka dari luar dengan Enum.IsDefined. Untuk enum [Flags], IsDefined mengembalikan false untuk gabungan yang tidak punya nama (Read | Share), jadi periksa bit-nya: (value & ~Permissions.All) == 0 dengan member All yang mencakup setiap bit.

Kesalahan umum

• Hanya mengandalkan TryParse. String berupa angka ikut ter-parse, dan parse yang gagal menghasilkan 0. Tambahkan Enum.IsDefined.
• Mengandalkan penomoran implisit untuk nilai yang disimpan. Menyisipkan member mengubah nomor member setelahnya. Beri nilai eksplisit pada setiap enum yang disimpan.
• Flags tanpa pangkat dua. Penomoran default (0, 1, 2, 3) membuat bit saling tumpang tindih. Pakai 1, 2, 4, 8, atau 1 << n.
• Menampilkan ToString() ke pengguna. Nama member adalah identifier kode. Petakan nilainya ke teks tampilan.
• Tidak ada default di switch. Enum bisa menyimpan nilai di luar member bernamanya.