Merge pull request #67 from hashmismatch/rust_2018

Rust 2018 updates, readme update

Author: rudib

README.md

@@ -5,13 +5,13 @@ Bit-level packing and unpacking for Rust
 [![Documentation](https://docs.rs/packed_struct/badge.svg)](https://docs.rs/packed_struct)
 ![master](https://github.com/hashmismatch/packed_struct.rs/workflows/Rust/badge.svg)
 
-## Introduction
+# Introduction
 
 Packing and unpacking bit-level structures is usually a programming tasks that needlessly reinvents the wheel. This library provides
 a meta-programming approach, using attributes to define fields and how they should be packed. The resulting trait implementations
 provide safe packing, unpacking and runtime debugging formatters with per-field documentation generated for each structure.
 
-## Features
+# Features
 
  * Plain Rust structures, decorated with attributes
  * MSB or LSB integers of user-defined bit widths
@@ -23,29 +23,32 @@ provide safe packing, unpacking and runtime debugging formatters with per-field
  * Arrays of packed structures as fields
  * Reserved fields, their bits are always 0 or 1
 
-## Sample usage
+# Crate-level feature flags
+ * `std`: use the Rust standard library. Default.
+ * `alloc`: use the `alloc` crate for `no_std` + `alloc` scenarios. Requires nightly Rust.
+ * `use_serde`: add serialization support to the built-in helper types.
+ * `byte_types_64`, `byte_types_256`: enlarge the size of the generated array, byte and bit width types.
 
-### Cargo.toml
+# Sample usage
+
+## Cargo.toml
 
 ```toml
 [dependencies]
-packed_struct = "0.4"
-packed_struct_codegen = "0.4"
+packed_struct = "0.5"
 ```
-### Including the library and the code generator
+## Importing the library with the the most common traits and the derive macros
 
 ```rust
-extern crate packed_struct;
-#[macro_use]
-extern crate packed_struct_codegen;
+// This is only needed for pre Rust 2018
+#[macro_use] extern crate packed_struct;
+// Prelude import with the common imports
+use packed_struct::prelude::*;
 ```
 
-### Example of a single-byte structure, with a 3 bit integer, primitive enum and a bool field.
+## Example of a single-byte structure, with a 3 bit integer, primitive enum and a bool field.
 
 ```rust
-extern crate packed_struct;
-#[macro_use] extern crate packed_struct_codegen;
-
 use packed_struct::prelude::*;
 
 #[derive(PackedStruct)]
@@ -91,13 +94,12 @@ fn main() -> Result<(), PackingError> {
 }
 ```
 
-## Packing attributes
+# Packing attributes
 
-### Syntax
+## Syntax
 
 ```rust
-extern crate packed_struct;
-#[macro_use] extern crate packed_struct_codegen;
+use packed_struct::prelude::*;
 
 #[derive(PackedStruct)]
 #[packed_struct(attr1="val", attr2="val")]
@@ -107,15 +109,15 @@ pub struct Structure {
 }
 ```
 
-### Per-structure attributes
+## Per-structure attributes
 
 Attribute | Values | Comment
 :--|:--|:--
 ```size_bytes``` | ```1``` ... n | Size of the packed byte stream
 ```bit_numbering``` | ```msb0``` or ```lsb0``` | Bit numbering for bit positioning of fields. Required if the bits attribute field is used.
 ```endian``` | ```msb``` or ```lsb``` | Default integer endianness
 
-### Per-field attributes
+## Per-field attributes
 
 Attribute | Values | Comment
 :--|:--|:--
@@ -128,7 +130,7 @@ Attribute | Values | Comment
 ```ty``` | ```enum``` | Packing helper for primitive enums.
 ```endian``` | ```msb``` or ```lsb``` | Integer endianness. Applies to u16/i16 and larger types.
 
-### Bit and byte positioning
+## Bit and byte positioning
 
 Used for either ```bits``` or ```bytes``` on fields. The examples are for MSB0 positioning.
 
@@ -139,14 +141,11 @@ Value | Comment
 ```0..2``` | Exclusive range, bits zero and one
 ```0:1```, ```0..=1``` | Inclusive range, bits zero and one
 
-## More examples
+# More examples
 
-### Mixed endian integers
+## Mixed endian integers
 
 ```rust
-extern crate packed_struct;
-#[macro_use] extern crate packed_struct_codegen;
-
 use packed_struct::prelude::*;
 
 #[derive(PackedStruct)]
@@ -169,12 +168,9 @@ fn main() -> Result<(), PackingError> {
 }
 ```
 
-### 24 bit LSB integers
+## 24 bit LSB integers
 
 ```rust
-extern crate packed_struct;
-#[macro_use] extern crate packed_struct_codegen;
-
 use packed_struct::prelude::*;
 
 #[derive(PackedStruct)]
@@ -194,12 +190,9 @@ fn main() -> Result<(), PackingError> {
 }
 ```
 
-### Nested packed types within arrays
+## Nested packed types within arrays
 
 ```rust
-extern crate packed_struct;
-#[macro_use] extern crate packed_struct_codegen;
-
 use packed_struct::prelude::*;
 
 #[derive(PackedStruct, Default, Debug, PartialEq)]
@@ -235,15 +228,14 @@ fn main() -> Result<(), PackingError> {
 }
 ```
 
-## Primitive enums with simple discriminants
+# Primitive enums with simple discriminants
 
 Supported backing integer types: ```u8```, ```u16```, ```u32```, ```u64```, ```i8```, ```i16```, ```i32```, ```i64```.
 
 Explicit or implicit backing type:
 
 ```rust
-extern crate packed_struct;
-#[macro_use] extern crate packed_struct_codegen;
+use packed_struct::prelude::*;
 
 #[derive(PrimitiveEnum, Clone, Copy, PartialEq, Debug)]
 pub enum ImplicitType {
@@ -269,11 +261,10 @@ fn main() {
 }
 ```
 
-## Primitive enum packing with support for catch-all unknown values
+# Primitive enum packing with support for catch-all unknown values
 
 ```rust
-extern crate packed_struct;
-#[macro_use] extern crate packed_struct_codegen;
+use packed_struct::prelude::*;
 
 #[derive(PrimitiveEnum_u8, Debug, Clone, Copy)]
 pub enum Field {

packed_struct/Cargo.toml

@@ -10,6 +10,7 @@ license = "MIT OR Apache-2.0"
 keywords = ["enum", "packing", "serialization"]
 categories = ["encoding"]
 readme = "../README.md"
+edition = "2018"
 
 [dependencies]
 packed_struct_codegen = { path = "../packed_struct_codegen/", version = "0.5.0" }

packed_struct/src/debug_fmt.rs

@@ -1,6 +1,6 @@
 //! Helper structures for runtime packing visualization.
 
-use internal_prelude::v1::*;
+use crate::internal_prelude::v1::*;
 
 #[cfg(any(feature="alloc", feature="std"))]
 pub trait PackedStructDebug {
@@ -101,8 +101,7 @@ impl<'a, P> PackedStructDisplay<'a, P> {
     }
 }
 
-use packing::{PackedStruct};
-
+use crate::packing::PackedStruct;
 use crate::types_bits::ByteArray;
 
 impl<'a, P> fmt::Display for PackedStructDisplay<'a, P> where P: PackedStruct + PackedStructDebug {

packed_struct/src/lib.rs

@@ -23,6 +23,12 @@
 //!  * Arrays of packed structures as fields
 //!  * Reserved fields, their bits are always 0 or 1
 //!
+//! # Crate-level feature flags
+//!  * `std`: use the Rust standard library. Default.
+//!  * `alloc`: use the `alloc` crate for `no_std` + `alloc` scenarios. Requires nightly Rust.
+//!  * `use_serde`: add serialization support to the built-in helper types.
+//!  * `byte_types_64`, `byte_types_256`: enlarge the size of the generated array, byte and bit width types.
+//!
 //! # Sample usage
 //!
 //! ## Cargo.toml
@@ -31,20 +37,20 @@
 //! [dependencies]
 //! packed_struct = "0.5"
 //! ```
-//! ## Importing the library with the derive macros
+//! ## Importing the library with the the most common traits and the derive macros
 //!
 //! ```rust
-//! #[macro_use]
-//! extern crate packed_struct;
+//! // This is only needed for pre Rust 2018
+//! #[macro_use] extern crate packed_struct;
+//! // Prelude import with the common imports
+//! use packed_struct::prelude::*;
 //! # fn main() {
 //! # }
 //! ```
 //!
 //! ## Example of a single-byte structure, with a 3 bit integer, primitive enum and a bool field.
 //!
 //! ```rust
-//! #[macro_use] extern crate packed_struct;
-//!
 //! use packed_struct::prelude::*;
 //!
 //! #[derive(PackedStruct)]
@@ -95,7 +101,6 @@
 //! ## Syntax
 //!
 //! ```rust
-//! #[macro_use] extern crate packed_struct;
 //! use packed_struct::prelude::*;
 //!
 //! #[derive(PackedStruct)]
@@ -145,8 +150,6 @@
 //! ## Mixed endian integers
 //!
 //! ```rust
-//! #[macro_use] extern crate packed_struct;
-//!
 //! use packed_struct::prelude::*;
 //!
 //! #[derive(PackedStruct)]
@@ -172,8 +175,6 @@
 //! ## 24 bit LSB integers
 //!
 //! ```rust
-//! #[macro_use] extern crate packed_struct;
-//!
 //! use packed_struct::prelude::*;
 //!
 //! #[derive(PackedStruct)]
@@ -196,8 +197,6 @@
 //! ## Nested packed types within arrays
 //!
 //! ```rust
-//! #[macro_use] extern crate packed_struct;
-//!
 //! use packed_struct::prelude::*;
 //!
 //! #[derive(PackedStruct, Default, Debug, PartialEq)]
@@ -240,7 +239,6 @@
 //! Explicit or implicit backing type:
 //! 
 //! ```rust
-//! #[macro_use] extern crate packed_struct;
 //! use packed_struct::prelude::*;
 //!
 //! #[derive(PrimitiveEnum, Clone, Copy, PartialEq, Debug)]
@@ -270,7 +268,6 @@
 //! # Primitive enum packing with support for catch-all unknown values
 //! 
 //! ```rust
-//! #[macro_use] extern crate packed_struct;
 //! use packed_struct::prelude::*;
 //! 
 //! #[derive(PrimitiveEnum_u8, Debug, Clone, Copy)]
@@ -363,22 +360,20 @@ pub mod prelude {
 
     pub use super::derive::*;
 
-    pub use PackedStruct;
-    pub use PackedStructSlice;
-    pub use PackingError;
+    pub use crate::{PackedStruct, PackedStructSlice, PackingError};
 
-    pub use PrimitiveEnum;
+    pub use crate::PrimitiveEnum;
     #[cfg(any(feature="alloc", feature="std"))]
-    pub use PrimitiveEnumDynamicStr;
+    pub use crate::PrimitiveEnumDynamicStr;
 
     #[cfg(not(any(feature="alloc", feature="std")))]
-    pub use PrimitiveEnumStaticStr;
+    pub use crate::PrimitiveEnumStaticStr;
 
 
-    pub use EnumCatchAll;
+    pub use crate::EnumCatchAll;
 
-    pub use types::*;
-    pub use types::bits as packed_bits;
+    pub use crate::types::*;
+    pub use crate::types::bits as packed_bits;
 }
 
 use internal_prelude::v1::*;

packed_struct/src/packing.rs

@@ -1,4 +1,4 @@
-use internal_prelude::v1::*;
+use crate::internal_prelude::v1::*;
 
 use crate::types_bits::ByteArray;
 
@@ -57,8 +57,8 @@ pub enum PackingError {
     InternalError
 }
 
-impl Display for PackingError {
-    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+impl crate::Display for PackingError {
+    fn fmt(&self, f: &mut crate::fmt::Formatter) -> crate::fmt::Result {
         write!(f, "{:?}", self)
     }    
 }
@@ -81,7 +81,7 @@ impl ::std::error::Error for PackingError {
     }
 }
 
-impl From<PackingError> for fmt::Error {
+impl From<PackingError> for crate::fmt::Error {
     fn from(_: PackingError) -> Self {
         Self
     }

packed_struct/src/primitive_enum.rs

@@ -1,4 +1,4 @@
-use internal_prelude::v1::*;
+use crate::internal_prelude::v1::*;
 
 /// An enum type that can be packed or unpacked from a simple primitive integer.
 pub trait PrimitiveEnum where Self: Sized + Copy {

packed_struct/src/types_bits.rs

@@ -1,7 +1,7 @@
 //! Unit bit sizes, used as a type parameter to concrete types to signify their
 //! intended size.
 
-use internal_prelude::v1::*;
+use crate::internal_prelude::v1::*;
 
 /// Number of bits that the generic type should occupy.
 pub trait NumberOfBits: Copy + Clone + Debug + Default {

packed_struct/src/types_num.rs

@@ -2,7 +2,7 @@
 //! as a native type, packing and unpacking into byte arrays, with MSB/LSB
 //! support.
 
-use internal_prelude::v1::*;
+use crate::internal_prelude::v1::*;
 use crate::{PackingResult, lib_get_slice, lib_get_mut_slice};
 
 use super::types_bits::*;
@@ -719,7 +719,7 @@ fn test_struct_info() {
 
 #[test]
 fn test_slice_packing() {
-    use packing::PackedStructSlice;
+    use crate::packing::PackedStructSlice;
 
     let mut data = vec![0xAA, 0xBB, 0xCC, 0xDD];
     let unpacked = <MsbInteger<_, _, Integer<u32, Bits32>>>::unpack_from_slice(&data).unwrap();
@@ -740,7 +740,7 @@ fn test_packed_int_lsb_sub() {
 
 #[test]
 fn test_big_slice_unpacking() {
-    use packing::PackedStructSlice;
+    use crate::packing::PackedStructSlice;
 
     let data = vec![0xAA, 0xBB, 0xCC, 0xDD];
     let unpacked = <MsbInteger<_, _, Integer<u32, Bits32>>>::unpack_from_slice(&data).unwrap();