Bit field

Declares a class data member with explicit size, in bits. Adjacent bit field members may be packed to share and straddle the individual bytes.

A bit field declaration is a class data member declaration which uses the following declarator:


identifier(optional) attr(optional) `:` size	(1)

identifier(optional) attr(optional) `:` size brace-or-equal-initializer	(2)	(since C++20)

The type of the bit field is introduced by the decl-specifier-seq of the declaration syntax.

attr(C++11)	-	optional sequence of any number of attributes
identifier	-	the name of the bit field that is being declared. The name is optional: nameless bitfields introduce the specified number of bits of padding
size	-	an integral constant expression with a value greater or equal to zero. When greater than zero, this is the number of bits that this bit field will occupy. The value zero is only allowed for nameless bitfields and has special meaning: it specifies that the next bit field in the class definition will begin at an allocation unit's boundary.
brace-or-equal-initializer	-	default member initializer to be used with this bit field

Explanation

The number of bits in a bit field sets the limit to the range of values it can hold:

Run this code

#include <iostream>
struct S {
 // three-bit unsigned field,
 // allowed values are 0...7
 unsigned int b : 3;
};
int main()
{
    S s = {7};
    ++s.b; // unsigned overflow (guaranteed wrap-around)
    std::cout << s.b << '\n'; // output: 0
}

Multiple adjacent bit fields are usually packed together (although this behavior is implementation-defined):

Run this code

#include <iostream>
struct S {
    // will usually occupy 2 bytes:
    // 3 bits: value of b1
    // 2 bits: unused
    // 6 bits: value of b2
    // 2 bits: value of b3
    // 3 bits: unused
    unsigned char b1 : 3, : 2, b2 : 6, b3 : 2;
};
int main()
{
    std::cout << sizeof(S) << '\n'; // usually prints 2
}

The special unnamed bit field of size zero can be forced to break up padding. It specifies that the next bit field begins at the beginning of its allocation unit:

Run this code

#include <iostream>
struct S {
    // will usually occupy 2 bytes:
    // 3 bits: value of b1
    // 5 bits: unused
    // 6 bits: value of b2
    // 2 bits: value of b3
    unsigned char b1 : 3;
    unsigned char :0; // start a new byte
    unsigned char b2 : 6;
    unsigned char b3 : 2;
};
int main()
{
    std::cout << sizeof(S) << '\n'; // usually prints 2
}

If the specified size of the bit field is greater than the size of its type, the value is limited by the type: a std::uint8_t b : 1000; would still hold values between 0 and 255. the extra bits become unused padding.

Because bit fields do not necessarily begin at the beginning of a byte, address of a bit field cannot be taken. Pointers and non-const references to bit fields are not possible. When initializing a const reference from a bit field, a temporary is created (its type is the type of the bit field), copy initialized with the value of the bit field, and the reference is bound to that temporary.

The type of a bit field can only be integral or enumeration type.

A bit field cannot be a static data member.

There are no bit field prvalues: lvalue-to-rvalue conversion always produces an object of the underlying type of the bit field.

There are no default member initializers for bit fields: int b : 1 = 0; and int b : 1 {0} are ill-formed.

(until C++20)

In case of ambiguity between the size of the bit field and the default member initializer, the longest sequence of tokens that forms a valid size is chosen:

int a;
  const int b = 0;
  struct S {
    // simple cases
    int x1 : 8 = 42;               // OK; "= 42" is brace-or-equal-initializer
    int x2 : 8 { 42 };             // OK; "{ 42 }" is brace-or-equal-initializer
    // ambiguities
    int y1 : true ? 8 : a = 42;    // OK; brace-or-equal-initializer is absent
    int y2 : true ? 8 : b = 42;    // error: cannot assign to const int
    int y3 : (true ? 8 : b) = 42;  // OK; "= 42" is brace-or-equal-initializer
    int z : 1 || new int { 0 };    // OK; brace-or-equal-initializer is absent
  };

(since C++20)

Notes

The following properties of bit fields are implementation-defined

The value that results from assigning or initializing a signed bit field with a value out of range, or from incrementing a signed bit field past its range.
Everything about the actual allocation details of bit fields within the class object

For example, on some platforms, bit fields don't straddle bytes, on others they do
Also, on some platforms, bit fields are packed left-to-right, on others right-to-left

Whether char, short, int, long, and long long bit fields that aren't explicitly signed or unsigned are signed or unsigned.

For example, int b:3; may have the range of values 0..7 or -4..3.

(until C++14)

In the C programming language, the width of a bit field cannot exceed the width of the underlying type.

References

C++11 standard (ISO/IEC 14882:2011):

9.6 Bit-fields [class.bit]

C++98 standard (ISO/IEC 14882:1998):

9.6 Bit-fields [class.bit]

Language
Headers
Freestanding and hosted implementations
Named requirements
Language support library
Concepts library (C++20)
Diagnostics library
Utilities library
Strings library
Containers library
Algorithms library
Iterators library
Numerics library
Input/output library
Localizations library
Regular expressions library (C++11)
Atomic operations library (C++11)
Thread support library (C++11)
Filesystem library (C++17)
Technical Specifications

General
overview
class/struct types
union types
injected-class-name
Members
data members
static members
the `this` pointer
nested classes
member templates
bit fields
using-declarations
member functions
member access specifiers
constructors and member initializer lists
default member initializer(C++11)
`friend` specifier
`explicit` specifier
converting constructor
Special member functions
default constructor
copy constructor
move constructor(C++11)
copy assignment operator
move assignment operator(C++11)
destructor
Inheritance
base and derived classes
empty base optimization
virtual member functions
pure virtual functions and abstract classes
override(C++11)
final(C++11)

Bit field

Explanation

Notes

References

See also