/rust/registry/src/index.crates.io-1949cf8c6b5b557f/tiff-0.10.3/src/directory.rs

Source
use core::fmt;
use std::{collections::BTreeMap, num::NonZeroU64};

use crate::{
    decoder::ifd::Entry,
    tags::{IfdPointer, Tag},
};

/// An Image File Directory (IFD).
///
/// A directory is a map of [`Tag`]s to [`Value`](crate::decoder::ifd::Value)s. The values are
/// stored anywhere in the file, with the directory containing the offsets and length of the
/// associated values for each tag present in the directory.
///
/// A directory can be created with with
/// [`Decoder::read_directory`](crate::decoder::Decoder::read_directory) or as an empty directory
/// to be extended with entries. A directory may be used with
/// [`Decoder::read_directory_tags`](crate::decoder::Decoder::read_directory_tags) to read the
/// values associated with tags from an underlying file.
#[doc(alias = "IFD")]
pub struct Directory {
    /// There are at most `u16::MAX` entries in any single directory, the count is stored as a
    /// 2-byte value. The order in the file is implied to be ascending by tag value (the decoder
    /// does not mind unordered entries).
    pub(crate) entries: BTreeMap<u16, Entry>,
    pub(crate) next_ifd: Option<NonZeroU64>,
}

impl Directory {
    /// Create a directory in an initial state without entries. Note that an empty directory can
    /// not be encoded in a file, it must contain at least one entry.
    pub fn empty() -> Self {
        Directory {
            entries: BTreeMap::new(),
            next_ifd: None,
        }
    }

    /// Retrieve the value associated with a tag.
    pub fn get(&self, tag: Tag) -> Option<&Entry> {
        self.entries.get(&tag.to_u16())
    }

    /// Check if the directory contains a specified tag.
    pub fn contains(&self, tag: Tag) -> bool {
        self.entries.contains_key(&tag.to_u16())
    }

    /// Iterate over all known and unknown tags in this directory.
    pub fn iter(&self) -> impl Iterator<Item = (Tag, &Entry)> + '_ {
        self.entries
            .iter()
            .map(|(k, v)| (Tag::from_u16_exhaustive(*k), v))
    }

    /// Insert additional entries into the directory.
    ///
    /// Note that a directory can contain at most `u16::MAX` values. There may be one entry that
    /// does not fit into the directory. This entry is silently ignored (please check [`Self::len`]
    /// to detect the condition). Providing a tag multiple times or a tag that already exists
    /// within this directory overwrites the entry.
    pub fn extend(&mut self, iter: impl IntoIterator<Item = (Tag, Entry)>) {
        // Code size conscious extension, avoid monomorphic extensions with the assumption of these
        // not being performance sensitive in practice. (Maybe we have a polymorphic interface for
        // the crate usage in the future.
        self.extend_inner(iter.into_iter().by_ref())
    }

    /// Get the number of entries.
    pub fn len(&self) -> usize {
        // The keys are `u16`. Since IFDs are required to have at least one entry this would have
        // been a trivial thing to do in the specification by storing it minus one but alas. In
        // BigTIFF the count is stored as 8-bit anyways.
        self.entries.len()
    }

    /// Check if there are any entries in this directory. Note that an empty directory can not be
    /// encoded in the file, it must contain at least one entry.
    pub fn is_empty(&self) -> bool {
        self.entries.is_empty()
    }

    /// Get the pointer to the next IFD, if it was defined.
    pub fn next(&self) -> Option<IfdPointer> {
        self.next_ifd.map(|n| IfdPointer(n.get()))
    }

    pub fn set_next(&mut self, next: Option<IfdPointer>) {
        self.next_ifd = next.and_then(|n| NonZeroU64::new(n.0));
    }

    fn extend_inner(&mut self, iter: &mut dyn Iterator<Item = (Tag, Entry)>) {
        for (tag, entry) in iter {
            // If the tag is already present, it will be overwritten.
            let map_entry = self.entries.entry(tag.to_u16());

            match map_entry {
                std::collections::btree_map::Entry::Vacant(vacant_entry) => {
                    vacant_entry.insert(entry);
                }
                std::collections::btree_map::Entry::Occupied(mut occupied_entry) => {
                    occupied_entry.insert(entry);
                }
            }
        }
    }
}

impl fmt::Debug for Directory {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("Directory")
            .field(
                "entries",
                &self.entries.iter().map(|(k, v)| (Tag::from_u16(*k), v)),
            )
            .field("next_ifd", &self.next_ifd)
            .finish()
    }
}

#[cfg(test)]
mod tests {
    use super::Directory;
    use crate::{decoder::ifd::Entry, tags::Tag};

    #[test]
    fn directory_multiple_entries() {
        let mut dir = Directory::empty();
        assert_eq!(dir.len(), 0);

        dir.extend((0..=u16::MAX).map(|i| {
            let tag = Tag::Unknown(1);
            let entry = Entry::new_u64(crate::tags::Type::BYTE, i.into(), [0; 8]);
            (tag, entry)
        }));

        assert_eq!(dir.len(), 1, "Only one tag was ever modified");

        assert_eq!(
            dir.get(Tag::Unknown(1))
                .expect("tag 1 should be present after this chain")
                .count(),
            u16::MAX.into()
        );
    }

    #[test]
    fn iteration_order() {
        let mut dir = Directory::empty();
        assert_eq!(dir.len(), 0);

        let fake_entry = Entry::new_u64(crate::tags::Type::BYTE, 0, [0; 8]);
        dir.extend((0..32).map(|i| {
            let tag = Tag::Unknown(i);
            let entry = fake_entry.clone();
            (tag, entry)
        }));

        let iter_order: Vec<u16> = dir.iter().map(|(tag, _e)| tag.to_u16()).collect();
        assert_eq!(
            iter_order,
            (0..32).collect::<Vec<_>>(),
            "Tags must be in ascending order according to the specification"
        );
    }
}

Line	Count	Source
1		use core::fmt;
2		use std::{collections::BTreeMap, num::NonZeroU64};
3
4		use crate::{
5		decoder::ifd::Entry,
6		tags::{IfdPointer, Tag},
7		};
8
9		/// An Image File Directory (IFD).
10		///
11		/// A directory is a map of [`Tag`]s to [`Value`](crate::decoder::ifd::Value)s. The values are
12		/// stored anywhere in the file, with the directory containing the offsets and length of the
13		/// associated values for each tag present in the directory.
14		///
15		/// A directory can be created with with
16		/// [`Decoder::read_directory`](crate::decoder::Decoder::read_directory) or as an empty directory
17		/// to be extended with entries. A directory may be used with
18		/// [`Decoder::read_directory_tags`](crate::decoder::Decoder::read_directory_tags) to read the
19		/// values associated with tags from an underlying file.
20		#[doc(alias = "IFD")]
21		pub struct Directory {
22		/// There are at most `u16::MAX` entries in any single directory, the count is stored as a
23		/// 2-byte value. The order in the file is implied to be ascending by tag value (the decoder
24		/// does not mind unordered entries).
25		pub(crate) entries: BTreeMap<u16, Entry>,
26		pub(crate) next_ifd: Option<NonZeroU64>,
27		}
28
29		impl Directory {
30		/// Create a directory in an initial state without entries. Note that an empty directory can
31		/// not be encoded in a file, it must contain at least one entry.
32	0	pub fn empty() -> Self {
33	0	Directory {
34	0	entries: BTreeMap::new(),
35	0	next_ifd: None,
36	0	}
37	0	}
38
39		/// Retrieve the value associated with a tag.
40	51.3k	pub fn get(&self, tag: Tag) -> Option<&Entry> {
41	51.3k	self.entries.get(&tag.to_u16())
42	51.3k	}
43
44		/// Check if the directory contains a specified tag.
45	16.9k	pub fn contains(&self, tag: Tag) -> bool {
46	16.9k	self.entries.contains_key(&tag.to_u16())
47	16.9k	}
48
49		/// Iterate over all known and unknown tags in this directory.
50	0	pub fn iter(&self) -> impl Iterator<Item = (Tag, &Entry)> + '_ {
51	0	self.entries
52	0	.iter()
53	0	.map(\|(k, v)\| (Tag::from_u16_exhaustive(*k), v)) Unexecuted instantiation: <tiff::directory::Directory>::iter::{closure#0} Unexecuted instantiation: <tiff::directory::Directory>::iter::{closure#0}
54	0	}
55
56		/// Insert additional entries into the directory.
57		///
58		/// Note that a directory can contain at most `u16::MAX` values. There may be one entry that
59		/// does not fit into the directory. This entry is silently ignored (please check [`Self::len`]
60		/// to detect the condition). Providing a tag multiple times or a tag that already exists
61		/// within this directory overwrites the entry.
62	0	pub fn extend(&mut self, iter: impl IntoIterator<Item = (Tag, Entry)>) {
63		// Code size conscious extension, avoid monomorphic extensions with the assumption of these
64		// not being performance sensitive in practice. (Maybe we have a polymorphic interface for
65		// the crate usage in the future.
66	0	self.extend_inner(iter.into_iter().by_ref())
67	0	} Unexecuted instantiation: <tiff::directory::Directory>::extend::<_> Unexecuted instantiation: <tiff::directory::Directory>::extend::<[(tiff::tags::Tag, tiff::decoder::ifd::Entry); 1]>
68
69		/// Get the number of entries.
70	0	pub fn len(&self) -> usize {
71		// The keys are `u16`. Since IFDs are required to have at least one entry this would have
72		// been a trivial thing to do in the specification by storing it minus one but alas. In
73		// BigTIFF the count is stored as 8-bit anyways.
74	0	self.entries.len()
75	0	}
76
77		/// Check if there are any entries in this directory. Note that an empty directory can not be
78		/// encoded in the file, it must contain at least one entry.
79	0	pub fn is_empty(&self) -> bool {
80	0	self.entries.is_empty()
81	0	}
82
83		/// Get the pointer to the next IFD, if it was defined.
84	7.30k	pub fn next(&self) -> Option<IfdPointer> {
85	7.30k	self.next_ifd.map(\|n\| IfdPointer(n.get()))
86	7.30k	}
87
88	0	pub fn set_next(&mut self, next: Option<IfdPointer>) {
89	0	self.next_ifd = next.and_then(\|n\| NonZeroU64::new(n.0));
90	0	}
91
92	0	fn extend_inner(&mut self, iter: &mut dyn Iterator<Item = (Tag, Entry)>) {
93	0	for (tag, entry) in iter {
94		// If the tag is already present, it will be overwritten.
95	0	let map_entry = self.entries.entry(tag.to_u16());
96
97	0	match map_entry {
98	0	std::collections::btree_map::Entry::Vacant(vacant_entry) => {
99	0	vacant_entry.insert(entry);
100	0	}
101	0	std::collections::btree_map::Entry::Occupied(mut occupied_entry) => {
102	0	occupied_entry.insert(entry);
103	0	}
104		}
105		}
106	0	}
107		}
108
109		impl fmt::Debug for Directory {
110	0	fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
111	0	f.debug_struct("Directory")
112	0	.field(
113	0	"entries",
114	0	&self.entries.iter().map(\|(k, v)\| (Tag::from_u16(*k), v)),
115		)
116	0	.field("next_ifd", &self.next_ifd)
117	0	.finish()
118	0	}
119		}
120
121		#[cfg(test)]
122		mod tests {
123		use super::Directory;
124		use crate::{decoder::ifd::Entry, tags::Tag};
125
126		#[test]
127		fn directory_multiple_entries() {
128		let mut dir = Directory::empty();
129		assert_eq!(dir.len(), 0);
130
131		dir.extend((0..=u16::MAX).map(\|i\| {
132		let tag = Tag::Unknown(1);
133		let entry = Entry::new_u64(crate::tags::Type::BYTE, i.into(), [0; 8]);
134		(tag, entry)
135		}));
136
137		assert_eq!(dir.len(), 1, "Only one tag was ever modified");
138
139		assert_eq!(
140		dir.get(Tag::Unknown(1))
141		.expect("tag 1 should be present after this chain")
142		.count(),
143		u16::MAX.into()
144		);
145		}
146
147		#[test]
148		fn iteration_order() {
149		let mut dir = Directory::empty();
150		assert_eq!(dir.len(), 0);
151
152		let fake_entry = Entry::new_u64(crate::tags::Type::BYTE, 0, [0; 8]);
153		dir.extend((0..32).map(\|i\| {
154		let tag = Tag::Unknown(i);
155		let entry = fake_entry.clone();
156		(tag, entry)
157		}));
158
159		let iter_order: Vec<u16> = dir.iter().map(\|(tag, _e)\| tag.to_u16()).collect();
160		assert_eq!(
161		iter_order,
162		(0..32).collect::<Vec<_>>(),
163		"Tags must be in ascending order according to the specification"
164		);
165		}
166		}

Coverage Report

Created: 2025-10-12 08:06