feat: add iter methods for Labels and Annotations (#720)

* use Vec instead of BTreeMap for KeyValuePairs

* rustfmt hangovers

* upgrade rust to 1.75.0

* add iterator methods for KeyValuePairs

* add iterator methods for Labels and Annotations

* impl PartialEq<AsRef<str>> for KeyPrefix

* impl PartialEq<AsRef<str>> for KeyName

* delegate iter/into_iter for Labels and Annotations

* update changelog

* ci: update rust toolchain version

* impl IntoIterator for KeyValuePairs, Labels and Attributes (instead of custom into_iter() method)

* fix unrelated clippy warnings
https://rust-lang.github.io/rust-clippy/master/index.html#/get_first

* update changelog

* Revert "use Vec instead of BTreeMap for KeyValuePairs"

This reverts commit 3b1ea5a.

* remove BTreeSet -> Vec from changelog

* docs: a note about why BTreeSet is used

* fix IntoIterator for BTreeSet

* use a real label prefix in tests

* add test for KeyName equality with AsRef<str>

Author: NickLarsenNZ

.github/workflows/build.yml

@@ -17,7 +17,7 @@ env:
   CARGO_TERM_COLOR: always
   CARGO_INCREMENTAL: '0'
   CARGO_PROFILE_DEV_DEBUG: '0'
-  RUST_TOOLCHAIN_VERSION: "1.71.0"
+  RUST_TOOLCHAIN_VERSION: "1.75.0"
   RUSTFLAGS: "-D warnings"
   RUSTDOCFLAGS: "-D warnings"
   RUST_LOG: "info"

CHANGELOG.md

@@ -7,14 +7,18 @@ All notable changes to this project will be documented in this file.
 ### Added
 
 - Added `Option::as_ref_or_else` to `utils` ([#717]).
+- Add `iter()` methods to `KeyValuePairs<T>`, and delegate iter() for `Labels`, and `Annotations` ([#720]).
+- Implement `IntoIterator` for `KeyValuePairs<T>`, `Labels` and `Annotations` ([#720]).
 - Added `ListenerOperatorVolumeSourceBuilder::build_pvc` ([#719]).
 
 ### Changed
 
 - Split `utils` into submodules ([#717]).
+- Bump rust to 1.75.0 ([#720]).
 - Renamed `ListenerOperatorVolumeSourceBuilder::build` to `::build_ephemeral` ([#719]).
 
 [#717]: https://github.com/stackabletech/operator-rs/pull/717
+[#720]: https://github.com/stackabletech/operator-rs/pull/720
 [#719]: https://github.com/stackabletech/operator-rs/pull/719
 
 ## [0.61.0] - 2024-01-15

rust-toolchain.toml

@@ -1,2 +1,2 @@
 [toolchain]
-channel = "1.71.0"
+channel = "1.75.0"

src/builder/meta.rs

@@ -343,7 +343,7 @@ mod tests {
         assert_eq!(meta.name, Some("foo".to_string()));
         assert_eq!(meta.owner_references.as_ref().unwrap().len(), 1);
         assert!(
-            matches!(meta.owner_references.unwrap().get(0), Some(OwnerReference { uid, ..}) if uid == "uid")
+            matches!(meta.owner_references.unwrap().first(), Some(OwnerReference { uid, ..}) if uid == "uid")
         );
         assert_eq!(meta.annotations.as_ref().unwrap().len(), 1);
         assert_eq!(

src/builder/pod/container.rs

@@ -392,7 +392,7 @@ mod tests {
 
         assert_eq!(container.name, "testcontainer");
         assert!(
-            matches!(container.env.as_ref().unwrap().get(0), Some(EnvVar {name, value: Some(value), ..}) if name == "foo" && value == "bar")
+            matches!(container.env.as_ref().unwrap().first(), Some(EnvVar {name, value: Some(value), ..}) if name == "foo" && value == "bar")
         );
         assert!(
             matches!(container.env.as_ref().unwrap().get(1), Some(EnvVar {name, value_from: Some(EnvVarSource {config_map_key_ref: Some(ConfigMapKeySelector {name: Some(config_map_name), key: config_map_key, ..}), ..}), ..}) if name == "envFromConfigMap" && config_map_name == "my-configmap" && config_map_key == "my-key")
@@ -402,7 +402,7 @@ mod tests {
         );
         assert_eq!(container.volume_mounts.as_ref().unwrap().len(), 1);
         assert!(
-            matches!(container.volume_mounts.as_ref().unwrap().get(0), Some(VolumeMount {mount_path, name, ..}) if mount_path == "/mount" && name == "configmap")
+            matches!(container.volume_mounts.as_ref().unwrap().first(), Some(VolumeMount {mount_path, name, ..}) if mount_path == "/mount" && name == "configmap")
         );
         assert_eq!(container.ports.as_ref().unwrap().len(), 2);
         assert_eq!(

src/builder/pod/mod.rs

@@ -691,13 +691,13 @@ mod tests {
             pod_spec
                 .init_containers
                 .as_ref()
-                .and_then(|containers| containers.get(0).as_ref().map(|c| c.name.clone())),
+                .and_then(|containers| containers.first().as_ref().map(|c| c.name.clone())),
             Some("init-containername".to_string())
         );
 
         assert_eq!(
             pod_spec.volumes.as_ref().and_then(|volumes| volumes
-                .get(0)
+                .first()
                 .as_ref()
                 .and_then(|volume| volume.config_map.as_ref()?.name.clone())),
             Some("configmap".to_string())

src/kvp/annotation/mod.rs

@@ -287,10 +287,25 @@ impl Annotations {
             /// provided `key`. Failure to parse/validate the [`Key`] will
             /// return `false`.
             pub fn contains_key(&self, key: impl TryInto<Key>) -> bool;
+
+            /// Returns an [`Iterator`] over [`Annotations`] yielding a reference to every [`Annotation`] contained within.
+            pub fn iter(&self) -> impl Iterator<Item = &KeyValuePair<AnnotationValue>>;
+
         }
     }
 }
 
+impl IntoIterator for Annotations {
+    type Item = KeyValuePair<AnnotationValue>;
+    type IntoIter = std::collections::btree_set::IntoIter<Self::Item>;
+
+    /// Returns a consuming [`Iterator`] over [`Annotations`] moving every [`Annotation`] out.
+    /// The [`Annotations`] cannot be used again after calling this.
+    fn into_iter(self) -> Self::IntoIter {
+        self.0.into_iter()
+    }
+}
+
 #[cfg(test)]
 mod test {
     use super::*;

src/kvp/key.rs

@@ -242,6 +242,15 @@ impl Display for KeyPrefix {
     }
 }
 
+impl<T> PartialEq<T> for KeyPrefix
+where
+    T: AsRef<str>,
+{
+    fn eq(&self, other: &T) -> bool {
+        self.as_str() == other.as_ref()
+    }
+}
+
 /// The error type for key name parsing/validation operations.
 #[derive(Debug, PartialEq, Snafu)]
 pub enum KeyNameError {
@@ -315,6 +324,15 @@ impl Display for KeyName {
     }
 }
 
+impl<T> PartialEq<T> for KeyName
+where
+    T: AsRef<str>,
+{
+    fn eq(&self, other: &T) -> bool {
+        self.as_str() == other.as_ref()
+    }
+}
+
 #[cfg(test)]
 mod test {
     use super::*;
@@ -338,6 +356,22 @@ mod test {
         assert_eq!(key.to_string(), "vendor");
     }
 
+    #[test]
+    fn prefix_equality() {
+        const EXAMPLE_PREFIX_STR: &str = "stackable.tech";
+
+        let example_prefix = KeyPrefix::from_str(EXAMPLE_PREFIX_STR).expect("valid test prefix");
+        assert!(example_prefix == EXAMPLE_PREFIX_STR);
+    }
+
+    #[test]
+    fn name_equality() {
+        const EXAMPLE_NAME_STR: &str = "managed-by";
+
+        let example_name = KeyName::from_str(EXAMPLE_NAME_STR).expect("valid test name");
+        assert!(example_name == EXAMPLE_NAME_STR);
+    }
+
     #[rstest]
     #[case("foo/bar/baz", KeyError::NestedPrefix)]
     #[case("", KeyError::EmptyInput)]

src/kvp/label/mod.rs

@@ -374,10 +374,25 @@ impl Labels {
             /// Returns if the set of labels contains a label with the provided `key`.
             /// Failure to parse/validate the [`Key`] will return `false`.
             pub fn contains_key(&self, key: impl TryInto<Key>) -> bool;
+
+            /// Returns an [`Iterator`] over [`Labels`] yielding a reference to every [`Label`] contained within.
+            pub fn iter(&self) -> impl Iterator<Item = &KeyValuePair<LabelValue>>;
+
         }
     }
 }
 
+impl IntoIterator for Labels {
+    type Item = KeyValuePair<LabelValue>;
+    type IntoIter = std::collections::btree_set::IntoIter<Self::Item>;
+
+    /// Returns a consuming [`Iterator`] over [`Labels`] moving every [`Label`] out.
+    /// The [`Labels`] cannot be used again after calling this.
+    fn into_iter(self) -> Self::IntoIter {
+        self.0.into_iter()
+    }
+}
+
 #[cfg(test)]
 mod test {
     use super::*;

src/kvp/mod.rs

@@ -161,6 +161,12 @@ pub enum KeyValuePairsError {
 /// - `From<KeyValuePairs<T>> for BTreeMap<String, String>`
 ///
 /// See [`Labels`] and [`Annotations`] on how these traits can be used.
+///
+/// # Note
+///
+/// A [`BTreeSet`] is used as the inner collection to preserve order of items
+/// which ultimately prevent unncessary reconciliations due to changes
+/// in item order.
 #[derive(Clone, Debug, Default)]
 pub struct KeyValuePairs<T: Value>(BTreeSet<KeyValuePair<T>>);
 
@@ -295,13 +301,17 @@ where
 
     /// Returns if the list contains a specific [`KeyValuePair`].
     pub fn contains(&self, kvp: impl TryInto<KeyValuePair<T>>) -> bool {
-        let Ok(kvp) = kvp.try_into() else {return false};
+        let Ok(kvp) = kvp.try_into() else {
+            return false;
+        };
         self.0.contains(&kvp)
     }
 
     /// Returns if the list contains a key/value pair with a specific [`Key`].
     pub fn contains_key(&self, key: impl TryInto<Key>) -> bool {
-        let Ok(key) = key.try_into() else {return false};
+        let Ok(key) = key.try_into() else {
+            return false;
+        };
 
         for kvp in &self.0 {
             if kvp.key == key {
@@ -311,6 +321,25 @@ where
 
         false
     }
+
+    /// Returns an [`Iterator`] over [`KeyValuePairs`] yielding a reference to every [`KeyValuePair`] contained within.
+    pub fn iter(&self) -> impl Iterator<Item = &KeyValuePair<T>> {
+        self.0.iter()
+    }
+}
+
+impl<T> IntoIterator for KeyValuePairs<T>
+where
+    T: Value,
+{
+    type Item = KeyValuePair<T>;
+    type IntoIter = std::collections::btree_set::IntoIter<Self::Item>;
+
+    /// Returns a consuming [`Iterator`] over [`KeyValuePairs`] moving every [`KeyValuePair`] out.
+    /// The [`KeyValuePairs`] cannot be used again after calling this.
+    fn into_iter(self) -> Self::IntoIter {
+        self.0.into_iter()
+    }
 }
 
 /// A recommended set of labels to set on objects created by Stackable