diff --git a/README.md b/README.md index 79fdb4b..9946bf8 100644 --- a/README.md +++ b/README.md @@ -27,6 +27,17 @@ let encryption_key = Secret::new("hello world"); assert_eq!("hello world", *encryption_key.expose_secret()) ``` +The secret may alternatively be transformed into another secret value +using the [map][Secret::map] method, which acts similarly to +[Option::map][Option::map]. + +```rust +use redact::Secret; + +let encryption_key = Secret::new("hello world").map(str::to_string); +assert_eq!("hello world", *encryption_key.expose_secret()) +``` + The `Secret` type doubles as a useful documentation tool. Documenting values maintainers should be careful with. diff --git a/src/lib.rs b/src/lib.rs index 152d96c..b2a8458 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -45,6 +45,15 @@ impl Secret { pub const fn expose_secret(&self) -> &T { &self.0 } + /// See [module level documentation][crate] + #[inline] + #[must_use = "the secret will be dropped if not used"] + pub fn map(self, mapper: F) -> Secret + where + F: FnOnce(T) -> U, + { + Secret::new(mapper(self.0)) + } } impl From for Secret {