1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
//! Ordered warnings and diagnostics for PDF processing.
//!
//! qpdf correspondence: `QPDF::Members::warnings` represented as Rust values.
//!
//! qpdf stores warnings as a single ordered `std::vector<QPDFExc>` and copies
//! each exception into that vector before optional logger delivery
//! (`include/qpdf/QPDF.hh:261-273`, `libqpdf/QPDF.cc:487-504`). The collection
//! therefore stores [`crate::QpdfExc`] directly. Fatal operation results belong
//! to [`crate::Error`] or a job-specific error, not to this warning collection.
/// The document-owned, ordered qpdf warning collection.
///
/// Every entry retains qpdf's independent error code, source filename, object
/// description, signed file position, and detail bytes. `push` appends in
/// warning order and `drain` transfers the current batch, matching qpdf's
/// `getWarnings` lifecycle. Callers that need the logger-visible
/// representation must use [`crate::QpdfExc::what_bytes`]; it intentionally
/// stops at the first NUL just like C++ `what()` consumers.
#[derive(Debug, Default, Clone, PartialEq, Eq)]
pub struct Diagnostics {
entries: Vec<crate::QpdfExc>,
}
impl Diagnostics {
/// Append a warning while preserving qpdf's emission order.
pub fn push(&mut self, warning: crate::QpdfExc) {
self.entries.push(warning);
}
/// Return all warnings in insertion order.
pub fn entries(&self) -> &[crate::QpdfExc] {
&self.entries
}
/// Return the number of collected warnings.
pub fn len(&self) -> usize {
self.entries.len()
}
/// Return whether no warnings have been collected.
pub fn is_empty(&self) -> bool {
self.entries.is_empty()
}
/// Move the ordered warnings out of this collection and leave it empty.
///
/// This is the Rust collection operation behind qpdf's
/// `QPDF::getWarnings` (`include/qpdf/QPDF.hh:261-266`): draining does not
/// replay logger output and a later warning starts a new drain batch.
pub(crate) fn drain(&mut self) -> Self {
std::mem::take(self)
}
}
#[cfg(test)]
mod tests {
use super::*;
use crate::error::{QpdfErrorCode, QpdfExc};
#[test]
fn qpdf_warning_collection_preserves_structured_exception() {
let warning = QpdfExc::new(
QpdfErrorCode::DamagedPdf,
b"file-\xff.pdf",
b"object 4 0",
-1,
b"detail-\xfe",
);
let mut diags = Diagnostics::default();
diags.push(warning.clone());
let entries = diags.entries();
assert_eq!(entries.len(), 1);
assert_eq!(entries[0], warning);
assert_eq!(entries[0].get_filename(), b"file-\xff.pdf");
assert_eq!(entries[0].get_object(), b"object 4 0");
assert_eq!(entries[0].get_file_position(), -1);
assert_eq!(entries[0].get_message_detail(), b"detail-\xfe");
assert_eq!(
entries[0].what_bytes(),
b"file-\xff.pdf (object 4 0): detail-\xfe"
);
}
#[test]
fn qpdf_warning_collection_clone_preserves_order_and_raw_what() {
let mut diags = Diagnostics::default();
diags.push(QpdfExc::new(
QpdfErrorCode::Object,
b"",
b"object 1 0",
0,
b"first",
));
diags.push(QpdfExc::new(
QpdfErrorCode::System,
b"source-\xff",
b"",
7,
b"second\0after-nul",
));
let cloned = diags.clone();
assert_eq!(cloned.entries().len(), 2);
assert_eq!(cloned.entries()[0].what_bytes(), b"object 1 0: first");
assert_eq!(
cloned.entries()[1].get_message_detail(),
b"second\0after-nul"
);
assert_eq!(
cloned.entries()[1].what_bytes(),
b"source-\xff (offset 7): second"
);
}
#[test]
fn warning_collection_length_and_empty_state_follow_pushes() {
let mut diagnostics = Diagnostics::default();
assert!(diagnostics.is_empty());
assert_eq!(diagnostics.len(), 0);
diagnostics.push(QpdfExc::new(QpdfErrorCode::Object, b"", b"", 0, b"warning"));
assert!(!diagnostics.is_empty());
assert_eq!(diagnostics.len(), 1);
}
#[test]
fn warning_collection_drain_returns_only_warnings_since_the_previous_drain() {
let first = QpdfExc::new(QpdfErrorCode::Object, b"", b"", 0, b"first");
let second = QpdfExc::new(QpdfErrorCode::System, b"", b"", 0, b"second");
let mut diagnostics = Diagnostics::default();
diagnostics.push(first.clone());
let drained = diagnostics.drain();
assert_eq!(drained.entries(), &[first]);
assert!(diagnostics.is_empty());
diagnostics.push(second.clone());
let drained = diagnostics.drain();
assert_eq!(drained.entries(), &[second]);
assert!(diagnostics.is_empty());
}
}