# CBitArray Class Reference

This class encapsulates an array of binary values represented as booleans, where true indicates a bit set to ON and false indicates a bit set to OFF. More...

`#include <xsi_bitarray.h>`

List of all members.

## Public Member Functions
| ~CBitArray ()
| CBitArray (LONG in_size=0)
| CBitArray (const CBitArray &in_str)
| CBitArray (const CBoolArray &in_boolArray)
CBitArray & | operator= (const CBitArray &in_array)
bool | operator== (const CBitArray &in_array) const
bool | operator!= (const CBitArray &in_array) const
const bool | operator[] (LONG in_pos) const
bool | operator[] (LONG in_pos)
CStatus | Add (const bool &in_bVal)
CStatus | Set (LONG in_pos, bool in_bVal)
CStatus | SetAll (bool in_bVal)
CStatus | Resize (LONG in_size, bool in_bVal=false)
CStatus | Clear ()
LONG | GetCount () const
LONG | GetTrueCount () const
bool | IsAny () const
CBitArray & | And (const CBitArray &in_array)
CBitArray & | Or (const CBitArray &in_array)
CBitArray & | XOr (const CBitArray &in_array)
CBitArray & | FlipAll ()
bool | Flip (LONG in_pos)
LONG | GetIterator (LONG in_pos=0) const
bool | GetNextTrueBit (LONG &in_Iterator) const
bool | GetNextFalseBit (LONG &in_Iterator) const

## Detailed Description

This class encapsulates an array of binary values represented as booleans, where true indicates a bit set to ON and false indicates a bit set to OFF.

CBitArray is suitable for dealing with large arrays of boolean values in a compact way. Because CBitArray uses much less memory than CBoolArray would use to represent the same number of bits, it is strongly recommended to use it when a large set of flags are needed.

Since:
  5.0

Example:

              using namespace XSI;
              Application app;
              CBitArray myFlags(10);
              CBitArray myOtherFlags(20);

              myOtherFlags.SetAll(0, true);

              myFlags.Or( myOtherFlags );
              for (LONG i=0; i<myFlags.GetCount(); i++)
              {
                  app.LogMessage( L"myFlags[" + CString(i) + L"] = " + CString(myFlags[i]) );
              }

## Constructor & Destructor Documentation

~CBitArray | ( |  | ) |

Default destructor.

CBitArray | ( | LONG | in_size = `0` | ) |

Constructs a CBitArray object of a specified size. The values are initially set to false. If a size is not supplied, the object is created with no bit values, we must then use CBitArray::Resize to initialize the object.

Parameters:

  | in_size | Number of bit values in the new CBitArray.

CBitArray | ( | const CBitArray & | in_str | ) |

Constructs a CBitArray object that contains bit values copied from another CBitArray object.

Parameters:

  | in_str | Constant CBitArray reference object.

CBitArray | ( | const CBoolArray & | in_boolArray | ) |

Constructs a CBitArray object and initializes it with the values coming from a CBoolArray object.

Parameters:

  | in_boolArray | Constant CBoolArray reference object.

## Member Function Documentation

CBitArray& operator= | ( | const CBitArray & | in_array | ) |

Assignment operator. Copies the bit values of a specified CBitArray to this CBitArray object. This CBitArray is resized to fit the size of the specified CBitArray object.

Parameters:

  | in_array | CBitArray object that we want to assign.

Returns:
  A reference to this CBitArray after it has been modified.

bool operator== | ( | const CBitArray & | in_array | ) | const

Equality operator. Tests if one CBitArray has the same contents as another.

Parameters:

  | in_array | CBitArray with which we want to compare.

Returns:
  True if all elements are the same; false if some or all elements are different.

bool operator!= | ( | const CBitArray & | in_array | ) | const

InEquality operator. Tests if two CBitArrays have different contents.

Parameters:

  | in_array | CBitArray with which we want to compare.

Returns:
  True if all elements are different; false if some or all elements are the same.

const bool operator[] | ( | LONG | in_pos | ) | const

Accessor to bit values at a given position. This function can only be called by constant objects, the returned value is read-only.

Parameters:

  | in_pos | Position in this zero-based array. The position must be smaller than the number of elements in the array, otherwise the results are unpredicted.

Returns:
  A read-only bit value.

bool operator[] | ( | LONG | in_pos | ) |

Array element operator. Gets the bit value at a specified position.

Parameters:

  | in_pos | 0-based position in the array. The result is unpredicted if the position is invalid.

Returns:
  A bit value.

CStatus Add | ( | const bool & | in_bVal | ) |

Adds a bit value at the end of this array.

Parameters:

  | in_bVal | New bit value to be added at the end of the array.

Returns:
  CStatus::OK success

CStatus Set | ( | LONG | in_pos,
|  | bool | in_bVal |
| ) |  |  |

Sets a bit value to true or false at the specified position.

Parameters:

  | in_pos | 0-based position in the array. The result is unpredicted if the position is invalid.
  | in_bVal | The boolean value to assign to the bit value.

Returns:
  CStatus::OK success

  CStatus::InvalidArgument Position is out of bound

CStatus SetAll | ( | bool | in_bVal | ) |

Sets all bit values to true or false.

Parameters:

  | in_bVal | The boolean value to assign to the bit values.

Returns:
  CStatus::OK success

CStatus Resize | ( | LONG | in_size,
|  | bool | in_bVal = `false` |
| ) |  |  |

Reallocates memory for the array, preserves its contents if new size is larger than existing size. The new elements are set to false by default.

Parameters:

  | in_size | New size of the array.
  | in_bVal | If true the new bit values are set to true (ON) or are set to false (OFF) if the value is false.

Returns:
  CStatus::OK success

  CStatus::Fail failure

CStatus Clear | ( |  | ) |

Clears the memory and set the number of bit values to 0.

Returns:
  CStatus::OK success

LONG GetCount | ( |  | ) | const

Returns the number of bit values in the array.

Returns:
  The number of bit values.

LONG GetTrueCount | ( |  | ) | const

Returns the number of bit values in the array set to true.

Returns:
  The number of bit values set to true.

bool IsAny | ( |  | ) | const

Returns true if at least one bit value is set to true.

Returns:
  True if at least one bit value is set to true.

CBitArray& And | ( | const CBitArray & | in_array | ) |

Performs the bitwise AND operation on the bit values in the CBitArray against the corresponding elements in the specified CBitArray. Two bits combined by the AND operator return true if each bit is true; otherwise, their combination returns false. If the input array is smaller, then it is temporarily padded with zeros; otherwise, if the input array is of equal or greater length, the operation is performed up to the length of the object's array.

Parameters:

  | in_array | CBitArray that is to be used to perform the bitwise AND operation.

Returns:
  Reference to this CBitArray object.

CBitArray& Or | ( | const CBitArray & | in_array | ) |

Performs the bitwise OR operation on the bit values in the CBitArray against the corresponding elements in the specified CBitArray. Two bits combined by the OR operator return true if at least one of the bits is true; if both bits are false, their combination returns false. If the input array is smaller, then it is temporarily padded with zeros; otherwise, if the input array is of equal or greater length, the operation is performed up to the length of the object's array.

Parameters:

  | in_array | CBitArray that is to be used to perform the bitwise OR operation.

Returns:
  Reference to this CBitArray object.

CBitArray& XOr | ( | const CBitArray & | in_array | ) |

Performs the bitwise XOR operation on the bit values in the CBitArray against the corresponding elements in the specified CBitArray. Two bits combined by the XOR operator return true if at least one, but not both, of the bits is true; otherwise, their combination returns false. If the input array is smaller, then it is temporarily padded with zeros; otherwise, if the input array is of equal or greater length, the operation is performed up to the length of the object's array.

Parameters:

  | in_array | CBitArray that is to be used to perform the bitwise OR operation.

Returns:
  Reference to this CBitArray object.

CBitArray& FlipAll | ( |  | ) |

Inverts all bit values of this CBitArray object.

Returns:
  Reference to this CBitArray object.

bool Flip | ( | LONG | in_pos | ) |

Inverts the value of a bit value at a specified position.

Parameters:

  | in_pos | 0-based position in the array. The result is unpredicted if the position is invalid.

Returns:
  The new bit value.

LONG GetIterator | ( | LONG | in_pos = `0` | ) | const

Returns an iterator used by the fast bit-lookup functions. This function must be used for getting the right iterator, don't use the bit value position directly as the resulting lookup operations can be unpredictable.

Parameters:

  | in_pos | The position in the array where to start the fast lookup.

Returns:
  A start iterator.

See also:
  CBitArray::GetNextTrueBit, CBitArray::GetNextFalseBit

bool GetNextTrueBit | ( | LONG & | in_Iterator | ) | const

Allows fast bit-lookup operations. It starts at the current iterator position, and looks for the next bit set to true. If the lookup is successful, the bit value position in the array is returned. This position can then be used to access the bit value.

Parameters:

  | in_Iterator | The iterator where the lookup starts. The function sets the iterator with the position of the next bit set to true. If the end of the array is reached, the iterator is set with the total number of bit values in the array.

Returns:
  True if the end of array is reached, false otherwise.

See also:
  CBitArray::GetNextFalseBit, CBitArray::GetIterator

Example:

              using namespace XSI;
              Application app;
              CBitArray bits(512);

              bits.Set( 0, true );
              bits.Set( 32, true );
              bits.Set( 44, true );
              bits.Set( 65, true );
              bits.Set( 312, true );

              LONG it = bits.GetIterator();
              while (bits.GetNextTrueBit(it))
              {
                  app.LogMessage( L"bits[" + CString(it) + L"] = " + CString(bits[it]) );
              }

              // Expected results
              // INFO: bits[0] = true
              // INFO: bits[32] = true
              // INFO: bits[44] = true
              // INFO: bits[65] = true
              // INFO: bits[312] = true

bool GetNextFalseBit | ( | LONG & | in_Iterator | ) | const

This function is similar to CBitArray::GetNextTrueBit, but looks up the bit values set to false instead.

Parameters:

  | in_Iterator | The iterator where the lookup starts. The function sets the iterator with the position of the next bit set to false. If the end of the array is reached, the iterator is set with the total number of bit values in the array.

Returns:
  True if the end of array is reached, false otherwise.

See also:
  CBitArray::GetNextTrueBit, CBitArray::GetIterator

Example:

              using namespace XSI;
              Application app;
              CBitArray bits(512);

              bits.SetAll(true);
              bits.Set( 15, false );
              bits.Set( 31, false );
              bits.Set( 63, false );
              bits.Set( 127, false );
              bits.Set( 255, false );
              bits.Set( 511, false );

              LONG it = bits.GetIterator();
              while (bits.GetNextFalseBit(it))
              {
                  app.LogMessage( L"bits[" + CString(it) + L"] = " + CString(bits[it]) );
              }

              // Expected results
              // INFO: bits[15] = false
              // INFO: bits[31] = false
              // INFO: bits[63] = false
              // INFO: bits[127] = false
              // INFO: bits[255] = false
              // INFO: bits[511] = false

The documentation for this class was generated from the following file:

- xsi_bitarray.h