Class Bits

Implements an efficient array of boolean values that can also perform bit oriented operations such as AND, OR, NOT, XOR.

Inheritance

object

Bits

Namespace: Neon.Collections

Assembly: Neon.Common.dll

Syntax

public class Bits

Remarks

note

This class is similar to the .NET BitArray class. The main difference is that this class serializes the bits to a byte array as you'd expect, with bit zero being the most significant bit of the first byte, bit one being the second significant bit, etc. The BitArray class serializes the first bit to the least significant bit of the first byte.

A Bits bitmap encodes internally as an array of 32-bit integers which is much more memory efficent than how the .NET Framework would encode an array of boolean values. Use the Bits(int) constructor to create a zeroed bitmap with the specified number of bits, Bits(bool[]) to initialize the bitmap from a boolean array, or Bits(string) to create a bitmap from a string of ones and zeros, and Bits(byte[], int) to load a bitmap from a byte array serialized by a previous call to ToBytes().

You can use the indexer to get/set specific bits in the bitmap. Note that all indexes are zero-based. ClearRange(int, int) sets the specified range of bits to zero, SetRange(int, int) sets the specified range of bits to one, and ClearAll() and SetAll() sets all bits to the appropriate value. Resize(int) can be used to resize a bitmap.

The class implements the following bitwise operations: Not(), And(Bits), Or(Bits), Xor(Bits), ShiftLeft(int), and ShiftRight(int). Note that the lengths of the two bitmaps passed to binary operations must be the same.

Clone() returns a copy of the bitmap and ToArray() converts the bitmap into a boolean array. The IsAllZeros and IsAllOnes properties can be used to determine if a bitmap is all zeros or ones and Equals(object) can be used to determine whether two bitmaps are the same. ToString() renders the bitmap as a string of 1s and 0s.

This class also defines explict casts for converting to and from a string of ones and zeros and also defines the bitwise ||, &, ~ and ^, <<, and >> operators.

Constructors

Bits(bool[])

Constructs a bitmap from a boolean array.

Declaration

public Bits(bool[] array)

Parameters

Type	Name	Description
bool[]	array	The array.

Exceptions

Type	Condition
ArgumentNullException	Thrown if array is null.

Bits(byte[])

Constructs a bitmap from a an array of bytes.

Declaration

public Bits(byte[] bytes)

Parameters

Type	Name	Description
byte[]	bytes	The byte array.

Remarks

This constructor is useful for deserializing bitmaps persisted to a binary structure.

Exceptions

Type	Condition
ArgumentNullException	Thrown if bytes is null.

Bits(byte[], int)

Constructs a bitmap from a specified number of bits from an array of bytes.

Declaration

public Bits(byte[] bytes, int length)

Parameters

Type	Name	Description
byte[]	bytes	The byte array.
int	length	Specifies length of the bitmap to be created.

Remarks

This constructor is useful for deserializing bitmaps persisted to a binary structure.

Exceptions

Type	Condition
ArgumentNullException	Thrown if bytes is null.
ArgumentException	Thrown is length is negative.

Bits(int)

Constructs a zeroed bitmap of a specified length.

Declaration

public Bits(int length)

Parameters

Type	Name	Description
int	length	The bitmap length.

Exceptions

Type	Condition
ArgumentException	Thrown is length is negative.

Bits(string)

Constructs a bitmap by parsing a string of 1s and 0s.

Declaration

public Bits(string bitString)

Parameters

Type	Name	Description
string	bitString	The bit string.

Exceptions

Type	Condition
ArgumentNullException	Thrown if bitString is null.
FormatException	Thrown if bitString contains a character other than a 1 or 0.

Properties

IsAllOnes

Returns true if all of the bits are set to ones.

Declaration

public bool IsAllOnes { get; }

Property Value

Type	Description
bool

IsAllZeros

Returns true if all of the bits are set to zeros.

Declaration

public bool IsAllZeros { get; }

Property Value

Type	Description
bool

this[int]

Gets or sets a bit in the bitmap.

Declaration

public bool this[int index] { get; set; }

Parameters

Type	Name	Description
int	index	The zero-based index of the bit.

Property Value

Type	Description
bool	The bit value.

Exceptions

Type	Condition
ArgumentOutOfRangeException	Throw if the index is not in range.

Length

Returns the length of the bitmap.

Declaration

public int Length { get; }

Property Value

Type	Description
int

Methods

And(Bits)

Performs a bitwise and on the bits passed and the current bits and returns the result.

Declaration

public Bits And(Bits bits)

Parameters

Type	Name	Description
Bits	bits	The source Bits.

Returns

Type	Description
Bits	A new Bits instance with the intersection.

Exceptions

Type	Condition
InvalidOperationException	Thrown if the source bitmaps don't have the same length.

ClearAll()

Zeros all bits.

Declaration

public void ClearAll()

ClearRange(int, int)

Zeros a number of bits starting at an index.

Declaration

public void ClearRange(int index, int count)

Parameters

Type	Name	Description
int	index	The start index.
int	count	Number of bits.

Exceptions

Type	Condition
ArgumentOutOfRangeException	Thrown if the index or count is out of range.

Clone()

Returns a clone of the bitmap.

Declaration

public Bits Clone()

Returns

Type	Description
Bits	The cloned copy.

Equals(object)

Determines if the bitmap passed is equal to the current bitmap.

Declaration

public override bool Equals(object obj)

Parameters

Type	Name	Description
object	obj	The instance to be compared.

Returns

Type	Description
bool	true of the bitmaps are equal.

Overrides

object.Equals(object)

GetHashCode()

Computes a hash code for the instance.

Declaration

public override int GetHashCode()

Returns

Type	Description
int	The hash code.

Overrides

object.GetHashCode()

Not()

Returns a bitmap that inverts all the bits of the current bitmap.

Declaration

public Bits Not()

Returns

Type	Description
Bits	The inverted Bits.

Or(Bits)

Performs a bitwise or on the bits passed and the current bits and returns the result.

Declaration

public Bits Or(Bits bits)

Parameters

Type	Name	Description
Bits	bits	The source Bits.

Returns

Type	Description
Bits	A new Bits instance with the union.

Exceptions

Type	Condition
InvalidOperationException	Thrown if the source bitmaps don't have the same length.

Resize(int)

Creates a new bitmap from the current instance, but resized to contain the specified number of bits.

Declaration

public Bits Resize(int length)

Parameters

Type	Name	Description
int	length	The length desired for the new bitmap.

Returns

Type	Description
Bits	The resized bitmap.

Exceptions

Type	Condition
ArgumentException	Thrown if length is negative.

SetAll()

Sets all bits.

Declaration

public void SetAll()

SetRange(int, int)

Sets a number of bits starting at an index.

Declaration

public void SetRange(int index, int count)

Parameters

Type	Name	Description
int	index	The start index.
int	count	Number of bits.

Exceptions

Type	Condition
ArgumentOutOfRangeException	Thrown if the index or count is out of range.

ShiftLeft(int)

Left shifts a bitmap by a number of positions and returns the result.

Declaration

public Bits ShiftLeft(int count)

Parameters

Type	Name	Description
int	count	The number of positions to shift.

Returns

Type	Description
Bits	The shifted bitmap.

Remarks

note

Any bits shifted left past position zero will be lost.

Exceptions

Type	Condition
ArgumentException	Thrown if count is less than zero.

ShiftRight(int)

Right shifts a bitmap by a number of positions and returns the result.

Declaration

public Bits ShiftRight(int count)

Parameters

Type	Name	Description
int	count	The number of positions to shift.

Returns

Type	Description
Bits	The shifted bitmap.

Remarks

note

Any bits shifted right past the end of the bitmap will be lost.

Exceptions

Type	Condition
ArgumentException	Thrown if count is less than zero.

ToArray()

Converts the bitmap into a boolean array.

Declaration

public bool[] ToArray()

Returns

Type	Description
bool[]	The boolean array.

ToBytes()

Converts the bitmap into an array of bytes.

Declaration

public byte[] ToBytes()

Returns

Type	Description
byte[]	The byte array.

Remarks

This method is useful for serializing bitmaps for storage in a binary structure.

ToString()

Renders the bitmap as a string of ones and zeros.

Declaration

public override string ToString()

Returns

Type	Description
string	The bitmap string.

Overrides

object.ToString()

Xor(Bits)

Performs a bitwise xor on the bits passed and the current bits and returns the result.

Declaration

public Bits Xor(Bits bits)

Parameters

Type	Name	Description
Bits	bits	The source Bits.

Returns

Type	Description
Bits	A new Bits instance with the exclusive or results.

Exceptions

Type	Condition
InvalidOperationException	Thrown if the source bitmaps don't have the same length.

Operators

operator &(Bits, Bits)

Returns the intersection of two bitmaps.

Declaration

public static Bits operator &(Bits b1, Bits b2)

Parameters

Type	Name	Description
Bits	b1	The first bitmap.
Bits	b2	The second bitmap.

Returns

Type	Description
Bits	The intersection.

Exceptions

Type	Condition
InvalidOperationException	Thrown if the source bitmaps don't have the same length.

operator |(Bits, Bits)

Returns the union of two bitmaps.

Declaration

public static Bits operator |(Bits b1, Bits b2)

Parameters

Type	Name	Description
Bits	b1	The first bitmap.
Bits	b2	The second bitmap.

Returns

Type	Description
Bits	The union.

Exceptions

Type	Condition
InvalidOperationException	Thrown if the source bitmaps don't have the same length.

operator ==(Bits, Bits)

Determines whether two bitmaps contain the same values.

Declaration

public static bool operator ==(Bits b1, Bits b2)

Parameters

Type	Name	Description
Bits	b1	The first bitmap.
Bits	b2	The second bitmap.

Returns

Type	Description
bool	true if the bitmaps are the same.

operator ^(Bits, Bits)

Returns the exclusive or of two bitmaps.

Declaration

public static Bits operator ^(Bits b1, Bits b2)

Parameters

Type	Name	Description
Bits	b1	The first bitmap.
Bits	b2	The second bitmap.

Returns

Type	Description
Bits	The exclusive-or of the bits.

Exceptions

Type	Condition
InvalidOperationException	Thrown if the source bitmaps don't have the same length.

explicit operator string(Bits)

Casts a Bits instance into a bit string of ones and zeros.

Declaration

public static explicit operator string(Bits bits)

Parameters

Type	Name	Description
Bits	bits	The bitmap.

Returns

Type	Description
string	The bit string.

explicit operator Bits(string)

Casts a bit string of ones and zeros into a Bits bitmap.

Declaration

public static explicit operator Bits(string bitString)

Parameters

Type	Name	Description
string	bitString	The bit string.

Returns

Type	Description
Bits	The bitmap.

Exceptions

Type	Condition
FormatException	Thrown if bitString contains a character other than a 1 or 0.

operator !=(Bits, Bits)

Determines whether two bitmaps do not contain the same values.

Declaration

public static bool operator !=(Bits b1, Bits b2)

Parameters

Type	Name	Description
Bits	b1	The first bitmap.
Bits	b2	The second bitmap.

Returns

Type	Description
bool	true if the bitmaps are the same.

operator <<(Bits, int)

Left shifts a bitmap by a number of positions and returns the result.

Declaration

public static Bits operator <<(Bits input, int count)

Parameters

Type	Name	Description
Bits	input	The input bitmap.
int	count	The number of positions to shift.

Returns

Type	Description
Bits	The shifted bitmap.

Remarks

note

Any bits shifted left past position zero will be lost.

Exceptions

Type	Condition
ArgumentException	Thrown if count is less than zero.

operator ~(Bits)

Returns the bitwise not on a bitmap.

Declaration

public static Bits operator ~(Bits bits)

Parameters

Type	Name	Description
Bits	bits	The source bitmap.

Returns

Type	Description
Bits	The output bitmap.

operator >>(Bits, int)

Right shifts a bitmap by a number of positions and returns the result.

Declaration

public static Bits operator >>(Bits input, int count)

Parameters

Type	Name	Description
Bits	input	The input bitmap.
int	count	The number of positions to shift.

Returns

Type	Description
Bits	The shifted bitmap.

Remarks

note

Any bits shifted right past the end of the bitmap will be lost.

Exceptions

Type	Condition
ArgumentException	Thrown if count is less than zero.