Merge of #1966

Author: mergify[bot]

.changelog/unreleased/1966_list_functions.yaml

@@ -0,0 +1,8 @@
+type: Added
+title: Add list and string helper functions to `pulumi_gestalt_rust::stdlib`
+description: |
+  - `element`: Returns an item by index with clear errors for negative and out-of-bounds indices.
+  - `join`: Joins a list of strings with a separator.
+  - `length`: Returns list length as `i64`.
+  - `split`: Splits text by a separator into `Vec<String>`.
+  - `single_or_none`: Returns `None` for empty lists, `Some` for single-item lists, and an error for larger lists.

crates/rust/src/stdlib.rs

@@ -1,4 +1,4 @@
-use anyhow::{Context, Result, anyhow};
+use anyhow::{Context, Result, anyhow, bail};
 use base64::Engine;
 use base64::engine::general_purpose::STANDARD;
 
@@ -28,9 +28,59 @@ pub fn from_base64(input: impl AsRef<str>) -> Result<String> {
     )
 }
 
+pub fn element<T: Clone, I: TryInto<i64>>(list: impl AsRef<[T]>, index: I) -> Result<T> {
+    let index = index
+        .try_into()
+        .map_err(|_| anyhow!("Failed to convert list index to i64"))?;
+    if index < 0 {
+        bail!("List index cannot be negative: {index}");
+    }
+    let index = usize::try_from(index).context("Failed to convert list index to usize")?;
+    let list_ref = list.as_ref();
+    list_ref.get(index).cloned().ok_or_else(|| {
+        anyhow!(
+            "List index {index} is out of bounds for length {}",
+            list_ref.len()
+        )
+    })
+}
+
+pub fn join<T: AsRef<str>>(separator: impl AsRef<str>, list: impl AsRef<[T]>) -> String {
+    list.as_ref()
+        .iter()
+        .map(AsRef::as_ref)
+        .collect::<Vec<_>>()
+        .join(separator.as_ref())
+}
+
+pub fn length<T>(list: impl AsRef<[T]>) -> i64 {
+    i64::try_from(list.as_ref().len()).expect("List length exceeds i64::MAX")
+}
+
+pub fn split(separator: impl AsRef<str>, text: impl AsRef<str>) -> Vec<String> {
+    text.as_ref()
+        .split(separator.as_ref())
+        .map(ToOwned::to_owned)
+        .collect()
+}
+
+pub fn single_or_none<T: Clone>(list: impl AsRef<[T]>) -> Result<Option<T>> {
+    let list_ref = list.as_ref();
+    if list_ref.is_empty() {
+        return Ok(None);
+    }
+    if list_ref.len() != 1 {
+        bail!(
+            "singleOrNone expected input list to have at most one element, got {}",
+            list_ref.len()
+        );
+    }
+    Ok(Some(list_ref[0].clone()))
+}
+
 #[cfg(test)]
 mod tests {
-    use super::{cwd, from_base64, to_base64};
+    use super::{cwd, element, from_base64, join, length, single_or_none, split, to_base64};
 
     #[test]
     fn to_base64_encodes_known_text() {
@@ -92,4 +142,60 @@ mod tests {
         assert_eq!(from_str, "YWJj");
         assert_eq!(from_str, from_bytes);
     }
+
+    #[test]
+    fn element_returns_item_for_valid_index() {
+        let values = vec!["a".to_string(), "b".to_string(), "c".to_string()];
+        assert_eq!(element(&values, 1).unwrap(), "b");
+    }
+
+    #[test]
+    fn element_returns_error_for_negative_index() {
+        let values = vec!["a", "b"];
+        let error = element(&values, -1).unwrap_err().to_string();
+        assert!(error.contains("cannot be negative"));
+    }
+
+    #[test]
+    fn element_returns_error_for_out_of_bounds_index() {
+        let values = vec!["a", "b"];
+        let error = element(&values, 2).unwrap_err().to_string();
+        assert!(error.contains("out of bounds"));
+    }
+
+    #[test]
+    fn join_joins_values_with_separator() {
+        let values = vec!["a".to_string(), "b".to_string(), "c".to_string()];
+        assert_eq!(join("|", &values), "a|b|c");
+    }
+
+    #[test]
+    fn length_returns_i64_length() {
+        let values = vec!["x", "y", "z"];
+        assert_eq!(length(&values), 3_i64);
+    }
+
+    #[test]
+    fn split_returns_segments() {
+        assert_eq!(split("-", "a-b-c"), vec!["a", "b", "c"]);
+    }
+
+    #[test]
+    fn single_or_none_returns_none_for_empty_list() {
+        let values: Vec<String> = vec![];
+        assert_eq!(single_or_none(&values).unwrap(), None);
+    }
+
+    #[test]
+    fn single_or_none_returns_some_for_single_item_list() {
+        let values = vec!["only".to_string()];
+        assert_eq!(single_or_none(&values).unwrap(), Some("only".to_string()));
+    }
+
+    #[test]
+    fn single_or_none_returns_error_for_multi_item_list() {
+        let values = vec!["a", "b"];
+        let error = single_or_none(&values).unwrap_err().to_string();
+        assert!(error.contains("at most one element"));
+    }
 }