commit | 7a88a49273d463146b854104c7c1ab163fb20295 | [log] [tgz] |
---|---|---|
author | Android Build Coastguard Worker <android-build-coastguard-worker@google.com> | Tue May 14 23:08:59 2024 +0000 |
committer | Android Build Coastguard Worker <android-build-coastguard-worker@google.com> | Tue May 14 23:08:59 2024 +0000 |
tree | 768d3db37920efb7f67a6b2872bcc12e3372c6e0 | |
parent | 014106820e27c14a5c595f3d67a7c5059f973178 [diff] | |
parent | 89a6bd0e1ad34e3a2be8da53fae1ef67ba539d48 [diff] |
Snap for 11841552 from 89a6bd0e1ad34e3a2be8da53fae1ef67ba539d48 to sdk-release Change-Id: I9cf6199781720a6f73feedcf9fd463f3bec087cd
From<docs>
This library provides a convenient derive macro for the standard library's core::fmt::Display
trait.
[dependencies] displaydoc = "0.2"
Compiler support: requires rustc 1.56+
Demonstration alongside the [Error
][std::error::Error] derive macro from thiserror
, to propagate source locations from [io::Error
][std::io::Error] with the #[source]
attribute:
use std::io; use displaydoc::Display; use thiserror::Error; #[derive(Display, Error, Debug)] pub enum DataStoreError { /// data store disconnected Disconnect(#[source] io::Error), /// the data for key `{0}` is not available Redaction(String), /// invalid header (expected {expected:?}, found {found:?}) InvalidHeader { expected: String, found: String, }, /// unknown data store error Unknown, } let error = DataStoreError::Redaction("CLASSIFIED CONTENT".to_string()); assert!("the data for key `CLASSIFIED CONTENT` is not available" == &format!("{}", error));
Note that although [io::Error
][std::io::Error] implements Display
, we do not add it to the generated message for DataStoreError::Disconnect
, since it is already made available via #[source]
. See further context on avoiding duplication in error reports at the rust blog here.
fmt::Display
impl is generated for your enum if you provide a docstring comment on each variant as shown above in the example. The Display
derive macro supports a shorthand for interpolating fields from the error:/// {var}
⟶ write!("{}", self.var)
/// {0}
⟶ write!("{}", self.0)
/// {var:?}
⟶ write!("{:?}", self.var)
/// {0:?}
⟶ write!("{:?}", self.0)
/// oh no, an error: {0} #[derive(Display)] pub struct Error<E>(pub E); let error: Error<&str> = Error("muahaha i am an error"); assert!("oh no, an error: muahaha i am an error" == &format!("{}", error));
Two optional attributes can be added to your types next to the derive:
#[ignore_extra_doc_attributes]
makes the macro ignore any doc comment attributes (or ///
lines) after the first. Multi-line comments using ///
are otherwise treated as an error, so use this attribute or consider switching to block doc comments (/** */
).
#[prefix_enum_doc_attributes]
combines the doc comment message on your enum itself with the messages for each variant, in the format “enum: variant”. When added to an enum, the doc comment on the enum becomes mandatory. When added to any other type, it has no effect.
In case you want to have an independent doc comment, the #[displaydoc("...")
atrribute may be used on the variant or struct to override it.
Is this crate no_std
compatible?
core::fmt::Display
trait, not the [std::fmt::Display
] trait, so it should work in std
and no_std
environments. Just add default-features = false
.Does this crate work with Path
and PathBuf
via the Display
trait?
Path
and PathBuf
, and when either of these types are found, it calls self.display()
to get a std::path::Display<'_>
type which can be used with the Display
format specifier!