| byte_slice.rs |
Traits for types that encapsulate a `[u8]`.
These traits are used to bound the `B` parameter of [`Ref`]. |
16332 |
| byteorder.rs |
Byte order-aware numeric primitives.
This module contains equivalents of the native multi-byte integer types with
no alignment requirement and supporting byte order conversions.
For each native multi-byte integer type - `u16`, `i16`, `u32`, etc - and
floating point type - `f32` and `f64` - an equivalent type is defined by
this module - [`U16`], [`I16`], [`U32`], [`F32`], [`F64`], etc. Unlike their
native counterparts, these types have alignment 1, and take a type parameter
specifying the byte order in which the bytes are stored in memory. Each type
implements this crate's relevant conversion and marker traits.
These two properties, taken together, make these types useful for defining
data structures whose memory layout matches a wire format such as that of a
network protocol or a file format. Such formats often have multi-byte values
at offsets that do not respect the alignment requirements of the equivalent
native types, and stored in a byte order not necessarily the same as that of
the target platform.
Type aliases are provided for common byte orders in the [`big_endian`],
[`little_endian`], [`network_endian`], and [`native_endian`] submodules.
# Example
One use of these types is for representing network packet formats, such as
UDP:
```rust
use zerocopy::{*, byteorder::network_endian::U16};
# use zerocopy_derive::*;
#[derive(FromBytes, IntoBytes, KnownLayout, Immutable, Unaligned)]
#[repr(C)]
struct UdpHeader {
src_port: U16,
dst_port: U16,
length: U16,
checksum: U16,
}
#[derive(FromBytes, IntoBytes, KnownLayout, Immutable, Unaligned)]
#[repr(C, packed)]
struct UdpPacket {
header: UdpHeader,
body: [u8],
}
impl UdpPacket {
fn parse(bytes: &[u8]) -> Option<&UdpPacket> {
UdpPacket::ref_from_bytes(bytes).ok()
}
}
``` |
53568 |
| deprecated.rs |
Deprecated items. These are kept separate so that they don't clutter up
other modules. |
5940 |
| doctests.rs |
Our UI test framework, built on the `trybuild` crate, does not support
testing for post-monomorphization errors. Instead, we use doctests, which
are able to test for post-monomorphization errors. |
4385 |
| error.rs |
Types related to error reporting.
## Single failure mode errors
Generally speaking, zerocopy's conversions may fail for one of up to three
reasons:
- [`AlignmentError`]: the conversion source was improperly aligned
- [`SizeError`]: the conversion source was of incorrect size
- [`ValidityError`]: the conversion source contained invalid data
Methods that only have one failure mode, like
[`FromBytes::read_from_bytes`], return that mode's corresponding error type
directly.
## Compound errors
Conversion methods that have either two or three possible failure modes
return one of these error types:
- [`CastError`]: the error type of reference conversions
- [`TryCastError`]: the error type of fallible reference conversions
- [`TryReadError`]: the error type of fallible read conversions
## [`Unaligned`] destination types
For [`Unaligned`] destination types, alignment errors are impossible. All
compound error types support infallibly discarding the alignment error via
[`From`] so long as `Dst: Unaligned`. For example, see [`<SizeError as
From<ConvertError>>::from`][size-error-from].
[size-error-from]: struct.SizeError.html#method.from-1
## Accessing the conversion source
All error types provide an `into_src` method that converts the error into
the source value underlying the failed conversion.
## Display formatting
All error types provide a `Display` implementation that produces a
human-readable error message. When `debug_assertions` are enabled, these
error messages are verbose and may include potentially sensitive
information, including:
- the names of the involved types
- the sizes of the involved types
- the addresses of the involved types
- the contents of the involved types
When `debug_assertions` are disabled (as is default for `release` builds),
such potentially sensitive information is excluded.
In the future, we may support manually configuring this behavior. If you are
interested in this feature, [let us know on GitHub][issue-1457] so we know
to prioritize it.
[issue-1457]: https://github.com/google/zerocopy/issues/1457
## Validation order
Our conversion methods typically check alignment, then size, then bit
validity. However, we do not guarantee that this is always the case, and
this behavior may change between releases.
## `Send`, `Sync`, and `'static`
Our error types are `Send`, `Sync`, and `'static` when their `Src` parameter
is `Send`, `Sync`, or `'static`, respectively. This can cause issues when an
error is sent or synchronized across threads; e.g.:
```compile_fail,E0515
use zerocopy::*;
let result: SizeError<&[u8], u32> = std::thread::spawn(|| {
let source = &mut [0u8, 1, 2][..];
// Try (and fail) to read a `u32` from `source`.
u32::read_from_bytes(source).unwrap_err()
}).join().unwrap();
```
To work around this, use [`map_src`][CastError::map_src] to convert the
source parameter to an unproblematic type; e.g.:
```
use zerocopy::*;
let result: SizeError<(), u32> = std::thread::spawn(|| {
let source = &mut [0u8, 1, 2][..];
// Try (and fail) to read a `u32` from `source`.
u32::read_from_bytes(source).unwrap_err()
// Erase the error source.
.map_src(drop)
}).join().unwrap();
```
Alternatively, use `.to_string()` to eagerly convert the error into a
human-readable message; e.g.:
```
use zerocopy::*;
let result: Result<u32, String> = std::thread::spawn(|| {
let source = &mut [0u8, 1, 2][..];
// Try (and fail) to read a `u32` from `source`.
u32::read_from_bytes(source)
// Eagerly render the error message.
.map_err(|err| err.to_string())
}).join().unwrap();
``` |
38090 |
| impls.rs |
|
94050 |
| layout.rs |
|
93376 |
| lib.rs |
|
250822 |
| macros.rs |
/// ...
/// # |
58349 |
| pointer |
|
|
| ref.rs |
|
46194 |
| split_at.rs |
/// ...,
/// # |
32754 |
| util |
|
|
| wrappers.rs |
/// ...
/// # |
29684 |