Bit String Functions

Defines
#define	OSRTBYTEARRAYSIZE(numbits)   ((numbits+7)/8)
Functions
OSUINT32	rtxGetBitCount (OSUINT32 value)
int	rtxSetBit (OSOCTET *pBits, OSSIZE numbits, OSSIZE bitIndex)
OSUINT32	rtxSetBitFlags (OSUINT32 flags, OSUINT32 mask, OSBOOL action)
int	rtxClearBit (OSOCTET *pBits, OSSIZE numbits, OSSIZE bitIndex)
OSBOOL	rtxTestBit (const OSOCTET *pBits, OSSIZE numbits, OSSIZE bitIndex)
OSSIZE	rtxLastBitSet (const OSOCTET *pBits, OSSIZE numbits)
int	rtxCheckBitBounds (OSCTXT *pctxt, OSOCTET **ppBits, OSSIZE *pNumocts, OSSIZE minRequiredBits, OSSIZE preferredLimitBits)

---

Detailed Description

Bit string functions allow bits to be set, cleared, or tested in arbitrarily sized byte arrays.

---

Define Documentation

#define OSRTBYTEARRAYSIZE

(

numbits

)

((numbits+7)/8)

This macro is used to calculate the byte array size required to hold the given number of bits.

---

Function Documentation

int rtxCheckBitBounds	(	OSCTXT *	pctxt,
		OSOCTET **	ppBits,
		OSSIZE *	pNumocts,
		OSSIZE	minRequiredBits,
		OSSIZE	preferredLimitBits
	)

Check whether the given bit string is large enough, and expand it if necessary.

Parameters:

	pctxt	The context to use should memory need to be allocated.
	ppBits	*ppBits is a pointer to the bit string, or NULL if one has not been created. If the string is expanded, *ppBits receives a pointer to the new bit string.
	pNumocts	pNumocts points to the current size of the bit string in octets. If the bit string is expanded, *pNumocts receives the new size.
	minRequiredBits	The minimum number of bits needed in the bit string. On return, pBits will point to a bit string with at least this many bits.
	preferredLimitBits	The number of bits over which we prefer not to go. If nonzero, no more bytes will be allocated than necessary for this many bits, unless explicitly required by minRequiredBits.

Returns:

If successful, 0. Otherwise, an error code.

int rtxClearBit	(	OSOCTET *	pBits,
		OSSIZE	numbits,
		OSSIZE	bitIndex
	)

This function clears the specified zero-counted bit in the bit string.

Parameters:

	pBits	Pointer to octets of bit string.
	numbits	Number of bits in the bit string.
	bitIndex	Index of bit to be cleared. The bit with index 0 is a most significant bit in the octet with index 0.

Returns:

If successful, returns the previous state of bit. If bit was set the return value is positive, if bit was not set the return value is zero. Otherwise, return value is an error code:

• RTERR_OUTOFBND = bitIndex is out of bounds

OSUINT32 rtxGetBitCount

(

OSUINT32

value

)

This function returns the minimum size of the bit field required to hold the given integer value.

Parameters:

value

Integer value

Returns:

Minimum size of the the field in bits required to hold value.

OSSIZE rtxLastBitSet	(	const OSOCTET *	pBits,
		OSSIZE	numbits
	)

This function returns the zero-counted index of the last bit set in a bit string.

Parameters:

	pBits	Pointer to the octets of the bit string.
	numbits	The number of bits in the bit string.

Returns:

Index of the last bit set in the bit string.

int rtxSetBit	(	OSOCTET *	pBits,
		OSSIZE	numbits,
		OSSIZE	bitIndex
	)

This function sets the specified zero-counted bit in the bit string.

Parameters:

	pBits	Pointer to octets of bit string.
	numbits	Number of bits in the bit string.
	bitIndex	Index of bit to be set. The bit with index 0 is a most significant bit in the octet with index 0.

Returns:

If successful, returns the previous state of bit. If bit was set the return value is positive, if bit was not set the return value is zero. Otherwise, return value is an error code:

• RTERR_OUTOFBND = bitIndex is out of bounds

OSUINT32 rtxSetBitFlags	(	OSUINT32	flags,
		OSUINT32	mask,
		OSBOOL	action
	)

This function sets one or more bits to TRUE or FALSE in a 32-bit unsigned bit flag set.

Parameters:

	flags	Flags to which mask will be applied.
	mask	Mask with one or more bits set that will be applied to pBitMask.
	action	Boolean action indicating if bits in flags should be set (TRUE) or cleared (FALSE).

Returns:

Updated flags after mask is applied.

OSBOOL rtxTestBit	(	const OSOCTET *	pBits,
		OSSIZE	numbits,
		OSSIZE	bitIndex
	)

This function tests the specified zero-counted bit in the bit string.

Parameters:

	pBits	Pointer to octets of bit string.
	numbits	Number of bits in the bit string.
	bitIndex	Index of bit to be tested. The bit with index 0 is a most significant bit in the octet with index 0.

Returns:

True if bit set or false if not set or array index is beyond range of number of bits in the string.