Implement FormatItem::First

CHANGELOG.md

@@ -38,6 +38,7 @@ The format is based on [Keep a Changelog]. This project adheres to [Semantic Ver
   change) once `impl const Default` is stabilized.
 - `FormatItem::Optional`, which will consume the contained value if present but still succeed
   otherwise.
+- `FormatItem::First`, which will consume the first successful parse, ignoring any prior errors.
 
 ### Fixed
 

src/format_description/mod.rs

@@ -63,6 +63,10 @@ pub enum FormatItem<'a> {
     ///
     /// This variant has no effect on formatting, as the value is guaranteed to be present.
     Optional(&'a Self),
+    /// A series of `FormatItem`s where, when parsing, the first successful parse is used. When
+    /// formatting, the first element of the slice is used.  An empty slice is a no-op when
+    /// formatting or parsing.
+    First(&'a [Self]),
 }
 
 #[cfg(feature = "alloc")]
@@ -73,6 +77,7 @@ impl fmt::Debug for FormatItem<'_> {
             FormatItem::Component(component) => component.fmt(f),
             FormatItem::Compound(compound) => compound.fmt(f),
             FormatItem::Optional(item) => f.debug_tuple("Optional").field(item).finish(),
+            FormatItem::First(items) => f.debug_tuple("First").field(items).finish(),
         }
     }
 }

src/formatting/formattable.rs

@@ -61,6 +61,10 @@ impl<'a> sealed::Sealed for FormatItem<'a> {
             Self::Component(component) => format_component(output, component, date, time, offset)?,
             Self::Compound(items) => items.format_into(output, date, time, offset)?,
             Self::Optional(item) => item.format_into(output, date, time, offset)?,
+            Self::First(items) => match items {
+                [] => 0,
+                [item, ..] => item.format_into(output, date, time, offset)?,
+            },
         })
     }
 }

src/parsing/parsed.rs

@@ -107,6 +107,24 @@ impl Parsed {
             FormatItem::Component(component) => self.parse_component(input, *component),
             FormatItem::Compound(compound) => self.parse_items(input, compound),
             FormatItem::Optional(item) => self.parse_item(input, item).or(Ok(input)),
+            FormatItem::First(items) => {
+                let mut first_err = None;
+
+                for item in items.iter() {
+                    match self.parse_item(input, item) {
+                        Ok(remaining_input) => return Ok(remaining_input),
+                        Err(err) if first_err.is_none() => first_err = Some(err),
+                        Err(_) => {}
+                    }
+                }
+
+                match first_err {
+                    Some(err) => Err(err),
+                    // This location will be reached if the slice is empty, skipping the `for` loop.
+                    // As this case is expected to be uncommon, there's no need to check up front.
+                    None => Ok(input),
+                }
+            }
         }
     }
 

tests/integration/derives.rs

@@ -158,5 +158,6 @@ fn debug() {
         FormatItem::Literal(b"abcdef");
         FormatItem::Compound(&[FormatItem::Component(Component::Day(modifier::Day::default()))]);
         FormatItem::Optional(&FormatItem::Compound(&[]));
+        FormatItem::First(&[]);
     }
 }

tests/integration/formatting.rs

@@ -350,6 +350,9 @@ fn insufficient_type_information() {
     assert_insufficient_type_information(Time::MIDNIGHT.format(&Rfc3339));
     assert_insufficient_type_information(date!(2021 - 001).format(&Rfc3339));
     assert_insufficient_type_information(datetime!(2021 - 001 0:00).format(&Rfc3339));
+    assert_insufficient_type_information(
+        Time::MIDNIGHT.format(&FormatItem::First(&[FormatItem::Compound(fd!("[year]"))])),
+    );
 }
 
 #[test]
@@ -425,3 +428,14 @@ fn failed_write() -> time::Result<()> {
 
     Ok(())
 }
+
+#[test]
+fn first() -> time::Result<()> {
+    assert_eq!(Time::MIDNIGHT.format(&FormatItem::First(&[]))?, "");
+    assert_eq!(
+        Time::MIDNIGHT.format(&FormatItem::First(&[FormatItem::Compound(fd!("[hour]"))]))?,
+        "00"
+    );
+
+    Ok(())
+}

tests/integration/parsing.rs

@@ -911,3 +911,55 @@ fn parse_optional() -> time::Result<()> {
 
     Ok(())
 }
+
+#[test]
+fn parse_first() -> time::Result<()> {
+    // Ensure the first item is parsed correctly.
+    let mut parsed = Parsed::new();
+    let remaining_input = parsed.parse_item(
+        b"2021-01-02",
+        &FormatItem::First(&[FormatItem::Compound(&fd::parse("[year]-[month]-[day]")?)]),
+    )?;
+    assert!(remaining_input.is_empty());
+    assert_eq!(parsed.year(), Some(2021));
+    assert_eq!(parsed.month(), Some(Month::January));
+    assert_eq!(parsed.day().map(NonZeroU8::get), Some(2));
+
+    // Ensure an empty slice is a no-op success.
+    let mut parsed = Parsed::new();
+    let remaining_input = parsed.parse_item(b"2021-01-02", &FormatItem::First(&[]))?;
+    assert_eq!(remaining_input, b"2021-01-02");
+    assert!(parsed.year().is_none());
+    assert!(parsed.month().is_none());
+    assert!(parsed.day().is_none());
+
+    // Ensure success when the first item fails.
+    let mut parsed = Parsed::new();
+    let remaining_input = parsed.parse_item(
+        b"2021-01-02",
+        &FormatItem::First(&[
+            FormatItem::Compound(&fd::parse("[period]")?),
+            FormatItem::Compound(&fd::parse("x")?),
+            FormatItem::Compound(&fd::parse("[year]-[month]-[day]")?),
+        ]),
+    )?;
+    assert!(remaining_input.is_empty());
+    assert_eq!(parsed.year(), Some(2021));
+    assert_eq!(parsed.month(), Some(Month::January));
+    assert_eq!(parsed.day().map(NonZeroU8::get), Some(2));
+
+    // Ensure the first error is returned.
+    let mut parsed = Parsed::new();
+    let err = parsed
+        .parse_item(
+            b"2021-01-02",
+            &FormatItem::First(&[
+                FormatItem::Compound(&fd::parse("[period]")?),
+                FormatItem::Compound(&fd::parse("x")?),
+            ]),
+        )
+        .unwrap_err();
+    assert_eq!(err, error::ParseFromDescription::InvalidComponent("period"));
+
+    Ok(())
+}