chore: Rename 'join_nulls' parameter to 'nulls_equal' in join functio…

…ns (#21507)

crates/polars-lazy/src/frame/mod.rs

@@ -1382,7 +1382,7 @@ impl LazyFrame {
             validation,
             suffix,
             slice,
-            join_nulls,
+            nulls_equal,
             coalesce,
             maintain_order,
         } = args;
@@ -1398,7 +1398,7 @@ impl LazyFrame {
             .right_on(right_on)
             .how(how)
             .validate(validation)
-            .join_nulls(join_nulls)
+            .join_nulls(nulls_equal)
             .coalesce(coalesce)
             .maintain_order(maintain_order);
 
@@ -2048,7 +2048,7 @@ pub struct JoinBuilder {
     force_parallel: bool,
     suffix: Option<PlSmallStr>,
     validation: JoinValidation,
-    join_nulls: bool,
+    nulls_equal: bool,
     coalesce: JoinCoalesce,
     maintain_order: MaintainOrderJoin,
 }
@@ -2065,7 +2065,7 @@ impl JoinBuilder {
             force_parallel: false,
             suffix: None,
             validation: Default::default(),
-            join_nulls: false,
+            nulls_equal: false,
             coalesce: Default::default(),
             maintain_order: Default::default(),
         }
@@ -2127,8 +2127,8 @@ impl JoinBuilder {
     }
 
     /// Join on null values. By default null values will never produce matches.
-    pub fn join_nulls(mut self, join_nulls: bool) -> Self {
-        self.join_nulls = join_nulls;
+    pub fn join_nulls(mut self, nulls_equal: bool) -> Self {
+        self.nulls_equal = nulls_equal;
         self
     }
 
@@ -2169,7 +2169,7 @@ impl JoinBuilder {
             validation: self.validation,
             suffix: self.suffix,
             slice: None,
-            join_nulls: self.join_nulls,
+            nulls_equal: self.nulls_equal,
             coalesce: self.coalesce,
             maintain_order: self.maintain_order,
         };
@@ -2266,7 +2266,7 @@ impl JoinBuilder {
             validation: self.validation,
             suffix: self.suffix,
             slice: None,
-            join_nulls: self.join_nulls,
+            nulls_equal: self.nulls_equal,
             coalesce: self.coalesce,
             maintain_order: self.maintain_order,
         };

crates/polars-ops/src/frame/join/args.rs

@@ -26,7 +26,7 @@ pub struct JoinArgs {
     pub validation: JoinValidation,
     pub suffix: Option<PlSmallStr>,
     pub slice: Option<(i64, usize)>,
-    pub join_nulls: bool,
+    pub nulls_equal: bool,
     pub coalesce: JoinCoalesce,
     pub maintain_order: MaintainOrderJoin,
 }
@@ -120,7 +120,7 @@ impl JoinArgs {
             validation: Default::default(),
             suffix: None,
             slice: None,
-            join_nulls: false,
+            nulls_equal: false,
             coalesce: Default::default(),
             maintain_order: Default::default(),
         }
@@ -312,7 +312,7 @@ impl JoinValidation {
         s_left: &Series,
         s_right: &Series,
         build_shortest_table: bool,
-        join_nulls: bool,
+        nulls_equal: bool,
     ) -> PolarsResult<()> {
         // In default, probe is the left series.
         //
@@ -330,7 +330,7 @@ impl JoinValidation {
             // The other side use `validate_build` to check
             ManyToMany | ManyToOne => true,
             OneToMany | OneToOne => {
-                if !join_nulls && probe.null_count() > 0 {
+                if !nulls_equal && probe.null_count() > 0 {
                     probe.n_unique()? - 1 == probe.len() - probe.null_count()
                 } else {
                     probe.n_unique()? == probe.len()

crates/polars-ops/src/frame/join/dispatch_left_right.rs

@@ -79,8 +79,13 @@ pub fn materialize_left_join_from_series(
         s_right = s_right.rechunk();
     }
 
-    let (left_idx, right_idx) =
-        sort_or_hash_left(&s_left, &s_right, verbose, args.validation, args.join_nulls)?;
+    let (left_idx, right_idx) = sort_or_hash_left(
+        &s_left,
+        &s_right,
+        verbose,
+        args.validation,
+        args.nulls_equal,
+    )?;
 
     let right = if let Some(drop_names) = drop_names {
         right.drop_many(drop_names)

crates/polars-ops/src/frame/join/hash_join/mod.rs

@@ -129,13 +129,13 @@ pub trait JoinDispatch: IntoDf {
         s_right: &Series,
         slice: Option<(i64, usize)>,
         anti: bool,
-        join_nulls: bool,
+        nulls_equal: bool,
     ) -> PolarsResult<DataFrame> {
         let ca_self = self.to_df();
         #[cfg(feature = "dtype-categorical")]
         _check_categorical_src(s_left.dtype(), s_right.dtype())?;
 
-        let idx = s_left.hash_join_semi_anti(s_right, anti, join_nulls)?;
+        let idx = s_left.hash_join_semi_anti(s_right, anti, nulls_equal)?;
         // SAFETY:
         // indices are in bounds
         Ok(unsafe { ca_self._finish_anti_semi_join(&idx, slice) })
@@ -153,7 +153,7 @@ pub trait JoinDispatch: IntoDf {
 
         // Get the indexes of the joined relations
         let (mut join_idx_l, mut join_idx_r) =
-            s_left.hash_join_outer(s_right, args.validation, args.join_nulls)?;
+            s_left.hash_join_outer(s_right, args.validation, args.nulls_equal)?;
 
         try_raise_keyboard_interrupt();
         if let Some((offset, len)) = args.slice {

crates/polars-ops/src/frame/join/hash_join/single_keys.rs

@@ -15,7 +15,7 @@ const MIN_ELEMS_PER_THREAD: usize = if cfg!(debug_assertions) { 1 } else { 128 }
 
 pub(crate) fn build_tables<T, I>(
     keys: Vec<I>,
-    join_nulls: bool,
+    nulls_equal: bool,
 ) -> Vec<PlHashMap<<T as ToTotalOrd>::TotalOrdItem, IdxVec>>
 where
     T: TotalHash + TotalEq + ToTotalOrd,
@@ -38,7 +38,7 @@ where
         for it in keys {
             for k in it {
                 let k = k.to_total_ord();
-                if !k.is_null() || join_nulls {
+                if !k.is_null() || nulls_equal {
                     hm.entry(k).or_default().push(offset);
                 }
                 offset += 1;
@@ -144,7 +144,7 @@ where
 
                         let key = *scatter_keys.get_unchecked(i);
 
-                        if !key.is_null() || join_nulls {
+                        if !key.is_null() || nulls_equal {
                             let idx = *scatter_idxs.get_unchecked(i);
                             match hm.entry(key) {
                                 Entry::Occupied(mut o) => {