pub struct NameTree { /* private fields */ }Expand description
Read and modify a PDF name tree (a /Names-style sorted key/value index).
Name keys are supplied as UTF-8 bytes. Both byte slices and strings are
accepted through [AsRef<[u8]>].
qpdf correspondence: NNTreeImpl (libqpdf/NNTree.cc) constructed with
NameTreeDetails (libqpdf/QPDFNameTreeObjectHelper.cc).
Implementations§
Source§impl NameTree
impl NameTree
Sourcepub fn new(root: ObjectHandle, auto_repair: bool) -> Self
pub fn new(root: ObjectHandle, auto_repair: bool) -> Self
Wrap an existing name-tree root handle.
The first PDF passed to an operation claims the handle’s document boundary; subsequent operations reject handles from another PDF.
Sourcepub fn new_empty<R: Read + Seek>(
pdf: &mut Pdf<R>,
auto_repair: bool,
) -> Result<Self>
pub fn new_empty<R: Read + Seek>( pdf: &mut Pdf<R>, auto_repair: bool, ) -> Result<Self>
Create an empty name tree with an indirect root.
§Errors
Returns an error when the PDF object-number space is exhausted.
Sourcepub fn get_object_handle(&self) -> ObjectHandle
pub fn get_object_handle(&self) -> ObjectHandle
Return the live root handle, matching qpdf’s getObjectHandle.
Sourcepub fn end(&self) -> NameTreeCursor
pub fn end(&self) -> NameTreeCursor
Return an invalid cursor representing the position past the tree.
Sourcepub fn begin<R: Read + Seek>(
&mut self,
pdf: &mut Pdf<R>,
) -> Result<NameTreeCursor>
pub fn begin<R: Read + Seek>( &mut self, pdf: &mut Pdf<R>, ) -> Result<NameTreeCursor>
Return a cursor positioned at the first entry.
§Errors
Returns an error when the tree cannot be resolved or traversed.
Sourcepub fn last<R: Read + Seek>(
&mut self,
pdf: &mut Pdf<R>,
) -> Result<NameTreeCursor>
pub fn last<R: Read + Seek>( &mut self, pdf: &mut Pdf<R>, ) -> Result<NameTreeCursor>
Return a cursor positioned at the last entry.
§Errors
Returns an error when the tree cannot be resolved or traversed.
Sourcepub fn find<R: Read + Seek, K: AsRef<[u8]>>(
&mut self,
pdf: &mut Pdf<R>,
key: K,
return_previous_if_missing: bool,
) -> Result<NameTreeCursor>
pub fn find<R: Read + Seek, K: AsRef<[u8]>>( &mut self, pdf: &mut Pdf<R>, key: K, return_previous_if_missing: bool, ) -> Result<NameTreeCursor>
Find key, optionally returning the closest lower entry.
§Errors
Returns an error when the tree cannot be resolved or searched.
Sourcepub fn insert<R: Read + Seek, K: AsRef<[u8]>>(
&mut self,
pdf: &mut Pdf<R>,
key: K,
value: ObjectHandle,
) -> Result<NameTreeCursor>
pub fn insert<R: Read + Seek, K: AsRef<[u8]>>( &mut self, pdf: &mut Pdf<R>, key: K, value: ObjectHandle, ) -> Result<NameTreeCursor>
Insert or replace an entry and return a cursor positioned at it.
§Errors
Returns an error when the tree cannot be resolved or mutated.
Sourcepub fn has_name<R: Read + Seek, K: AsRef<[u8]>>(
&mut self,
pdf: &mut Pdf<R>,
key: K,
) -> Result<bool>
pub fn has_name<R: Read + Seek, K: AsRef<[u8]>>( &mut self, pdf: &mut Pdf<R>, key: K, ) -> Result<bool>
Return whether the tree contains an explicit entry for key.
§Errors
Returns an error when the tree cannot be resolved or searched.
Sourcepub fn find_object<R: Read + Seek, K: AsRef<[u8]>>(
&mut self,
pdf: &mut Pdf<R>,
key: K,
) -> Result<Option<ObjectHandle>>
pub fn find_object<R: Read + Seek, K: AsRef<[u8]>>( &mut self, pdf: &mut Pdf<R>, key: K, ) -> Result<Option<ObjectHandle>>
Find the value stored at key.
§Errors
Returns an error when the tree cannot be resolved or searched.
Sourcepub fn remove<R: Read + Seek, K: AsRef<[u8]>>(
&mut self,
pdf: &mut Pdf<R>,
key: K,
) -> Result<Option<ObjectHandle>>
pub fn remove<R: Read + Seek, K: AsRef<[u8]>>( &mut self, pdf: &mut Pdf<R>, key: K, ) -> Result<Option<ObjectHandle>>
Remove the entry at key, returning its former value.
§Errors
Returns an error when the tree cannot be resolved or mutated.
Sourcepub fn as_map<R: Read + Seek>(
&mut self,
pdf: &mut Pdf<R>,
) -> Result<BTreeMap<Vec<u8>, ObjectHandle>>
pub fn as_map<R: Read + Seek>( &mut self, pdf: &mut Pdf<R>, ) -> Result<BTreeMap<Vec<u8>, ObjectHandle>>
Materialize the tree as a sorted map.
§Errors
Returns an error when the tree cannot be resolved or traversed.
Sourcepub fn set_split_threshold(&mut self, threshold: usize)
pub fn set_split_threshold(&mut self, threshold: usize)
Set the node split threshold.
This exists for qpdf-compatible tests; production callers normally retain the default threshold of 32.
Sourcepub fn set_max_depth(&mut self, max_depth: usize)
pub fn set_max_depth(&mut self, max_depth: usize)
Bound /Kids chain traversal to max_depth levels.
Unbounded by default; a caller reading an untrusted document should
set this (e.g. to DEFAULT_MAX_TREE_DEPTH) to reject a
pathologically deep tree with crate::Error::Unsupported instead
of recursing without bound.