XSI::CBitArray

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: