What does the [Flags] Enum Attribute mean in C#?

Question

From time to time I see an enum like the following:

[Flags]
public enum Options 
{
    None    = 0,
    Option1 = 1,
    Option2 = 2,
    Option3 = 4,
    Option4 = 8
}

I don't understand what exactly the [Flags] attribute does.

Anyone have a good explanation or example they could post?

Answer 1

This is a really old thread but I wanted to make a comment for anyone else that encounters it in the future. I found this thread while searching for the enum flags attribute after realizing I had implemented my own version of this years ago in C#. I wanted to share how you can do much of this manually if the flags enum doesn't fit your needs, as is my case.

In my case, I needed a way to build a binary array that represents the various fields used to determine the state of an order. Then convert the array to an int and cast to an enum to determine the current status.

I called this a binary-state-machine because I am using it to determine the state of an order using a binary array that I can cast to an enum.

Note:

My enum is not limited to using only binary values from the enum. For example, in a flags enum if you have 1 and 2, I can also add a 3 by combining them [one=1, two=2, three=1&2]. But, in a custom version you can have 7 [1 & 2 & 4) without having 1 or 2 in the enum. You cannot do that with a flags enum. My point is that I can do the same sort of things, but I have more flexibility.

I did not create a ToString() that list ALL the enum values that apply, as I don't need it. That could be added. You could combine both here by adding a second flags enum and take advantage of both approaches. I am doing that in my sample below and it works well.

The sample below is a little long because I am showing you both the custom version and the flags enum. If you remove the flags enum and the associated functions in the struc, you can see the minimum code needed to support a custom version.

For me, this simple logic replaced many hundreds of lines of C# code to determine the status of an order.

using System;

namespace ConsoleApp
{
    internal class BinaryStateMachine
    {

        public Register Reg;

        public void SetRegister()
        {
            // The binary values need to be replaced with business rules to determine the bit values.
            // In my case, I check to see if a given field has been set. For this test, I am hard coding
            // them directly, but the actual app sets them via business rules. I am doing that from a
            // CRM system, so the code wouldn't make any sense here and I removed it.

            Reg.Byte = new int[8];

            Reg.Byte[7] = 0b0; // 
            Reg.Byte[6] = 0b0; // ApplicationDate
            Reg.Byte[5] = 0b0; // EnteredDate
            Reg.Byte[4] = 0b0;
            Reg.Byte[3] = 0b0; // ShippedDate
            Reg.Byte[2] = 0b0; // 
            Reg.Byte[1] = 0b1; // ReadyToShipDateCompleted
            Reg.Byte[0] = 0b1; // FundedDate
        }
        
        private enum SingleLoanStatus : short
        {
            // With the single status values, any combination of status values can be combined to create new status values. PreQual and Funded are examples. 
            NoStatus,
            Completion = 1,                     // 
            Application = 2,                    // ApplicationDate 
            Entered = 4,                        // EnteredDate 
            PreQual = 6,                        // EnteredDate and ApplicationDate
            ShippedToInvestor = 8,              // ShippedDate and ReadyToShipDateCompleted
            Funded = 192
        }

        [Flags]
        private enum MultiLoanStatus : short
        {
            // To support multiple status values, all enums have to be binary bit values... 1, 2, 4, 8, 32, 64, etc.
            NoStatus,
            Completion = 1,                         // 
            Application = 2,                        // ApplicationDate 
            LoanEntered = 4,                        // LoanEnteredDate (not a real status)
            PreQual = Application & LoanEntered,    // LoanEnteredDate and Application Date
            ShippedToInvestor = 8,                  // ShippedDate and ReadyToShipDateCompleted
            ReadyToShip = 64,                       // ShippedDate NULL and ReadyToShipDateCompleted  
            FundedDate = 128,                       // FundedDate 
            Funded = ReadyToShip & FundedDate       // ReadyToShipDateCompleted and FundedDate  
        }
  
        public struct Register
        {
            public int[] Byte;

            public int ToDec() => ToByte();
            public string ToBinary() => Convert.ToString(ToByte(), 2).PadLeft(8, '0');
            //public string ToState() => Convert.ToString((MultiLoanStatus)ToDec()); 

            // Example use the flags enum and my custom version
            public string ToSingleState() => Convert.ToString((SingleLoanStatus)ToDec());
            public string ToMultiState() => Convert.ToString((MultiLoanStatus)ToDec());

            // This is really the key to making this work. 
            // Takes the byte array and converts it to an int that can be used by the enum.
            private int ToByte()
            {
                var data = 0;
                for (var n = 0; n < 8; n += 1)
                    data = (data << 1) + (Byte[n] == 1 ? 1 : 0);
                return data;
            }
        }

        #endregion

    }

}

The code above is setup as a simple test in a console app. To execute it, I am running...

private static void ExecuteBinaryStateMachine()
{
    var state = new BinaryStateMachine();
    state.SetRegister();

    Console.WriteLine($" {state.Reg.ToBinary()} ({state.Reg.ToDec()})");
    Console.WriteLine($" {state.Reg.ToSingleState()}");
    Console.WriteLine($" {state.Reg.ToMultiState()}");
}

Answer 2

Define the Problem

Let’s define an enum that represents the types of users:

public enum UserType
{
    Customer = 1,
    Driver = 2,  
    Admin = 3,
}

We define the UserType enum that contains three values: Customer, Driver, and Admin.

But what if we need to represent a collection of values?

For example, at a delivery company, we know that both the Admin and the Driver are employees. So let’s add a new enumeration item Employee. Later on, we will show you how we can represent both the admin and the driver with it:

public enum UserType
{   
    Customer = 1,
    Driver = 2,  
    Admin = 3,
    Employee = 4
}

Define and Declare a Flags Attribute

A Flags is an attribute that allows us to represent an enum as a collection of values ​​rather than a single value. So, let’s see how we can implement the Flags attribute on enumeration:

[Flags]
public enum UserType
{   
    Customer = 1,
    Driver = 2,  
    Admin = 4,
}

We add the Flags attribute and number the values with powers of 2. Without both, this won’t work.

Now going back to our previous problem, we can represent Employee using the | operator:

var employee = UserType.Driver | UserType.Admin;

Also, we can define it as a constant inside the enum to use it directly:

[Flags]
public enum UserType
{                
    Customer = 1,             
    Driver = 2,               
    Admin = 4,                
    Employee = Driver | Admin
}

Behind the Scenes

To understand the Flags attribute better, we must go back to the binary representation of the number. For example, we can represent 1 as binary 0b_0001 and 2 as 0b_0010:

[Flags]
public enum UserType
{
    Customer = 0b_0001,
    Driver = 0b_0010,
    Admin = 0b_0100,
    Employee = Driver | Admin, //0b_0110
}

We can see that each value is represented in an active bit. And this is where the idea of ​​numbering the values ​​with the power of 2 came from. We can also note that Employee contains two active bits, that is, it is a composite of two values Driver and Admin.

Operations on Flags Attribute

We can use the bitwise operators to work with Flags.

Initialize a Value

For the initialization, we should use the value 0 named None, which means the collection is empty:

[Flags]
public enum UserType
{
    None = 0,
    Customer = 1,
    Driver = 2,
    Admin = 4,
    Employee = Driver | Admin
}

Now, we can define a variable:

var flags = UserType.None;

Add a Value

We can add value by using | operator:

flags |= UserType.Driver;

Now, the flags variable equals Driver.

Remove a Value

We can remove value by use &, ~ operators:

flags &= ~UserType.Driver;

Now, flagsvariable equals None.

We can check if the value exists by using & operator:

Console.WriteLine((flags & UserType.Driver) == UserType.Driver);

The result is False.

Also, we can do this by using the HasFlag method:

Console.WriteLine(flags.HasFlag(UserType.Driver));

Also, the result will be False.

As we can see, both ways, using the & operator and the HasFlag method, give the same result, but which one should we use? To find out, we will test the performance on several frameworks.

Measure the Performance

First, we will create a Console App, and in the .csproj file we will replace the TargetFramwork tag with the TargetFramworks tag:

<TargetFrameworks>net48;netcoreapp3.1;net6.0</TargetFrameworks>
We use the TargetFramworks tag to support multiple frameworks: .NET Framework 4.8, .Net Core 3.1, and .Net 6.0.

Secondly, let’s introduce the BenchmarkDotNet library to get the benchmark results:

[Benchmark]
public bool HasFlag()
{
    var result = false;
    for (int i = 0; i < 100000; i++)
    {
        result = UserType.Employee.HasFlag(UserType.Driver);
    }
    return result;
}
[Benchmark]
public bool BitOperator()
{
    var result = false;
    for (int i = 0; i < 100000; i++)
    {
        result = (UserType.Employee & UserType.Driver) == UserType.Driver;
    }
    return result;
}

We add [SimpleJob(RuntimeMoniker.Net48)], [SimpleJob(RuntimeMoniker.NetCoreApp31)], and [SimpleJob(RuntimeMoniker.Net60)] attributes to the HasFlagBenchmarker class to see the performance differences between different versions of .NET Framework / .NET Core:

Method	Job	Runtime	Mean	Error	StdDev	Median
HasFlag	.NET 6.0	.NET 6.0	37.79 us	3.781 us	11.15 us	30.30 us
BitOperator	.NET 6.0	.NET 6.0	38.17 us	3.853 us	11.36 us	30.38 us
HasFlag	.NET Core 3.1	.NET Core 3.1	38.31 us	3.939 us	11.61 us	30.37 us
BitOperator	.NET Core 3.1	.NET Core 3.1	38.07 us	3.819 us	11.26 us	30.33 us
HasFlag	.NET Framework 4.8	.NET Framework 4.8	2,893.10 us	342.563 us	1,010.06 us	2,318.93 us
BitOperator	.NET Framework 4.8	.NET Framework 4.8	38.04 us	3.920 us	11.56 us	30.17 us

So, in .NET Framework 4.8 a HasFlag method was much slower than the BitOperator. But, the performance improves in .Net Core 3.1 and .Net 6.0. So in newer versions, we can use both ways.

Answer 3

• Flags are used when an enumerable value represents a collection of enum members.

• here we use bitwise operators, | and &

• Example

               [Flags]
               public enum Sides { Left=0, Right=1, Top=2, Bottom=3 }
  
               Sides leftRight = Sides.Left | Sides.Right;
               Console.WriteLine (leftRight);//Left, Right
  
               string stringValue = leftRight.ToString();
               Console.WriteLine (stringValue);//Left, Right
  
               Sides s = Sides.Left;
               s |= Sides.Right;
               Console.WriteLine (s);//Left, Right
  
               s ^= Sides.Right; // Toggles Sides.Right
               Console.WriteLine (s); //Left
  

Answer 4

Apologies if someone already noticed this scenario. A perfect example of flags we can see in reflection. Yes Binding Flags ENUM.

[System.Flags]
[System.Runtime.InteropServices.ComVisible(true)]
[System.Serializable]
public enum BindingFlags

Usage

// BindingFlags.InvokeMethod
// Call a static method.
Type t = typeof (TestClass);

Console.WriteLine();
Console.WriteLine("Invoking a static method.");
Console.WriteLine("-------------------------");
t.InvokeMember ("SayHello", BindingFlags.InvokeMethod | BindingFlags.Public | 
    BindingFlags.Static, null, null, new object [] {});

Answer 5

When working with flags I often declare additional None and All items. These are helpful to check whether all flags are set or no flag is set.

[Flags] 
enum SuitsFlags { 

    None =     0,

    Spades =   1 << 0, 
    Clubs =    1 << 1, 
    Diamonds = 1 << 2, 
    Hearts =   1 << 3,

    All =      ~(~0 << 4)

}

Usage:

Spades | Clubs | Diamonds | Hearts == All  // true
Spades & Clubs == None  // true

 
Update 2019-10:

Since C# 7.0 you can use binary literals, which are probably more intuitive to read:

[Flags] 
enum SuitsFlags { 

    None =     0b0000,

    Spades =   0b0001, 
    Clubs =    0b0010, 
    Diamonds = 0b0100, 
    Hearts =   0b1000,

    All =      0b1111

}

Answer 6

The [Flags] attribute should be used whenever the enumerable represents a collection of possible values, rather than a single value. Such collections are often used with bitwise operators, for example:

var allowedColors = MyColor.Red | MyColor.Green | MyColor.Blue;

Note that the [Flags] attribute doesn't enable this by itself - all it does is allow a nice representation by the .ToString() method:

enum Suits { Spades = 1, Clubs = 2, Diamonds = 4, Hearts = 8 }
[Flags] enum SuitsFlags { Spades = 1, Clubs = 2, Diamonds = 4, Hearts = 8 }

...

var str1 = (Suits.Spades | Suits.Diamonds).ToString();
           // "5"
var str2 = (SuitsFlags.Spades | SuitsFlags.Diamonds).ToString();
           // "Spades, Diamonds"

It is also important to note that [Flags] does not automatically make the enum values powers of two. If you omit the numeric values, the enum will not work as one might expect in bitwise operations, because by default the values start with 0 and increment.

Incorrect declaration:

[Flags]
public enum MyColors
{
    Yellow,  // 0
    Green,   // 1
    Red,     // 2
    Blue     // 3
}

The values, if declared this way, will be Yellow = 0, Green = 1, Red = 2, Blue = 3. This will render it useless as flags.

Here's an example of a correct declaration:

[Flags]
public enum MyColors
{
    Yellow = 1,
    Green = 2,
    Red = 4,
    Blue = 8
}

To retrieve the distinct values in your property, one can do this:

if (myProperties.AllowedColors.HasFlag(MyColor.Yellow))
{
    // Yellow is allowed...
}

or prior to .NET 4:

if((myProperties.AllowedColors & MyColor.Yellow) == MyColor.Yellow)
{
    // Yellow is allowed...
}

if((myProperties.AllowedColors & MyColor.Green) == MyColor.Green)
{
    // Green is allowed...
}    

Under the covers

This works because you used powers of two in your enumeration. Under the covers, your enumeration values look like this in binary ones and zeros:

 Yellow: 00000001
 Green:  00000010
 Red:    00000100
 Blue:   00001000

Similarly, after you've set your property AllowedColors to Red, Green and Blue using the binary bitwise OR | operator, AllowedColors looks like this:

myProperties.AllowedColors: 00001110

So when you retrieve the value you are actually performing bitwise AND & on the values:

myProperties.AllowedColors: 00001110
             MyColor.Green: 00000010
             -----------------------
                            00000010 // Hey, this is the same as MyColor.Green!

The None = 0 value

And regarding the use of 0 in your enumeration, quoting from MSDN:

[Flags]
public enum MyColors
{
    None = 0,
    ....
}

Use None as the name of the flag enumerated constant whose value is zero. You cannot use the None enumerated constant in a bitwise AND operation to test for a flag because the result is always zero. However, you can perform a logical, not a bitwise, comparison between the numeric value and the None enumerated constant to determine whether any bits in the numeric value are set.

You can find more info about the flags attribute and its usage at msdn and designing flags at msdn

Answer 7

In extension to the accepted answer, in C#7 the enum flags can be written using binary literals:

[Flags]
public enum MyColors
{
    None   = 0b0000,
    Yellow = 0b0001,
    Green  = 0b0010,
    Red    = 0b0100,
    Blue   = 0b1000
}

I think this representation makes it clear how the flags work under the covers.

Answer 8

Please see the following for an example which shows the declaration and potential usage:

namespace Flags
{
    class Program
    {
        [Flags]
        public enum MyFlags : short
        {
            Foo = 0x1,
            Bar = 0x2,
            Baz = 0x4
        }

        static void Main(string[] args)
        {
            MyFlags fooBar = MyFlags.Foo | MyFlags.Bar;

            if ((fooBar & MyFlags.Foo) == MyFlags.Foo)
            {
                Console.WriteLine("Item has Foo flag set");
            }
        }
    }
}

Answer 9

To add Mode.Write:

Mode = Mode | Mode.Write;

Answer 10

Flags allow you to use bitmasking inside your enumeration. This allows you to combine enumeration values, while retaining which ones are specified.

[Flags]
public enum DashboardItemPresentationProperties : long
{
    None = 0,
    HideCollapse = 1,
    HideDelete = 2,
    HideEdit = 4,
    HideOpenInNewWindow = 8,
    HideResetSource = 16,
    HideMenu = 32
}

Answer 11

You can also do this

[Flags]
public enum MyEnum
{
    None   = 0,
    First  = 1 << 0,
    Second = 1 << 1,
    Third  = 1 << 2,
    Fourth = 1 << 3
}

I find the bit-shifting easier than typing 4,8,16,32 and so on. It has no impact on your code because it's all done at compile time

Answer 12

There's something overly verbose to me about the if ((x & y) == y)... construct, especially if x AND y are both compound sets of flags and you only want to know if there's any overlap.

In this case, all you really need to know is if there's a non-zero value[1] after you've bitmasked.

[1] See Jaime's comment. If we were authentically bitmasking, we'd only need to check that the result was positive. But since enums can be negative, even, strangely, when combined with the [Flags] attribute, it's defensive to code for != 0 rather than > 0.

Building off of @andnil's setup...

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;

namespace BitFlagPlay
{
    class Program
    {
        [Flags]
        public enum MyColor
        {
            Yellow = 0x01,
            Green = 0x02,
            Red = 0x04,
            Blue = 0x08
        }

        static void Main(string[] args)
        {
            var myColor = MyColor.Yellow | MyColor.Blue;
            var acceptableColors = MyColor.Yellow | MyColor.Red;

            Console.WriteLine((myColor & MyColor.Blue) != 0);     // True
            Console.WriteLine((myColor & MyColor.Red) != 0);      // False                
            Console.WriteLine((myColor & acceptableColors) != 0); // True
            // ... though only Yellow is shared.

            Console.WriteLine((myColor & MyColor.Green) != 0);    // Wait a minute... ;^D

            Console.Read();
        }
    }
}

Answer 13

Combining answers https://stackoverflow.com/a/8462/1037948 (declaration via bit-shifting) and https://stackoverflow.com/a/9117/1037948 (using combinations in declaration) you can bit-shift previous values rather than using numbers. Not necessarily recommending it, but just pointing out you can.

Rather than:

[Flags]
public enum Options : byte
{
    None    = 0,
    One     = 1 << 0,   // 1
    Two     = 1 << 1,   // 2
    Three   = 1 << 2,   // 4
    Four    = 1 << 3,   // 8

    // combinations
    OneAndTwo = One | Two,
    OneTwoAndThree = One | Two | Three,
}

You can declare

[Flags]
public enum Options : byte
{
    None    = 0,
    One     = 1 << 0,       // 1
    // now that value 1 is available, start shifting from there
    Two     = One << 1,     // 2
    Three   = Two << 1,     // 4
    Four    = Three << 1,   // 8

    // same combinations
    OneAndTwo = One | Two,
    OneTwoAndThree = One | Two | Three,
}

---

Confirming with LinqPad:

foreach(var e in Enum.GetValues(typeof(Options))) {
    string.Format("{0} = {1}", e.ToString(), (byte)e).Dump();
}

Results in:

None = 0
One = 1
Two = 2
OneAndTwo = 3
Three = 4
OneTwoAndThree = 7
Four = 8

Answer 14

I asked recently about something similar.

If you use flags you can add an extension method to enums to make checking the contained flags easier (see post for detail)

This allows you to do:

[Flags]
public enum PossibleOptions : byte
{
    None = 0,
    OptionOne = 1,
    OptionTwo = 2,
    OptionThree = 4,
    OptionFour = 8,

    //combinations can be in the enum too
    OptionOneAndTwo = OptionOne | OptionTwo,
    OptionOneTwoAndThree = OptionOne | OptionTwo | OptionThree,
    ...
}

Then you can do:

PossibleOptions opt = PossibleOptions.OptionOneTwoAndThree 

if( opt.IsSet( PossibleOptions.OptionOne ) ) {
    //optionOne is one of those set
}

I find this easier to read than the most ways of checking the included flags.

Answer 15

@Nidonocu

To add another flag to an existing set of values, use the OR assignment operator.

Mode = Mode.Read;
//Add Mode.Write
Mode |= Mode.Write;
Assert.True(((Mode & Mode.Write) == Mode.Write)
  && ((Mode & Mode.Read) == Mode.Read)));