rename variant -> child array

Author: friendlymatthew

arrow-cast/src/cast/mod.rs

@@ -110,7 +110,7 @@ pub fn can_cast_types(from_type: &DataType, to_type: &DataType) -> bool {
             can_cast_types(from_value_type, to_value_type)
         }
         (Dictionary(_, value_type), _) => can_cast_types(value_type, to_type),
-        (Union(fields, _), _) => union::resolve_variant(fields, to_type).is_some(),
+        (Union(fields, _), _) => union::resolve_child_array(fields, to_type).is_some(),
         (_, Union(_, _)) => false,
         (RunEndEncoded(_, value_type), _) => can_cast_types(value_type.data_type(), to_type),
         (_, RunEndEncoded(_, value_type)) => can_cast_types(from_type, value_type.data_type()),

arrow-cast/src/cast/union.rs

@@ -25,8 +25,8 @@ use arrow_select::union_extract::union_extract;
 
 use super::CastOptions;
 
-// this is used during variant selection to prefer a "close" type over a distant cast
-// for example: when targeting Utf8View, a Utf8 variant is preferred over Int32 despite both being castable
+// this is used during child array selection to prefer a "close" type over a distant cast
+// for example: when targeting Utf8View, a Utf8 child is preferred over Int32 despite both being castable
 fn same_type_family(a: &DataType, b: &DataType) -> bool {
     use DataType::*;
     matches!(
@@ -61,7 +61,7 @@ fn same_type_family(a: &DataType, b: &DataType) -> bool {
 ///    nulls, which can conflict with non-nullable inner fields
 ///
 /// Each pass greedily picks the first matching field by type_id order
-pub(crate) fn resolve_variant<'a>(
+pub(crate) fn resolve_child_array<'a>(
     fields: &'a UnionFields,
     target_type: &DataType,
 ) -> Option<&'a FieldRef> {
@@ -74,7 +74,7 @@ pub(crate) fn resolve_variant<'a>(
                 .find(|(_, f)| same_type_family(f.data_type(), target_type))
         })
         .or_else(|| {
-            // skip nested types in pass 3 — union extraction introduces nulls,
+            // skip nested types in pass 3 because union extraction introduces nulls,
             // and casting nullable arrays to nested types like List/Struct/Map can fail
             // when inner fields are non-nullable.
             if target_type.is_nested() {
@@ -90,8 +90,8 @@ pub(crate) fn resolve_variant<'a>(
 /// Extracts the best-matching child array from a [`UnionArray`] for a given target type,
 /// and casts it to that type.
 ///
-/// Rows where a different variant is active become NULL.
-/// If no variant matches, returns a null array.
+/// Rows where a different child array is active become NULL.
+/// If no child array matches, returns an error.
 ///
 /// # Example
 ///
@@ -120,7 +120,7 @@ pub(crate) fn resolve_variant<'a>(
 /// )
 /// .unwrap();
 ///
-/// // extract the Utf8 variant and cast to Utf8View
+/// // extract the Utf8 child array and cast to Utf8View
 /// let result = union_extract_by_type(&union, &DataType::Utf8View, &CastOptions::default()).unwrap();
 /// assert_eq!(result.data_type(), &DataType::Utf8View);
 /// assert!(result.is_null(0));   // Int32 row -> NULL
@@ -137,7 +137,7 @@ pub fn union_extract_by_type(
         _ => unreachable!("union_extract_by_type called on non-union array"),
     };
 
-    let Some(field) = resolve_variant(fields, target_type) else {
+    let Some(field) = resolve_child_array(fields, target_type) else {
         return Err(ArrowError::CastError(format!(
             "cannot cast Union with fields {} to {}",
             fields
@@ -182,7 +182,7 @@ mod tests {
     }
 
     // pass 1: exact type match.
-    // Union(Int32, Utf8) targeting Utf8 — the Utf8 variant matches exactly.
+    // Union(Int32, Utf8) targeting Utf8. The Utf8 child matches exactly.
     // Int32 rows become NULL. tested for both sparse and dense.
     #[test]
     fn test_exact_type_match() {
@@ -237,7 +237,7 @@ mod tests {
     }
 
     // pass 2: same type family match.
-    // Union(Int32, Utf8) targeting Utf8View — no exact match, but Utf8 and Utf8View
+    // Union(Int32, Utf8) targeting Utf8View. No exact match, but Utf8 and Utf8View
     // are in the same family. picks the Utf8 variant and casts to Utf8View.
     // this is the bug that motivated this work: without pass 2, pass 3 would
     // greedily pick Int32 (since can_cast_types(Int32, Utf8View) is true).