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
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
//! Defines the [PdfBookmarks] struct, exposing functionality related to the
//! bookmarks contained within a single `PdfDocument`.
use crate::bindgen::FPDF_DOCUMENT;
use crate::bindings::PdfiumLibraryBindings;
use crate::bookmark::PdfBookmark;
use crate::error::{PdfiumError, PdfiumInternalError};
use std::ptr::null_mut;
/// The bookmarks contained within a single `PdfDocument`.
///
/// Bookmarks in PDF files form a tree structure, branching out from a top-level root bookmark.
/// The [PdfBookmarks::root()] returns the root bookmark in the containing `PdfDocument`, if any;
/// use the root's [PdfBookmark::first_child()] and [PdfBookmark::next_sibling()] functions to
/// traverse the bookmark tree.
///
/// To search the tree for a bookmark with a specific title, use the [PdfBookmarks::find_first_by_title()]
/// and [PdfBookmarks::find_all_by_title()] functions. To traverse the tree breadth-first, visiting
/// every bookmark in the tree, create an iterator using the [PdfBookmarks::iter()] function.
pub struct PdfBookmarks<'a> {
document_handle: FPDF_DOCUMENT,
bindings: &'a dyn PdfiumLibraryBindings,
}
impl<'a> PdfBookmarks<'a> {
#[inline]
pub(crate) fn from_pdfium(
document_handle: FPDF_DOCUMENT,
bindings: &'a dyn PdfiumLibraryBindings,
) -> Self {
Self {
document_handle,
bindings,
}
}
/// Returns the root [PdfBookmark] in the containing `PdfDocument`, if any.
pub fn root(&self) -> Option<PdfBookmark> {
let handle = self
.bindings
.FPDFBookmark_GetFirstChild(self.document_handle, null_mut());
if handle.is_null() {
None
} else {
Some(PdfBookmark::from_pdfium(
handle,
None,
self.document_handle,
self.bindings,
))
}
}
/// Returns the first [PdfBookmark] in the containing `PdfDocument` that has a title matching
/// the given string.
///
/// Note that bookmarks are not required to have unique titles, so in theory any number of
/// bookmarks could match a given title. This function only ever returns the first. To return
/// all matches, use [PdfBookmarks::find_all_by_title()].
pub fn find_first_by_title(&self, title: &str) -> Result<PdfBookmark, PdfiumError> {
let handle = self
.bindings
.FPDFBookmark_Find_str(self.document_handle, title);
if handle.is_null() {
Err(PdfiumError::PdfiumLibraryInternalError(
self.bindings
.get_pdfium_last_error()
.unwrap_or(PdfiumInternalError::Unknown),
))
} else {
Ok(PdfBookmark::from_pdfium(
handle,
None,
self.document_handle,
self.bindings,
))
}
}
/// Returns all [PdfBookmark] objects in the containing `PdfDocument` that have a title
/// matching the given string.
///
/// Note that bookmarks are not required to have unique titles, so in theory any number of
/// bookmarks could match a given title. This function returns all matches by performing
/// a complete breadth-first traversal of the entire bookmark tree. To return just the first
/// match, use [PdfBookmarks::find_first_by_title()].
pub fn find_all_by_title(&self, title: &str) -> Vec<PdfBookmark> {
self.iter()
.filter(|bookmark| match bookmark.title() {
Some(bookmark_title) => bookmark_title == title,
None => false,
})
.collect()
}
/// Returns a breadth-first iterator over all the [PdfBookmark] objects in the containing
/// `PdfDocument`, starting from the top-level root bookmark.
#[inline]
pub fn iter(&self) -> PdfBookmarksIterator {
PdfBookmarksIterator::new(self.root(), true, true, true, None)
}
}
pub struct PdfBookmarksIterator<'a> {
node: Option<PdfBookmark<'a>>,
include_siblings: bool,
include_direct_children: bool,
include_all_descendants: bool,
skip_sibling: Option<PdfBookmark<'a>>,
}
impl<'a> PdfBookmarksIterator<'a> {
pub(crate) fn new(
node: Option<PdfBookmark<'a>>,
include_siblings: bool,
include_direct_children: bool,
include_all_descendants: bool,
skip_sibling: Option<PdfBookmark<'a>>,
) -> Self {
PdfBookmarksIterator {
node,
include_siblings,
include_direct_children,
include_all_descendants,
skip_sibling,
}
}
}
impl<'a> Iterator for PdfBookmarksIterator<'a> {
type Item = PdfBookmark<'a>;
fn next(&mut self) -> Option<Self::Item> {
self.node = match self.node.as_ref() {
Some(current_node) => {
let next_sibling = if self.include_siblings {
match (self.skip_sibling.as_ref(), current_node.next_sibling()) {
(None, next_sibling) => next_sibling,
(Some(skip_sibling), Some(next_sibling)) => {
// PdfBookmark::iter_siblings() attempts to achieve consistent
// iteration irrespective of which sibling is used to initiate
// the traversal. It does this by actually iterating over the
// direct children of the bookmark's parent, rather than the
// immediate siblings of the target node. When we iterate over the
// siblings of the target node's parent's children, we want to
// skip over the target node itself. Check for this now.
if skip_sibling.handle() == next_sibling.handle() {
// This sibling was the target node that initiated iteration.
// Skip over it.
next_sibling.next_sibling()
} else {
Some(next_sibling)
}
}
(_, None) => None,
}
} else {
None
};
if next_sibling.is_some() {
next_sibling
} else if self.include_direct_children {
self.include_siblings = true;
self.include_direct_children = self.include_all_descendants;
current_node.first_child()
} else {
None
}
}
None => None,
};
self.node.as_ref().map(|next_node| next_node.clone())
}
}