Public Member Functions
CBitArray Class Reference

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]) );
        }

#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

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_sizeNumber 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_strConstant 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_boolArrayConstant 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_arrayCBitArray 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_arrayCBitArray 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_arrayCBitArray 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_posPosition 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_pos0-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_bValNew 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_pos0-based position in the array. The result is unpredicted if the position is invalid.
in_bValThe 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_bValThe 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_sizeNew size of the array.
in_bValIf 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_arrayCBitArray 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_arrayCBitArray 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_arrayCBitArray 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_pos0-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_posThe 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_IteratorThe 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_IteratorThe 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:
Generated on Fri May 11 2012 12:34:17 by doxygen 1.7.4
Please send us your comment about this page