BitField.Extensions 1.0.4

.NET Standard 2.0 .NET Framework 4.5.2

dotnet add package BitField.Extensions --version 1.0.4

NuGet\Install-Package BitField.Extensions -Version 1.0.4

This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.

<PackageReference Include="BitField.Extensions" Version="1.0.4" />

For projects that support PackageReference, copy this XML node into the project file to reference the package.

paket add BitField.Extensions --version 1.0.4

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

#r "nuget: BitField.Extensions, 1.0.4"

#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.

// Install BitField.Extensions as a Cake Addin
#addin nuget:?package=BitField.Extensions&version=1.0.4

// Install BitField.Extensions as a Cake Tool
#tool nuget:?package=BitField.Extensions&version=1.0.4

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

BitField.Extensions

.NET Library For BitField & Enum Extensions

	Description
CREATED BY:	Latency McLaughlin
UPDATED:	4/9/2024
FRAMEWORK:	[net452], [netstandard2.0], [netstandard2.1] ([Latest])
LANGUAGE:	[C#] preview
OUTPUT TYPE:	Library [API]
SUPPORTS:	[Visual Studio]
GFX SUBSYS:	[None]
TAGS:	[BitField BitFields C# Enum Enums Library]
STATUS
LICENSE:
VERSION:

<hr>

<ul> <li><a href="#introduction">Introduction</a></li> <li><a href="#background">Background</a></li> <li><a href="#Understanding">Understanding bit shifting <<</a></li> <li><a href="#operations">Understanding bitwise operations</a></li> <li><a href="#using">Using the code</a></li> <li><a href="#methods">Methods</a></li> <li><a href="#points">Points of Interest</a></li> <li><a href="#references">References</a></li> <li><a href="#installation">Installation</a></li> <li><a href="#license">License</a></li> </ul>

<hr>

<a name="introduction"><h2>Introduction</h2></a>

This article demonstrates a simple use of bit fields as flags for Windows forms. Bit fields allow packaging of data into simple structures, and they are particularly useful when bandwidth, memory or data storage is at a premium. This might not appear to be an issue with modern day equipment or every day applications, but we can save up to 16 times more memory and storage when using bit fields instead of other value types such as boolean.

<a name="background"><h2>Background</h2></a>

<h3>Storage</h3> Consider a boolean value in .NET:<pre lang=cs>bool bVal;</pre> Boolean value data types are stored as 16-bit (2-byte) numbers that can only be true or false. Consider an unsigned 16-bit number which ranges from 0 to 65535:<pre lang=text>Decimal Hexidecimal Binary 0 0x0000 0000000000000000 65535 0xffff 1111111111111111</pre> When numeric data types are converted to boolean values, 0 becomes false and all other values become true. When Boolean values are converted to numeric types, false becomes 0 and true becomes -1 (using a signed number). If we want to use a boolean value to represent a two-state value of a flag or setting in our program (true <=> on, false <=> off), then this would be stored as a 16-bit number. Consider using a binary digit to represent the same two-state value: (1 <=> on, 0 <=> off):<pre lang=text>Decimal Hexidecimal Binary 0 0x0000 0000000000000000 1 0x0001 0000000000000001</pre> We can use this same 16-bit number to represent 16 unique settings by inspecting each digit and determining if it is 1/on or 0/off:<pre lang=text>Decimal Hexidecimal Binary 1 0x0001 0000000000000001 2 0x0002 0000000000000010 4 0x0004 0000000000000100 8 0x0008 0000000000001000 16 0x0010 0000000000010000 32 0x0020 0000000000100000 64 0x0040 0000000001000000 128 0x0080 0000000010000000 256 0x0100 0000000100000000 512 0x0200 0000001000000000 1024 0x0400 0000010000000000 2048 0x0800 0000100000000000 4096 0x1000 0001000000000000 8192 0x2000 0010000000000000 16384 0x4000 0100000000000000 32768 0x8000 1000000000000000</pre> With only 16 settings, this might not appear to be an issue and one would more than likely store the settings as Boolean values, however, storing a history of those settings can quickly add up, and saving space by a factor of 16 can make a difference. Ever tried loading a 100MB file into memory and then manipulating it? How about a 1.6GB file?

<h3>Understanding bit shifting <<</h3>

<pre lang=cs>f1 = 0x01 // 0x01 1 00000001 f2 = f1 << 1, // 0x02 2 00000010 f3 = f2 << 1, // 0x04 4 00000100 f4 = f3 << 1, // 0x08 8 00001000</pre> Shifting to the Left or the Right. There are two operators: <ul> <li><code lang=cs><<</code> for shifting a specified number of bits to the left (towards the "high order" bits) <li><code lang=cs>>></code> for shifting to the right. </li> </ul> If a shift operation causes some number of bits to go outside of an underlying data type, then those bits are discarded. Empty bit positions created by the shift operation are always filled with 0s in a left shift operation and in a positive right shift operation. If a negative number of bit places is requested in a right shift operation <code lang=cs>f2 >> -2</code>, then the vacated bit positions are filled with 1s.

<h3>Understanding bitwise operations</h3>

Bitwise operations are used to manipulate the bit field, and determine if a specified flag is set. The following truth tables illustrate the truth values of some operations:<pre lang=text>Mask OR Flag Mask AND NOT Flag Mask XOR Flag
0 | 0 = 0 0 & ~0 = 0 0 ^ 0 = 0
1 | 0 = 1 1 & ~0 = 1 1 ^ 0 = 1
0 | 1 = 1 0 & ~1 = 0 0 ^ 1 = 1
1 | 1 = 1 1 & ~1 = 0 1 ^ 1 = 0</pre>

<a name="using"><h2>Using the code</h2></a>

The <code>BitField</code> class/structure uses an enumeration to define the flags in the bit field. The field can store up to 64 unique flags using the 64-bit unsigned <code lang=cs>ulong</code> value type. The flags can have any name, but be careful with the <code>Clear</code> flag as this has a special value that is used to clear and fill the entire bit field.<pre lang=cs>[Flags] public enum Flag : ulong { Clear = 0x00, f1 = 0x01, f2 = f1 << 1, . . . }</pre> Each <code>Flag</code> enumeration is a number that in binary form has one digit set to 1 and the rest set to 0. With this enumeration, there are exactly 64 distinct values with a single 1, and 2^64 (18446744073709551616) possible combinations of these 64 flags. Some points to make about <code lang=cs>[FlagsAttribute] == [Flags]</code>: <ul> <li>An enumeration is treated as a bit field; that is, a mask comprised of a set of flags. <li>The results from bitwise operations are also bit fields. <li>Bit fields are generally used for lists of elements that might occur in combination, whereas enumeration constants are generally used for lists of mutually exclusive elements. Therefore, bit fields are designed to be combined to generate unnamed values, whereas enumerated constants are not. </li> </ul> The bit field is stored in the variable <code>_Mask</code>, and external access is provided through the public properties <code lang=cs>get</code> and <code lang=cs>set</code>.<pre lang=cs>private ulong _Mask;
public ulong Mask { get { return _Mask; } set { _Mask = value; } }</pre>

<a name="methods"><h2>Methods</h2></a>

The <code>SetField</code> method sets the specified flag in the mask and turns all other flags off. <ul> <li>Bits that are set to 1 in the flag will be set to one in the mask. <li>Bits that are set to 0 in the flag will be set to zero in the mask. </li> </ul><pre lang=cs>private void SetField(Flag flg) { Mask = (ulong)flg; }</pre> This is particularly useful for setting all bits off using the <code>Flag.Clear</code> flag <code>SetField(Flag.Clear)</code>,<pre lang=text> Mask = Flag.Clear <=> Mask = 0000000000000000000000000000000000000000000000000000000000000000</pre> or setting all bits on using the negation of the <code>Flag.Clear</code> flag <code>SetField(~Flag.Clear)</code>.<pre lang=text> Mask = ~Flag.Clear <=> Mask = ~0000000000000000000000000000000000000000000000000000000000000000 <=> Mask = 1111111111111111111111111111111111111111111111111111111111111111</pre> The <code>SetOn</code> method sets the specified flag(s) in the mask and leaves all other flags unchanged (using the binary bitwise inclusive OR operator). <ul> <li>Bits that are set to 1 in the flag will be set to one in the mask. <li>Bits that are set to 0 in the flag will be unchanged in the mask. </li> </ul><pre lang=cs>public void SetOn(Flag flg) { Mask |= (ulong)flg; }</pre> Since a flag has exactly one digit with a value of 1, and the rest of the digits 0, this will leave the mask unchanged, except for the position(s) where there is a value 1: Consider this operation on a random 16-bit Mask:<pre lang=text> 1101001000011001 OR F2 ------------------------- <=> 1101001000011001 OR 0000000000000010 ------------------------- <=> 1101001000011011</pre> This has the same effect as placing the digit 1 into the appropriate position in the Mask to set the flag to on. The <code>SetOff</code> method sets the specified flag(s) off in the mask and leaves all other flags unchanged (using the unary bitwise complement NOT, followed by the binary bitwise AND operator). <ul> <li>Bits that are set to 1 in the flag will be set to zero in the mask. <li>Bits that are set to 0 in the flag will be unchanged in the mask. </li> </ul><pre lang=cs>public void SetOff(Flag flg) { Mask &= ~(ulong)flg; }</pre> Since a flag has exactly one digit with a value of 1, and the rest of the digits 0, this will leave the mask unchanged, except for the position(s) where there is a value 1: Consider this operation on a random 16-bit Mask:<pre lang=text> 1101001000011001 AND ~F1 -------------------------- <=> 1101001000011001 AND ~0000000000000001 -------------------------- <=> 1101001000011001 AND 1111111111111110 -------------------------- <=> 1101001000011000</pre> This has the same effect as placing the digit 0 into the appropriate position in the Mask to set the flag to off. The <code>SetToggle</code> method toggles the specified flag and leaves all other bits unchanged (using the binary bitwise exclusive OR, XOR operator). <ul> <li>Bits that are set to 1 in the flag will be toggled in the mask. <li>Bits that are set to 0 in the flag will be unchanged in the mask. </li> </ul><pre lang=cs>public void SetToggle(Flag flg) { Mask ^= (ulong)flg; }</pre> Since a flag has exactly one digit with a value of 1, and the rest of the digits 0, this will leave the mask unchanged, except for the position where there is a value 1: Consider this operation on a random 16-bit Mask:<pre lang=text> 1101001000011001 XOR F1 ------------------------- <=> 1101001000011001 XOR 0000000000000001 ------------------------- <=> 1101001000011000</pre> This has the same effect as placing the opposite digit in the appropriate position in the Mask to toggle the flag. Using this flag, we don't have to remember the previous state of the flag. The <code>AnyOn</code> method checks if any of the specified flag(s) are set to on in the mask. It isolates the appropriate digit(s) and returns true if any are non zero, false otherwise.<pre lang=cs>public bool AnyOn (Flag flg) { return (Mask & (ulong)flg) != 0; }</pre> The <code>AllOn</code> method checks if all of the specified flag(s) are set to on in the mask. It isolates the appropriate digit(s) and returns true if they all are non zero, false otherwise.<pre lang=cs>public bool AllOn (Flag flg) { return (Mask & (ulong)flg) == (ulong)flg; }</pre> The <code>IsEqual</code> method checks if all of the specified flag(s) are the same as in the mask. It isolates the appropriate digit(s) and returns true if they are all the same, false otherwise.<pre lang=cs>public bool IsEqual (Flag flg) { return Mask == (ulong)flg; }</pre> The <code>DecimalToFlag</code> method converts a decimal value to a <code>Flag FlagsAttribute</code> value. The input can be a index between 0 and 64, and the output will be the <code>Flag</code> enumeration corresponding to that index. All it does is take the index, and shift a bit that many positions.<pre lang=cs>public static Flag DecimalToFlag(decimal dec) { Flag flg = Flag.Clear; ulong tMsk = 0; byte shift; try { shift = (byte)dec; if (shift > 0 && shift <= 64) tMsk = (ulong) 0x01 << (shift - 1); flg = (Flag)tMsk; } catch (OverflowException e) { //Byte cast operation Console.WriteLine("Exception caught in DecimalToFlag: {0}", e.ToString()); } return flg; }</pre> The three methods <code>ToStringDec</code>, <code>ToStringHex</code>, <code>ToStringBin</code> return a string representation of the mask in decimal, hexadecimal, and binary notation respectively. <h4>Using the BitField class/structure.</h4> Instantiating the object is straight forward:<pre lang=cs>BitField bitField = new BitField();</pre> When creating the <code lang=cs>struct</code> object using the <code lang=cs>new</code> operator, it gets created and the appropriate constructor is called. Unlike classes, <code lang=cs>struct</code>s can be instantiated without using the <code lang=cs>new</code> operator, so if you do not use <code lang=cs>new</code>, the fields will remain unassigned and the object cannot be used until all of the fields are initialized. This will create a new bit field and set all flags off. To set all flags on, you can call the method:<pre lang=cs>bitField.FillField();</pre> To set a flag, use:<pre lang=cs>bitField.SetOff(BitField.Flag.F1); //Flag F1 off bitField.SetOn(BitField.Flag.F1); //Flag F1 on bitField.SetToggle(BitField.Flag.F1); //Flag F1 off bitField.SetToggle(BitField.Flag.F1); //Flag F1 on</pre> To check if a Flag is on, use:<pre lang=cs>if (bitField.IsOn(BitField.Flag.f1)) { Console.WriteLine("Flag F1 is On"); }</pre>

<a name="points"><h2>Points of Interest</h2></a>

The mask value is a 64-bit number that can be stored, retrieved, or passed to other processes and applications that support 64-bit numbers. The <code>BitField</code> class/structure can then be used to retrieve and manipulate the mask. I did not find any resources that explains how bitwise operations are implemented in .NET, and if the operations are implemented efficiently. There might be ways to optimize the code but I have not found a good resource for this yet. It is also important to note that there is some overhead in creating a class object, as classes are reference types and structures are value types. If this is an issue then it is possible to implement the bit field operations directly in your code, but that would defeat the purpose of the object-oriented model. Another option to consider is using a structure instead of the class. A structure can be preferable when: <ul> <li>You have a small amount of data less than 16-bytes, or 128-bits. <li>You perform a large number of operations on each instance and would incur performance degradation with heap management. <li>You have no need to inherit the structure or to specialize functionality among its instances. <li>You do not box and unbox the structure. <li>You are passing blittable data across a managed/unmanaged boundary. </li> </ul> A class is preferable when: <ul> <li>You need to use inheritance and polymorphism. <li>You need to initialize one or more members at creation time. <li>You need to supply an un-parameterized constructor. <li>You need unlimited event handling support. </li> </ul> A similar bit field class and bit field structure are included in the source code and demo project. Depending on the use, it might be preferable to use one over the other. It would be interesting to time them and compare actual results to see under which circumstances and how much more efficiently the system can handle the structure.<a name=history></a>

<a name="references"><h2>References</h2></a>

Edward Smoljanovic, 20 Apr 2004 - Masks and flags using bit fields in .NET

<h2><a name="installation">Installation</a></h2>

This library can be installed using NuGet found here.

<h2><a name="license">License</a></h2>

The source code for the site is licensed under the MIT license, which you can find in the MIT-LICENSE.txt file.

All graphical assets are licensed under the Creative Commons Attribution 3.0 Unported License.

Product	Compatible and additional computed target framework versions.
.NET	net5.0 was computed. net5.0-windows was computed. net6.0 was computed. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net7.0 was computed. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 was computed. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed.
.NET Core	netcoreapp2.0 was computed. netcoreapp2.1 was computed. netcoreapp2.2 was computed. netcoreapp3.0 was computed. netcoreapp3.1 was computed.
.NET Standard	netstandard2.0 is compatible. netstandard2.1 is compatible.
.NET Framework	net452 is compatible. net46 was computed. net461 was computed. net462 was computed. net463 was computed. net47 was computed. net471 was computed. net472 was computed. net48 was computed. net481 was computed.
MonoAndroid	monoandroid was computed.
MonoMac	monomac was computed.
MonoTouch	monotouch was computed.
Tizen	tizen40 was computed. tizen60 was computed.
Xamarin.iOS	xamarinios was computed.
Xamarin.Mac	xamarinmac was computed.
Xamarin.TVOS	xamarintvos was computed.
Xamarin.WatchOS	xamarinwatchos was computed.

Compatible target framework(s)

Included target framework(s) (in package)

Learn more about Target Frameworks and .NET Standard.

.NETFramework 4.5.2
- AssemblyLoader (>= 1.2.0)
- Ranges (>= 1.0.4)
.NETStandard 2.0
- AssemblyLoader (>= 1.2.0)
- Ranges (>= 1.0.4)
.NETStandard 2.1
- AssemblyLoader (>= 1.2.0)

NuGet packages (1)

Showing the top 1 NuGet packages that depend on BitField.Extensions:

Package	Downloads
Interacord Package Description	250

GitHub repositories

This package is not used by any popular GitHub repositories.

Version	Downloads	Last updated
1.0.4	111	4/9/2024
1.0.3	596	1/9/2021
1.0.2	946	9/26/2017
1.0.1	1,003	9/20/2017

Update target framework to include .NET 9.0

BitField.Extensions 1.0.4

BitField.Extensions

.NET Library For BitField & Enum Extensions

Navigation

.NETFramework 4.5.2

.NETStandard 2.0

.NETStandard 2.1

NuGet packages (1)

GitHub repositories