feat: Add TryFromIterator trait and implement it for Labels and Annotations (#715)

* Add `TryFromIterator` trait, add impl for `Labels` and `Annotations`

* Update changelog

* Add new PR link to changelog

* Add examples in doc comments for labels and annotations

* Add doc comment for TryFromIterator

* Add TryFromIterator tests

Author: Techassi

CHANGELOG.md

@@ -8,12 +8,18 @@ All notable changes to this project will be documented in this file.
 
 - Add `TryFrom<[(K, V); N]>` implementation for `Annotations` and `Labels` ([#711]).
 - Add `parse_insert` associated function for `Annotations` and `Labels` ([#711]).
+- Add generic types for `TryFrom<BTreeMap<K, V>>` impl ([#714]).
+- Add `TryFromIterator` trait, which tries to construct `Self` from an iterator. It is a falliable version of
+  `FromIterator` ([#715]).
+- Add `TryFromIterator` impl for `Labels` and `Annotations` ([#715]).
 
 ### Changed
 
 - Adjust `try_insert` for `Annotations` and `Labels` slightly ([#711]).
 
 [#711]: https://github.com/stackabletech/operator-rs/pull/711
+[#714]: https://github.com/stackabletech/operator-rs/pull/714
+[#715]: https://github.com/stackabletech/operator-rs/pull/715
 
 ## [0.60.1] - 2024-01-04
 

src/iter.rs

@@ -45,9 +45,21 @@ where
     }
 }
 
+/// This is a fallible version of the std [`FromIterator`] trait.
+///
+/// The standard [`FromIterator`] trait specifies it must never fail. This trait
+/// makes it easier to work with iterators, which can fail during the creation
+/// `Self`. It will immediately return an error if processing failed and will
+/// not continue to process items.
+pub trait TryFromIterator<T>: Sized {
+    type Error: std::error::Error;
+
+    fn try_from_iter<I: IntoIterator<Item = T>>(iter: I) -> Result<Self, Self::Error>;
+}
+
 #[cfg(test)]
 mod tests {
-    use crate::iter::try_flatten;
+    use super::*;
 
     #[test]
     fn try_flatten_marble_test() {
@@ -62,4 +74,50 @@ mod tests {
             vec![Ok(1), Err(2), Ok(3), Err(4), Err(5), Ok(6)],
         );
     }
+
+    #[test]
+    fn try_from_iter_success() {
+        let iter = [1, 2, 3, 4];
+
+        #[derive(Debug, PartialEq)]
+        struct Sum(usize);
+
+        impl TryFromIterator<usize> for Sum {
+            type Error = std::convert::Infallible;
+
+            fn try_from_iter<I: IntoIterator<Item = usize>>(iter: I) -> Result<Self, Self::Error> {
+                let sum = iter.into_iter().sum();
+                Ok(Sum(sum))
+            }
+        }
+
+        assert_eq!(Sum(10), Sum::try_from_iter(iter).unwrap());
+    }
+
+    #[test]
+    fn try_from_iter_error() {
+        let iter = ["1", "2", "3", "-4"];
+
+        #[derive(Debug, PartialEq)]
+        struct Sum(usize);
+
+        impl<T> TryFromIterator<T> for Sum
+        where
+            T: AsRef<str>,
+        {
+            type Error = std::num::ParseIntError;
+
+            fn try_from_iter<I: IntoIterator<Item = T>>(iter: I) -> Result<Self, Self::Error> {
+                let mut sum = 0;
+
+                for item in iter {
+                    sum += item.as_ref().parse::<usize>()?;
+                }
+
+                Ok(Self(sum))
+            }
+        }
+
+        assert!(Sum::try_from_iter(iter).is_err());
+    }
 }

src/kvp/annotation/mod.rs

@@ -19,6 +19,7 @@ use delegate::delegate;
 
 use crate::{
     builder::SecretOperatorVolumeScope,
+    iter::TryFromIterator,
     kvp::{Key, KeyValuePair, KeyValuePairError, KeyValuePairs, KeyValuePairsError},
 };
 
@@ -138,6 +139,31 @@ impl Annotation {
 ///
 /// It provides selected associated functions to manipulate the set of
 /// annotations, like inserting or extending.
+///
+/// ## Examples
+///
+/// ### Converting a BTreeMap into a list of labels
+///
+/// ```
+/// # use std::collections::BTreeMap;
+/// # use stackable_operator::kvp::Annotations;
+/// let map = BTreeMap::from([
+///     ("stackable.tech/managed-by", "stackablectl"),
+///     ("stackable.tech/vendor", "Stäckable"),
+/// ]);
+///
+/// let labels = Annotations::try_from(map).unwrap();
+/// ```
+///
+/// ### Creating a list of labels from an array
+///
+/// ```
+/// # use stackable_operator::kvp::Annotations;
+/// let labels = Annotations::try_from([
+///     ("stackable.tech/managed-by", "stackablectl"),
+///     ("stackable.tech/vendor", "Stäckable"),
+/// ]).unwrap();
+/// ```
 #[derive(Clone, Debug, Default)]
 pub struct Annotations(KeyValuePairs<AnnotationValue>);
 
@@ -148,9 +174,8 @@ where
 {
     type Error = AnnotationError;
 
-    fn try_from(value: BTreeMap<K, V>) -> Result<Self, Self::Error> {
-        let kvps = KeyValuePairs::try_from(value)?;
-        Ok(Self(kvps))
+    fn try_from(map: BTreeMap<K, V>) -> Result<Self, Self::Error> {
+        Self::try_from_iter(map)
     }
 }
 
@@ -161,9 +186,8 @@ where
 {
     type Error = AnnotationError;
 
-    fn try_from(value: &BTreeMap<K, V>) -> Result<Self, Self::Error> {
-        let kvps = KeyValuePairs::try_from(value)?;
-        Ok(Self(kvps))
+    fn try_from(map: &BTreeMap<K, V>) -> Result<Self, Self::Error> {
+        Self::try_from_iter(map)
     }
 }
 
@@ -174,9 +198,8 @@ where
 {
     type Error = AnnotationError;
 
-    fn try_from(value: [(K, V); N]) -> Result<Self, Self::Error> {
-        let kvps = KeyValuePairs::try_from(value)?;
-        Ok(Self(kvps))
+    fn try_from(array: [(K, V); N]) -> Result<Self, Self::Error> {
+        Self::try_from_iter(array)
     }
 }
 
@@ -187,6 +210,19 @@ impl FromIterator<KeyValuePair<AnnotationValue>> for Annotations {
     }
 }
 
+impl<K, V> TryFromIterator<(K, V)> for Annotations
+where
+    K: AsRef<str>,
+    V: AsRef<str>,
+{
+    type Error = AnnotationError;
+
+    fn try_from_iter<I: IntoIterator<Item = (K, V)>>(iter: I) -> Result<Self, Self::Error> {
+        let kvps = KeyValuePairs::try_from_iter(iter)?;
+        Ok(Self(kvps))
+    }
+}
+
 impl From<Annotations> for BTreeMap<String, String> {
     fn from(value: Annotations) -> Self {
         value.0.into()

src/kvp/label/mod.rs

@@ -18,6 +18,7 @@ use delegate::delegate;
 use kube::{Resource, ResourceExt};
 
 use crate::{
+    iter::TryFromIterator,
     kvp::{
         consts::{
             K8S_APP_COMPONENT_KEY, K8S_APP_INSTANCE_KEY, K8S_APP_MANAGED_BY_KEY, K8S_APP_NAME_KEY,
@@ -139,6 +140,31 @@ impl Label {
 ///
 /// It provides selected associated functions to manipulate the set of labels,
 /// like inserting or extending.
+///
+/// ## Examples
+///
+/// ### Converting a BTreeMap into a list of labels
+///
+/// ```
+/// # use std::collections::BTreeMap;
+/// # use stackable_operator::kvp::Labels;
+/// let map = BTreeMap::from([
+///     ("stackable.tech/managed-by", "stackablectl"),
+///     ("stackable.tech/vendor", "Stackable"),
+/// ]);
+///
+/// let labels = Labels::try_from(map).unwrap();
+/// ```
+///
+/// ### Creating a list of labels from an array
+///
+/// ```
+/// # use stackable_operator::kvp::Labels;
+/// let labels = Labels::try_from([
+///     ("stackable.tech/managed-by", "stackablectl"),
+///     ("stackable.tech/vendor", "Stackable"),
+/// ]).unwrap();
+/// ```
 #[derive(Clone, Debug, Default)]
 pub struct Labels(KeyValuePairs<LabelValue>);
 
@@ -150,8 +176,7 @@ where
     type Error = LabelError;
 
     fn try_from(map: BTreeMap<K, V>) -> Result<Self, Self::Error> {
-        let kvps = KeyValuePairs::try_from(map)?;
-        Ok(Self(kvps))
+        Self::try_from_iter(map)
     }
 }
 
@@ -163,8 +188,7 @@ where
     type Error = LabelError;
 
     fn try_from(map: &BTreeMap<K, V>) -> Result<Self, Self::Error> {
-        let kvps = KeyValuePairs::try_from(map)?;
-        Ok(Self(kvps))
+        Self::try_from_iter(map)
     }
 }
 
@@ -175,9 +199,8 @@ where
 {
     type Error = LabelError;
 
-    fn try_from(value: [(K, V); N]) -> Result<Self, Self::Error> {
-        let kvps = KeyValuePairs::try_from(value)?;
-        Ok(Self(kvps))
+    fn try_from(array: [(K, V); N]) -> Result<Self, Self::Error> {
+        Self::try_from_iter(array)
     }
 }
 
@@ -188,6 +211,19 @@ impl FromIterator<KeyValuePair<LabelValue>> for Labels {
     }
 }
 
+impl<K, V> TryFromIterator<(K, V)> for Labels
+where
+    K: AsRef<str>,
+    V: AsRef<str>,
+{
+    type Error = LabelError;
+
+    fn try_from_iter<I: IntoIterator<Item = (K, V)>>(iter: I) -> Result<Self, Self::Error> {
+        let kvps = KeyValuePairs::try_from_iter(iter)?;
+        Ok(Self(kvps))
+    }
+}
+
 impl From<Labels> for BTreeMap<String, String> {
     fn from(value: Labels) -> Self {
         value.0.into()