rust: str: implement `Display` and `Debug` for `BStr`
PATCH v2 1/1 rust: str: implement `Display` and `Debug` for `BStr`
Currently, BStr is just a type alias of [u8], limiting its representation to a byte list rather than a character list, which is not ideal for printing and debugging.
Implement Display and Debug traits for BStr to facilitate easier printing and debugging.
Also, for this purpose, change BStr from a type alias of [u8] to a struct wrapper of [u8].
---
V1 -> V2:
- Ensured there are no changes to the behavior of CStr's Display and Debug.
- Made other few changes based on review comments.
rust/kernel/str.rs | 192 +++++++++++++++++++++++++++++++++++++++------ 1 file changed, 166 insertions(+), 26 deletions(-)
rust/kernel/str.rs +166 -26
@@ -13,9 +13,92 @@ };/// Byte string without UTF-8 validity guarantee. -/// -/// `BStr` is simply an alias to `[u8]`, but has a more evident semantical meaning. -pub type BStr = [u8 ]; +#[repr(transparent)] +pub struct BStr ([u8 ]); + +impl BStr { +/// Returns the length of this string. +#[inline] +pub const fn len (&self) ->usize { + self.0 .len () + } + +/// Returns `true` if the string is empty. +#[inline] +pub const fn is_empty (&self) ->bool { + self.len () ==0 + } + +/// Creates a [`BStr`] from a `[u8]`. +#[inline] +pub const fn from_bytes (bytes: &[u8 ]) -> &Self { +// SAFETY: BStr is transparent to [u8]. +unsafe { &*(bytesas *const [u8 ]as *const BStr ) } + } +} + +impl fmt::Display for BStr { +/// Formats printable ASCII characters, escaping the rest. +/// +/// ``` +/// # use kernel::{fmt, b_str, str::{BStr, CString}}; +/// let ascii = b_str!("Hello, BStr!"); +/// let s = CString::try_from_fmt(fmt!("{}", ascii)).unwrap(); +/// assert_eq!(s.as_bytes(), "Hello, BStr!".as_bytes()); +/// +/// let non_ascii = b_str!("🦀"); +/// let s = CString::try_from_fmt(fmt!("{}", non_ascii)).unwrap(); +/// assert_eq!(s.as_bytes(), "\\xf0\\x9f\\xa6\\x80".as_bytes()); +/// ``` +fn fmt (&self, f: &mut fmt::Formatter <'_>) -> fmt::Result { +for &bin &self.0 { +match b { +// Printable characters. +0x20 ..=0x7e => f.write_char (bas char )?, + _ =>write! (f,"\\x{:02x}" , b)?, + } + } +Ok (()) + } +} + +impl fmt::Debug for BStr { +/// Formats printable ASCII characters with a double quote on either end, +/// escaping the rest. +/// +/// ``` +/// # use kernel::{fmt, b_str, str::{BStr, CString}}; +/// // Embedded double quotes are escaped. +/// let ascii = b_str!("Hello, \"BStr\"!"); +/// let s = CString::try_from_fmt(fmt!("{:?}", ascii)).unwrap(); +/// assert_eq!(s.as_bytes(), "\"Hello, \\\"BStr\\\"!\"".as_bytes()); +/// +/// let non_ascii = b_str!("😺"); +/// let s = CString::try_from_fmt(fmt!("{:?}", non_ascii)).unwrap(); +/// assert_eq!(s.as_bytes(), "\"\\xf0\\x9f\\x98\\xba\"".as_bytes()); +/// ``` +fn fmt (&self, f: &mut fmt::Formatter <'_>) -> fmt::Result { + f.write_str ("\"" )?; +for &bin &self.0 { +match b { +// Printable characters. +b'\"' => f.write_str ("\\\"" )?, +0x20 ..=0x7e => f.write_char (bas char )?, + _ =>write! (f,"\\x{:02x}" , b)?, + } + } + f.write_str ("\"" ) + } +} + +impl Deref for BStr { +type Target = [u8 ]; + +#[inline] +fn deref (&self) -> &Self ::Target { + &self.0 + } +}/// Creates a new [`BStr`] from a string literal. ///
@@ -33,7 +116,7 @@macro_rules! b_str { ($str:literal) => {{const S : &'static str = $str; -const C : &'static $crate::str ::BStr =S .as_bytes (); +const C : &'static $crate::str ::BStr =BStr ::from_bytes (S .as_bytes ());C }}; }
@@ -225,15 +308,7 @@ impl fmt::Display for CStr {/// assert_eq!(s.as_bytes_with_nul(), "so \"cool\"\0".as_bytes()); /// ``` fn fmt (&self, f: &mut fmt::Formatter <'_>) -> fmt::Result { -for &cin self.as_bytes () { -if (0x20 ..0x7f ).contains (&c) { -// Printable character. - f.write_char (cas char )?; - }else { -write! (f,"\\x{:02x}" , c)?; - } - } -Ok (()) + fmt::Display ::fmt (self.as_ref (), f) } }
@@ -255,23 +330,14 @@ impl fmt::Debug for CStr {/// assert_eq!(s.as_bytes_with_nul(), "\"so \\\"cool\\\"\"\0".as_bytes()); /// ``` fn fmt (&self, f: &mut fmt::Formatter <'_>) -> fmt::Result { - f.write_str ("\"" )?; -for &cin self.as_bytes () { -match c { -// Printable characters. -b'\"' => f.write_str ("\\\"" )?, -0x20 ..=0x7e => f.write_char (cas char )?, - _ =>write! (f,"\\x{:02x}" , c)?, - } - } - f.write_str ("\"" ) + fmt::Debug ::fmt (self.as_ref (), f) } }impl AsRef <BStr >for CStr {#[inline] fn as_ref (&self) -> &BStr { - self.as_bytes () +BStr ::from_bytes (self.as_bytes ()) } }
@@ -280,7 +346,7 @@ impl Deref for CStr {#[inline] fn deref (&self) -> &Self ::Target { - self.as_bytes () + self.as_ref () } }
@@ -327,7 +393,7 @@ impl<Idx> Index<Idx> for CStr#[inline] fn index (&self, index:Idx ) -> &Self ::Output { - &self.as_bytes ()[index] + &self.as_ref ()[index] } }
@@ -357,6 +423,21 @@ macro_rules! c_str {#[cfg(test)] mod tests {use super ::*; +use alloc::format; + +const ALL_ASCII_CHARS : &'staticstr = +"\\x01\\x02\\x03\\x04\\x05\\x06\\x07\\x08\\x09\\x0a\\x0b\\x0c\\x0d\\x0e\\x0f\ +\\x10\\x11\\x12\\x13\\x14\\x15\\x16\\x17\\x18\\x19\\x1a\\x1b\\x1c\\x1d\\x1e\\x1f \ +!\"#$%&'()*+,-./0123456789:;<=>?@\ +ABCDEFGHIJKLMNOPQRSTUVWXYZ[\\]^_`abcdefghijklmnopqrstuvwxyz{|}~\\x7f\ +\\x80\\x81\\x82\\x83\\x84\\x85\\x86\\x87\\x88\\x89\\x8a\\x8b\\x8c\\x8d\\x8e\\x8f\ +\\x90\\x91\\x92\\x93\\x94\\x95\\x96\\x97\\x98\\x99\\x9a\\x9b\\x9c\\x9d\\x9e\\x9f\ +\\xa0\\xa1\\xa2\\xa3\\xa4\\xa5\\xa6\\xa7\\xa8\\xa9\\xaa\\xab\\xac\\xad\\xae\\xaf\ +\\xb0\\xb1\\xb2\\xb3\\xb4\\xb5\\xb6\\xb7\\xb8\\xb9\\xba\\xbb\\xbc\\xbd\\xbe\\xbf\ +\\xc0\\xc1\\xc2\\xc3\\xc4\\xc5\\xc6\\xc7\\xc8\\xc9\\xca\\xcb\\xcc\\xcd\\xce\\xcf\ +\\xd0\\xd1\\xd2\\xd3\\xd4\\xd5\\xd6\\xd7\\xd8\\xd9\\xda\\xdb\\xdc\\xdd\\xde\\xdf\ +\\xe0\\xe1\\xe2\\xe3\\xe4\\xe5\\xe6\\xe7\\xe8\\xe9\\xea\\xeb\\xec\\xed\\xee\\xef\ +\\xf0\\xf1\\xf2\\xf3\\xf4\\xf5\\xf6\\xf7\\xf8\\xf9\\xfa\\xfb\\xfc\\xfd\\xfe\\xff" ;#[test] fn test_cstr_to_str () {
@@ -381,6 +462,65 @@ fn test_cstr_as_str_unchecked() {let unchecked_str =unsafe { checked_cstr.as_str_unchecked () };assert_eq! (unchecked_str,"🐧" ); } + +#[test] +fn test_cstr_display () { +let hello_world =CStr ::from_bytes_with_nul (b"hello, world!\0" ).unwrap (); +assert_eq! (format! ("{}" , hello_world),"hello, world!" ); +let non_printables =CStr ::from_bytes_with_nul (b"\x01\x09\x0a\0" ).unwrap (); +assert_eq! (format! ("{}" , non_printables),"\\x01\\x09\\x0a" ); +let non_ascii =CStr ::from_bytes_with_nul (b"d\xe9j\xe0 vu\0" ).unwrap (); +assert_eq! (format! ("{}" , non_ascii),"d\\xe9j\\xe0 vu" ); +let good_bytes =CStr ::from_bytes_with_nul (b"\xf0\x9f\xa6\x80\0" ).unwrap (); +assert_eq! (format! ("{}" , good_bytes),"\\xf0\\x9f\\xa6\\x80" ); + } + +#[test] +fn test_cstr_debug () { +let hello_world =CStr ::from_bytes_with_nul (b"hello, world!\0" ).unwrap (); +assert_eq! (format! ("{:?}" , hello_world),"\"hello, world!\"" ); +let non_printables =CStr ::from_bytes_with_nul (b"\x01\x09\x0a\0" ).unwrap (); +assert_eq! (format! ("{:?}" , non_printables),"\"\\x01\\x09\\x0a\"" ); +let non_ascii =CStr ::from_bytes_with_nul (b"d\xe9j\xe0 vu\0" ).unwrap (); +assert_eq! (format! ("{:?}" , non_ascii),"\"d\\xe9j\\xe0 vu\"" ); +let good_bytes =CStr ::from_bytes_with_nul (b"\xf0\x9f\xa6\x80\0" ).unwrap (); +assert_eq! (format! ("{:?}" , good_bytes),"\"\\xf0\\x9f\\xa6\\x80\"" ); + } + +#[test] +fn test_bstr_display () { +let hello_world =BStr ::from_bytes (b"hello, world!" ); +assert_eq! (format! ("{}" , hello_world),"hello, world!" ); +let non_printables =BStr ::from_bytes (b"\x01\x09\x0a" ); +assert_eq! (format! ("{}" , non_printables),"\\x01\\x09\\x0a" ); +let non_ascii =BStr ::from_bytes (b"d\xe9j\xe0 vu" ); +assert_eq! (format! ("{}" , non_ascii),"d\\xe9j\\xe0 vu" ); +let good_bytes =BStr ::from_bytes (b"\xf0\x9f\xa6\x80" ); +assert_eq! (format! ("{}" , good_bytes),"\\xf0\\x9f\\xa6\\x80" ); + } + +#[test] +fn test_bstr_debug () { +let hello_world =BStr ::from_bytes (b"hello, world!" ); +assert_eq! (format! ("{:?}" , hello_world),"\"hello, world!\"" ); +let non_printables =BStr ::from_bytes (b"\x01\x09\x0a" ); +assert_eq! (format! ("{:?}" , non_printables),"\"\\x01\\x09\\x0a\"" ); +let non_ascii =BStr ::from_bytes (b"d\xe9j\xe0 vu" ); +assert_eq! (format! ("{:?}" , non_ascii),"\"d\\xe9j\\xe0 vu\"" ); +let good_bytes =BStr ::from_bytes (b"\xf0\x9f\xa6\x80" ); +assert_eq! (format! ("{:?}" , good_bytes),"\"\\xf0\\x9f\\xa6\\x80\"" ); + } + +#[test] +fn test_cstr_display_all_bytes () { +let mut bytes: [u8 ;256 ] = [0 ;256 ]; +// fill `bytes` with [1..=255] + [0] +for iin u8::MIN ..=u8::MAX { + bytes[ias usize ] = i.wrapping_add (1 ); + } +let cstr =CStr ::from_bytes_with_nul (&bytes).unwrap (); +assert_eq! (format! ("{}" , cstr),ALL_ASCII_CHARS ); + } }/// Allows formatting of [`fmt::Arguments`] into a raw buffer.
Signature · 1 line
2.43.0
Alice Ryhl
reviewerQuoted 30 lines · Yutaro Ohno
Currently,
BStris just a type alias of[u8], limiting its representation to a byte list rather than a character list, which is not ideal for printing and debugging.Implement
DisplayandDebugtraits forBStrto facilitate easier printing and debugging.Also, for this purpose, change
BStrfrom a type alias of[u8]to a struct wrapper of[u8].Co-developed-by Virgile Andreani <[email protected]>Signed-off-by Virgile Andreani <[email protected]>Signed-off-by Yutaro Ohno <[email protected]>[...]
rust/kernel/str.rs +14
-0+impl fmt::Display for BStr { +/// Formats printable ASCII characters, escaping the rest. +/// +/// ``` +/// # use kernel::{fmt, b_str, str::{BStr, CString}}; +/// let ascii = b_str!("Hello, BStr!"); +/// let s = CString::try_from_fmt(fmt!("{}", ascii)).unwrap(); +/// assert_eq!(s.as_bytes(), "Hello, BStr!".as_bytes()); +/// +/// let non_ascii = b_str!("🦀"); +/// let s = CString::try_from_fmt(fmt!("{}", non_ascii)).unwrap(); +/// assert_eq!(s.as_bytes(), "\\xf0\\x9f\\xa6\\x80".as_bytes()); +/// ``` +fn fmt (&self, f: &mut fmt::Formatter <'_>) -> fmt::Result {
rust/kernel/str.rs line 63
Quoted 10 lines
rust/kernel/str.rs +10
-0+for &bin &self.0 { +match b { +// Printable characters. +0x20 ..=0x7e => f.write_char (bas char )?, + _ =>write! (f,"\\x{:02x}" , b)?, + } + } +Ok (()) + } +}
What about newlines and tabs? Those are printable.
If you are intentionally excluding them, please add a comment saying that.
Quoted 18 lines
rust/kernel/str.rs +18
-0+impl fmt::Debug for BStr { +/// Formats printable ASCII characters with a double quote on either end, +/// escaping the rest. +/// +/// ``` +/// # use kernel::{fmt, b_str, str::{BStr, CString}}; +/// // Embedded double quotes are escaped. +/// let ascii = b_str!("Hello, \"BStr\"!"); +/// let s = CString::try_from_fmt(fmt!("{:?}", ascii)).unwrap(); +/// assert_eq!(s.as_bytes(), "\"Hello, \\\"BStr\\\"!\"".as_bytes()); +/// +/// let non_ascii = b_str!("😺"); +/// let s = CString::try_from_fmt(fmt!("{:?}", non_ascii)).unwrap(); +/// assert_eq!(s.as_bytes(), "\"\\xf0\\x9f\\x98\\xba\"".as_bytes()); +/// ``` +fn fmt (&self, f: &mut fmt::Formatter <'_>) -> fmt::Result { + f.write_str ("\"" )?; +for &bin &self.0 {
rust/kernel/str.rs line 92
Quoted 10 lines
rust/kernel/str.rs +10
-0+match b { +// Printable characters. +b'\"' => f.write_str ("\\\"" )?, +0x20 ..=0x7e => f.write_char (bas char )?, + _ =>write! (f,"\\x{:02x}" , b)?, + } + } + f.write_str ("\"" ) + } +}
This escapes quotes, but what about backslashes?
Also, perhaps write_char('"') makes more sense than write_str("\"")?
rust/kernel/str.rs line 122
Quoted 8 lines
macro_rules! b_str { ($str:literal) => {{ const S: &'static str = $str;rust/kernel/str.rs +1
-1-const C : &'static $crate::str::BStr =S .as_bytes (); +const C : &'static $crate::str::BStr =BStr ::from_bytes (S .as_bytes ());C }}; }
This should use the full path both times:
const C: &'static $crate::str::BStr = $crate::str::BStr::from_bytes(S.as_bytes());
Alice
Quoted 4 lines · Alice Ryhl
What about newlines and tabs? Those are printable.
If you are intentionally excluding them, please add a comment saying that.
+1 and, either way, it would also nice a test for those too.
Quoted 1 line
This escapes quotes, but what about backslashes?
Ditto.
Cheers,
Miguel
Thank you both for the comments!
Quoted 11 lines · Miguel Ojeda
Quoted 4 lines · Alice Ryhl
What about newlines and tabs? Those are printable.
If you are intentionally excluding them, please add a comment saying that.
+1 and, either way, it would also nice a test for those too.
Quoted 1 line
This escapes quotes, but what about backslashes?
Ditto.
Newlines and tabs are omitted here because this patch doesn't intend to change the current behavior of CStr's Display/Debug in this patch, aligning with the feedback provided in V1.
So, how about removing the changes to CStr's Display/Debug from my patch, and adding '\t' and '\n' as printable characters to BStr's Display/Debug? (Backslashes for Debug as well.)
I'm considering whether it would be preferable for BStr's Display and Debug to have distinct behavior from CStr's.
Quoted 1 line · Alice Ryhl
Also, perhaps
write_char('"')makes more sense thanwrite_str("\"")?
I agree. Will change in V3.
Quoted 9 lines · Alice Ryhl
rust/kernel/str.rs line 122
Quoted 8 lines
macro_rules! b_str { ($str:literal) => {{ const S: &'static str = $str;rust/kernel/str.rs +1
-1-const C : &'static $crate::str::BStr =S .as_bytes (); +const C : &'static $crate::str::BStr =BStr ::from_bytes (S .as_bytes ());C }}; }
Quoted 3 lines
This should use the full path both times:
const C: &'static $crate::str::BStr = $crate::str::BStr::from_bytes(S.as_bytes());
Thanks. I'll also change this.
Best regards,
Yutaro Ohno