qubit_redact/facade/redactor/
domain.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//! Domain-value and scalar-field redaction operations.
9
10use std::fmt::Display;
11
12use super::Redactor;
13use crate::Redact;
14use crate::RedactionInspection;
15use crate::RedactionInspectionError;
16use crate::RedactionTextOutput;
17use crate::runtime::runtime_session::RuntimeSession;
18
19impl Redactor {
20    /// Creates a lazy borrowed view with an owned snapshot of this policy.
21    ///
22    /// No source access or budget consumption occurs until the view is used.
23    /// Formatting requires `Redact`. With the `serde` feature, a derived
24    /// value's view serializes structurally when its fields support the
25    /// required Serde adapters. Each use starts an independent execution.
26    ///
27    /// # Type Parameters
28    ///
29    /// - `'value`: Lifetime of the borrowed source value.
30    /// - `T`: Source type; capabilities are checked when the view is used.
31    ///
32    /// # Parameters
33    ///
34    /// - `value`: Source retained by reference without evaluating it.
35    ///
36    /// # Returns
37    ///
38    /// A reusable borrowed view that owns this redactor’s policy snapshot.
39    #[must_use]
40    #[inline(always)]
41    pub fn redact_view<'value, T: ?Sized>(&self, value: &'value T) -> crate::RedactedView<'value, T> {
42        crate::RedactedView::new(value, self.clone())
43    }
44
45    /// Redacts one domain value into final text and an execution summary.
46    ///
47    /// # Type Parameters
48    ///
49    /// - `T`: Domain type exposing structured redaction.
50    ///
51    /// # Parameters
52    ///
53    /// - `value`: Borrowed domain value visited within one fresh budget.
54    ///
55    /// # Returns
56    ///
57    /// Final redacted text and its execution summary, including any truncation
58    /// or admission failure recorded while processing the value.
59    #[must_use]
60    #[inline]
61    pub fn redact_text<T>(&self, value: &T) -> RedactionTextOutput
62    where
63        T: Redact + ?Sized,
64    {
65        let mut session = self.text_runtime();
66        let _ = session.value(value);
67        session.finish()
68    }
69
70    /// Inspects one domain value without rendering any field content.
71    ///
72    /// # Errors
73    ///
74    /// Returns an inconclusive result when structural or input admission
75    /// prevents the complete domain value from being classified.
76    ///
77    /// # Type Parameters
78    ///
79    /// - `T`: Domain type exposing structured redaction.
80    ///
81    /// # Parameters
82    ///
83    /// - `value`: Borrowed domain value to classify without rendering fields.
84    ///
85    /// # Returns
86    ///
87    /// A conclusive sensitivity inspection, or a value-free error containing
88    /// resource usage and reasons why complete classification was unavailable.
89    #[inline]
90    pub fn inspect<T>(&self, value: &T) -> Result<RedactionInspection, RedactionInspectionError>
91    where
92        T: Redact + ?Sized,
93    {
94        let mut session = self.inspection_runtime();
95        session.inspect(value);
96        session.finish()
97    }
98
99    /// Redacts one scalar field through a complete one-item transaction.
100    ///
101    /// # Type Parameters
102    ///
103    /// - `T`: Scalar formatter evaluated only when admission and masking
104    ///   require it.
105    ///
106    /// # Parameters
107    ///
108    /// - `field`: Raw field key used for admission and classification.
109    /// - `value`: Scalar whose formatting is deferred until required.
110    ///
111    /// # Returns
112    ///
113    /// Final redacted text and its execution summary, including any truncation
114    /// or admission failure recorded while processing the value.
115    #[must_use]
116    #[inline]
117    pub fn redact_field<T>(&self, field: &str, value: &T) -> RedactionTextOutput
118    where
119        T: Display + ?Sized,
120    {
121        let mut session = self.text_runtime();
122        let _ = session.field(field, value);
123        session.finish()
124    }
125
126    /// Inspects one scalar field without rendering its value.
127    ///
128    /// # Errors
129    ///
130    /// Returns [`RedactionInspectionError`] when an input, structural, or key
131    /// limit prevents a conclusive classification.
132    ///
133    /// # Parameters
134    ///
135    /// - `field`: Raw key used for admission and classification.
136    /// - `value`: Source text counted for inspection without rendering it.
137    ///
138    /// # Returns
139    ///
140    /// A conclusive sensitivity inspection, or a value-free error containing
141    /// resource usage and reasons why complete classification was unavailable.
142    #[inline]
143    pub fn inspect_field(&self, field: &str, value: &str) -> Result<RedactionInspection, RedactionInspectionError> {
144        let mut session = self.inspection_runtime();
145        session.inspect_field(field, value);
146        session.finish()
147    }
148}
qubit_redact/facade/redactor/domain.rs

qubit_redact/facade/redactor/
domain.rs
