Repository: BurntSushi/jiff (language: rust)

Issue:
expose a "broken down" representation of parsing a Temporal ISO 8601 datetime
This has come up a few times in one form or another, but it basically boils down to the fact that if you're given something like `2024-08-24T14:00:00-05`, then there's no easy way to get access to the `-05` offset. You can do it with [`strptime` APIs](https://docs.rs/jiff/latest/jiff/fmt/strtime/struct.BrokenDownTime.html#method.offset), but it's not obvious. And in particular, going that route means abandoning the Temporal ISO 8601 datetime parser, which is a fair bit more flexible (and has a specification). Trying to re-create that with `strptime` is annoying and probably impossible.

So, I think supporting this use case should be possible. But we don't want to make it work without an explicit opt-in, since (as is done today), Jiff will prevent you from parsing a `2024-08-24T14:00:00-05` directly into a `Zoned`, even though a `Zoned` can have a fixed offset time zone. The reason is that it's often a mistake to do so, since the resulting `Zoned` won't do DST safe arithmetic. [This issue on the Temporal tracker goes into this in more depth.](https://github.com/tc39/proposal-temporal/issues/2930)

One way of supporting this is by permitting the offset to be parsed via a config knob on [`jiff::fmt::temporal::DateTimeParser`](https://docs.rs/jiff/latest/jiff/fmt/temporal/struct.DateTimeParser.html). But I think a better approach is to expose a new parsing routine that returns a "parse result" indicating the components that were parsed from the string. That is strictly more flexible and might unlock some other use cases. Notably, using the Temporal ISO 8601 datetime parser currently requires one to ask for what they need. But this new API should let them parse and then _inspect_ what was given.

See also:

* https://github.com/BurntSushi/jiff/discussions/112#discussioncomment-10438890
* https://github.com/BurntSushi/jiff/discussions/181


Discussion / hints:
I believe you meant #190 rather than this in #191 ?
Gah, yup! Thank you!

Fix patch:
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 3b72000a..631d3589 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,26 @@
 # CHANGELOG
 
+0.1.20 (2025-01-03)
+===================
+This release inclues a new type, `Pieces`, in the `jiff::fmt::temporal`
+sub-module. This exposes the individual components of a parsed Temporal
+ISO 8601 datetime string. It allows users of Jiff to circumvent the checks
+in the higher level parsing routines that prevent you from shooting yourself
+in the foot.
+
+For example, parsing into a `Zoned` will return an error for raw RFC 3339
+timestamps like `2025-01-03T22:03-05` because there is no time zone annotation.
+Without a time zone, Jiff cannot do time zone aware arithmetic and rounding.
+Instead, such a datetime can only be parsed into a `Timestamp`. This lower
+level `Pieces` API now permits users of Jiff to parse this string into its
+component parts and assemble it into a `Zoned` if they so choose.
+
+Enhancements:
+
+* [#188](https://github.com/BurntSushi/jiff/issues/188):
+Add `fmt::temporal::Pieces` for granular datetime parsing and formatting.
+
+
 0.1.19 (2025-01-02)
 ===================
 This releases includes a UTF-8 related bug fix and a few enhancements.
diff --git a/src/fmt/offset.rs b/src/fmt/offset.rs
index 96da13b0..3b1a13ef 100644
--- a/src/fmt/offset.rs
+++ b/src/fmt/offset.rs
@@ -106,6 +106,7 @@ from [Temporal's hybrid grammar].
 use crate::{
     error::{err, Error, ErrorContext},
     fmt::{
+        temporal::{PiecesNumericOffset, PiecesOffset},
         util::{parse_temporal_fraction, FractionalFormatter},
         Parsed,
     },
@@ -156,6 +157,24 @@ impl ParsedOffset {
         }
     }
 
+    /// Convert a parsed offset to a more structured representation.
+    ///
+    /// This is like `to_offset`, but preserves `Z` and `-00:00` versus
+    /// `+00:00`. This does still attempt to create an `Offset`, and that
+    /// construction can fail.
+    pub(crate) fn to_pieces_offset(&self) -> Result<PiecesOffset, Error> {
+        match self.kind {
+            ParsedOffsetKind::Zulu => Ok(PiecesOffset::Zulu),
+            ParsedOffsetKind::Numeric(ref numeric) => {
+                let mut off = PiecesNumericOffset::from(numeric.to_offset()?);
+                if numeric.sign < 0 {
+                    off = off.with_negative_zero();
+                }
+                Ok(PiecesOffset::from(off))
+            }
+        }
+    }
+
     /// Whether this parsed offset corresponds to Zulu time or not.
     ///
     /// This is useful in error reporting for parsing civil times. Namely, we
diff --git a/src/fmt/rfc9557.rs b/src/fmt/rfc9557.rs
index e50cf209..817992f1 100644
--- a/src/fmt/rfc9557.rs
+++ b/src/fmt/rfc9557.rs
@@ -98,9 +98,9 @@ use crate::{
     error::{err, Error},
     fmt::{
         offset::{self, ParsedOffset},
+        temporal::{TimeZoneAnnotation, TimeZoneAnnotationKind},
         Parsed,
     },
-    tz::{TimeZone, TimeZoneDatabase},
     util::{escape, parse},
 };
 
@@ -130,41 +130,16 @@ impl<'i> ParsedAnnotations<'i> {
         ParsedAnnotations { input: escape::Bytes(&[]), time_zone: None }
     }
 
-    /// If a time zone annotation was parsed, then this returns the annotation
-    /// converted to a `TimeZone`, along with a flag indicating whether it
-    /// is "critical" or not. (When it's "critical," there should be more
-    /// stringent validation.)
+    /// Turns this parsed time zone into a structured time zone annotation,
+    /// if an annotation was found. Otherwise, returns `Ok(None)`.
     ///
-    /// If the time zone annotation parsed successfully but was either not
-    /// found in the database given or otherwise invalid, then an error is
-    /// returned.
-    ///
-    /// `None` is returned only when there was no time zone annotation.
-    pub(crate) fn to_time_zone(
+    /// This can return an error if the parsed offset could not be converted
+    /// to a `crate::tz::Offset`.
+    pub(crate) fn to_time_zone_annotation(
         &self,
-        db: &TimeZoneDatabase,
-    ) -> Result<Option<(TimeZone, bool)>, Error> {
+    ) -> Result<Option<TimeZoneAnnotation<'i>>, Error> {
         let Some(ref parsed) = self.time_zone else { return Ok(None) };
-        // NOTE: We don't currently utilize the critical flag here. Temporal
-        // seems to ignore it. It's not quite clear what else we'd do with it,
-        // particularly given that we provide a way to do conflict resolution
-        // between offsets and time zones.
-        match *parsed {
-            ParsedTimeZone::Named { critical, name } => {
-                let tz = match db.get(name) {
-                    Ok(tz) => tz,
-                    Err(err) => return Err(err!("{}", err)),
-                };
-                Ok(Some((tz, critical)))
-            }
-            ParsedTimeZone::Offset { critical, ref offset } => {
-                let offset = match offset.to_offset() {
-                    Ok(offset) => offset,
-                    Err(err) => return Err(err),
-                };
-                Ok(Some((TimeZone::fixed(offset), critical)))
-            }
-        }
+        Ok(Some(parsed.to_time_zone_annotation()?))
     }
 }
 
@@ -187,6 +162,31 @@ enum ParsedTimeZone<'i> {
     },
 }
 
+impl<'i> ParsedTimeZone<'i> {
+    /// Turns this parsed time zone into a structured time zone annotation.
+    ///
+    /// This can return an error if the parsed offset could not be converted
+    /// to a `crate::tz::Offset`.
+    ///
+    /// This also includes a flag of whether the annotation is "critical" or
+    /// not.
+    pub(crate) fn to_time_zone_annotation(
+        &self,
+    ) -> Result<TimeZoneAnnotation<'i>, Error> {
+        let (kind, critical) = match *self {
+            ParsedTimeZone::Named { name, critical } => {
+                let kind = TimeZoneAnnotationKind::from(name);
+                (kind, critical)
+            }
+            ParsedTimeZone::Offset { ref offset, critical } => {
+                let kind = TimeZoneAnnotationKind::Offset(offset.to_offset()?);
+                (kind, critical)
+            }
+        };
+        Ok(TimeZoneAnnotation { kind, critical })
+    }
+}
+
 /// A parser for RFC 9557 annotations.
 #[derive(Debug)]
 pub(crate) struct Parser {
@@ -603,8 +603,9 @@ mod tests {
                 .parse(input)
                 .unwrap()
                 .value
-                .to_time_zone(crate::tz::db())
+                .to_time_zone_annotation()
                 .unwrap()
+                .map(|ann| (ann.to_time_zone().unwrap(), ann.is_critical()))
         };
 
         insta::assert_debug_snapshot!(p(b"[America/New_York]"), @r###"
@@ -1024,13 +1025,16 @@ mod tests {
 
     #[cfg(feature = "std")]
     #[test]
-    fn err_time_zone() {
+    fn err_time_zone_db_lookup() {
         let p = |input| {
             Parser::new()
                 .parse(input)
                 .unwrap()
                 .value
-                .to_time_zone(crate::tz::db())
+                .to_time_zone_annotation()
+                .unwrap()
+                .unwrap()
+                .to_time_zone()
                 .unwrap_err()
         };
 
diff --git a/src/fmt/temporal/mod.rs b/src/fmt/temporal/mod.rs
index a1bfdd42..446d4c95 100644
--- a/src/fmt/temporal/mod.rs
+++ b/src/fmt/temporal/mod.rs
@@ -175,7 +175,13 @@ use crate::{
     SignedDuration, Timestamp, Zoned,
 };
 
+pub use self::pieces::{
+    Pieces, PiecesNumericOffset, PiecesOffset, TimeZoneAnnotation,
+    TimeZoneAnnotationKind, TimeZoneAnnotationName,
+};
+
 mod parser;
+mod pieces;
 mod printer;
 
 /// The default date time parser that we use throughout Jiff.
@@ -753,6 +759,129 @@ impl DateTimeParser {
         let time = parsed_time.to_time();
         Ok(time)
     }
+
+    /// Parse a Temporal datetime string into [`Pieces`].
+    ///
+    /// This is a lower level routine meant to give callers raw access to the
+    /// individual "pieces" of a parsed Temporal ISO 8601 datetime string.
+    /// Note that this only includes strings that have a date component.
+    ///
+    /// The benefit of this routine is that it only checks that the datetime
+    /// is itself valid. It doesn't do any automatic diambiguation, offset
+    /// conflict resolution or attempt to prevent you from shooting yourself
+    /// in the foot. For example, this routine will let you parse a fixed
+    /// offset datetime into a `Zoned` without a time zone abbreviation.
+    ///
+    /// Note that when using this routine, the
+    /// [`DateTimeParser::offset_conflict`] and
+    /// [`DateTimeParser::disambiguation`] configuration knobs are completely
+    /// ignored. This is because with the lower level `Pieces`, callers must
+    /// handle offset conflict resolution (if they want it) themselves. See
+    /// the [`Pieces`] documentation for a case study on how to do this if
+    /// you need it.
+    ///
+    /// # Errors
+    ///
+    /// This returns an error if the datetime string given is invalid or if it
+    /// is valid but doesn't fit in the date range supported by Jiff.
+    ///
+    /// # Example
+    ///
+    /// This shows how to parse a fixed offset timestamp into a `Zoned`.
+    ///
+    /// ```
+    /// use jiff::{fmt::temporal::DateTimeParser, tz::TimeZone};
+    ///
+    /// static PARSER: DateTimeParser = DateTimeParser::new();
+    ///
+    /// let timestamp = "2025-01-02T15:13-05";
+    ///
+    /// // Normally this operation will fail.
+    /// assert_eq!(
+    ///     PARSER.parse_zoned(timestamp).unwrap_err().to_string(),
+    ///     "failed to find time zone in square brackets in \
+    ///      \"2025-01-02T15:13-05\", which is required for \
+    ///      parsing a zoned instant",
+    /// );
+    ///
+    /// // But you can work-around this with `Pieces`, which gives you direct
+    /// // access to the components parsed from the string.
+    /// let pieces = PARSER.parse_pieces(timestamp)?;
+    /// let time = pieces.time().unwrap_or_else(jiff::civil::Time::midnight);
+    /// let dt = pieces.date().to_datetime(time);
+    /// let tz = match pieces.to_time_zone()? {
+    ///     Some(tz) => tz,
+    ///     None => {
+    ///         let Some(offset) = pieces.to_numeric_offset() else {
+    ///             let msg = format!(
+    ///                 "timestamp `{timestamp}` has no time zone \
+    ///                  or offset, and thus cannot be parsed into \
+    ///                  an instant",
+    ///             );
+    ///             return Err(msg.into());
+    ///         };
+    ///         TimeZone::fixed(offset)
+    ///     }
+    /// };
+    /// // We don't bother with offset conflict resolution. And note that
+    /// // this uses automatic "compatible" disambiguation in the case of
+    /// // discontinuities. Of course, this is all moot if `TimeZone` is
+    /// // fixed. The above code handles the case where it isn't!
+    /// let zdt = tz.to_zoned(dt)?;
+    /// assert_eq!(zdt.to_string(), "2025-01-02T15:13:00-05:00[-05:00]");
+    ///
+    /// # Ok::<(), Box<dyn std::error::Error>>(())
+    /// ```
+    ///
+    /// # Example: work around errors when a `Z` (Zulu) offset is encountered
+    ///
+    /// Because parsing a date with a `Z` offset and interpreting it as
+    /// a civil date or time is usually a bug, it is forbidden:
+    ///
+    /// ```
+    /// use jiff::{civil::date, fmt::temporal::DateTimeParser};
+    ///
+    /// static PARSER: DateTimeParser = DateTimeParser::new();
+    ///
+    /// assert_eq!(
+    ///     PARSER.parse_date("2024-03-10T00:00:00Z").unwrap_err().to_string(),
+    ///     "cannot parse civil date from string with a Zulu offset, \
+    ///      parse as a `Timestamp` and convert to a civil date instead",
+    /// );
+    ///
+    /// # Ok::<(), Box<dyn std::error::Error>>(())
+    /// ```
+    ///
+    /// But this sort of error checking doesn't happen when you parse into a
+    /// [`Pieces`]. You just get what was parsed, which lets you extract a
+    /// date even if the higher level APIs forbid it:
+    ///
+    /// ```
+    /// use jiff::{civil, fmt::temporal::DateTimeParser, tz::Offset};
+    ///
+    /// static PARSER: DateTimeParser = DateTimeParser::new();
+    ///
+    /// let pieces = PARSER.parse_pieces("2024-03-10T00:00:00Z")?;
+    /// assert_eq!(pieces.date(), civil::date(2024, 3, 10));
+    /// assert_eq!(pieces.time(), Some(civil::time(0, 0, 0, 0)));
+    /// assert_eq!(pieces.to_numeric_offset(), Some(Offset::UTC));
+    /// assert_eq!(pieces.to_time_zone()?, None);
+    ///
+    /// # Ok::<(), Box<dyn std::error::Error>>(())
+    /// ```
+    ///
+    /// This is usually not the right thing to do. It isn't even suggested in
+    /// the error message above. But if you know it's the right thing, then
+    /// `Pieces` will let you do it.
+    pub fn parse_pieces<'i, I: ?Sized + AsRef<[u8]> + 'i>(
+        &self,
+        input: &'i I,
+    ) -> Result<Pieces<'i>, Error> {
+        let input = input.as_ref();
+        let parsed = self.p.parse_temporal_datetime(input)?.into_full()?;
+        let pieces = parsed.to_pieces()?;
+        Ok(pieces)
+    }
 }
 
 /// A printer for Temporal datetimes.
@@ -1162,6 +1291,50 @@ impl DateTimePrinter {
         buf
     }
 
+    /// Format `Pieces` of a Temporal datetime.
+    ///
+    /// This is a convenience routine for [`DateTimePrinter::print_pieces`]
+    /// with a `String`.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use jiff::{
+    ///     fmt::temporal::{DateTimePrinter, Pieces},
+    ///     tz::offset,
+    ///     Timestamp,
+    /// };
+    ///
+    /// const PRINTER: DateTimePrinter = DateTimePrinter::new();
+    ///
+    /// let pieces = Pieces::from(Timestamp::UNIX_EPOCH);
+    /// assert_eq!(
+    ///     PRINTER.pieces_to_string(&pieces),
+    ///     "1970-01-01T00:00:00Z",
+    /// );
+    ///
+    /// let pieces = Pieces::from((Timestamp::UNIX_EPOCH, offset(0)));
+    /// assert_eq!(
+    ///     PRINTER.pieces_to_string(&pieces),
+    ///     "1970-01-01T00:00:00+00:00",
+    /// );
+    ///
+    /// let pieces = Pieces::from((Timestamp::UNIX_EPOCH, offset(-5)));
+    /// assert_eq!(
+    ///     PRINTER.pieces_to_string(&pieces),
+    ///     "1969-12-31T19:00:00-05:00",
+    /// );
+    ///
+    /// # Ok::<(), Box<dyn std::error::Error>>(())
+    /// ```
+    #[cfg(feature = "alloc")]
+    pub fn pieces_to_string(&self, pieces: &Pieces) -> alloc::string::String {
+        let mut buf = alloc::string::String::with_capacity(4);
+        // OK because writing to `String` never fails.
+        self.print_pieces(pieces, &mut buf).unwrap();
+        buf
+    }
+
     /// Print a `Zoned` datetime to the given writer.
     ///
     /// # Errors
@@ -1412,6 +1585,40 @@ impl DateTimePrinter {
     ) -> Result<(), Error> {
         self.p.print_time(time, wtr)
     }
+
+    /// Print the `Pieces` of a Temporal datetime.
+    ///
+    /// # Errors
+    ///
+    /// This only returns an error when writing to the given [`Write`]
+    /// implementation would fail. Some such implementations, like for `String`
+    /// and `Vec<u8>`, never fail (unless memory allocation fails). In such
+    /// cases, it would be appropriate to call `unwrap()` on the result.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use jiff::{civil::date, fmt::temporal::{DateTimePrinter, Pieces}};
+    ///
+    /// const PRINTER: DateTimePrinter = DateTimePrinter::new();
+    ///
+    /// let pieces = Pieces::from(date(2024, 6, 15))
+    ///     .with_time_zone_name("US/Eastern");
+    ///
+    /// let mut buf = String::new();
+    /// // Printing to a `String` can never fail.
+    /// PRINTER.print_pieces(&pieces, &mut buf).unwrap();
+    /// assert_eq!(buf, "2024-06-15[US/Eastern]");
+    ///
+    /// # Ok::<(), Box<dyn std::error::Error>>(())
+    /// ```
+    pub fn print_pieces<W: Write>(
+        &self,
+        pieces: &Pieces,
+        wtr: W,
+    ) -> Result<(), Error> {
+        self.p.print_pieces(pieces, wtr)
+    }
 }
 
 /// A parser for Temporal durations.
diff --git a/src/fmt/temporal/parser.rs b/src/fmt/temporal/parser.rs
index c0c521cb..e10cffa5 100644
--- a/src/fmt/temporal/parser.rs
+++ b/src/fmt/temporal/parser.rs
@@ -4,6 +4,7 @@ use crate::{
     fmt::{
         offset::{self, ParsedOffset},
         rfc9557::{self, ParsedAnnotations},
+        temporal::Pieces,
         util::{
             fractional_time_to_duration, fractional_time_to_span,
             parse_temporal_fraction,
@@ -35,6 +36,21 @@ pub(super) struct ParsedDateTime<'i> {
 }
 
 impl<'i> ParsedDateTime<'i> {
+    #[inline(always)]
+    pub(super) fn to_pieces(&self) -> Result<Pieces<'i>, Error> {
+        let mut pieces = Pieces::from(self.date.date);
+        if let Some(ref time) = self.time {
+            pieces = pieces.with_time(time.time);
+        }
+        if let Some(ref offset) = self.offset {
+            pieces = pieces.with_offset(offset.to_pieces_offset()?);
+        }
+        if let Some(ann) = self.annotations.to_time_zone_annotation()? {
+            pieces = pieces.with_time_zone_annotation(ann);
+        }
+        Ok(pieces)
+    }
+
     #[inline(always)]
     pub(super) fn to_zoned(
         &self,
@@ -56,14 +72,15 @@ impl<'i> ParsedDateTime<'i> {
         let dt = DateTime::from_parts(self.date.date, time);
 
         // We always require a time zone when parsing a zoned instant.
-        let (tz, _critical) =
-            self.annotations.to_time_zone(db)?.ok_or_else(|| {
+        let tz_annotation =
+            self.annotations.to_time_zone_annotation()?.ok_or_else(|| {
                 err!(
                     "failed to find time zone in square brackets \
                      in {:?}, which is required for parsing a zoned instant",
                     self.input,
                 )
             })?;
+        let tz = tz_annotation.to_time_zone_with(db)?;
 
         // If there's no offset, then our only choice, regardless of conflict
         // resolution preference, is to use the time zone. That is, there is no
diff --git a/src/fmt/temporal/pieces.rs b/src/fmt/temporal/pieces.rs
new file mode 100644
index 00000000..7fcf6682
--- /dev/null
+++ b/src/fmt/temporal/pieces.rs
@@ -0,0 +1,1725 @@
+use crate::{
+    civil::{Date, DateTime, Time},
+    error::Error,
+    tz::{Offset, TimeZone, TimeZoneDatabase},
+    util::borrow::StringCow,
+    Timestamp, Zoned,
+};
+
+/// A low level representation of a parsed Temporal ISO 8601 datetime string.
+///
+/// Most users should not need to use or care about this type. Its purpose is
+/// to represent the individual components of a datetime string for more
+/// flexible parsing when use cases call for it.
+///
+/// One can parse into `Pieces` via [`Pieces::parse`]. Its date, time
+/// (optional), offset (optional) and time zone annotation (optional) can be
+/// queried independently. Each component corresponds to the following in a
+/// datetime string:
+///
+/// ```text
+/// {date}T{time}{offset}[{time-zone-annotation}]
+/// ```
+///
+/// For example:
+///
+/// ```text
+/// 2025-01-03T19:54-05[America/New_York]
+/// ```
+///
+/// A date is the only required component.
+///
+/// A `Pieces` can also be constructed from structured values via its `From`
+/// trait implementations. The `From` trait has the following implementations
+/// available:
+///
+/// * `From<Date>` creates a `Pieces` with just a civil [`Date`]. All other
+/// components are left empty.
+/// * `From<DateTime>` creates a `Pieces` with a civil [`Date`] and [`Time`].
+/// The offset and time zone annotation are left empty.
+/// * `From<Timestamp>` creates a `Pieces` from a [`Timestamp`] using
+/// a Zulu offset. This signifies that the precise instant is known, but the
+/// local time's offset from UTC is unknown. The [`Date`] and [`Time`] are
+/// determined via `Offset::UTC.to_datetime(timestamp)`. The time zone
+/// annotation is left empty.
+/// * `From<(Timestamp, Offset)>` creates a `Pieces` from a [`Timestamp`] and
+/// an [`Offset`]. The [`Date`] and [`Time`] are determined via
+/// `offset.to_datetime(timestamp)`. The time zone annotation is left empty.
+/// * `From<&Zoned>` creates a `Pieces` from a [`Zoned`]. This populates all
+/// fields of a `Pieces`.
+///
+/// A `Pieces` can be converted to a Temporal ISO 8601 string via its `Display`
+/// trait implementation.
+///
+/// # Example: distinguishing between `Z`, `+00:00` and `-00:00`
+///
+/// With `Pieces`, it's possible to parse a datetime string and inspect the
+/// "type" of its offset when it is zero. This makes use of the
+/// [`PiecesOffset`] and [`PiecesNumericOffset`] auxiliary types.
+///
+/// ```
+/// use jiff::{
+///     fmt::temporal::{Pieces, PiecesNumericOffset, PiecesOffset},
+///     tz::Offset,
+/// };
+///
+/// let pieces = Pieces::parse("1970-01-01T00:00:00Z")?;
+/// let off = pieces.offset().unwrap();
+/// // Parsed as Zulu.
+/// assert_eq!(off, PiecesOffset::Zulu);
+/// // Gets converted from Zulu to UTC, i.e., just zero.
+/// assert_eq!(off.to_numeric_offset(), Offset::UTC);
+///
+/// let pieces = Pieces::parse("1970-01-01T00:00:00-00:00")?;
+/// let off = pieces.offset().unwrap();
+/// // Parsed as a negative zero.
+/// assert_eq!(off, PiecesOffset::from(
+///     PiecesNumericOffset::from(Offset::UTC).with_negative_zero(),
+/// ));
+/// // Gets converted from -00:00 to UTC, i.e., just zero.
+/// assert_eq!(off.to_numeric_offset(), Offset::UTC);
+///
+/// let pieces = Pieces::parse("1970-01-01T00:00:00+00:00")?;
+/// let off = pieces.offset().unwrap();
+/// // Parsed as a positive zero.
+/// assert_eq!(off, PiecesOffset::from(
+///     PiecesNumericOffset::from(Offset::UTC),
+/// ));
+/// // Gets converted from -00:00 to UTC, i.e., just zero.
+/// assert_eq!(off.to_numeric_offset(), Offset::UTC);
+///
+/// # Ok::<(), Box<dyn std::error::Error>>(())
+/// ```
+///
+/// It's rare to need to care about these differences, but the above example
+/// demonstrates that `Pieces` doesn't try to do any automatic translation for
+/// you.
+///
+/// # Example: it is very easy to misuse `Pieces`
+///
+/// This example shows how easily you can shoot yourself in the foot with
+/// `Pieces`:
+///
+/// ```
+/// use jiff::{fmt::temporal::{Pieces, TimeZoneAnnotation}, tz};
+///
+/// let mut pieces = Pieces::parse("2025-01-03T07:55+02[Africa/Cairo]")?;
+/// pieces = pieces.with_offset(tz::offset(-10));
+/// // This is nonsense because the offset isn't compatible with the time zone!
+/// // Moreover, the actual instant that this timestamp represents has changed.
+/// assert_eq!(pieces.to_string(), "2025-01-03T07:55:00-10:00[Africa/Cairo]");
+///
+/// # Ok::<(), Box<dyn std::error::Error>>(())
+/// ```
+///
+/// In the above example, we take a parsed `Pieces`, change its offset and
+/// then format it back into a string. There are no speed bumps or errors.
+/// A `Pieces` will just blindly follow your instruction, even if it produces
+/// a nonsense result. Nonsense results are still parsable back into `Pieces`:
+///
+/// ```
+/// use jiff::{civil, fmt::temporal::Pieces, tz::{TimeZone, offset}};
+///
+/// let pieces = Pieces::parse("2025-01-03T07:55:00-10:00[Africa/Cairo]")?;
+/// assert_eq!(pieces.date(), civil::date(2025, 1, 3));
+/// assert_eq!(pieces.time(), Some(civil::time(7, 55, 0, 0)));
+/// assert_eq!(pieces.to_numeric_offset(), Some(offset(-10)));
+/// assert_eq!(pieces.to_time_zone()?, Some(TimeZone::get("Africa/Cairo")?));
+///
+/// # Ok::<(), Box<dyn std::error::Error>>(())
+/// ```
+///
+/// This exemplifies that `Pieces` is a mostly "dumb" type that passes
+/// through the data it contains, even if it doesn't make sense.
+///
+/// # Case study: how to parse `2025-01-03T17:28-05` into `Zoned`
+///
+/// One thing in particular that `Pieces` enables callers to do is side-step
+/// some of the stricter requirements placed on the higher level parsing
+/// functions (such as `Zoned`'s `FromStr` trait implementation). For example,
+/// parsing a datetime string into a `Zoned` _requires_ that the string contain
+/// a time zone annotation. Namely, parsing `2025-01-03T17:28-05` into a
+/// `Zoned` will fail:
+///
+/// ```
+/// use jiff::Zoned;
+///
+/// assert_eq!(
+///     "2025-01-03T17:28-05".parse::<Zoned>().unwrap_err().to_string(),
+///     "failed to find time zone in square brackets in \
+///      \"2025-01-03T17:28-05\", which is required for \
+///      parsing a zoned instant",
+/// );
+/// ```
+///
+/// The above fails because an RFC 3339 timestamp only contains an offset,
+/// not a time zone, and thus the resulting `Zoned` could never do time zone
+/// aware arithmetic.
+///
+/// However, in some cases, you might want to bypass these protections and
+/// creat a `Zoned` value with a fixed offset time zone anyway. For example,
+/// perhaps your use cases don't need time zone aware arithmetic, but want to
+/// preserve the offset anyway. This can be accomplished with `Pieces`:
+///
+/// ```
+/// use jiff::{fmt::temporal::Pieces, tz::TimeZone};
+///
+/// let pieces = Pieces::parse("2025-01-03T17:28-05")?;
+/// let time = pieces.time().unwrap_or_else(jiff::civil::Time::midnight);
+/// let dt = pieces.date().to_datetime(time);
+/// let Some(offset) = pieces.to_numeric_offset() else {
+///     let msg = format!(
+///         "datetime string has no offset, \
+///          and thus cannot be parsed into an instant",
+///     );
+///     return Err(msg.into());
+/// };
+/// let zdt = TimeZone::fixed(offset).to_zoned(dt)?;
+/// assert_eq!(zdt.to_string(), "2025-01-03T17:28:00-05:00[-05:00]");
+///
+/// # Ok::<(), Box<dyn std::error::Error>>(())
+/// ```
+///
+/// One problem with the above code snippet is that it completely ignores if
+/// a time zone annotation is present. If it is, it probably makes sense to use
+/// it, but "fall back" to a fixed offset time zone if it isn't (which the
+/// higher level `Zoned` parsing function won't do for you):
+///
+/// ```
+/// use jiff::{fmt::temporal::Pieces, tz::TimeZone};
+///
+/// let timestamp = "2025-01-02T15:13-05";
+///
+/// let pieces = Pieces::parse(timestamp)?;
+/// let time = pieces.time().unwrap_or_else(jiff::civil::Time::midnight);
+/// let dt = pieces.date().to_datetime(time);
+/// let tz = match pieces.to_time_zone()? {
+///     Some(tz) => tz,
+///     None => {
+///         let Some(offset) = pieces.to_numeric_offset() else {
+///             let msg = format!(
+///                 "timestamp `{timestamp}` has no time zone \
+///                  or offset, and thus cannot be parsed into \
+///                  an instant",
+///             );
+///             return Err(msg.into());
+///         };
+///         TimeZone::fixed(offset)
+///     }
+/// };
+/// // We don't bother with offset conflict resolution. And note that
+/// // this uses automatic "compatible" disambiguation in the case of
+/// // discontinuities. Of course, this is all moot if `TimeZone` is
+/// // fixed. The above code handles the case where it isn't!
+/// let zdt = tz.to_zoned(dt)?;
+/// assert_eq!(zdt.to_string(), "2025-01-02T15:13:00-05:00[-05:00]");
+///
+/// # Ok::<(), Box<dyn std::error::Error>>(())
+/// ```
+///
+/// This is mostly the same as above, but if an annotation is present, we use
+/// a `TimeZone` derived from that over the offset present.
+///
+/// However, this still doesn't quite capture what happens when parsing into a
+/// `Zoned` value. In particular, parsing into a `Zoned` is _also_ doing offset
+/// conflict resolution for you. An offset conflict occurs when there is a
+/// mismatch between the offset in an RFC 3339 timestamp and the time zone in
+/// an RFC 9557 time zone annotation.
+///
+/// For example, `2024-06-14T17:30-05[America/New_York]` has a mismatch
+/// since the date is in daylight saving time, but the offset, `-05`, is the
+/// offset for standard time in `America/New_York`. If this datetime were
+/// fed to the above code, then the `-05` offset would be completely ignored
+/// and `America/New_York` would resolve the datetime based on its rules. In
+/// this case, you'd get `2024-06-14T17:30-04`, which is a different instant
+/// than the original datetime!
+///
+/// You can either implement your own conflict resolution or use
+/// [`tz::OffsetConflict`](crate::tz::OffsetConflict) to do it for you.
+///
+/// ```
+/// use jiff::{fmt::temporal::Pieces, tz::{OffsetConflict, TimeZone}};
+///
+/// let timestamp = "2024-06-14T17:30-05[America/New_York]";
+/// // The default for conflict resolution when parsing into a `Zoned` is
+/// // actually `Reject`, but we use `AlwaysOffset` here to show a different
+/// // strategy. You'll want to pick the conflict resolution that suits your
+/// // needs. The `Reject` strategy is what you should pick if you aren't
+/// // sure.
+/// let conflict_resolution = OffsetConflict::AlwaysOffset;
+///
+/// let pieces = Pieces::parse(timestamp)?;
+/// let time = pieces.time().unwrap_or_else(jiff::civil::Time::midnight);
+/// let dt = pieces.date().to_datetime(time);
+/// let ambiguous_zdt = match pieces.to_time_zone()? {
+///     Some(tz) => {
+///         match pieces.to_numeric_offset() {
+///             None => tz.into_ambiguous_zoned(dt),
+///             Some(offset) => {
+///                 conflict_resolution.resolve(dt, offset, tz)?
+///             }
+///         }
+///     }
+///     None => {
+///         let Some(offset) = pieces.to_numeric_offset() else {
+///             let msg = format!(
+///                 "timestamp `{timestamp}` has no time zone \
+///                  or offset, and thus cannot be parsed into \
+///                  an instant",
+///             );
+///             return Err(msg.into());
+///         };
+///         // Won't even be ambiguous, but gets us the same
+///         // type as the branch above.
+///         TimeZone::fixed(offset).into_ambiguous_zoned(dt)
+///     }
+/// };
+/// // We do compatible disambiguation here like we do in the previous
+/// // examples, but you could choose any strategy. As with offset conflict
+/// // resolution, if you aren't sure what to pick, a safe choice here would
+/// // be `ambiguous_zdt.unambiguous()`, which will return an error if the
+/// // datetime is ambiguous in any way. Then, if you ever hit an error, you
+/// // can examine the case to see if it should be handled in a different way.
+/// let zdt = ambiguous_zdt.compatible()?;
+/// // Notice that we now have a different civil time and offset, but the
+/// // instant it corresponds to is the same as the one we started with.
+/// assert_eq!(zdt.to_string(), "2024-06-14T18:30:00-04:00[America/New_York]");
+///
+/// # Ok::<(), Box<dyn std::error::Error>>(())
+/// ```
+///
+/// The above has effectively completely rebuilt the higher level `Zoned`
+/// parsing routine, but with a fallback to a fixed time zone when a time zone
+/// annotation is not present.
+///
+/// # Case study: inferring the time zone of RFC 3339 timestamps
+///
+/// As [one real world use case details][infer-time-zone], it might be
+/// desirable to try and infer the time zone of RFC 3339 timestamps with
+/// varying offsets. This might be applicable when:
+///
+/// * You have out-of-band information, possibly contextual, that indicates
+/// the timestamps have to come from a fixed set of time zones.
+/// * The time zones have different standard offsets.
+/// * You have a specific desire or need to use a [`Zoned`] value for its
+/// ergonomics and time zone aware handling. After all, in this case, you
+/// believe the timestamps to actually be generated from a specific time zone,
+/// but the interchange format doesn't support carrying that information. Or
+/// the source data simply omits it.
+///
+/// In other words, you might be trying to make the best of a bad situation.
+///
+/// A `Pieces` can help you accomplish this because it gives you access to each
+/// component of a parsed datetime, and thus lets you implement arbitrary logic
+/// for how to translate that into a `Zoned`. In this case, there is
+/// contextual information that Jiff can't possibly know about.
+///
+/// The general approach we take here is to make use of
+/// [`tz::OffsetConflict`](crate::tz::OffsetConflict) to query whether a
+/// timestamp has a fixed offset compatible with a particular time zone. And if
+/// so, we can _probably_ assume it comes from that time zone. One hitch is
+/// that it's possible for the timestamp to be valid for multiple time zones,
+/// so we check that as well.
+///
+/// In the use case linked above, we have fixed offset timestamps from
+/// `America/Chicago` and `America/New_York`. So let's try implementing the
+/// above strategy. Note that we assume our inputs are RFC 3339 fixed offset
+/// timestamps and error otherwise. This is just to keep things simple. To
+/// handle data that is more varied, see the previous case study where we
+/// respect a time zone annotation if it's present, and fall back to a fixed
+/// offset time zone if it isn't.
+///
+/// ```
+/// use jiff::{fmt::temporal::Pieces, tz::{OffsetConflict, TimeZone}, Zoned};
+///
+/// // The time zones we're allowed to choose from.
+/// let tzs = &[
+///     TimeZone::get("America/New_York")?,
+///     TimeZone::get("America/Chicago")?,
+/// ];
+///
+/// // Here's our data that lacks time zones. The task is to assign a time zone
+/// // from `tzs` to each below and convert it to a `Zoned`. If we fail on any
+/// // one, then we substitute `None`.
+/// let data = &[
+///     "2024-01-13T10:33-05",
+///     "2024-01-25T12:15-06",
+///     "2024-03-10T02:30-05",
+///     "2024-06-08T14:01-05",
+///     "2024-06-12T11:46-04",
+///     "2024-11-03T01:30-05",
+/// ];
+/// // Our answers.
+/// let mut zdts: Vec<Option<Zoned>> = vec![];
+/// for string in data {
+///     // Parse and gather up the data that we can from the input.
+///     // In this case, that's a civil datetime and an offset from UTC.
+///     let pieces = Pieces::parse(string)?;
+///     let time = pieces.time().unwrap_or_else(jiff::civil::Time::midnight);
+///     let dt = pieces.date().to_datetime(time);
+///     let Some(offset) = pieces.to_numeric_offset() else {
+///         // A robust implementation should use a TZ annotation if present.
+///         return Err("missing offset".into());
+///     };
+///     // Now collect all time zones that are valid for this timestamp.
+///     let mut candidates = vec![];
+///     for tz in tzs {
+///         let result = OffsetConflict::Reject.resolve(dt, offset, tz.clone());
+///         // The parsed offset isn't valid for this time zone, so reject it.
+///         let Ok(ambiguous_zdt) = result else { continue };
+///         // This can never fail because we used the "reject" conflict
+///         // resolution strategy. It will never return an ambiguous
+///         // `Zoned` since we always have a valid offset that does
+///         // disambiguation for us.
+///         let zdt = ambiguous_zdt.unambiguous().unwrap();
+///         candidates.push(zdt);
+///     }
+///     if candidates.len() == 1 {
+///         zdts.push(Some(candidates.pop().unwrap()));
+///     } else {
+///         zdts.push(None);
+///     }
+/// }
+/// assert_eq!(zdts, vec![
+///     Some("2024-01-13T10:33-05[America/New_York]".parse()?),
+///     Some("2024-01-25T12:15-06[America/Chicago]".parse()?),
+///     // Failed because the clock time falls in a gap in the
+///     // transition to daylight saving time, and it could be
+///     // valid for either America/New_York or America/Chicago.
+///     None,
+///     Some("2024-06-08T14:01-05[America/Chicago]".parse()?),
+///     Some("2024-06-12T11:46-04[America/New_York]".parse()?),
+///     // Failed because the clock time falls in a fold in the
+///     // transition out of daylight saving time, and it could be
+///     // valid for either America/New_York or America/Chicago.
+///     None,
+/// ]);
+///
+/// # Ok::<(), Box<dyn std::error::Error>>(())
+/// ```
+///
+/// The one hitch here is that if the time zones are close to each
+/// geographically and both have daylight saving time, then there are some
+/// RFC 3339 timestamps that are truly ambiguous. For example,
+/// `2024-11-03T01:30-05` is perfectly valid for both `America/New_York` and
+/// `America/Chicago`. In this case, there is no way to tell which time zone
+/// the timestamp belongs to. It might be reasonable to return an error in
+/// this case or omit the timestamp. It depends on what you need to do.
+///
+/// With more effort, it would also be possible to optimize the above routine
+/// by utilizing [`TimeZone::preceding`] and [`TimeZone::following`] to get
+/// the exact boundaries of each time zone transition. Then you could use an
+/// offset lookup table for each range to determine the appropriate time zone.
+///
+/// [infer-time-zone]: https://github.com/BurntSushi/jiff/discussions/181#discussioncomment-11729435
+#[derive(Clone, Debug, Eq, Hash, PartialEq)]
+pub struct Pieces<'n> {
+    date: Date,
+    time: Option<Time>,
+    offset: Option<PiecesOffset>,
+    time_zone_annotation: Option<TimeZoneAnnotation<'n>>,
+}
+
+impl<'n> Pieces<'n> {
+    /// Parses a Temporal ISO 8601 datetime string into a `Pieces`.
+    ///
+    /// This is a convenience routine for
+    /// [`DateTimeParser::parses_pieces`](crate::fmt::temporal::DateTimeParser::parse_pieces).
+    ///
+    /// Note that the `Pieces` returned is parameterized by the lifetime of
+    /// `input`. This is because it might borrow a sub-slice of `input` for
+    /// a time zone annotation name. For example,
+    /// `Canada/Yukon` in `2025-01-03T16:42-07[Canada/Yukon]`.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use jiff::{civil, fmt::temporal::Pieces, tz::TimeZone};
+    ///
+    /// let pieces = Pieces::parse("2025-01-03T16:42[Canada/Yukon]")?;
+    /// assert_eq!(pieces.date(), civil::date(2025, 1, 3));
+    /// assert_eq!(pieces.time(), Some(civil::time(16, 42, 0, 0)));
+    /// assert_eq!(pieces.to_numeric_offset(), None);
+    /// assert_eq!(pieces.to_time_zone()?, Some(TimeZone::get("Canada/Yukon")?));
+    ///
+    /// # Ok::<(), Box<dyn std::error::Error>>(())
+    /// ```
+    #[inline]
+    pub fn parse<I: ?Sized + AsRef<[u8]> + 'n>(
+        input: &'n I,
+    ) -> Result<Pieces<'n>, Error> {
+        let input = input.as_ref();
+        super::DEFAULT_DATETIME_PARSER.parse_pieces(input)
+    }
+
+    /// Returns the civil date in this `Pieces`.
+    ///
+    /// Note that every `Pieces` value is guaranteed to have a `Date`.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use jiff::{civil, fmt::temporal::Pieces};
+    ///
+    /// let pieces = Pieces::parse("2025-01-03")?;
+    /// assert_eq!(pieces.date(), civil::date(2025, 1, 3));
+    ///
+    /// # Ok::<(), Box<dyn std::error::Error>>(())
+    /// ```
+    #[inline]
+    pub fn date(&self) -> Date {
+        self.date
+    }
+
+    /// Returns the civil time in this `Pieces`.
+    ///
+    /// The time component is optional. In
+    /// [`DateTimeParser`](crate::fmt::temporal::DateTimeParser), parsing
+    /// into types that require a time (like [`DateTime`]) when a time is
+    /// missing automatically set the time to midnight. (Or, more precisely,
+    /// the first instant of the day.)
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use jiff::{civil, fmt::temporal::Pieces, Zoned};
+    ///
+    /// let pieces = Pieces::parse("2025-01-03T14:49:01")?;
+    /// assert_eq!(pieces.date(), civil::date(2025, 1, 3));
+    /// assert_eq!(pieces.time(), Some(civil::time(14, 49, 1, 0)));
+    ///
+    /// // tricksy tricksy, the first instant of 2015-10-18 in Sao Paulo is
+    /// // not midnight!
+    /// let pieces = Pieces::parse("2015-10-18[America/Sao_Paulo]")?;
+    /// // Parsing into pieces just gives us the component parts, so no time:
+    /// assert_eq!(pieces.time(), None);
+    ///
+    /// // But if this uses higher level routines to parse into a `Zoned`,
+    /// // then we can see that the missing time implies the first instant
+    /// // of the day:
+    /// let zdt: Zoned = "2015-10-18[America/Sao_Paulo]".parse()?;
+    /// assert_eq!(zdt.time(), jiff::civil::time(1, 0, 0, 0));
+    ///
+    /// # Ok::<(), Box<dyn std::error::Error>>(())
+    /// ```
+    #[inline]
+    pub fn time(&self) -> Option<Time> {
+        self.time
+    }
+
+    /// Returns the offset in this `Pieces`.
+    ///
+    /// The offset returned can be infallibly converted to a numeric offset,
+    /// i.e., [`Offset`]. But it also includes extra data to indicate whether
+    /// a `Z` or a `-00:00` was parsed. (Neither of which are representable by
+    /// an `Offset`, which doesn't distinguish between Zulu and UTC and doesn't
+    /// represent negative and positive zero differently.)
+    ///
+    /// # Example
+    ///
+    /// This example shows how different flavors of `Offset::UTC` can be parsed
+    /// and inspected.
+    ///
+    /// ```
+    /// use jiff::{
+    ///     fmt::temporal::{Pieces, PiecesNumericOffset, PiecesOffset},
+    ///     tz::Offset,
+    /// };
+    ///
+    /// let pieces = Pieces::parse("1970-01-01T00:00:00Z")?;
+    /// let off = pieces.offset().unwrap();
+    /// // Parsed as Zulu.
+    /// assert_eq!(off, PiecesOffset::Zulu);
+    /// // Gets converted from Zulu to UTC, i.e., just zero.
+    /// assert_eq!(off.to_numeric_offset(), Offset::UTC);
+    ///
+    /// let pieces = Pieces::parse("1970-01-01T00:00:00-00:00")?;
+    /// let off = pieces.offset().unwrap();
+    /// // Parsed as a negative zero.
+    /// assert_eq!(off, PiecesOffset::from(
+    ///     PiecesNumericOffset::from(Offset::UTC).with_negative_zero(),
+    /// ));
+    /// // Gets converted from -00:00 to UTC, i.e., just zero.
+    /// assert_eq!(off.to_numeric_offset(), Offset::UTC);
+    ///
+    /// let pieces = Pieces::parse("1970-01-01T00:00:00+00:00")?;
+    /// let off = pieces.offset().unwrap();
+    /// // Parsed as a positive zero.
+    /// assert_eq!(off, PiecesOffset::from(
+    ///     PiecesNumericOffset::from(Offset::UTC),
+    /// ));
+    /// // Gets converted from -00:00 to UTC, i.e., just zero.
+    /// assert_eq!(off.to_numeric_offset(), Offset::UTC);
+    ///
+    /// # Ok::<(), Box<dyn std::error::Error>>(())
+    /// ```
+    #[inline]
+    pub fn offset(&self) -> Option<PiecesOffset> {
+        self.offset
+    }
+
+    /// Returns the time zone annotation in this `Pieces`.
+    ///
+    /// A time zone annotation is optional. The higher level
+    /// [`DateTimeParser`](crate::fmt::temporal::DateTimeParser)
+    /// requires a time zone annotation when parsing into a [`Zoned`].
+    ///
+    /// A time zone annotation is either an offset, or more commonly, an IANA
+    /// time zone identifier.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use jiff::{fmt::temporal::{Pieces, TimeZoneAnnotation}, tz::offset};
+    ///
+    /// // A time zone annotation from a name:
+    /// let pieces = Pieces::parse("2025-01-02T16:47-05[America/New_York]")?;
+    /// assert_eq!(
+    ///     pieces.time_zone_annotation().unwrap(),
+    ///     &TimeZoneAnnotation::from("America/New_York"),
+    /// );
+    ///
+    /// // A time zone annotation from an offset:
+    /// let pieces = Pieces::parse("2025-01-02T16:47-05[-05:00]")?;
+    /// assert_eq!(
+    ///     pieces.time_zone_annotation().unwrap(),
+    ///     &TimeZoneAnnotation::from(offset(-5)),
+    /// );
+    ///
+    /// # Ok::<(), Box<dyn std::error::Error>>(())
+    /// ```
+    #[inline]
+    pub fn time_zone_annotation(&self) -> Option<&TimeZoneAnnotation<'n>> {
+        self.time_zone_annotation.as_ref()
+    }
+
+    /// A convenience routine for converting an offset on this `Pieces`,
+    /// if present, to a numeric [`Offset`].
+    ///
+    /// This collapses the offsets `Z`, `-00:00` and `+00:00` all to
+    /// [`Offset::UTC`]. If you need to distinguish between them, then use
+    /// [`Pieces::offset`].
+    ///
+    /// # Example
+    ///
+    /// This example shows how `Z`, `-00:00` and `+00:00` all map to the same
+    /// [`Offset`] value:
+    ///
+    /// ```
+    /// use jiff::{fmt::temporal::Pieces, tz::Offset};
+    ///
+    /// let pieces = Pieces::parse("1970-01-01T00:00:00Z")?;
+    /// assert_eq!(pieces.to_numeric_offset(), Some(Offset::UTC));
+    ///
+    /// let pieces = Pieces::parse("1970-01-01T00:00:00-00:00")?;
+    /// assert_eq!(pieces.to_numeric_offset(), Some(Offset::UTC));
+    ///
+    /// let pieces = Pieces::parse("1970-01-01T00:00:00+00:00")?;
+    /// assert_eq!(pieces.to_numeric_offset(), Some(Offset::UTC));
+    ///
+    /// # Ok::<(), Box<dyn std::error::Error>>(())
+    /// ```
+    #[inline]
+    pub fn to_numeric_offset(&self) -> Option<Offset> {
+        self.offset().map(|poffset| poffset.to_numeric_offset())
+    }
+
+    /// A convenience routine for converting a time zone annotation, if
+    /// present, into a [`TimeZone`].
+    ///
+    /// If no annotation is on this `Pieces`, then this returns `Ok(None)`.
+    ///
+    /// This may return an error if the time zone annotation is a name and it
+    /// couldn't be found in Jiff's global time zone database.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use jiff::{fmt::temporal::Pieces, tz::{TimeZone, offset}};
+    ///
+    /// // No time zone annotations means you get `Ok(None)`:
+    /// let pieces = Pieces::parse("2025-01-03T17:13-05")?;
+    /// assert_eq!(pieces.to_time_zone()?, None);
+    ///
+    /// // An offset time zone annotation gets you a fixed offset `TimeZone`:
+    /// let pieces = Pieces::parse("2025-01-03T17:13-05[-05]")?;
+    /// assert_eq!(pieces.to_time_zone()?, Some(TimeZone::fixed(offset(-5))));
+    ///
+    /// // A time zone annotation name gets you a IANA time zone:
+    /// let pieces = Pieces::parse("2025-01-03T17:13-05[America/New_York]")?;
+    /// assert_eq!(pieces.to_time_zone()?, Some(TimeZone::get("America/New_York")?));
+    ///
+    /// // A time zone annotation name that doesn't exist gives you an error:
+    /// let pieces = Pieces::parse("2025-01-03T17:13-05[Australia/Bluey]")?;
+    /// assert_eq!(
+    ///     pieces.to_time_zone().unwrap_err().to_string(),
+    ///     "failed to find time zone `Australia/Bluey` in time zone database",
+    /// );
+    ///
+    /// # Ok::<(), Box<dyn std::error::Error>>(())
+    /// ```
+    #[inline]
+    pub fn to_time_zone(&self) -> Result<Option<TimeZone>, Error> {
+        self.to_time_zone_with(crate::tz::db())
+    }
+
+    /// A convenience routine for converting a time zone annotation, if
+    /// present, into a [`TimeZone`] using the given [`TimeZoneDatabase`].
+    ///
+    /// If no annotation is on this `Pieces`, then this returns `Ok(None)`.
+    ///
+    /// This may return an error if the time zone annotation is a name and it
+    /// couldn't be found in Jiff's global time zone database.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use jiff::{fmt::temporal::Pieces, tz::TimeZone};
+    ///
+    /// // A time zone annotation name gets you a IANA time zone:
+    /// let pieces = Pieces::parse("2025-01-03T17:13-05[America/New_York]")?;
+    /// assert_eq!(
+    ///     pieces.to_time_zone_with(jiff::tz::db())?,
+    ///     Some(TimeZone::get("America/New_York")?),
+    /// );
+    ///
+    /// # Ok::<(), Box<dyn std::error::Error>>(())
+    /// ```
+    #[inline]
+    pub fn to_time_zone_with(
+        &self,
+        db: &TimeZoneDatabase,
+    ) -> Result<Option<TimeZone>, Error> {
+        let Some(ann) = self.time_zone_annotation() else { return Ok(None) };
+        ann.to_time_zone_with(db).map(Some)
+    }
+
+    /// Set the date on this `Pieces` to the one given.
+    ///
+    /// A `Date` is the minimal piece of information necessary to create a
+    /// `Pieces`. This method will override any previous setting.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use jiff::{civil, fmt::temporal::Pieces, Timestamp};
+    ///
+    /// let pieces = Pieces::from(civil::date(2025, 1, 3));
+    /// assert_eq!(pieces.to_string(), "2025-01-03");
+    ///
+    /// // Alternatively, build a `Pieces` from another data type, and the
+    /// // date field will be automatically populated.
+    /// let pieces = Pieces::from(Timestamp::from_second(1735930208)?);
+    /// assert_eq!(pieces.date(), civil::date(2025, 1, 3));
+    /// assert_eq!(pieces.to_string(), "2025-01-03T18:50:08Z");
+    ///
+    /// # Ok::<(), Box<dyn std::error::Error>>(())
+    /// ```
+    #[inline]
+    pub fn with_date(self, date: Date) -> Pieces<'n> {
+        Pieces { date, ..self }
+    }
+
+    /// Set the time on this `Pieces` to the one given.
+    ///
+    /// Setting a [`Time`] on `Pieces` is optional. When formatting a
+    /// `Pieces` to a string, a missing `Time` may be omitted from the datetime
+    /// string in some cases. See [`Pieces::with_offset`] for more details.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use jiff::{civil, fmt::temporal::Pieces};
+    ///
+    /// let pieces = Pieces::from(civil::date(2025, 1, 3))
+    ///     .with_time(civil::time(13, 48, 0, 0));
+    /// assert_eq!(pieces.to_string(), "2025-01-03T13:48:00");
+    /// // Alternatively, build a `Pieces` from a `DateTime` directly:
+    /// let pieces = Pieces::from(civil::date(2025, 1, 3).at(13, 48, 0, 0));
+    /// assert_eq!(pieces.to_string(), "2025-01-03T13:48:00");
+    ///
+    /// # Ok::<(), Box<dyn std::error::Error>>(())
+    /// ```
+    #[inline]
+    pub fn with_time(self, time: Time) -> Pieces<'n> {
+        Pieces { time: Some(time), ..self }
+    }
+
+    /// Set the offset on this `Pieces` to the one given.
+    ///
+    /// Setting the offset on `Pieces` is optional.
+    ///
+    /// The type of offset is polymorphic, and includes anything that can be
+    /// infallibly converted into a [`PiecesOffset`]. This includes an
+    /// [`Offset`].
+    ///
+    /// This refers to the offset in the [RFC 3339] component of a Temporal
+    /// ISO 8601 datetime string.
+    ///
+    /// Since a string like `2025-01-03+11` is not valid, if a `Pieces` has
+    /// an offset set but no [`Time`] set, then formatting the `Pieces` will
+    /// write an explicit `Time` set to midnight.
+    ///
+    /// Note that this is distinct from [`Pieces::with_time_zone_offset`].
+    /// This routine sets the offset on the datetime, while
+    /// `Pieces::with_time_zone_offset` sets the offset inside the time zone
+    /// annotation. When the timestamp offset and the time zone annotation
+    /// offset are both present, then they must be equivalent or else the
+    /// datetime string is not a valid Temporal ISO 8601 string. However, a
+    /// `Pieces` will let you format a string with mismatching offsets.
+    ///
+    /// # Example
+    ///
+    /// This example shows how easily you can shoot yourself in the foot with
+    /// this routine:
+    ///
+    /// ```
+    /// use jiff::{fmt::temporal::{Pieces, TimeZoneAnnotation}, tz};
+    ///
+    /// let mut pieces = Pieces::parse("2025-01-03T07:55+02[+02]")?;
+    /// pieces = pieces.with_offset(tz::offset(-10));
+    /// // This is nonsense because the offsets don't match!
+    /// // And notice also that the instant that this timestamp refers to has
+    /// // changed.
+    /// assert_eq!(pieces.to_string(), "2025-01-03T07:55:00-10:00[+02:00]");
+    ///
+    /// # Ok::<(), Box<dyn std::error::Error>>(())
+    /// ```
+    ///
+    /// This exemplifies that `Pieces` is a mostly "dumb" type that passes
+    /// through the data it contains, even if it doesn't make sense.
+    ///
+    /// # Example: changing the offset can change the instant
+    ///
+    /// Consider this case where a `Pieces` is created directly from a
+    /// `Timestamp`, and then the offset is changed.
+    ///
+    /// ```
+    /// use jiff::{fmt::temporal::Pieces, tz, Timestamp};
+    ///
+    /// let pieces = Pieces::from(Timestamp::UNIX_EPOCH)
+    ///     .with_offset(tz::offset(-5));
+    /// assert_eq!(pieces.to_string(), "1970-01-01T00:00:00-05:00");
+    /// ```
+    ///
+    /// You might do this naively as a way of printing the timestamp of the
+    /// Unix epoch with an offset of `-05` from UTC. But the above does not
+    /// correspond to the Unix epoch:
+    ///
+    /// ```
+    /// use jiff::{Timestamp, ToSpan, Unit};
+    ///
+    /// let ts: Timestamp = "1970-01-01T00:00:00-05:00".parse()?;
+    /// assert_eq!(ts.since((Unit::Hour, Timestamp::UNIX_EPOCH))?, 5.hours());
+    ///
+    /// # Ok::<(), Box<dyn std::error::Error>>(())
+    /// ```
+    ///
+    /// This further exemplifies how `Pieces` is just a "dumb" type that
+    /// passes through the data it contains.
+    ///
+    /// This specific example is also why `Pieces` has a `From` trait
+    /// implementation for `(Timestamp, Offset)`, which correspond more to
+    /// what you want:
+    ///
+    /// ```
+    /// use jiff::{fmt::temporal::Pieces, tz, Timestamp};
+    ///
+    /// let pieces = Pieces::from((Timestamp::UNIX_EPOCH, tz::offset(-5)));
+    /// assert_eq!(pieces.to_string(), "1969-12-31T19:00:00-05:00");
+    /// ```
+    ///
+    /// A decent mental model of `Pieces` is that setting fields on `Pieces`
+    /// can't change the values in memory of other fields.
+    ///
+    /// # Example: setting an offset forces a time to be written
+    ///
+    /// Consider these cases where formatting a `Pieces` won't write a
+    /// [`Time`]:
+    ///
+    /// ```
+    /// use jiff::fmt::temporal::Pieces;
+    ///
+    /// let pieces = Pieces::from(jiff::civil::date(2025, 1, 3));
+    /// assert_eq!(pieces.to_string(), "2025-01-03");
+    ///
+    /// let pieces = Pieces::from(jiff::civil::date(2025, 1, 3))
+    ///     .with_time_zone_name("Africa/Cairo");
+    /// assert_eq!(pieces.to_string(), "2025-01-03[Africa/Cairo]");
+    /// ```
+    ///
+    /// This works because the resulting strings are valid. In particular, when
+    /// one parses a `2025-01-03[Africa/Cairo]` into a `Zoned`, it results in a
+    /// time component of midnight automatically (or more precisely, the first
+    /// instead of the corresponding day):
+    ///
+    /// ```
+    /// use jiff::{civil::Time, Zoned};
+    ///
+    /// let zdt: Zoned = "2025-01-03[Africa/Cairo]".parse()?;
+    /// assert_eq!(zdt.time(), Time::midnight());
+    ///
+    /// // tricksy tricksy, the first instant of 2015-10-18 in Sao Paulo is
+    /// // not midnight!
+    /// let zdt: Zoned = "2015-10-18[America/Sao_Paulo]".parse()?;
+    /// assert_eq!(zdt.time(), jiff::civil::time(1, 0, 0, 0));
+    /// // This happens because midnight didn't appear on the clocks in
+    /// // Sao Paulo on 2015-10-18. So if you try to parse a datetime with
+    /// // midnight, automatic disambiguation kicks in and chooses the time
+    /// // after the gap automatically:
+    /// let zdt: Zoned = "2015-10-18T00:00:00[America/Sao_Paulo]".parse()?;
+    /// assert_eq!(zdt.time(), jiff::civil::time(1, 0, 0, 0));
+    ///
+    /// # Ok::<(), Box<dyn std::error::Error>>(())
+    /// ```
+    ///
+    /// However, if you have a date and an offset, then since things like
+    /// `2025-01-03+10` aren't valid Temporal ISO 8601 datetime strings, the
+    /// default midnight time is automatically written:
+    ///
+    /// ```
+    /// use jiff::{fmt::temporal::Pieces, tz};
+    ///
+    /// let pieces = Pieces::from(jiff::civil::date(2025, 1, 3))
+    ///     .with_offset(tz::offset(-5));
+    /// assert_eq!(pieces.to_string(), "2025-01-03T00:00:00-05:00");
+    ///
+    /// let pieces = Pieces::from(jiff::civil::date(2025, 1, 3))
+    ///     .with_offset(tz::offset(2))
+    ///     .with_time_zone_name("Africa/Cairo");
+    /// assert_eq!(pieces.to_string(), "2025-01-03T00:00:00+02:00[Africa/Cairo]");
+    /// ```
+    ///
+    /// # Example: formatting a Zulu or `-00:00` offset
+    ///
+    /// A [`PiecesOffset`] encapsulates not just a numeric offset, but also
+    /// whether a `Z` or a signed zero are used. While it's uncommon to need
+    /// this, this permits one to format a `Pieces` using either of these
+    /// constructs:
+    ///
+    /// ```
+    /// use jiff::{
+    ///     civil,
+    ///     fmt::temporal::{Pieces, PiecesNumericOffset, PiecesOffset},
+    ///     tz::Offset,
+    /// };
+    ///
+    /// let pieces = Pieces::from(civil::date(1970, 1, 1).at(0, 0, 0, 0))
+    ///     .with_offset(Offset::UTC);
+    /// assert_eq!(pieces.to_string(), "1970-01-01T00:00:00+00:00");
+    ///
+    /// let pieces = Pieces::from(civil::date(1970, 1, 1).at(0, 0, 0, 0))
+    ///     .with_offset(PiecesOffset::Zulu);
+    /// assert_eq!(pieces.to_string(), "1970-01-01T00:00:00Z");
+    ///
+    /// let pieces = Pieces::from(civil::date(1970, 1, 1).at(0, 0, 0, 0))
+    ///     .with_offset(PiecesNumericOffset::from(Offset::UTC).with_negative_zero());
+    /// assert_eq!(pieces.to_string(), "1970-01-01T00:00:00-00:00");
+    /// ```
+    ///
+    /// [RFC 3339]: https://www.rfc-editor.org/rfc/rfc3339
+    #[inline]
+    pub fn with_offset<T: Into<PiecesOffset>>(self, offset: T) -> Pieces<'n> {
+        Pieces { offset: Some(offset.into()), ..self }
+    }
+
+    /// Sets the time zone annotation on this `Pieces` to the given time zone
+    /// name.
+    ///
+    /// Setting a time zone annotation on `Pieces` is optional.
+    ///
+    /// This is a convenience routine for using
+    /// [`Pieces::with_time_zone_annotation`] with an explicitly constructed
+    /// [`TimeZoneAnnotation`] for a time zone name.
+    ///
+    /// # Example
+    ///
+    /// This example shows how easily you can shoot yourself in the foot with
+    /// this routine:
+    ///
+    /// ```
+    /// use jiff::fmt::temporal::{Pieces, TimeZoneAnnotation};
+    ///
+    /// let mut pieces = Pieces::parse("2025-01-03T07:55+02[Africa/Cairo]")?;
+    /// pieces = pieces.with_time_zone_name("Australia/Bluey");
+    /// // This is nonsense because `Australia/Bluey` isn't a valid time zone!
+    /// assert_eq!(pieces.to_string(), "2025-01-03T07:55:00+02:00[Australia/Bluey]");
+    ///
+    /// # Ok::<(), Box<dyn std::error::Error>>(())
+    /// ```
+    ///
+    /// This exemplifies that `Pieces` is a mostly "dumb" type that passes
+    /// through the data it contains, even if it doesn't make sense.
+    #[inline]
+    pub fn with_time_zone_name<'a>(self, name: &'a str) -> Pieces<'a> {
+        self.with_time_zone_annotation(TimeZoneAnnotation::from(name))
+    }
+
+    /// Sets the time zone annotation on this `Pieces` to the given offset.
+    ///
+    /// Setting a time zone annotation on `Pieces` is optional.
+    ///
+    /// This is a convenience routine for using
+    /// [`Pieces::with_time_zone_annotation`] with an explicitly constructed
+    /// [`TimeZoneAnnotation`] for a time zone offset.
+    ///
+    /// Note that this is distinct from [`Pieces::with_offset`]. This
+    /// routine sets the offset inside the time zone annotation, while
+    /// `Pieces::with_offset` sets the offset on the timestamp itself. When the
+    /// timestamp offset and the time zone annotation offset are both present,
+    /// then they must be equivalent or else the datetime string is not a valid
+    /// Temporal ISO 8601 string. However, a `Pieces` will let you format a
+    /// string with mismatching offsets.
+    ///
+    /// # Example
+    ///
+    /// This example shows how easily you can shoot yourself in the foot with
+    /// this routine:
+    ///
+    /// ```
+    /// use jiff::{fmt::temporal::{Pieces, TimeZoneAnnotation}, tz};
+    ///
+    /// let mut pieces = Pieces::parse("2025-01-03T07:55+02[Africa/Cairo]")?;
+    /// pieces = pieces.with_time_zone_offset(tz::offset(-7));
+    /// // This is nonsense because the offset `+02` does not match `-07`.
+    /// assert_eq!(pieces.to_string(), "2025-01-03T07:55:00+02:00[-07:00]");
+    ///
+    /// # Ok::<(), Box<dyn std::error::Error>>(())
+    /// ```
+    ///
+    /// This exemplifies that `Pieces` is a mostly "dumb" type that passes
+    /// through the data it contains, even if it doesn't make sense.
+    #[inline]
+    pub fn with_time_zone_offset(self, offset: Offset) -> Pieces<'static> {
+        self.with_time_zone_annotation(TimeZoneAnnotation::from(offset))
+    }
+
+    /// Returns a new `Pieces` with the given time zone annotation.
+    ///
+    /// Setting a time zone annotation on `Pieces` is optional.
+    ///
+    /// You may find it more convenient to use
+    /// [`Pieces::with_time_zone_name`] or [`Pieces::with_time_zone_offset`].
+    ///
+    /// # Example
+    ///
+    /// This example shows how easily you can shoot yourself in the foot with
+    /// this routine:
+    ///
+    /// ```
+    /// use jiff::fmt::temporal::{Pieces, TimeZoneAnnotation};
+    ///
+    /// let mut pieces = Pieces::parse("2025-01-03T07:55+02[Africa/Cairo]")?;
+    /// pieces = pieces.with_time_zone_annotation(
+    ///     TimeZoneAnnotation::from("Canada/Yukon"),
+    /// );
+    /// // This is nonsense because the offset `+02` is never valid for the
+    /// // `Canada/Yukon` time zone.
+    /// assert_eq!(pieces.to_string(), "2025-01-03T07:55:00+02:00[Canada/Yukon]");
+    ///
+    /// # Ok::<(), Box<dyn std::error::Error>>(())
+    /// ```
+    ///
+    /// This exemplifies that `Pieces` is a mostly "dumb" type that passes
+    /// through the data it contains, even if it doesn't make sense.
+    #[inline]
+    pub fn with_time_zone_annotation<'a>(
+        self,
+        ann: TimeZoneAnnotation<'a>,
+    ) -> Pieces<'a> {
+        Pieces { time_zone_annotation: Some(ann), ..self }
+    }
+
+    /// Converts this `Pieces` into an "owned" value whose lifetime is
+    /// `'static`.
+    ///
+    /// Ths "owned" value in this context refers to the time zone annotation
+    /// name, if present. For example, `Canada/Yukon` in
+    /// `2025-01-03T07:55-07[Canada/Yukon]`. When parsing into a `Pieces`,
+    /// the time zone annotation name is borrowed. But callers may find it more
+    /// convenient to work with an owned value. By calling this method, the
+    /// borrowed string internally will be copied into a new string heap
+    /// allocation.
+    ///
+    /// If `Pieces` doesn't have a time zone annotation, is already owned or
+    /// the time zone annotation is an offset, then this is a no-op.
+    #[cfg(feature = "alloc")]
+    #[inline]
+    pub fn into_owned(self) -> Pieces<'static> {
+        Pieces {
+            date: self.date,
+            time: self.time,
+            offset: self.offset,
+            time_zone_annotation: self
+                .time_zone_annotation
+                .map(|ann| ann.into_owned()),
+        }
+    }
+}
+
+impl From<Date> for Pieces<'static> {
+    #[inline]
+    fn from(date: Date) -> Pieces<'static> {
+        Pieces { date, time: None, offset: None, time_zone_annotation: None }
+    }
+}
+
+impl From<DateTime> for Pieces<'static> {
+    #[inline]
+    fn from(dt: DateTime) -> Pieces<'static> {
+        Pieces::from(dt.date()).with_time(dt.time())
+    }
+}
+
+impl From<Timestamp> for Pieces<'static> {
+    #[inline]
+    fn from(ts: Timestamp) -> Pieces<'static> {
+        let dt = Offset::UTC.to_datetime(ts);
+        Pieces::from(dt).with_offset(PiecesOffset::Zulu)
+    }
+}
+
+impl From<(Timestamp, Offset)> for Pieces<'static> {
+    #[inline]
+    fn from((ts, offset): (Timestamp, Offset)) -> Pieces<'static> {
+        Pieces::from(offset.to_datetime(ts)).with_offset(offset)
+    }
+}
+
+impl<'a> From<&'a Zoned> for Pieces<'a> {
+    #[inline]
+    fn from(zdt: &'a Zoned) -> Pieces<'a> {
+        let mut pieces =
+            Pieces::from(zdt.datetime()).with_offset(zdt.offset());
+        if let Some(name) = zdt.time_zone().iana_name() {
+            pieces = pieces.with_time_zone_name(name);
+        } else {
+            pieces = pieces.with_time_zone_offset(zdt.offset());
+        }
+        pieces
+    }
+}
+
+impl<'n> core::fmt::Display for Pieces<'n> {
+    fn fmt(&self, f: &mut core::fmt::Formatter) -> core::fmt::Result {
+        use crate::fmt::StdFmtWrite;
+
+        let precision =
+            f.precision().map(|p| u8::try_from(p).unwrap_or(u8::MAX));
+        super::DateTimePrinter::new()
+            .precision(precision)
+            .print_pieces(self, StdFmtWrite(f))
+            .map_err(|_| core::fmt::Error)
+    }
+}
+
+/// An offset parsed from a Temporal ISO 8601 datetime string, for use with
+/// [`Pieces`].
+///
+/// One can almost think of this as effectively equivalent to an `Offset`. And
+/// indeed, all `PiecesOffset` values can be convert to an `Offset`. However,
+/// some offsets in a datetime string have a different connotation that can't
+/// be captured by an `Offset`.
+///
+/// For example, the offsets `Z`, `-00:00` and `+00:00` all map to
+/// [`Offset::UTC`] after parsing. However, `Z` and `-00:00` generally
+/// indicate that the offset from local time is unknown, where as `+00:00`
+/// indicates that the offset from local is _known_ and is zero. This type
+/// permits callers to inspect what offset was actually written.
+///
+/// # Example
+///
+/// This example shows how one can create Temporal ISO 8601 datetime strings
+/// with `+00:00`, `-00:00` or `Z` offsets.
+///
+/// ```
+/// use jiff::{
+///     fmt::temporal::{Pieces, PiecesNumericOffset},
+///     tz::Offset,
+///     Timestamp,
+/// };
+///
+/// // If you create a `Pieces` from a `Timestamp` with a UTC offset,
+/// // then this is interpreted as "the offset from UTC is known and is
+/// // zero."
+/// let pieces = Pieces::from((Timestamp::UNIX_EPOCH, Offset::UTC));
+/// assert_eq!(pieces.to_string(), "1970-01-01T00:00:00+00:00");
+///
+/// // Otherwise, if you create a `Pieces` from just a `Timestamp` with
+/// // no offset, then it is interpreted as "the offset from UTC is not
+/// // known." Typically, this is rendered with `Z` for "Zulu":
+/// let pieces = Pieces::from(Timestamp::UNIX_EPOCH);
+/// assert_eq!(pieces.to_string(), "1970-01-01T00:00:00Z");
+///
+/// // But it might be the case that you want to use `-00:00` instead,
+/// // perhaps to conform to some existing convention or legacy
+/// // applications that require it:
+/// let pieces = Pieces::from(Timestamp::UNIX_EPOCH)
+///     .with_offset(
+///         PiecesNumericOffset::from(Offset::UTC).with_negative_zero(),
+///     );
+/// assert_eq!(pieces.to_string(), "1970-01-01T00:00:00-00:00");
+/// ```
+///
+/// Without `Pieces`, it's not otherwise possible to emit a `-00:00` offset.
+/// For example,
+/// [`DateTimePrinter::print_timestamp`](crate::fmt::temporal::DateTimePrinter::print_timestamp)
+/// will always emit `Z`, which is consider semantically identical to `-00:00`
+/// by [RFC 9557]. There's no specific use case where it's expected that you
+/// should need to write `-00:00` instead of `Z`, but it's conceivable legacy
+/// or otherwise inflexible applications might want it. Or perhaps, in some
+/// systems, there is a distinction to draw between `Z` and `-00:00`.
+///
+/// [RFC 9557]: https://www.rfc-editor.org/rfc/rfc9557.html
+#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
+#[non_exhaustive]
+pub enum PiecesOffset {
+    /// The "Zulu" offset, corresponding to UTC in a context where the offset
+    /// for civil time is unknown or unavailable.
+    ///
+    /// [RFC 9557] defines this as equivalent in semantic meaning to `-00:00`:
+    ///
+    /// > If the time in UTC is known, but the offset to local time is unknown,
+    /// > this can be represented with an offset of `Z`. (The original version
+    /// > of this specification provided `-00:00` for this purpose, which is
+    /// > not allowed by ISO-8601:2000 and therefore is less interoperable;
+    /// > Section 3.3 of RFC 5322 describes a related convention for email,
+    /// > which does not have this problem). This differs semantically from an
+    /// > offset of `+00:00`, which implies that UTC is the preferred reference
+    /// > point for the specified time.
+    ///
+    /// [RFC 9557]: https://www.rfc-editor.org/rfc/rfc9557
+    Zulu,
+    /// A specific numeric offset, including whether the parsed sign is
+    /// negative.
+    ///
+    /// The sign is usually redundant, since an `Offset` is itself signed. But
+    /// it can be used to distinguish between `+00:00` (`+00` is the preferred
+    /// offset) and `-00:00` (`+00` is what should be used, but only because
+    /// the offset to local time is not known). Generally speaking, one should
+    /// regard `-00:00` as equivalent to `Z`, per RFC 9557.
+    Numeric(PiecesNumericOffset),
+}
+
+impl PiecesOffset {
+    /// Converts this offset to a concrete numeric offset in all cases.
+    ///
+    /// If this was a `Z` or a `-00:00` offset, then `Offset::UTC` is returned.
+    /// In all other cases, the underlying numeric offset is returned as-is.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use jiff::{
+    ///     fmt::temporal::{Pieces, PiecesNumericOffset, PiecesOffset},
+    ///     tz::Offset,
+    /// };
+    ///
+    /// let pieces = Pieces::parse("1970-01-01T00:00:00Z")?;
+    /// let off = pieces.offset().unwrap();
+    /// // Parsed as Zulu.
+    /// assert_eq!(off, PiecesOffset::Zulu);
+    /// // Gets converted from Zulu to UTC, i.e., just zero.
+    /// assert_eq!(off.to_numeric_offset(), Offset::UTC);
+    ///
+    /// let pieces = Pieces::parse("1970-01-01T00:00:00-00:00")?;
+    /// let off = pieces.offset().unwrap();
+    /// // Parsed as a negative zero.
+    /// assert_eq!(off, PiecesOffset::from(
+    ///     PiecesNumericOffset::from(Offset::UTC).with_negative_zero(),
+    /// ));
+    /// // Gets converted from -00:00 to UTC, i.e., just zero.
+    /// assert_eq!(off.to_numeric_offset(), Offset::UTC);
+    ///
+    /// let pieces = Pieces::parse("1970-01-01T00:00:00+00:00")?;
+    /// let off = pieces.offset().unwrap();
+    /// // Parsed as a positive zero.
+    /// assert_eq!(off, PiecesOffset::from(
+    ///     PiecesNumericOffset::from(Offset::UTC),
+    /// ));
+    /// // Gets converted from -00:00 to UTC, i.e., just zero.
+    /// assert_eq!(off.to_numeric_offset(), Offset::UTC);
+    ///
+    /// # Ok::<(), Box<dyn std::error::Error>>(())
+    /// ```
+    #[inline]
+    pub fn to_numeric_offset(&self) -> Offset {
+        match *self {
+            PiecesOffset::Zulu => Offset::UTC,
+            // -00:00 and +00:00 both collapse to zero here.
+            PiecesOffset::Numeric(ref noffset) => noffset.offset(),
+        }
+    }
+}
+
+impl From<Offset> for PiecesOffset {
+    #[inline]
+    fn from(offset: Offset) -> PiecesOffset {
+        PiecesOffset::from(PiecesNumericOffset::from(offset))
+    }
+}
+
+impl From<PiecesNumericOffset> for PiecesOffset {
+    #[inline]
+    fn from(offset: PiecesNumericOffset) -> PiecesOffset {
+        PiecesOffset::Numeric(offset)
+    }
+}
+
+/// A specific numeric offset, including the sign of the offset, for use with
+/// [`Pieces`].
+///
+/// # Signedness
+///
+/// The sign attached to this type is usually redundant, since the underlying
+/// [`Offset`] is itself signed. But it can be used to distinguish between
+/// `+00:00` (`+00` is the preferred offset) and `-00:00` (`+00` is what should
+/// be used, but only because the offset to local time is not known). Generally
+/// speaking, one should regard `-00:00` as equivalent to `Z`, per [RFC 9557].
+///
+/// [RFC 9557]: https://www.rfc-editor.org/rfc/rfc9557
+#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
+pub struct PiecesNumericOffset {
+    offset: Offset,
+    is_negative: bool,
+}
+
+impl PiecesNumericOffset {
+    /// Returns the numeric offset.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use jiff::{
+    ///     fmt::temporal::{Pieces, PiecesOffset},
+    ///     tz::Offset,
+    /// };
+    ///
+    /// let pieces = Pieces::parse("1970-01-01T00:00:00-05:30")?;
+    /// let off = match pieces.offset().unwrap() {
+    ///     PiecesOffset::Numeric(off) => off,
+    ///     _ => unreachable!(),
+    /// };
+    /// // This is really only useful if you care that an actual
+    /// // numeric offset was written and not, e.g., `Z`. Otherwise,
+    /// // you could just use `PiecesOffset::to_numeric_offset`.
+    /// assert_eq!(
+    ///     off.offset(),
+    ///     Offset::from_seconds(-5 * 60 * 60 - 30 * 60).unwrap(),
+    /// );
+    ///
+    /// # Ok::<(), Box<dyn std::error::Error>>(())
+    /// ```
+    #[inline]
+    pub fn offset(&self) -> Offset {
+        self.offset
+    }
+
+    /// Returns whether the sign of the offset is negative or not.
+    ///
+    /// When formatting a [`Pieces`] to a string, this is _only_ used to
+    /// determine the rendered sign when the [`Offset`] is itself zero. In
+    /// all other cases, the sign rendered matches the sign of the `Offset`.
+    ///
+    /// Since `Offset` does not keep track of a sign when its value is zero,
+    /// when using the `From<Offset>` trait implementation for this type,
+    /// `is_negative` is always set to `false` when the offset is zero.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use jiff::{
+    ///     fmt::temporal::{Pieces, PiecesOffset},
+    ///     tz::Offset,
+    /// };
+    ///
+    /// let pieces = Pieces::parse("1970-01-01T00:00:00-00:00")?;
+    /// let off = match pieces.offset().unwrap() {
+    ///     PiecesOffset::Numeric(off) => off,
+    ///     _ => unreachable!(),
+    /// };
+    /// // The numeric offset component in this case is
+    /// // indistiguisable from `Offset::UTC`. This is
+    /// // because an `Offset` does not use different
+    /// // representations for negative and positive zero.
+    /// assert_eq!(off.offset(), Offset::UTC);
+    /// // This is where `is_negative` comes in handy:
+    /// assert_eq!(off.is_negative(), true);
+    ///
+    /// # Ok::<(), Box<dyn std::error::Error>>(())
+    /// ```
+    #[inline]
+    pub fn is_negative(&self) -> bool {
+        self.is_negative
+    }
+
+    /// Sets this numeric offset to use `-00:00` if and only if the offset
+    /// is zero.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use jiff::{
+    ///     fmt::temporal::{Pieces, PiecesNumericOffset},
+    ///     tz::Offset,
+    ///     Timestamp,
+    /// };
+    ///
+    /// // If you create a `Pieces` from a `Timestamp` with a UTC offset,
+    /// // then this is interpreted as "the offset from UTC is known and is
+    /// // zero."
+    /// let pieces = Pieces::from((Timestamp::UNIX_EPOCH, Offset::UTC));
+    /// assert_eq!(pieces.to_string(), "1970-01-01T00:00:00+00:00");
+    ///
+    /// // Otherwise, if you create a `Pieces` from just a `Timestamp` with
+    /// // no offset, then it is interpreted as "the offset from UTC is not
+    /// // known." Typically, this is rendered with `Z` for "Zulu":
+    /// let pieces = Pieces::from(Timestamp::UNIX_EPOCH);
+    /// assert_eq!(pieces.to_string(), "1970-01-01T00:00:00Z");
+    ///
+    /// // But it might be the case that you want to use `-00:00` instead,
+    /// // perhaps to conform to some existing convention or legacy
+    /// // applications that require it:
+    /// let pieces = Pieces::from(Timestamp::UNIX_EPOCH)
+    ///     .with_offset(
+    ///         PiecesNumericOffset::from(Offset::UTC).with_negative_zero(),
+    ///     );
+    /// assert_eq!(pieces.to_string(), "1970-01-01T00:00:00-00:00");
+    /// ```
+    #[inline]
+    pub fn with_negative_zero(self) -> PiecesNumericOffset {
+        PiecesNumericOffset { is_negative: true, ..self }
+    }
+}
+
+impl From<Offset> for PiecesNumericOffset {
+    #[inline]
+    fn from(offset: Offset) -> PiecesNumericOffset {
+        // This can of course never return a -00:00 offset, only +00:00.
+        PiecesNumericOffset { offset, is_negative: offset.is_negative() }
+    }
+}
+
+/// An [RFC 9557] time zone annotation, for use with [`Pieces`].
+///
+/// A time zone annotation is either a time zone name (typically an IANA time
+/// zone identifier) like `America/New_York`, or an offset like `-05:00`. This
+/// is normally an implementation detail of parsing into a [`Zoned`], but the
+/// raw annotation can be accessed via [`Pieces::time_zone_annotation`] after
+/// parsing into a [`Pieces`].
+///
+/// The lifetime parameter refers to the lifetime of the time zone
+/// name. The lifetime is static when the time zone annotation is
+/// offset or if the name is owned. An owned value can be produced via
+/// [`TimeZoneAnnotation::into_owned`] when the `alloc` crate feature is
+/// enabled.
+///
+/// # Construction
+///
+/// If you're using [`Pieces`], then its [`Pieces::with_time_zone_name`] and
+/// [`Pieces::with_time_zone_offset`] methods should absolve you of needing to
+/// build values of this type explicitly. But if the need arises, there are
+/// `From` impls for `&str` (time zone annotation name) and [`Offset`] (time
+/// zone annotation offset) for this type.
+///
+/// # Example
+///
+/// ```
+/// use jiff::{fmt::temporal::{Pieces, TimeZoneAnnotation}, tz::offset};
+///
+/// // A time zone annotation from a name:
+/// let pieces = Pieces::parse("2025-01-02T16:47-05[America/New_York]")?;
+/// assert_eq!(
+///     pieces.time_zone_annotation().unwrap(),
+///     &TimeZoneAnnotation::from("America/New_York"),
+/// );
+///
+/// // A time zone annotation from an offset:
+/// let pieces = Pieces::parse("2025-01-02T16:47-05[-05:00]")?;
+/// assert_eq!(
+///     pieces.time_zone_annotation().unwrap(),
+///     &TimeZoneAnnotation::from(offset(-5)),
+/// );
+///
+/// # Ok::<(), Box<dyn std::error::Error>>(())
+/// ```
+///
+/// [RFC 9557]: https://www.rfc-editor.org/rfc/rfc9557.html
+#[derive(Clone, Debug, Eq, Hash, PartialEq)]
+pub struct TimeZoneAnnotation<'n> {
+    pub(crate) kind: TimeZoneAnnotationKind<'n>,
+    /// Whether the annotation is marked as "critical," i.e., with a
+    /// `!` prefix. When enabled, it's supposed to make the annotation
+    /// un-ignorable.
+    ///
+    /// This is basically unused. And there's no way for callers to flip this
+    /// switch currently. But it can be queried after parsing. Jiff also
+    /// doesn't alter its behavior based on this flag. In particular, Jiff
+    /// basically always behaves as if `critical` is true.
+    pub(crate) critical: bool,
+}
+
+impl<'n> TimeZoneAnnotation<'n> {
+    /// Returns the "kind" of this annotation. The kind is either a name or an
+    /// offset.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use jiff::fmt::temporal::{Pieces, TimeZoneAnnotation};
+    ///
+    /// // A time zone annotation from a name, which doesn't necessarily have
+    /// // to point to a valid IANA time zone.
+    /// let pieces = Pieces::parse("2025-01-02T16:47-05[Australia/Bluey]")?;
+    /// assert_eq!(
+    ///     pieces.time_zone_annotation().unwrap(),
+    ///     &TimeZoneAnnotation::from("Australia/Bluey"),
+    /// );
+    ///
+    /// # Ok::<(), Box<dyn std::error::Error>>(())
+    /// ```
+    #[inline]
+    pub fn kind(&self) -> &TimeZoneAnnotationKind<'n> {
+        &self.kind
+    }
+
+    /// Returns true when this time zone is marked as "critical." This occurs
+    /// when the time zone annotation is preceded by a `!`. It is meant to
+    /// signify that, basically, implementations should error if the annotation
+    /// is invalid in some way. And when it's absent, it's left up to the
+    /// implementation's discretion about what to do (including silently
+    /// ignoring the invalid annotation).
+    ///
+    /// Generally speaking, Jiff ignores this altogether for time zone
+    /// annotations and behaves as if it's always true. But it's exposed here
+    /// for callers to query in case it's useful.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use jiff::fmt::temporal::{Pieces, TimeZoneAnnotation};
+    ///
+    /// // not critical
+    /// let pieces = Pieces::parse("2025-01-02T16:47-05[Australia/Bluey]")?;
+    /// assert_eq!(
+    ///     Some(false),
+    ///     pieces.time_zone_annotation().map(|a| a.is_critical()),
+    /// );
+    ///
+    /// // critical
+    /// let pieces = Pieces::parse("2025-01-02T16:47-05[!Australia/Bluey]")?;
+    /// assert_eq!(
+    ///     Some(true),
+    ///     pieces.time_zone_annotation().map(|a| a.is_critical()),
+    /// );
+    ///
+    /// # Ok::<(), Box<dyn std::error::Error>>(())
+    /// ```
+    #[inline]
+    pub fn is_critical(&self) -> bool {
+        self.critical
+    }
+
+    /// A convenience routine for converting this annotation into a time zone.
+    ///
+    /// This can fail if the annotation contains a name that couldn't be found
+    /// in the global time zone database. If you need to use something other
+    /// than the global time zone database, then use
+    /// [`TimeZoneAnnotation::to_time_zone_with`].
+    ///
+    /// Note that it may be more convenient to use
+    /// [`Pieces::to_time_zone`].
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use jiff::{fmt::temporal::Pieces, tz::TimeZone};
+    ///
+    /// let pieces = Pieces::parse("2025-01-02T16:47-05[Australia/Tasmania]")?;
+    /// let ann = pieces.time_zone_annotation().unwrap();
+    /// assert_eq!(
+    ///     ann.to_time_zone().unwrap(),
+    ///     TimeZone::get("Australia/Tasmania").unwrap(),
+    /// );
+    ///
+    /// let pieces = Pieces::parse("2025-01-02T16:47-05[Australia/Bluey]")?;
+    /// let ann = pieces.time_zone_annotation().unwrap();
+    /// assert_eq!(
+    ///     ann.to_time_zone().unwrap_err().to_string(),
+    ///     "failed to find time zone `Australia/Bluey` in time zone database",
+    /// );
+    ///
+    /// # Ok::<(), Box<dyn std::error::Error>>(())
+    /// ```
+    #[inline]
+    pub fn to_time_zone(&self) -> Result<TimeZone, Error> {
+        self.to_time_zone_with(crate::tz::db())
+    }
+
+    /// This is like [`TimeZoneAnnotation::to_time_zone`], but permits the
+    /// caller to pass in their own time zone database.
+    ///
+    /// This can fail if the annotation contains a name that couldn't be found
+    /// in the global time zone database. If you need to use something other
+    /// than the global time zone database, then use
+    /// [`TimeZoneAnnotation::to_time_zone_with`].
+    ///
+    /// Note that it may be more convenient to use
+    /// [`Pieces::to_time_zone_with`].
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use jiff::{fmt::temporal::Pieces, tz::TimeZone};
+    ///
+    /// let pieces = Pieces::parse("2025-01-02T16:47-05[Australia/Tasmania]")?;
+    /// let ann = pieces.time_zone_annotation().unwrap();
+    /// assert_eq!(
+    ///     ann.to_time_zone_with(jiff::tz::db()).unwrap(),
+    ///     TimeZone::get("Australia/Tasmania").unwrap(),
+    /// );
+    ///
+    /// # Ok::<(), Box<dyn std::error::Error>>(())
+    /// ```
+    #[inline]
+    pub fn to_time_zone_with(
+        &self,
+        db: &TimeZoneDatabase,
+    ) -> Result<TimeZone, Error> {
+        // NOTE: We don't currently utilize the critical flag here. Temporal
+        // seems to ignore it. It's not quite clear what else we'd do with it,
+        // particularly given that we provide a way to do conflict resolution
+        // between offsets and time zones.
+        let tz = match *self.kind() {
+            TimeZoneAnnotationKind::Named(ref name) => {
+                db.get(name.as_str())?
+            }
+            TimeZoneAnnotationKind::Offset(offset) => TimeZone::fixed(offset),
+        };
+        Ok(tz)
+    }
+
+    /// Converts this time zone annotation into an "owned" value whose lifetime
+    /// is `'static`.
+    ///
+    /// If this was already an "owned" value or a time zone annotation offset,
+    /// then this is a no-op.
+    #[cfg(feature = "alloc")]
+    #[inline]
+    pub fn into_owned(self) -> TimeZoneAnnotation<'static> {
+        TimeZoneAnnotation {
+            kind: self.kind.into_owned(),
+            critical: self.critical,
+        }
+    }
+}
+
+impl<'n> From<&'n str> for TimeZoneAnnotation<'n> {
+    fn from(string: &'n str) -> TimeZoneAnnotation<'n> {
+        let kind = TimeZoneAnnotationKind::from(string);
+        TimeZoneAnnotation { kind, critical: false }
+    }
+}
+
+impl From<Offset> for TimeZoneAnnotation<'static> {
+    fn from(offset: Offset) -> TimeZoneAnnotation<'static> {
+        let kind = TimeZoneAnnotationKind::from(offset);
+        TimeZoneAnnotation { kind, critical: false }
+    }
+}
+
+/// The kind of time zone found in an [RFC 9557] timestamp, for use with
+/// [`Pieces`].
+///
+/// The lifetime parameter refers to the lifetime of the time zone
+/// name. The lifetime is static when the time zone annotation is
+/// offset or if the name is owned. An owned value can be produced via
+/// [`TimeZoneAnnotation::into_owned`] when the `alloc` crate feature is
+/// enabled.
+///
+/// [RFC 9557]: https://www.rfc-editor.org/rfc/rfc9557.html
+#[derive(Clone, Debug, Eq, Hash, PartialEq)]
+#[non_exhaustive]
+pub enum TimeZoneAnnotationKind<'n> {
+    /// The time zone annotation is a name, usually an IANA time zone
+    /// identifier. For example, `America/New_York`.
+    Named(TimeZoneAnnotationName<'n>),
+    /// The time zone annotation is an offset. For example, `-05:00`.
+    Offset(Offset),
+}
+
+impl<'n> TimeZoneAnnotationKind<'n> {
+    /// Converts this time zone annotation kind into an "owned" value whose
+    /// lifetime is `'static`.
+    ///
+    /// If this was already an "owned" value or a time zone annotation offset,
+    /// then this is a no-op.
+    #[cfg(feature = "alloc")]
+    #[inline]
+    pub fn into_owned(self) -> TimeZoneAnnotationKind<'static> {
+        match self {
+            TimeZoneAnnotationKind::Named(named) => {
+                TimeZoneAnnotationKind::Named(named.into_owned())
+            }
+            TimeZoneAnnotationKind::Offset(offset) => {
+                TimeZoneAnnotationKind::Offset(offset)
+            }
+        }
+    }
+}
+
+impl<'n> From<&'n str> for TimeZoneAnnotationKind<'n> {
+    fn from(string: &'n str) -> TimeZoneAnnotationKind<'n> {
+        let name = TimeZoneAnnotationName::from(string);
+        TimeZoneAnnotationKind::Named(name)
+    }
+}
+
+impl From<Offset> for TimeZoneAnnotationKind<'static> {
+    fn from(offset: Offset) -> TimeZoneAnnotationKind<'static> {
+        TimeZoneAnnotationKind::Offset(offset)
+    }
+}
+
+/// A time zone annotation parsed from a datetime string.
+///
+/// By default, a time zone annotation name borrows its name from the
+/// input it was parsed from. When the `alloc` feature is enabled,
+/// callers can de-couple the annotation from the parsed input with
+/// [`TimeZoneAnnotationName::into_owned`].
+///
+/// A value of this type is usually found via [`Pieces::time_zone_annotation`],
+/// but callers can also construct one via this type's `From<&str>` trait
+/// implementation if necessary.
+#[derive(Clone, Debug, Eq, Hash, PartialEq)]
+pub struct TimeZoneAnnotationName<'n> {
+    name: StringCow<'n>,
+}
+
+impl<'n> TimeZoneAnnotationName<'n> {
+    /// Returns the name of this time zone annotation as a string slice.
+    ///
+    /// Note that the lifetime of the string slice returned is tied to the
+    /// lifetime of this time zone annotation. This may be shorter than the
+    /// lifetime of the string, `'n`, in this annotation.
+    #[inline]
+    pub fn as_str<'a>(&'a self) -> &'a str {
+        self.name.as_str()
+    }
+
+    /// Converts this time zone annotation name into an "owned" value whose
+    /// lifetime is `'static`.
+    ///
+    /// If this was already an "owned" value, then this is a no-op.
+    #[cfg(feature = "alloc")]
+    #[inline]
+    pub fn into_owned(self) -> TimeZoneAnnotationName<'static> {
+        TimeZoneAnnotationName { name: self.name.into_owned() }
+    }
+}
+
+impl<'n> From<&'n str> for TimeZoneAnnotationName<'n> {
+    fn from(string: &'n str) -> TimeZoneAnnotationName<'n> {
+        TimeZoneAnnotationName { name: StringCow::from(string) }
+    }
+}
diff --git a/src/fmt/temporal/printer.rs b/src/fmt/temporal/printer.rs
index 0597c3c9..2e8aa81e 100644
--- a/src/fmt/temporal/printer.rs
+++ b/src/fmt/temporal/printer.rs
@@ -2,6 +2,7 @@ use crate::{
     civil::{Date, DateTime, Time},
     error::Error,
     fmt::{
+        temporal::{Pieces, PiecesOffset, TimeZoneAnnotationKind},
         util::{DecimalFormatter, FractionalFormatter},
         Write, WriteExt,
     },
@@ -143,6 +144,73 @@ impl DateTimePrinter {
         Ok(())
     }
 
+    pub(super) fn print_pieces<W: Write>(
+        &self,
+        pieces: &Pieces,
+        mut wtr: W,
+    ) -> Result<(), Error> {
+        if let Some(time) = pieces.time() {
+            let dt = DateTime::from_parts(pieces.date(), time);
+            self.print_datetime(&dt, &mut wtr)?;
+            if let Some(poffset) = pieces.offset() {
+                self.print_pieces_offset(&poffset, &mut wtr)?;
+            }
+        } else if let Some(poffset) = pieces.offset() {
+            // In this case, we have an offset but no time component. Since
+            // `2025-01-02-05:00` isn't valid, we forcefully write out the
+            // default time (which is what would be assumed anyway).
+            let dt = DateTime::from_parts(pieces.date(), Time::midnight());
+            self.print_datetime(&dt, &mut wtr)?;
+            self.print_pieces_offset(&poffset, &mut wtr)?;
+        } else {
+            // We have no time and no offset, so we can just write the date.
+            // It's okay to write this followed by an annotation, e.g.,
+            // `2025-01-02[America/New_York]` or even `2025-01-02[-05:00]`.
+            self.print_date(&pieces.date(), &mut wtr)?;
+        }
+        // For the time zone annotation, a `Pieces` gives us the annotation
+        // name or offset directly, where as with `Zoned`, we have a
+        // `TimeZone`. So we hand-roll our own formatter directly from the
+        // annotation.
+        if let Some(ann) = pieces.time_zone_annotation() {
+            // Note that we explicitly ignore `self.rfc9557` here, since with
+            // `Pieces`, the annotation has been explicitly provided. Also,
+            // at time of writing, `self.rfc9557` is always enabled anyway.
+            wtr.write_str("[")?;
+            if ann.is_critical() {
+                wtr.write_str("!")?;
+            }
+            match *ann.kind() {
+                TimeZoneAnnotationKind::Named(ref name) => {
+                    wtr.write_str(name.as_str())?
+                }
+                TimeZoneAnnotationKind::Offset(offset) => {
+                    self.print_offset(&offset, &mut wtr)?
+                }
+            }
+            wtr.write_str("]")?;
+        }
+        Ok(())
+    }
+
+    /// Formats the given "pieces" offset into the writer given.
+    fn print_pieces_offset<W: Write>(
+        &self,
+        poffset: &PiecesOffset,
+        mut wtr: W,
+    ) -> Result<(), Error> {
+        match *poffset {
+            PiecesOffset::Zulu => self.print_zulu(wtr),
+            PiecesOffset::Numeric(ref noffset) => {
+                if noffset.offset().is_zero() && noffset.is_negative() {
+                    wtr.write_str("-00:00")
+                } else {
+                    self.print_offset(&noffset.offset(), wtr)
+                }
+            }
+        }
+    }
+
     /// Formats the given offset into the writer given.
     fn print_offset<W: Write>(
         &self,
diff --git a/src/lib.rs b/src/lib.rs
index 79b9392f..323e886a 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -44,9 +44,10 @@ All three of these components are used to provide convenient high level
 operations on `Zoned` such as computing durations, adding durations and
 rounding.
 
-This crate defines a single duration type, [`Span`], which mixes calendar
-and clock units into a single type. All datetime types in Jiff use spans for
-operating on durations.
+A [`Span`] is this crate's primary duration type. It mixes calendar and clock
+units into a single type. Jiff also provides [`SignedDuration`], which is like
+[`std::time::Duration`], but signed. Users should default to a `Span` for
+representing durations when using Jiff.
 
 [Unix epoch]: https://en.wikipedia.org/wiki/Unix_time
 [UTC]: https://en.wikipedia.org/wiki/Coordinated_Universal_Time
diff --git a/src/tz/offset.rs b/src/tz/offset.rs
index a4d9c97d..1a2f4708 100644
--- a/src/tz/offset.rs
+++ b/src/tz/offset.rs
@@ -343,6 +343,42 @@ impl Offset {
         Offset { span: -self.span }
     }
 
+    /// Returns the "sign number" or "signum" of this offset.
+    ///
+    /// The number returned is `-1` when this offset is negative,
+    /// `0` when this offset is zero and `1` when this span is positive.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use jiff::tz;
+    ///
+    /// assert_eq!(tz::offset(5).signum(), 1);
+    /// assert_eq!(tz::offset(0).signum(), 0);
+    /// assert_eq!(tz::offset(-5).signum(), -1);
+    /// ```
+    #[inline]
+    pub fn signum(self) -> i8 {
+        t::Sign::rfrom(self.span.signum()).get()
+    }
+
+    /// Returns true if and only if this offset is positive.
+    ///
+    /// This returns false when the offset is zero or negative.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use jiff::tz;
+    ///
+    /// assert!(tz::offset(5).is_positive());
+    /// assert!(!tz::offset(0).is_positive());
+    /// assert!(!tz::offset(-5).is_positive());
+    /// ```
+    pub fn is_positive(self) -> bool {
+        self.seconds_ranged() > 0
+    }
+
     /// Returns true if and only if this offset is less than zero.
     ///
     /// # Example
@@ -358,6 +394,23 @@ impl Offset {
         self.seconds_ranged() < 0
     }
 
+    /// Returns true if and only if this offset is zero.
+    ///
+    /// Or equivalently, when this offset corresponds to [`Offset::UTC`].
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use jiff::tz;
+    ///
+    /// assert!(!tz::offset(5).is_zero());
+    /// assert!(tz::offset(0).is_zero());
+    /// assert!(!tz::offset(-5).is_zero());
+    /// ```
+    pub fn is_zero(self) -> bool {
+        self.seconds_ranged() == 0
+    }
+
     /// Converts this offset into a [`TimeZone`].
     ///
     /// This is a convenience function for calling [`TimeZone::fixed`] with
@@ -1343,6 +1396,9 @@ pub enum OffsetConflict {
     /// unless the offset is invalid for the provided time zone. In that case,
     /// use the time zone. When the time zone is used, it's possible for an
     /// ambiguous datetime to be returned.
+    ///
+    /// See [`ZonedWith::offset_conflict`](crate::ZonedWith::offset_conflict)
+    /// for an example of when this strategy is useful.
     PreferOffset,
     /// When the offset and time zone are in conflict, this strategy always
     /// results in conflict resolution returning an error.
diff --git a/src/util/borrow.rs b/src/util/borrow.rs
index dd96a71e..21bda661 100644
--- a/src/util/borrow.rs
+++ b/src/util/borrow.rs
@@ -29,3 +29,69 @@ impl<'a, T: core::fmt::Display> core::fmt::Display for DumbCow<'a, T> {
         core::fmt::Display::fmt(core::ops::Deref::deref(self), f)
     }
 }
+
+/// A `Cow`, but can be used in core-only mode.
+///
+/// In core-only, the `Owned` variant doesn't exist.
+#[derive(Clone, Debug, Eq, Hash, PartialEq, PartialOrd, Ord)]
+pub(crate) enum StringCow<'a> {
+    #[cfg(feature = "alloc")]
+    Owned(alloc::string::String),
+    Borrowed(&'a str),
+}
+
+impl<'a> StringCow<'a> {
+    /// Returns this `String` or `&str` as a `&str`.
+    ///
+    /// Like `std::borrow::Cow`, the lifetime of the string slice returned
+    /// is tied to `StringCow`, and _not_ the original lifetime of the string
+    /// slice.
+    pub(crate) fn as_str<'s>(&'s self) -> &'s str {
+        match *self {
+            #[cfg(feature = "alloc")]
+            StringCow::Owned(ref s) => s,
+            StringCow::Borrowed(s) => s,
+        }
+    }
+
+    /// Converts this cow into an "owned" variant, copying if necessary.
+    ///
+    /// If this cow is already an "owned" variant, then this is a no-op.
+    #[cfg(feature = "alloc")]
+    pub(crate) fn into_owned(self) -> StringCow<'static> {
+        use alloc::string::ToString;
+
+        match self {
+            StringCow::Owned(string) => StringCow::Owned(string),
+            StringCow::Borrowed(string) => {
+                StringCow::Owned(string.to_string())
+            }
+        }
+    }
+}
+
+impl<'a> core::ops::Deref for StringCow<'a> {
+    type Target = str;
+    fn deref(&self) -> &str {
+        self.as_str()
+    }
+}
+
+impl<'a> core::fmt::Display for StringCow<'a> {
+    fn fmt(&self, f: &mut core::fmt::Formatter) -> core::fmt::Result {
+        core::fmt::Display::fmt(self.as_str(), f)
+    }
+}
+
+#[cfg(feature = "alloc")]
+impl From<alloc::string::String> for StringCow<'static> {
+    fn from(string: alloc::string::String) -> StringCow<'static> {
+        StringCow::Owned(string)
+    }
+}
+
+impl<'a> From<&'a str> for StringCow<'a> {
+    fn from(string: &'a str) -> StringCow<'a> {
+        StringCow::Borrowed(string)
+    }
+}
diff --git a/src/zoned.rs b/src/zoned.rs
index 2ae7fd27..8f8ce28e 100644
--- a/src/zoned.rs
+++ b/src/zoned.rs
@@ -496,8 +496,8 @@ impl Zoned {
     /// Create a builder for constructing a new `DateTime` from the fields of
     /// this datetime.
     ///
-    /// See the methods on [`DateTimeWith`] for the different ways one can set
-    /// the fields of a new `DateTime`.
+    /// See the methods on [`ZonedWith`] for the different ways one can set
+    /// the fields of a new `Zoned`.
     ///
     /// Note that this doesn't support changing the time zone. If you want a
     /// `Zoned` value of the same instant but in a different time zone, use
@@ -5038,10 +5038,6 @@ impl ZonedWith {
     /// let zdt2 = zdt1.with().hour(0).build()?;
     /// assert_eq!(
     ///     zdt2.to_string(),
-    ///     // Without taking the offset of the `Zoned` value into account,
-    ///     // this would have defaulted to using the "compatible"
-    ///     // disambiguation strategy, which would have selected the earlier
-    ///     // offset of -04 instead of sticking with the later offset of -05.
     ///     "2024-11-03T00:30:00-04:00[America/New_York]",
     /// );
     ///


Test patch: