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

A bit-field declaration is aclass data member declaration which uses the following declarator:

Thetype of the bit-field is introduced by thedecl-specifier-seq of thedeclaration syntax.

[edit]Explanation

The type of a bit-field can only be integral (includingbool) or (possibly cv-qualified) enumeration type, an unnamed bit-field cannot be declared with a cv-qualified type.

A bit-field cannot be astatic data member.

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

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

#include <iostream> struct S{// three-bit unsigned field, allowed values are 0...7unsignedint b:3;}; int main(){    S s={6}; ++s.b;// store the value 7 in the bit-fieldstd::cout<< s.b<<'\n'; ++s.b;// the value 8 does not fit in this bit-fieldstd::cout<< s.b<<'\n';// formally implementation-defined, typically 0}

70

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

#include <bit>#include <cstdint>#include <iostream> struct S{// will usually occupy 2 bytes:unsignedchar b1:3;// 1st 3 bits (in 1st byte) are b1unsignedchar:2;// next 2 bits (in 1st byte) are blocked out as unusedunsignedchar b2:6;// 6 bits for b2 - doesn't fit into the 1st byte => starts a 2ndunsignedchar b3:2;// 2 bits for b3 - next (and final) bits in the 2nd byte}; int main(){std::cout<< sizeof(S)<<'\n';// usually prints 2     S s;// set distinguishable field values    s.b1=0b111;    s.b2=0b101111;    s.b3=0b11; // show layout of fields in Sauto i=std::bit_cast<std::uint16_t>(s);// usually prints 1110000011110111// breakdown is:  └┬┘├┘└┬┘└─┬──┘└┤//                b1 u  a   b2  b3// where “u” marks the unused :2 specified in the struct, and// “a” marks compiler-added padding to byte-align the next field.// Byte-alignment is happening because b2's type is declared unsigned char;// if b2 were declared uint16_t there would be no “a”, b2 would abut “u”.for(auto b= i; b; b>>=1)// print LSB-firststd::cout<<(b&1);std::cout<<'\n';}

21110000011110111

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:

#include <iostream> struct S{// will usually occupy 2 bytes:// 3 bits: value of b1// 5 bits: unused// 2 bits: value of b2// 6 bits: unusedunsignedchar b1:3;unsignedchar:0;// start a new byteunsignedchar b2:2;}; int main(){std::cout<< sizeof(S)<<'\n';// usually prints 2// would usually print 1 if not for// the padding break in line 11}

2

If the specified size of the bit-field is greater than the size of its type, the value is limited by the type: astd::uint8_t b:1000; would still hold values in the range[​0​, 255]. The extra bits arepadding bits.

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. Wheninitializing 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.

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

[edit]Notes

The following properties of bit-fields areimplementation-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.

In the C programming language, the width of a bit-field cannot exceed the width of the underlying type, and whetherint bit-fields that are not explicitlysigned orunsigned are signed or unsigned is implementation-defined. For example,int b:3; may have the range of values[​0​, 7] or[-4, 3] in C, but only the latter choice is allowed in C++.

[edit]Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

[edit]References

[edit]See also

• In other languages

• Español
• 日本語
• Русский
• 中文