Merge pull request #811 from plaes/byte-slice-hints-example

book: Add some examples for byte slice/array hints as well
knurling-rs · Mar 6, 2024 · 4db33ca · 4db33ca
2 parents 7a0b42c + 98a351c
commit 4db33ca
Show file tree

Hide file tree

Showing 3 changed files with 20 additions and 1 deletion.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,10 +7,12 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [Unreleased]
 
-- [#813] doc: add note for the alloc feature flag
+- [#813]: doc: add note for the alloc feature flag
+- [#811]: `book`: Add some examples for byte slice/array hints as well
 - [#800]: `defmt-macros`: Fix generic trait bounds in Format derive macro
 
 [#813]: https://github.com/knurling-rs/defmt/pull/813
+[#811]: https://github.com/knurling-rs/defmt/pull/811
 [#800]: https://github.com/knurling-rs/defmt/pull/800
 
 ## [v0.3.6] - 2024-02-05

diff --git a/book/src/hints.md b/book/src/hints.md
@@ -74,6 +74,20 @@ defmt::info!("{=u8:#08X}", 42); // -> INFO 0x00002A
 
 When the alternate form is used for hex and binary, the `0x`/`0b` length is subtracted from the leading zeros.  This matches [`core::fmt` behavior](https://play.rust-lang.org/?version=stable&mode=debug&edition=2018&gist=b11809759f975e266251f7968e542756).
 
+## Display hints for byte slice and byte array elements
+
+Besides ASCII hints, byte slice and array elements can be formatted using hexadecimal or binary hints:
+
+```rust
+# extern crate defmt;
+let bytes = [4, 101, 5, 108, 6, 111];
+
+defmt::info!("{=[u8]}", bytes);         // -> INFO [4, 101, 5, 108, 6, 111]
+defmt::info!("{=[u8]:x}", bytes);       // -> INFO [4, 65, 5, 6c, 6, 6f]
+defmt::info!("{=[u8]:#04x}", bytes);    // -> INFO [0x04, 0x65, 0x05, 0x6c, 0x06, 0x6f]
+defmt::info!("{=[u8]:#010b}", bytes);   // -> INFO [0b00000100, 0b01100101, 0b00000101, 0b01101100, 0b00000110, 0b01101111]
+```
+
 ## Propagation
 
 Display hints "propagate downwards" and apply to formatting parameters that specify no display hint.

diff --git a/parser/src/tests.rs b/parser/src/tests.rs
@@ -10,6 +10,7 @@ use super::*;
 #[case::two_param_type_hint("=u8:x", None, Type::U8, Some(DisplayHint::Hexadecimal {alternate: false, uppercase: false, zero_pad: 0}))]
 #[case::two_param_index_type("0=u8", Some(0), Type::U8, None)]
 #[case::two_param_index_hint("0:a", Some(0), Type::Format, Some(DisplayHint::Ascii))]
+#[case::two_param_type_hint("=[u8]:#04x", None, Type::U8Slice, Some(DisplayHint::Hexadecimal {alternate: true, uppercase: false, zero_pad: 4}))]
 #[case::all_param("1=u8:b", Some(1), Type::U8, Some(DisplayHint::Binary { alternate: false, zero_pad: 0}))]
 fn all_parse_param_cases(
     #[case] input: &str,
@@ -28,7 +29,9 @@ fn all_parse_param_cases(
 #[case(":b", DisplayHint::Binary { alternate: false, zero_pad: 0 })]
 #[case(":#b", DisplayHint::Binary { alternate: true, zero_pad: 0 })]
 #[case(":x", DisplayHint::Hexadecimal { alternate: false, uppercase: false, zero_pad: 0 })]
+#[case(":02x", DisplayHint::Hexadecimal { alternate: false, uppercase: false, zero_pad: 2 })]
 #[case(":#x", DisplayHint::Hexadecimal { alternate: true, uppercase: false, zero_pad: 0 })]
+#[case(":#04x", DisplayHint::Hexadecimal { alternate: true, uppercase: false, zero_pad: 4 })]
 #[case(":X", DisplayHint::Hexadecimal { alternate: false, uppercase: true, zero_pad: 0 })]
 #[case(":#X", DisplayHint::Hexadecimal { alternate: true, uppercase: true, zero_pad: 0 })]
 #[case(":ms", DisplayHint::Seconds(TimePrecision::Millis))]