ostd-pod 0.3.0

A trait for plain old data (POD)
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175

<!--
To promote a "single source of truth", the content of `README.md` is also included in `lib.rs`
as the crate-level documentation. So when writing this README, bear in mind that its content
should be recognized correctly by both a Markdown renderer and the rustdoc tool.
-->

# ostd-pod

A trait and macros for Plain Old Data (POD) types.

This crate provides the [`Pod`] trait, 
which marks types that can be safely converted to and from arbitrary byte sequences. 
It's built on top of the mature [zerocopy] crate to ensure type safety.

## Features

- **Safe Byte Conversion**: POD types can be safely converted to byte sequences and created from
  byte sequences.
- **Based on zerocopy**: Built on top of the [zerocopy] crate for type safety guarantees.
- **Derive Macro Support**: Provides `#[derive(Pod)]` to simplify POD type definitions.
- **Union Support**: Supports union types via the `#[pod_union]` macro.
- **Automatic Padding Management**: Automatically handles padding bytes through the
  `#[padding_struct]` macro.

## What is a POD Type?

A POD (Plain Old Data) type is a type 
that can be safely converted to and from an arbitrary byte sequence. 
For example, primitive types like `u8` and `i16` are POD types; 
yet, `bool` is not a POD type. 
A struct whose fields are POD types is also considered a POD. 
A union whose fields are all POD types is also a POD. 
The memory layout of any POD type is `#[repr(C)]`.

## Quick Start

### Step 1: Edit your `Cargo.toml`

Add these dependencies to your `Cargo.toml`. 

```toml
[dependencies]
ostd-pod = "0.2.0"
zerocopy = { version = "0.8.34", features = ["derive" ] }
```

`zerocopy` must be explicitly specified as a dependency
because `ostd-pod` relies on its procedural macros, 
which expand to compile-time checks that reference internal `zerocopy`
types hardcoded to the `zerocopy` crate name.

### Step 2: Edit your `lib.rs` (or `main.rs`)

Insert the following lines to your `lib.rs` or `main.rs`:

```rust
#[macro_use]
extern crate ostd_pod;
```

We import the `ostd_pod` crate with `extern` and `#[macro_use]`
for the convenience of having Rust's built-in `derive` attribute macro
globally overridden by the custom `derive` attribute macro provided by this crate.
This custom `derive` macro is needed
because the `Pod` trait cannot be derived in the regular way as other traits.

### Step 3: Define your first POD type

Now we can define a POD struct that
can be converted to and from any byte sequence of the same size.

```rust
#[macro_use]
extern crate ostd_pod;
use ostd_pod::{IntoBytes, FromBytes, Pod};

#[repr(C)]
#[derive(Pod, Clone, Copy, Debug, PartialEq)]
struct Point {
    x: i32,
    y: i32,
}

fn main() {
    let point = Point { x: 10, y: 20 };

    // Convert to bytes
    let bytes = point.as_bytes();
    assert_eq!(bytes, &[10, 0, 0, 0, 20, 0, 0, 0]);

    // Create from bytes
    let point2 = Point::from_bytes(bytes);
    assert_eq!(point, point2);
}
```

## Advanced Usage

### Use POD Unions

Union fields cannot be accessed safely because we cannot know which variant is currently active.
To address this, we provide a [`pod_union`] macro
that enables safe access to union fields.

```rust
#[macro_use]
extern crate ostd_pod;
use ostd_pod::{FromZeros, IntoBytes};

#[pod_union]
#[derive(Copy, Clone)]
#[repr(C)]
union Data {
    value: u64,
    bytes: [u8; 4],
}

fn main() {
    let mut data = Data::new_value(0x1234567890ABCDEF);

    // Access the same memory through different fields
    assert_eq!(*data.value(), 0x1234567890ABCDEF);
    assert_eq!(*data.bytes(), [0xEF, 0xCD, 0xAB, 0x90]);
}
```

### Automatic Padding Handling

When a struct has fields with different sizes, 
there may be implicit padding bytes between fields.
The [`padding_struct`] macro automatically inserts explicit padding fields
so the struct can be safely used as a POD type.

```rust
#[macro_use]
extern crate ostd_pod;
use ostd_pod::IntoBytes;

#[repr(C)]
#[padding_struct]
#[derive(Pod, Clone, Copy, Debug, Default)]
struct PackedData {
    a: u8,
    // `padding_struct` automatically inserts 3 bytes of padding here
    b: u32,
    c: u16,
    // `padding_struct` automatically inserts 2 bytes of padding here
}

fn main() {
    let data = PackedData {
        a: 1,
        b: 2,
        c: 3,
        ..Default::default()
    };

    // Can safely convert to bytes, padding bytes are explicitly handled
    let bytes = data.as_bytes();
    assert_eq!(bytes.len(), 12);
    assert_eq!(bytes, [1, 0, 0, 0, 2, 0, 0, 0, 3, 0, 0, 0]);
}
```

## License

This project is licensed under MPL-2.0.

<!--
External links.
-->
[`Pod`]: https://docs.rs/ostd-pod/0.3.0/trait.Pod.html
[`padding_struct`]: https://docs.rs/ostd-pod/0.3.0/attr.padding_struct.html
[`pod_union`]: https://docs.rs/ostd-pod/0.3.0/attr.pod_union.html
[zerocopy]: https://docs.rs/zerocopy/