Proposal: Rename `packed` keyword to `bitpacked`

[ikskuh]

Accepted Proposal

---

As Zig is a lot about communication, we should probably rename packed struct into something that represents more what it actually is.

Right now, a lot of people assume that packed struct follows similar rules as regular or extern structs, which isn't true anymore with stage2. Thus, a lot of confusion is created and people misuse packed structs accidently or try to solve problems with them where extern struct is the right hammer.

I propose to change the name of packed struct into something that clearly represents what it is. My current best guess would be bitrecord or bitfield, and respectivly rename packed union to bitunion (which is not a good name).

This change is also a good idea as you cannot put arrays or pointers into packed structs

[dee0xeed]

This change is also a good idea as you cannot put arrays or pointers into packed structs

I would say there is no need at all to hold pointers in packed structs - for me they are just very convenient feature when dealing with various binary network protocols or binary file formats.

I think bitfield would have been ideal, if it weren't for the analogous bitunion, which is quite terrible. Maybe the same clarification value can be achieved by renaming packed to bitpacked? Thinking further, extern could then become bytepacked.

[leecannon]

@zzyxyzz extern are not byte packed, you have to add explicit align(1) to non-byte aligned fields to get that behaviour

const HasPadding = extern struct {
    b: bool,
    n: u32,

    comptime {
        std.debug.assert(@sizeOf(HasPadding) == 8);
    }
};

const NoPadding = extern struct {
    b: bool,
    n: u32 align(1),

    comptime {
        std.debug.assert(@sizeOf(NoPadding) == 5);
    }
};

@leecannon, thanks for the correction.
In that case, bytepacked could become an independent qualifier rather than replacing extern.

[eLeCtrOssSnake]

tl;dr; I think both names show exact purpose and are fine. I am against changing them.

extern struct - struct for usage in external modules/code/functions thus "extern". packed struct means bitpacked, which means it bitpacks integers. I think both names nail their task 100%. Andre Weissflog said on zig discord that he mistook packed struct with attribute((packed)) in C. But if we follow the zig philosophy then we shouldn't continue to carry this legacy into zig. Because we already have align(1). Packed means a different thing in zig and it's fine.

[ikskuh]

Andre Weissflog said on zig discord that he mistook packed struct with __attribute__((packed)) in C.

That's exactly what this is about. packed in C means byte packed. packed in Zig means bitpacked. This is an arbitrary choice and both are 100% legal choices. packed in Zig does not convey the information that it is bitpacked, and it's afaik the only language doing this right now. All other languages use bitfield or similar for this kind of construct.

extern in Zig also does not mean "external module/codes/functions", but "well defined memory layout based on the natural alignment of types". Using extern here isn't perfect, but doesn't spark as much confusion as packed. Even people using Zig for longer times confuse this all the time, which means we have a readability defect in the language.

[eLeCtrOssSnake]

Andre Weissflog said on zig discord that he mistook packed struct with __attribute__((packed)) in C.

That's exactly what this is about. packed in C means byte packed. packed in Zig means bitpacked. This is an arbitrary choice and both are 100% legal choices. packed in Zig does not convey the information that it is bitpacked, and it's afaik the only language doing this right now. All other languages use bitfield or similar for this kind of construct.

extern in Zig also does not mean "external module/codes/functions", but "well defined memory layout based on the natural alignment of types". Using extern here isn't perfect, but doesn't spark as much confusion as packed. Even people using Zig for longer times confuse this all the time, which means we have a readability defect in the language.

I don't understand the difference between extern and packed being a different level of readability defect because extern serves as much of a different purpose in Zig compared to C as packed.

[eLeCtrOssSnake]

The whole argument is that somebody confuses packed with C packed and now suddenly we have to change it. But we're not C. We're a different language.

The whole argument is that somebody confuses packed with C packed and now suddenly we have to change it. But we're not C. We're a different language.

I would argue that this issue goes deeper than naming and superficial differences between languages. I feel that bitpacking, while certainly a useful feauture, is the wrong default for dense, fixed-layout structures due to their limited composability: you cannot embed arrays or other non-packed structs, and you can have neither field pointers nor pointer fields. Byte-packed structs have none of these problems and should be the default packed layout unless you plan to do actual bit slicing.

However, since the packed struct semantics was changed, Zig no longer has a linear byte-packed struct. Yes, you can use extern with align(1), but besides being a bit of a pain, it is an abuse of a type intended for something else. From the documentation:

An extern struct has in-memory layout guaranteed to match the C ABI for the target. This kind of struct should only be used for compatibility with the C ABI.

extern struct does not actually guarantee any fixed layout, and even if it did, you'd have to know some details about the C ABI to be sure.

The expectation that packed struct should behave like _attribute__((packed)) is not just an accident of history. It actually makes sense. Hence I'd be very much in favor of reintroducing byte-packed struct semantics alongside bitfield, possibly with a syntax like packed(.bit), packed(.byte), packed(.C) as suggested by @tleydxdy in the other thread.

[eLeCtrOssSnake]

The whole argument is that somebody confuses packed with C packed and now suddenly we have to change it. But we're not C. We're a different language.

I would argue that this issue goes deeper than naming and superficial differences between languages. I feel that bitpacking, while certainly a useful feauture, is the wrong default for dense, fixed-layout structures due to their limited composability: you cannot embed arrays or other non-packed structs, and you can have neither field pointers nor pointer fields. Byte-packed structs have none of these problems and should be the default packed layout unless you plan to do actual bit slicing.

However, since the packed struct semantics was changed, Zig no longer has a linear byte-packed struct. Yes, you can use extern with align(1), but besides being a bit of a pain, it is an abuse of a type intended for something else. From the documentation:

An extern struct has in-memory layout guaranteed to match the C ABI for the target. This kind of struct should only be used for compatibility with the C ABI.

extern struct does not actually guarantee any fixed layout, and even if it did, you'd have to know some details about the C ABI to be sure.

The expectation that packed struct should behave like _attribute__((packed)) is not just an accident of history. It actually makes sense. Hence I'd be very much in favor of reintroducing byte-packed struct semantics alongside bitfield, possibly with a syntax like packed(.bit), packed(.byte), packed(.C) as suggested by @tleydxdy in the other thread.

Yes, there are things to clarify. extern struct actually won't depend on C ABI if you don't use C types. This is kind of unwritten rule as of now. packed struct makes a compact memory representation and it doesn't guarantee memory layout.
While I still do not agree that packed struct and attribute((packed)) should mean the same thing, I do think we can do better by clarifying which semantics are for what purpose. For example default packed struct is compact representation of a struct by bitpacking, extern struct is for C ABI compatibility and/or guaranteed memory layout.

My proposal is to make clarify that extern can also be used for guarenteed memory layout, packed is NOT attribute((packed)), and for alignning to 1 you should do extern align(1).
I don't see how changing packed or extern keywords for struct would somehow reduce confusion.

edit:
And I think that making "packed(.bit), packed(.byte), packed(.C)" WILL FURTHER more cause confusion because for aligning semantics we already have align()

[praschke]

Right now, a lot of people assume that packed struct follows similar rules as regular or extern structs, which isn't true anymore with stage2. Thus, a lot of confusion is created and people misuse packed structs accidently or try to solve problems with them where extern struct is the right hammer.

I think before changing the name based on peoples' confusion, the documentation for extern struct should perhaps first be changed from

This kind of struct should only be used for compatibility with the C ABI. Every other use case should be solved with packed struct or normal struct.

With such a skeletal and foreboding warning, I don't think it is any wonder people think packed struct is what you should use for defining file headers and such.

EDIT: I will admit, I wouldn't be against this proposal if bitunion wasn't such a terrible name. The documentation needs to be fleshed out either way.

[candrewlee14]

How about just renaming packed to bitfield? Then it’d bebitfield struct and bitfield union, with no bitunion.