Enum ב-C#: ערכים, ToString, Parse, Flags ומעבר על הערכים

enum (enumeration) הוא טיפוס שהערכים שלו הם קבוצה קבועה של קבועים עם שמות: סטטוסים של הזמנה, ימים בשבוע, רמות לוג. מתחת לפני השטח כל שם הוא מספר שלם, אבל מערכת הטיפוסים מונעת בלבול בין OrderStatus לבין int רגיל או enum אחר.

הצהרה על enum ושימוש בו

כתבו את שמות האיברים בתוך סוגריים מסולסלים. כברירת מחדל הראשון הוא 0 וכל אחד שאחריו גדול באחד:

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);
    }
}

פלט:

Paid
On its way
True
2

ה-enum הוא טיפוס אמיתי: אי אפשר לקרוא בטעות למתודה שמקבלת OrderStatus עם 3 או עם LogLevel. enums הם טיפוסי ערך, ולכן הם אף פעם לא null ומושווים עם == לפי ערך.

ערכים מפורשים והטיפוס שבבסיס

אפשר להציב מספרים בעצמכם. זה חשוב בכל פעם שהמספר יוצא מהתוכנית שלכם (עמודה במסד נתונים, סטטוס HTTP, פורמט קובץ), כי אז מספור מחדש שובר נתונים מאוחסנים:

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);
    }
}

פלט:

404
Created
418
1
Byte

שני דברים לשים לב אליהם. המרה של int ל-enum אף פעם לא נכשלת: (HttpStatus)418 הוא ערך תקין שפשוט אין לו שם, והוא מודפס כמספר. והטיפוס שבבסיס יכול להיות כל טיפוס שלם (byte, short, long, ...), וזה חשוב רק בקוד שרגיש לאחסון; int היא ברירת המחדל וכמעט תמיד הבחירה הנכונה.

כשמוסיפים איברים בהמשך, הוסיפו אותם בסוף או תנו ערכים מפורשים. הכנסת Refunded בין Paid ל-Shipped משנה בשקט את המספר של כל איבר שאחריו.

enum למחרוזת

ToString() מחזירה את שם האיבר, וזה גם מה ש-Console.WriteLine ו-string interpolation משתמשים בו. מחרוזות פורמט משנות את הפלט:

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));
    }
}

פלט:

Warning
2
00000002
[Warning]
Error
Error
Needs attention

שמות איברים הם מזהים, ולכן הם לא יכולים להכיל רווחים והם לא מתורגמים. לטקסט שמוצג למשתמשים, מפו את הערכים בעצמכם, כמו ש-Label עושה, או עם Dictionary<LogLevel, string>. בחלק מבסיסי הקוד שמים attribute [Description("Needs attention")] על כל איבר וקוראים אותו עם reflection; הדף על reflection ו-attributes מראה איך החיפוש הזה עובד.

מחרוזת ל-enum: Parse ו-TryParse

Enum.Parse ממירה שם בחזרה לערך וזורקת ArgumentException אם שום דבר לא תואם. Enum.TryParse מחזירה false במקום, וזה מה שרוצים לכל קלט שאינו בשליטתכם:

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)}");
        }
    }
}

פלט:

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

שתי השורות האחרונות הן המלכודת. שתי המתודות מקבלות מחרוזות מספריות, כך ש-"7" מתפענח בהצלחה ל-Size שאין לו שם. ו-TryParse שנכשלה מציבה בתוצאה 0, שכאן הוא Small, שנראה תקין. כשהטקסט מגיע מ-query string, מקובץ הגדרות או מטופס, בדקו תמיד גם את ערך ההחזרה וגם את Enum.IsDefined:

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

.NET Core 2.0 ואילך מוסיפות Enum.Parse<Size>("Large") גנרית שלא צריכה cast.

רשימת כל הערכים

Enum.GetValues מחזירה כל איבר, ממוין לפי ערך מספרי (בהשוואה כמספר ללא סימן, כך שאיברים שליליים באים אחרונים); Enum.GetNames מחזירה את השמות שלהם. כך ממלאים רשימה נפתחת או מאמתים מול כל האפשרויות:

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");
    }
}

פלט:

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)) מחזירה Array רגיל, ומכאן ה-Cast<Plan>() לפני LINQ. ב-.NET 5 ואילך, Enum.GetValues<Plan>() מחזירה ישירות Plan[] עם טיפוס.

Flags: שילוב ערכים

חלק מה-enums מתארים קבוצה של אפשרויות ולא בחירה אחת: הרשאות קבצים, הימים שבהם חנות פתוחה, ערוצי התראות. תנו לכל איבר ביט משלו (1, 2, 4, 8, ...), הוסיפו None = 0, וסמנו את ה-enum ב-[Flags]. אז ערכים משתלבים עם |:

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
    }
}

פלט:

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

מה כל אופרטור עושה: | מדליק ביטים, & ~X מכבה אותם, ^ הופך אותם, ו-(value & X) != 0 או value.HasFlag(X) בודקים אותם. HasFlag(X) פירושו "כל הביטים של X דולקים", כך ש-HasFlag(None) נכון לכל ערך, ו-HasFlag(Editor) דורש גם Read וגם Write.

שימו לב לשורה השנייה: כששילוב עם שם מכסה חלק מהביטים הדולקים, ToString משתמשת בו, כך ש-Read | Write | Share מודפס כ-Editor, Share. זכרו את זה לפני שאתם מפענחים את הפלט של ToString עם משהו אחר מלבד Enum.Parse.

ה-attribute לא משנה את החשבון. הוא משנה את העיצוב: בלי [Flags], Read | Share מודפס כ-9, כי לאף איבר בודד אין את הערך הזה. איתו, ToString ו-Parse עובדות שתיהן עם הצורה המופרדת בפסיקים. האיברים עדיין חייבים להיות חזקות של שתיים; כתיבה של Read, Write, Delete עם המספור של ברירת המחדל (0, 1, 2) הופכת את Write | Delete ל-3, ערך חסר משמעות.

switch על enum

switch הוא הדרך הטבעית לפעול לפי enum. כללו ענף default, כי משתנה enum יכול להחזיק ערכים שאין להם שם:

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";
}

מאז C# 8 ביטוי switch קצר יותר. בלי זרוע _ הקומפיילר מזהיר: CS8509 כשחסר איבר עם שם, ו-CS8524 כשכל השמות מטופלים אבל ערכים בלי שם כמו (OrderStatus)7 לא:

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)),
};

ערכי ברירת מחדל וערכים לא מוגדרים

ערך ברירת המחדל של כל enum הוא 0, בין אם יש איבר עם הערך הזה ובין אם לא. שדות, איברי מערך ו-TryParse שנכשלה מפיקים אותו. תכננו בהתאם:

• הפכו את 0 לאיבר "לא הוגדר" בעל משמעות (None, Unknown) ולא לבחירה אמיתית. אחרת שדה שלא אותחל נקרא בשקט כאפשרות האמיתית הראשונה.
• אמתו מספרים שמגיעים מבחוץ עם Enum.IsDefined. ב-enums עם [Flags], IsDefined מחזירה false לשילובים שאין להם שם (Read | Share), אז בדקו את הביטים במקום: (value & ~Permissions.All) == 0 עם איבר All שמכסה כל ביט.

טעויות נפוצות

• הסתמכות על TryParse בלבד. מחרוזות מספריות מתפענחות, ופענוח שנכשל מחזיר 0. הוסיפו Enum.IsDefined.
• הסתמכות על מספור מרומז לערכים מאוחסנים. הכנסת איבר ממספרת מחדש את אלה שאחריו. הציבו ערכים מפורשים לכל enum שנשמר.
• Flags בלי חזקות של שתיים. המספור של ברירת המחדל (0, 1, 2, 3) גורם לחפיפה בביטים. השתמשו ב-1, 2, 4, 8, או ב-1 << n.
• הצגת ToString() למשתמשים. שמות איברים הם מזהים בקוד. מפו ערכים לטקסט תצוגה.
• בלי default ב-switch. enum יכול להחזיק ערכים מחוץ לאיברים עם השמות.