diff --git a/src/doc.rs b/src/doc.rs new file mode 100644 index 0000000..fca304a --- /dev/null +++ b/src/doc.rs @@ -0,0 +1,146 @@ +// +// Copyright (c) 2020 KAMADA Ken'ichi. +// All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions +// are met: +// 1. Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// 2. Redistributions in binary form must reproduce the above copyright +// notice, this list of conditions and the following disclaimer in the +// documentation and/or other materials provided with the distribution. +// +// THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +// ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +// FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +// DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +// OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +// HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +// LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +// OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +// SUCH DAMAGE. +// + +//! Documentation + +/// # Upgrade Guide +/// +/// ## Upgrade from 0.4.x to 0.5.x +/// +/// ### API compatibilities +/// +/// * `Reader` has been split into two: `Reader` and `Exif`. +/// `Reader` is now the builder for `Exif`, and `Exif` provides +/// access to `Field`s via `get_field`, `fields`, and other methods. +/// Old code `Reader::new(data)` should be changed to +/// `Reader::new().read_raw(data)` or +/// `Reader::new().read_from_container(data)`. +/// +/// The old code using 0.4.x: +/// ```ignore +/// # use exif::Reader; +/// # let file = std::fs::File::open("tests/exif.jpg").unwrap(); +/// # let mut bufreader = std::io::BufReader::new(&file); +/// let reader = Reader::new(&mut bufreader).unwrap(); +/// for f in reader.fields() { /* do something */ } +/// ``` +/// The new code using 0.5.x: +/// ``` +/// # use exif::{Exif, Reader}; +/// # let file = std::fs::File::open("tests/exif.jpg").unwrap(); +/// # let mut bufreader = std::io::BufReader::new(&file); +/// let exif = Reader::new().read_from_container(&mut bufreader).unwrap(); +/// for f in exif.fields() { /* do something */ } +/// ``` +/// +/// ### Other new features +/// +/// * Support for parsing Exif in HEIF (HEIC/AVIF) has been added. +/// +/// ## Upgrade from 0.3.x to 0.4.x +/// +/// ### API compatibilities +/// +/// * Use struct `In` instead of `bool` to indicate primary/thumbnail images. +/// - On `Reader::get_field`, the old code using 0.3.x: +/// ```ignore +/// reader.get_field(Tag::DateTime, false) +/// ``` +/// The new code using 0.4.x: +/// ```ignore +/// # use exif::{In, Reader, Tag}; +/// # let file = std::fs::File::open("tests/exif.tif").unwrap(); +/// # let reader = Reader::new( +/// # &mut std::io::BufReader::new(&file)).unwrap(); +/// reader.get_field(Tag::DateTime, In::PRIMARY) +/// # ; +/// ``` +/// As an additional feature, access to the 2nd or further IFD, +/// which some TIFF-based RAW formats may have, is also possible +/// with 0.4.x: +/// ```ignore +/// # use exif::{In, Reader, Tag}; +/// # let file = std::fs::File::open("tests/exif.tif").unwrap(); +/// # let reader = Reader::new( +/// # &mut std::io::BufReader::new(&file)).unwrap(); +/// reader.get_field(Tag::ImageWidth, In(2)) +/// # ; +/// ``` +/// - On `Field`, the old code using 0.3.x: +/// ```ignore +/// if field.thumbnail { +/// // for the thumbnail image +/// } else { +/// // for the primary image +/// } +/// ``` +/// The new code using 0.4.x: +/// ``` +/// # use exif::{In, Reader}; +/// # let file = std::fs::File::open("tests/exif.tif").unwrap(); +/// # let exif = Reader::new().read_from_container( +/// # &mut std::io::BufReader::new(&file)).unwrap(); +/// # let field = exif.fields().next().unwrap(); +/// match field.ifd_num { +/// In::PRIMARY => {}, // for the primary image +/// In::THUMBNAIL => {}, // for the thumbnail image +/// _ => {}, +/// } +/// ``` +/// * `Reader::fields` now returns an iterator instead of a slice. +/// * Enum variants of `Context` and `Error` are no longer exhaustive. +/// You need a wildcard arm (`_`) in a match expression. +/// * The associated value of `Value::Undefined` and `Value::Ascii` has +/// been changed from a slice to a `Vec`. +/// +/// ### Other new features +/// +/// * `Field::display_value` has been introduced. +/// It is usually handier than `Value::display_as`. +/// ``` +/// # let file = std::fs::File::open("tests/exif.tif").unwrap(); +/// # let exif = exif::Reader::new().read_from_container( +/// # &mut std::io::BufReader::new(&file)).unwrap(); +/// # let field = exif.fields().next().unwrap(); +/// assert_eq!(field.display_value().to_string(), +/// field.value.display_as(field.tag).to_string()); +/// ``` +/// * Displaying a value with its unit is supported. +/// ```ignore +/// # let file = std::fs::File::open("tests/exif.tif").unwrap(); +/// # let reader = exif::Reader::new( +/// # &mut std::io::BufReader::new(&file)).unwrap(); +/// # let field = reader.fields().next().unwrap(); +/// // Display the value only. +/// println!("{}", field.display_value()); +/// // Display the value with its unit. If the unit depends on another +/// // field, it is taken from the reader. +/// println!("{}", field.display_value().with_unit(&reader)); +/// ``` +/// * `Value` and `Field` are self-contained and no longer borrow the raw +/// buffer or `Reader` (thanks to the change of `Value::Undefined` +/// and `Value::Ascii` described above). +pub mod upgrade {} diff --git a/src/lib.rs b/src/lib.rs index ab1031b..3be59cd 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -49,121 +49,9 @@ //! # Ok(()) } //! ``` //! -//! # Upgrade Guide from 0.4.x to 0.5.x +//! # Upgrade Guide //! -//! ## API compatibilities -//! -//! * `Reader` has been split into two: `Reader` and `Exif`. -//! `Reader` is now the builder for `Exif`, and `Exif` provides -//! access to `Field`s via `get_field`, `fields`, and other methods. -//! Old code `Reader::new(data)` should be changed to -//! `Reader::new().read_raw(data)` or -//! `Reader::new().read_from_container(data)`. -//! -//! The old code using 0.4.x: -//! ```ignore -//! # use exif::Reader; -//! # let file = std::fs::File::open("tests/exif.jpg").unwrap(); -//! # let mut bufreader = std::io::BufReader::new(&file); -//! let reader = Reader::new(&mut bufreader).unwrap(); -//! for f in reader.fields() { /* do something */ } -//! ``` -//! The new code using 0.5.x: -//! ``` -//! # use exif::{Exif, Reader}; -//! # let file = std::fs::File::open("tests/exif.jpg").unwrap(); -//! # let mut bufreader = std::io::BufReader::new(&file); -//! let exif = Reader::new().read_from_container(&mut bufreader).unwrap(); -//! for f in exif.fields() { /* do something */ } -//! ``` -//! -//! ## Other new features -//! -//! * Support for parsing Exif in HEIF (HEIC/AVIF) has been added. -//! -//! # Upgrade Guide from 0.3.x to 0.4.x -//! -//! ## API compatibilities -//! -//! * Use struct `In` instead of `bool` to indicate primary/thumbnail images. -//! - On `Reader::get_field`, the old code using 0.3.x: -//! ```ignore -//! reader.get_field(Tag::DateTime, false) -//! ``` -//! The new code using 0.4.x: -//! ```ignore -//! # use exif::{In, Reader, Tag}; -//! # let file = std::fs::File::open("tests/exif.tif").unwrap(); -//! # let reader = Reader::new( -//! # &mut std::io::BufReader::new(&file)).unwrap(); -//! reader.get_field(Tag::DateTime, In::PRIMARY) -//! # ; -//! ``` -//! As an additional feature, access to the 2nd or further IFD, -//! which some TIFF-based RAW formats may have, is also possible -//! with 0.4.x: -//! ```ignore -//! # use exif::{In, Reader, Tag}; -//! # let file = std::fs::File::open("tests/exif.tif").unwrap(); -//! # let reader = Reader::new( -//! # &mut std::io::BufReader::new(&file)).unwrap(); -//! reader.get_field(Tag::ImageWidth, In(2)) -//! # ; -//! ``` -//! - On `Field`, the old code using 0.3.x: -//! ```ignore -//! if field.thumbnail { -//! // for the thumbnail image -//! } else { -//! // for the primary image -//! } -//! ``` -//! The new code using 0.4.x: -//! ``` -//! # use exif::{In, Reader}; -//! # let file = std::fs::File::open("tests/exif.tif").unwrap(); -//! # let exif = Reader::new().read_from_container( -//! # &mut std::io::BufReader::new(&file)).unwrap(); -//! # let field = exif.fields().next().unwrap(); -//! match field.ifd_num { -//! In::PRIMARY => {}, // for the primary image -//! In::THUMBNAIL => {}, // for the thumbnail image -//! _ => {}, -//! } -//! ``` -//! * `Reader::fields` now returns an iterator instead of a slice. -//! * Enum variants of `Context` and `Error` are no longer exhaustive. -//! You need a wildcard arm (`_`) in a match expression. -//! * The associated value of `Value::Undefined` and `Value::Ascii` has -//! been changed from a slice to a `Vec`. -//! -//! ## Other new features -//! -//! * `Field::display_value` has been introduced. -//! It is usually handier than `Value::display_as`. -//! ``` -//! # let file = std::fs::File::open("tests/exif.tif").unwrap(); -//! # let exif = exif::Reader::new().read_from_container( -//! # &mut std::io::BufReader::new(&file)).unwrap(); -//! # let field = exif.fields().next().unwrap(); -//! assert_eq!(field.display_value().to_string(), -//! field.value.display_as(field.tag).to_string()); -//! ``` -//! * Displaying a value with its unit is supported. -//! ```ignore -//! # let file = std::fs::File::open("tests/exif.tif").unwrap(); -//! # let reader = exif::Reader::new( -//! # &mut std::io::BufReader::new(&file)).unwrap(); -//! # let field = reader.fields().next().unwrap(); -//! // Display the value only. -//! println!("{}", field.display_value()); -//! // Display the value with its unit. If the unit depends on another -//! // field, it is taken from the reader. -//! println!("{}", field.display_value().with_unit(&reader)); -//! ``` -//! * `Value` and `Field` are self-contained and no longer borrow the raw -//! buffer or `Reader` (thanks to the change of `Value::Undefined` -//! and `Value::Ascii` described above). +//! See the [upgrade guide](doc/upgrade/index.html) for API incompatibilities. pub use error::Error; pub use jpeg::get_exif_attr as get_exif_attr_from_jpeg; @@ -183,6 +71,7 @@ pub mod experimental { #[macro_use] mod tmacro; +pub mod doc; mod endian; mod error; mod isobmff;