vendor/zerocopy-0.7.32/README.md - toolchain/rustc - Git at Google

 <!-- Copyright 2022 The Fuchsia Authors

 Licensed under a BSD-style license <LICENSE-BSD>, Apache License, Version 2.0
 <LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0>, or the MIT
 license <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your option.
 This file may not be copied, modified, or distributed except according to
 those terms.

 WARNING: DO NOT EDIT THIS FILE. It is generated automatically. Edits should be
 made in the doc comment on `src/lib.rs` or in `generate-readme.sh`.
 -->

 # zerocopy

 *<span style="font-size: 100%; color:grey;">Want to help improve zerocopy?
 Fill out our [user survey][user-survey]!</span>*

 ***<span style="font-size: 140%">Fast, safe, <span
 style="color:red;">compile error</span>. Pick two.</span>***

 Zerocopy makes zero-cost memory manipulation effortless. We write `unsafe`
 so you don't have to.

 ## Overview

 Zerocopy provides four core marker traits, each of which can be derived
 (e.g., `#[derive(FromZeroes)]`):
 - `FromZeroes` indicates that a sequence of zero bytes represents a valid
   instance of a type
 - `FromBytes` indicates that a type may safely be converted from an
   arbitrary byte sequence
 - `AsBytes` indicates that a type may safely be converted *to* a byte
   sequence
 - `Unaligned` indicates that a type's alignment requirement is 1

 Types which implement a subset of these traits can then be converted to/from
 byte sequences with little to no runtime overhead.

 Zerocopy also provides byte-order aware integer types that support these
 conversions; see the `byteorder` module. These types are especially useful
 for network parsing.

 [user-survey]: https://docs.google.com/forms/d/e/1FAIpQLSdzBNTN9tzwsmtyZxRFNL02K36IWCdHWW2ZBckyQS2xiO3i8Q/viewform?usp=published_options

 ## Cargo Features

 - **`alloc`**
   By default, `zerocopy` is `no_std`. When the `alloc` feature is enabled,
   the `alloc` crate is added as a dependency, and some allocation-related
   functionality is added.

 - **`byteorder`** (enabled by default)
   Adds the `byteorder` module and a dependency on the `byteorder` crate.
   The `byteorder` module provides byte order-aware equivalents of the
   multi-byte primitive numerical types. Unlike their primitive equivalents,
   the types in this module have no alignment requirement and support byte
   order conversions. This can be useful in handling file formats, network
   packet layouts, etc which don't provide alignment guarantees and which may
   use a byte order different from that of the execution platform.

 - **`derive`**
   Provides derives for the core marker traits via the `zerocopy-derive`
   crate. These derives are re-exported from `zerocopy`, so it is not
   necessary to depend on `zerocopy-derive` directly.

   However, you may experience better compile times if you instead directly
   depend on both `zerocopy` and `zerocopy-derive` in your `Cargo.toml`,
   since doing so will allow Rust to compile these crates in parallel. To do
   so, do *not* enable the `derive` feature, and list both dependencies in
   your `Cargo.toml` with the same leading non-zero version number; e.g:

   ```toml
   [dependencies]
   zerocopy = "0.X"
   zerocopy-derive = "0.X"
   ```

 - **`simd`**
   When the `simd` feature is enabled, `FromZeroes`, `FromBytes`, and
   `AsBytes` impls are emitted for all stable SIMD types which exist on the
   target platform. Note that the layout of SIMD types is not yet stabilized,
   so these impls may be removed in the future if layout changes make them
   invalid. For more information, see the Unsafe Code Guidelines Reference
   page on the [layout of packed SIMD vectors][simd-layout].

 - **`simd-nightly`**
   Enables the `simd` feature and adds support for SIMD types which are only
   available on nightly. Since these types are unstable, support for any type
   may be removed at any point in the future.

 [simd-layout]: https://rust-lang.github.io/unsafe-code-guidelines/layout/packed-simd-vectors.html

 ## Security Ethos

 Zerocopy is expressly designed for use in security-critical contexts. We
 strive to ensure that that zerocopy code is sound under Rust's current
 memory model, and *any future memory model*. We ensure this by:
 - **...not 'guessing' about Rust's semantics.**
   We annotate `unsafe` code with a precise rationale for its soundness that
   cites a relevant section of Rust's official documentation. When Rust's
   documented semantics are unclear, we work with the Rust Operational
   Semantics Team to clarify Rust's documentation.
 - **...rigorously testing our implementation.**
   We run tests using [Miri], ensuring that zerocopy is sound across a wide
   array of supported target platforms of varying endianness and pointer
   width, and across both current and experimental memory models of Rust.
 - **...formally proving the correctness of our implementation.**
   We apply formal verification tools like [Kani][kani] to prove zerocopy's
   correctness.

 For more information, see our full [soundness policy].

 [Miri]: https://github.com/rust-lang/miri
 [Kani]: https://github.com/model-checking/kani
 [soundness policy]: https://github.com/google/zerocopy/blob/main/POLICIES.md#soundness

 ## Relationship to Project Safe Transmute

 [Project Safe Transmute] is an official initiative of the Rust Project to
 develop language-level support for safer transmutation. The Project consults
 with crates like zerocopy to identify aspects of safer transmutation that
 would benefit from compiler support, and has developed an [experimental,
 compiler-supported analysis][mcp-transmutability] which determines whether,
 for a given type, any value of that type may be soundly transmuted into
 another type. Once this functionality is sufficiently mature, zerocopy
 intends to replace its internal transmutability analysis (implemented by our
 custom derives) with the compiler-supported one. This change will likely be
 an implementation detail that is invisible to zerocopy's users.

 Project Safe Transmute will not replace the need for most of zerocopy's
 higher-level abstractions. The experimental compiler analysis is a tool for
 checking the soundness of `unsafe` code, not a tool to avoid writing
 `unsafe` code altogether. For the foreseeable future, crates like zerocopy
 will still be required in order to provide higher-level abstractions on top
 of the building block provided by Project Safe Transmute.

 [Project Safe Transmute]: https://rust-lang.github.io/rfcs/2835-project-safe-transmute.html
 [mcp-transmutability]: https://github.com/rust-lang/compiler-team/issues/411

 ## MSRV

 See our [MSRV policy].

 [MSRV policy]: https://github.com/google/zerocopy/blob/main/POLICIES.md#msrv

 ## Changelog

 Zerocopy uses [GitHub Releases].

 [GitHub Releases]: https://github.com/google/zerocopy/releases

 ## Disclaimer

 Disclaimer: Zerocopy is not an officially supported Google product.
	<!-- Copyright 2022 The Fuchsia Authors

	Licensed under a BSD-style license <LICENSE-BSD>, Apache License, Version 2.0
	<LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0>, or the MIT
	license <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your option.
	This file may not be copied, modified, or distributed except according to
	those terms.

	WARNING: DO NOT EDIT THIS FILE. It is generated automatically. Edits should be
	made in the doc comment on `src/lib.rs` or in `generate-readme.sh`.
	-->

	# zerocopy

	*<span style="font-size: 100%; color:grey;">Want to help improve zerocopy?
	Fill out our [user survey][user-survey]!</span>*

	***<span style="font-size: 140%">Fast, safe, <span
	style="color:red;">compile error</span>. Pick two.</span>***

	Zerocopy makes zero-cost memory manipulation effortless. We write `unsafe`
	so you don't have to.

	## Overview

	Zerocopy provides four core marker traits, each of which can be derived
	(e.g., `#[derive(FromZeroes)]`):
	- `FromZeroes` indicates that a sequence of zero bytes represents a valid
	instance of a type
	- `FromBytes` indicates that a type may safely be converted from an
	arbitrary byte sequence
	- `AsBytes` indicates that a type may safely be converted to a byte
	sequence
	- `Unaligned` indicates that a type's alignment requirement is 1

	Types which implement a subset of these traits can then be converted to/from
	byte sequences with little to no runtime overhead.

	Zerocopy also provides byte-order aware integer types that support these
	conversions; see the `byteorder` module. These types are especially useful
	for network parsing.

	[user-survey]: https://docs.google.com/forms/d/e/1FAIpQLSdzBNTN9tzwsmtyZxRFNL02K36IWCdHWW2ZBckyQS2xiO3i8Q/viewform?usp=published_options

	## Cargo Features

	- `alloc`
	By default, `zerocopy` is `no_std`. When the `alloc` feature is enabled,
	the `alloc` crate is added as a dependency, and some allocation-related
	functionality is added.

	- `byteorder` (enabled by default)
	Adds the `byteorder` module and a dependency on the `byteorder` crate.
	The `byteorder` module provides byte order-aware equivalents of the
	multi-byte primitive numerical types. Unlike their primitive equivalents,
	the types in this module have no alignment requirement and support byte
	order conversions. This can be useful in handling file formats, network
	packet layouts, etc which don't provide alignment guarantees and which may
	use a byte order different from that of the execution platform.

	- `derive`
	Provides derives for the core marker traits via the `zerocopy-derive`
	crate. These derives are re-exported from `zerocopy`, so it is not
	necessary to depend on `zerocopy-derive` directly.

	However, you may experience better compile times if you instead directly
	depend on both `zerocopy` and `zerocopy-derive` in your `Cargo.toml`,
	since doing so will allow Rust to compile these crates in parallel. To do
	so, do not enable the `derive` feature, and list both dependencies in
	your `Cargo.toml` with the same leading non-zero version number; e.g:

	```toml
	[dependencies]
	zerocopy = "0.X"
	zerocopy-derive = "0.X"
	```

	- `simd`
	When the `simd` feature is enabled, `FromZeroes`, `FromBytes`, and
	`AsBytes` impls are emitted for all stable SIMD types which exist on the
	target platform. Note that the layout of SIMD types is not yet stabilized,
	so these impls may be removed in the future if layout changes make them
	invalid. For more information, see the Unsafe Code Guidelines Reference
	page on the [layout of packed SIMD vectors][simd-layout].

	- `simd-nightly`
	Enables the `simd` feature and adds support for SIMD types which are only
	available on nightly. Since these types are unstable, support for any type
	may be removed at any point in the future.

	[simd-layout]: https://rust-lang.github.io/unsafe-code-guidelines/layout/packed-simd-vectors.html

	## Security Ethos

	Zerocopy is expressly designed for use in security-critical contexts. We
	strive to ensure that that zerocopy code is sound under Rust's current
	memory model, and any future memory model. We ensure this by:
	- ...not 'guessing' about Rust's semantics.
	We annotate `unsafe` code with a precise rationale for its soundness that
	cites a relevant section of Rust's official documentation. When Rust's
	documented semantics are unclear, we work with the Rust Operational
	Semantics Team to clarify Rust's documentation.
	- ...rigorously testing our implementation.
	We run tests using [Miri], ensuring that zerocopy is sound across a wide
	array of supported target platforms of varying endianness and pointer
	width, and across both current and experimental memory models of Rust.
	- ...formally proving the correctness of our implementation.
	We apply formal verification tools like [Kani][kani] to prove zerocopy's
	correctness.

	For more information, see our full [soundness policy].

	[Miri]: https://github.com/rust-lang/miri
	[Kani]: https://github.com/model-checking/kani
	[soundness policy]: https://github.com/google/zerocopy/blob/main/POLICIES.md#soundness

	## Relationship to Project Safe Transmute

	[Project Safe Transmute] is an official initiative of the Rust Project to
	develop language-level support for safer transmutation. The Project consults
	with crates like zerocopy to identify aspects of safer transmutation that
	would benefit from compiler support, and has developed an [experimental,
	compiler-supported analysis][mcp-transmutability] which determines whether,
	for a given type, any value of that type may be soundly transmuted into
	another type. Once this functionality is sufficiently mature, zerocopy
	intends to replace its internal transmutability analysis (implemented by our
	custom derives) with the compiler-supported one. This change will likely be
	an implementation detail that is invisible to zerocopy's users.

	Project Safe Transmute will not replace the need for most of zerocopy's
	higher-level abstractions. The experimental compiler analysis is a tool for
	checking the soundness of `unsafe` code, not a tool to avoid writing
	`unsafe` code altogether. For the foreseeable future, crates like zerocopy
	will still be required in order to provide higher-level abstractions on top
	of the building block provided by Project Safe Transmute.

	[Project Safe Transmute]: https://rust-lang.github.io/rfcs/2835-project-safe-transmute.html
	[mcp-transmutability]: https://github.com/rust-lang/compiler-team/issues/411

	## MSRV

	See our [MSRV policy].

	[MSRV policy]: https://github.com/google/zerocopy/blob/main/POLICIES.md#msrv

	## Changelog

	Zerocopy uses [GitHub Releases].

	[GitHub Releases]: https://github.com/google/zerocopy/releases

	## Disclaimer

	Disclaimer: Zerocopy is not an officially supported Google product.