exif/doc.rs
1//
2// Copyright (c) 2020 KAMADA Ken'ichi.
3// All rights reserved.
4//
5// Redistribution and use in source and binary forms, with or without
6// modification, are permitted provided that the following conditions
7// are met:
8// 1. Redistributions of source code must retain the above copyright
9// notice, this list of conditions and the following disclaimer.
10// 2. Redistributions in binary form must reproduce the above copyright
11// notice, this list of conditions and the following disclaimer in the
12// documentation and/or other materials provided with the distribution.
13//
14// THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
15// ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
17// ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
18// FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
19// DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
20// OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
21// HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
22// LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
23// OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
24// SUCH DAMAGE.
25//
26
27//! Documentation
28
29// Rust 1.54 stabilized invoking function-like macros in attributes.
30// We will use it after bumping MSRV.
31// #![feature(extended_key_value_attributes)],
32// #[doc = include_str!("../NEWS")]
33// pub mod news {}
34macro_rules! doc_module_with_external_source {
35 ($( #[$attr:meta] )*
36 $name: ident, $doc: expr) => {
37 $( #[$attr] )*
38 #[doc = ""]
39 #[doc = $doc]
40 pub mod $name {}
41 }
42}
43doc_module_with_external_source!(
44 /// # News
45 news, include_str!("../NEWS"));
46
47/// # Upgrade Guide
48///
49/// ## Upgrade from 0.4.x to 0.5.x
50///
51/// ### API compatibilities
52///
53/// * `Reader` has been split into two: `Reader` and `Exif`.
54/// `Reader` is now the builder for `Exif`, and `Exif` provides
55/// access to `Field`s via `get_field`, `fields`, and other methods.
56/// Old code `Reader::new(data)` should be changed to
57/// `Reader::new().read_raw(data)` or
58/// `Reader::new().read_from_container(data)`.
59///
60/// The old code using 0.4.x:
61/// ```ignore
62/// # use exif::Reader;
63/// # let file = std::fs::File::open("tests/exif.jpg").unwrap();
64/// # let mut bufreader = std::io::BufReader::new(&file);
65/// let reader = Reader::new(&mut bufreader).unwrap();
66/// for f in reader.fields() { /* do something */ }
67/// ```
68/// The new code using 0.5.x:
69/// ```
70/// # use exif::{Exif, Reader};
71/// # let file = std::fs::File::open("tests/exif.jpg").unwrap();
72/// # let mut bufreader = std::io::BufReader::new(&file);
73/// let exif = Reader::new().read_from_container(&mut bufreader).unwrap();
74/// for f in exif.fields() { /* do something */ }
75/// ```
76///
77/// ### Other new features
78///
79/// * Support for parsing Exif in HEIF (HEIC/AVIF) has been added.
80///
81/// ## Upgrade from 0.3.x to 0.4.x
82///
83/// ### API compatibilities
84///
85/// * Use struct `In` instead of `bool` to indicate primary/thumbnail images.
86/// - On `Reader::get_field`, the old code using 0.3.x:
87/// ```ignore
88/// reader.get_field(Tag::DateTime, false)
89/// ```
90/// The new code using 0.4.x:
91/// ```ignore
92/// # use exif::{In, Reader, Tag};
93/// # let file = std::fs::File::open("tests/exif.tif").unwrap();
94/// # let reader = Reader::new(
95/// # &mut std::io::BufReader::new(&file)).unwrap();
96/// reader.get_field(Tag::DateTime, In::PRIMARY)
97/// # ;
98/// ```
99/// As an additional feature, access to the 2nd or further IFD,
100/// which some TIFF-based RAW formats may have, is also possible
101/// with 0.4.x:
102/// ```ignore
103/// # use exif::{In, Reader, Tag};
104/// # let file = std::fs::File::open("tests/exif.tif").unwrap();
105/// # let reader = Reader::new(
106/// # &mut std::io::BufReader::new(&file)).unwrap();
107/// reader.get_field(Tag::ImageWidth, In(2))
108/// # ;
109/// ```
110/// - On `Field`, the old code using 0.3.x:
111/// ```ignore
112/// if field.thumbnail {
113/// // for the thumbnail image
114/// } else {
115/// // for the primary image
116/// }
117/// ```
118/// The new code using 0.4.x:
119/// ```
120/// # use exif::{In, Reader};
121/// # let file = std::fs::File::open("tests/exif.tif").unwrap();
122/// # let exif = Reader::new().read_from_container(
123/// # &mut std::io::BufReader::new(&file)).unwrap();
124/// # let field = exif.fields().next().unwrap();
125/// match field.ifd_num {
126/// In::PRIMARY => {}, // for the primary image
127/// In::THUMBNAIL => {}, // for the thumbnail image
128/// _ => {},
129/// }
130/// ```
131/// * `Reader::fields` now returns an iterator instead of a slice.
132/// * Enum variants of `Context` and `Error` are no longer exhaustive.
133/// You need a wildcard arm (`_`) in a match expression.
134/// * The associated value of `Value::Undefined` and `Value::Ascii` has
135/// been changed from a slice to a `Vec`.
136///
137/// ### Other new features
138///
139/// * `Field::display_value` has been introduced.
140/// It is usually handier than `Value::display_as`.
141/// ```
142/// # let file = std::fs::File::open("tests/exif.tif").unwrap();
143/// # let exif = exif::Reader::new().read_from_container(
144/// # &mut std::io::BufReader::new(&file)).unwrap();
145/// # let field = exif.fields().next().unwrap();
146/// assert_eq!(field.display_value().to_string(),
147/// field.value.display_as(field.tag).to_string());
148/// ```
149/// * Displaying a value with its unit is supported.
150/// ```ignore
151/// # let file = std::fs::File::open("tests/exif.tif").unwrap();
152/// # let reader = exif::Reader::new(
153/// # &mut std::io::BufReader::new(&file)).unwrap();
154/// # let field = reader.fields().next().unwrap();
155/// // Display the value only.
156/// println!("{}", field.display_value());
157/// // Display the value with its unit. If the unit depends on another
158/// // field, it is taken from the reader.
159/// println!("{}", field.display_value().with_unit(&reader));
160/// ```
161/// * `Value` and `Field` are self-contained and no longer borrow the raw
162/// buffer or `Reader` (thanks to the change of `Value::Undefined`
163/// and `Value::Ascii` described above).
164pub mod upgrade {}