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/// # News
30#[doc = include_str!("../NEWS")]
31pub mod news {}
32
33/// # Upgrade Guide
34///
35/// ## Upgrade from 0.5.x to 0.6.x
36///
37/// ### API compatibilities
38///
39/// * `From<Rational>` and `From<SRational>` implementations for `f32`
40///   and `f64` have been removed.
41///   Use `Rational::to_f64` and so on.
42///
43/// ### Compiler
44///
45/// * Rust 1.60 or later is required.
46///
47/// ## Upgrade from 0.4.x to 0.5.x
48///
49/// ### API compatibilities
50///
51/// * `Reader` has been split into two: `Reader` and `Exif`.
52///   `Reader` is now the builder for `Exif`, and `Exif` provides
53///   access to `Field`s via `get_field`, `fields`, and other methods.
54///   Old code `Reader::new(data)` should be changed to
55///   `Reader::new().read_raw(data)` or
56///   `Reader::new().read_from_container(data)`.
57///
58///   The old code using 0.4.x:
59///   ```ignore
60///   # use exif::Reader;
61///   # let file = std::fs::File::open("tests/exif.jpg").unwrap();
62///   # let mut bufreader = std::io::BufReader::new(&file);
63///   let reader = Reader::new(&mut bufreader).unwrap();
64///   for f in reader.fields() { /* do something */ }
65///   ```
66///   The new code using 0.5.x:
67///   ```
68///   # use exif::{Exif, Reader};
69///   # let file = std::fs::File::open("tests/exif.jpg").unwrap();
70///   # let mut bufreader = std::io::BufReader::new(&file);
71///   let exif = Reader::new().read_from_container(&mut bufreader).unwrap();
72///   for f in exif.fields() { /* do something */ }
73///   ```
74///
75/// ### Other new features
76///
77/// * Support for parsing Exif in HEIF (HEIC/AVIF) has been added.
78///
79/// ## Upgrade from 0.3.x to 0.4.x
80///
81/// ### API compatibilities
82///
83/// * Use struct `In` instead of `bool` to indicate primary/thumbnail images.
84///   - On `Reader::get_field`, the old code using 0.3.x:
85///     ```ignore
86///     reader.get_field(Tag::DateTime, false)
87///     ```
88///     The new code using 0.4.x:
89///     ```ignore
90///     # use exif::{In, Reader, Tag};
91///     # let file = std::fs::File::open("tests/exif.tif").unwrap();
92///     # let reader = Reader::new(
93///     #     &mut std::io::BufReader::new(&file)).unwrap();
94///     reader.get_field(Tag::DateTime, In::PRIMARY)
95///     # ;
96///     ```
97///     As an additional feature, access to the 2nd or further IFD,
98///     which some TIFF-based RAW formats may have, is also possible
99///     with 0.4.x:
100///     ```ignore
101///     # use exif::{In, Reader, Tag};
102///     # let file = std::fs::File::open("tests/exif.tif").unwrap();
103///     # let reader = Reader::new(
104///     #     &mut std::io::BufReader::new(&file)).unwrap();
105///     reader.get_field(Tag::ImageWidth, In(2))
106///     # ;
107///     ```
108///   - On `Field`, the old code using 0.3.x:
109///     ```ignore
110///     if field.thumbnail {
111///         // for the thumbnail image
112///     } else {
113///         // for the primary image
114///     }
115///     ```
116///     The new code using 0.4.x:
117///     ```
118///     # use exif::{In, Reader};
119///     # let file = std::fs::File::open("tests/exif.tif").unwrap();
120///     # let exif = Reader::new().read_from_container(
121///     #     &mut std::io::BufReader::new(&file)).unwrap();
122///     # let field = exif.fields().next().unwrap();
123///     match field.ifd_num {
124///         In::PRIMARY => {},   // for the primary image
125///         In::THUMBNAIL => {}, // for the thumbnail image
126///         _ => {},
127///     }
128///     ```
129/// * `Reader::fields` now returns an iterator instead of a slice.
130/// * Enum variants of `Context` and `Error` are no longer exhaustive.
131///   You need a wildcard arm (`_`) in a match expression.
132/// * The associated value of `Value::Undefined` and `Value::Ascii` has
133///   been changed from a slice to a `Vec`.
134///
135/// ### Other new features
136///
137/// * `Field::display_value` has been introduced.
138///   It is usually handier than `Value::display_as`.
139///   ```
140///   # let file = std::fs::File::open("tests/exif.tif").unwrap();
141///   # let exif = exif::Reader::new().read_from_container(
142///   #     &mut std::io::BufReader::new(&file)).unwrap();
143///   # let field = exif.fields().next().unwrap();
144///   assert_eq!(field.display_value().to_string(),
145///              field.value.display_as(field.tag).to_string());
146///   ```
147/// * Displaying a value with its unit is supported.
148///   ```ignore
149///   # let file = std::fs::File::open("tests/exif.tif").unwrap();
150///   # let reader = exif::Reader::new(
151///   #     &mut std::io::BufReader::new(&file)).unwrap();
152///   # let field = reader.fields().next().unwrap();
153///   // Display the value only.
154///   println!("{}", field.display_value());
155///   // Display the value with its unit.  If the unit depends on another
156///   // field, it is taken from the reader.
157///   println!("{}", field.display_value().with_unit(&reader));
158///   ```
159/// * `Value` and `Field` are self-contained and no longer borrow the raw
160///   buffer or `Reader` (thanks to the change of `Value::Undefined`
161///   and `Value::Ascii` described above).
162pub mod upgrade {}
exif/doc.rs

exif/
doc.rs
