bdlb_bitmaskutil

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Usage
    • Example 1: Creation of Simple Bit Masks

Purpose

Provide simple mask values of uint32_t and uint64_t types.

Classes

• bdlb::BitMaskUtil: namespace for bit-level mask operations

Description

This component provides a utility struct, bdlb::BitMaskUtil, that serves as a namespace for a collection of functions that provide simple binary masks.

Usage

This section illustrates intended use of this component.

Example 1: Creation of Simple Bit Masks

The following usage examples illustrate how some of the methods provided by this component are used. Note that, in all of these examples, the low-order bit is considered bit 0 and resides on the right edge of the bit string.

First, the ge function takes a single argument, index, and returns a bit mask with all bits below the specified index cleared and all bits at or above the index set:

+-------------------------------------------------------------------------+
| 'bdlb::BitMaskUtil::ge(16)' in binary:                                  |
|                                                                         |
| 'index': bit 16:                                      *                 |
| All bits at and above bit 16 are set:  11111111111111110000000000000000 |
+-------------------------------------------------------------------------+
 
const uint32_t expGe = 0xffff0000;
assert(expGe == bdlb::BitMaskUtil::ge(16));

Next, the lt function returns a bit mask with all bits at or above the specified index cleared, and all bits below index set. lt and ge return the complement of each other if passed the same index:

+-------------------------------------------------------------------------+
| 'bdlb::BitMaskUtil::lt(16)' in binary:                                  |
|                                                                         |
| 'index': bit 16:                                      *                 |
| All bits below bit 16 are set:         00000000000000001111111111111111 |
+-------------------------------------------------------------------------+
 
const uint32_t expLt = 0x0000ffff;
assert(expLt == bdlb::BitMaskUtil::lt(16));
 
assert(expGe == ~expLt);

Then, the eq function returns a bit mask with only the bit at the specified index set:

+-------------------------------------------------------------------------+
| 'bdlb::BitMaskUtil::eq(23)' in binary:                                  |
|                                                                         |
| 'index': bit 23:                               *                        |
| Only bit 23 is set:                    00000000100000000000000000000000 |
+-------------------------------------------------------------------------+
 
const uint32_t expEq = 0x00800000;
assert(expEq == bdlb::BitMaskUtil::eq(23));

Now, the ne function returns a bit mask with only the bit at the specified index cleared. ne and eq return the complement of each other for a given index:

+-------------------------------------------------------------------------+
| 'bdlb::BitMaskUtil::ne(23)' in binary:                                  |
|                                                                         |
| 'index': bit 23:                               *                        |
| All bits other than bit 16 are set:    11111111011111111111111111111111 |
+-------------------------------------------------------------------------+
 
const uint32_t expNe = 0xff7fffff;
assert(expNe == bdlb::BitMaskUtil::ne(23));
 
assert(expEq == ~expNe);

Finally, one and zero return a bit mask with all bits within a specified range starting from a specified index either set or cleared, respectively. For the same arguments, one and zero return the complement of each other:

+-------------------------------------------------------------------------+
| 'bdlb::BitMaskUtil::one(16, 4)' in binary:                              |
|                                                                         |
| bit 16:                                               *                 |
| 4 bits starting at bit 16:                         ****                 |
| Result: only those bits set:           00000000000011110000000000000000 |
+-------------------------------------------------------------------------+
 
const uint32_t expOne = 0x000f0000;
assert(expOne == bdlb::BitMaskUtil::one(16, 4));
 
+-------------------------------------------------------------------------+
| 'bdlb::BitMaskUtil::zero(16, 4)' in binary:                             |
|                                                                         |
| bit 16:                                               *                 |
| 4 bits starting at bit 16:                         ****                 |
| Result: only those bits cleared:       11111111111100001111111111111111 |
+-------------------------------------------------------------------------+
 
const uint32_t expZero = 0xfff0ffff;
assert(expZero == bdlb::BitMaskUtil::zero(16, 4));
 
assert(expZero == ~expOne);