qubit_redact/text/
redacted_debug.rs

1// =============================================================================
2//    Copyright (c) 2025 - 2026 Haixing Hu.
3//
4//    SPDX-License-Identifier: Apache-2.0
5//
6//    Licensed under the Apache License, Version 2.0.
7// =============================================================================
8//! A debug wrapper that emits a fixed redaction marker.
9
10use std::fmt::{
11    Debug,
12    Formatter,
13    Result,
14};
15
16/// A borrowed value whose debug representation is always `<redacted>`.
17///
18/// This wrapper does not require or invoke `T`'s [`Debug`] implementation. It
19/// retains the borrow so the wrapper cannot outlive the value it protects.
20///
21/// ```compile_fail
22/// #![deny(unused_must_use)]
23/// use qubit_redact::redacted_debug;
24///
25/// let secret = String::from("secret");
26/// redacted_debug(&secret);
27/// ```
28///
29/// # Type Parameters
30///
31/// * `'a` - Lifetime of the protected borrowed value.
32/// * `T` - Protected value type, which need not implement [`Debug`].
33#[must_use = "render the redacted debug marker instead of discarding it"]
34pub struct RedactedDebug<'a, T: ?Sized> {
35    /// The protected value, retained only to preserve its borrow and traits.
36    _value: &'a T,
37}
38
39impl<T: ?Sized> Debug for RedactedDebug<'_, T> {
40    /// Writes the fixed redaction marker without formatting the wrapped value.
41    ///
42    /// # Parameters
43    ///
44    /// - `formatter`: Destination formatter.
45    ///
46    /// # Returns
47    ///
48    /// The result of writing the marker to `formatter`.
49    ///
50    /// # Errors
51    ///
52    /// Returns [`std::fmt::Error`] when the formatter rejects the write.
53    #[inline(always)]
54    fn fmt(&self, formatter: &mut Formatter<'_>) -> Result {
55        formatter.write_str("<redacted>")
56    }
57}
58
59/// Wraps a value so debug formatting emits only `<redacted>`.
60///
61/// The returned wrapper never invokes the value's [`Debug`] implementation.
62///
63/// # Type Parameters
64///
65/// * `T` - Protected value type, which need not implement [`Debug`].
66///
67/// # Parameters
68///
69/// - `value`: The value whose debug representation must be hidden.
70///
71/// # Returns
72///
73/// A wrapper borrowing `value` and rendering the fixed redaction marker.
74#[inline(always)]
75pub const fn redacted_debug<T: ?Sized>(value: &T) -> RedactedDebug<'_, T> {
76    RedactedDebug { _value: value }
77}
qubit_redact/text/redacted_debug.rs

qubit_redact/text/
redacted_debug.rs
