diff --git a/doc/language-reference.md b/doc/language-reference.md index 40da052..d9e132a 100644 --- a/doc/language-reference.md +++ b/doc/language-reference.md @@ -619,6 +619,20 @@ struct Message: This can be useful as a way to group related fields together. +#### Using `struct` to define a C-like `union` + +Emboss doesn't support C-like `union`s directly via built in type +definitions. However, you can use Emboss's overlapping fields feature to +effectively create a `union`: + +``` +struct Foo: + 0 [+1] UInt a + 0 [+2] UInt b + 0 [+4] UInt c +``` + + #### Automatically-Generated Fields A `struct` will have `$size_in_bytes`, `$max_size_in_bytes`, and @@ -917,6 +931,61 @@ the entire field to be read or written -- something to keep in mind when reading or writing a memory-mapped register space. +#### Anonymous `bits` + +It is possible to use an anonymous `bits` definition directly in a `struct`; +for example: + +``` +struct Message: + [$default byte_order: "BigEndian"] + 0 [+4] UInt message_length + 4 [+4] bits: + 0 [+1] Flag incoming + 1 [+1] Flag last_fragment + 2 [+4] UInt scale_factor + 31 [+1] Flag error +``` + +In this case, the fields of the `bits` will be treated as though they are fields +of the outer struct. + + +#### Inline `bits` + +Like `enum`s, it is also possible to define a named `bits` inline in a `struct` +or `bits`. For example: + +``` +struct Message: + [$default byte_order: "BigEndian"] + 0 [+4] UInt message_length + 4 [+4] bits payload: + 0 [+1] Flag incoming + 1 [+1] Flag last_fragment + 2 [+4] UInt scale_factor + 31 [+1] Flag error +``` + +This is equivalent to: + +``` +struct Message: + [$default byte_order: "BigEndian"] + + bits Payload: + 0 [+1] Flag incoming + 1 [+1] Flag last_fragment + 2 [+4] UInt scale_factor + 31 [+1] Flag error + + 0 [+4] UInt message_length + 4 [+4] Payload payload +``` + +This can be useful as a way to group related fields together. + + #### Automatically-Generated Fields A `bits` will have `$size_in_bits`, `$max_size_in_bits`, and `$min_size_in_bits` @@ -974,61 +1043,6 @@ value as `$size_in_bits`. It is provided for consistency with `$min_size_in_bytes`. -#### Anonymous `bits` - -It is possible to use an anonymous `bits` definition directly in a `struct`; -for example: - -``` -struct Message: - [$default byte_order: "BigEndian"] - 0 [+4] UInt message_length - 4 [+4] bits: - 0 [+1] Flag incoming - 1 [+1] Flag last_fragment - 2 [+4] UInt scale_factor - 31 [+1] Flag error -``` - -In this case, the fields of the `bits` will be treated as though they are fields -of the outer struct. - - -#### Inline `bits` - -Like `enum`s, it is also possible to define a named `bits` inline in a `struct` -or `bits`. For example: - -``` -struct Message: - [$default byte_order: "BigEndian"] - 0 [+4] UInt message_length - 4 [+4] bits payload: - 0 [+1] Flag incoming - 1 [+1] Flag last_fragment - 2 [+4] UInt scale_factor - 31 [+1] Flag error -``` - -This is equivalent to: - -``` -struct Message: - [$default byte_order: "BigEndian"] - - bits Payload: - 0 [+1] Flag incoming - 1 [+1] Flag last_fragment - 2 [+4] UInt scale_factor - 31 [+1] Flag error - - 0 [+4] UInt message_length - 4 [+4] Payload payload -``` - -This can be useful as a way to group related fields together. - - ### `external` An `external` type is used when a type cannot be defined in Emboss itself;