improve monotonicity api

datafusion-examples/examples/advanced_udf.rs

@@ -187,7 +187,7 @@ impl ScalarUDFImpl for PowUdf {
     }
 
     fn monotonicity(&self) -> Result<Option<FuncMonotonicity>> {
-        Ok(Some(vec![Some(true)]))
+        Ok(Some(FuncMonotonicity::new_increasing()))
     }
 }
 

datafusion/expr/src/signature.rs

@@ -346,13 +346,81 @@ impl Signature {
     }
 }
 
-/// Monotonicity of the `ScalarFunctionExpr` with respect to its arguments.
-/// Each element of this vector corresponds to an argument and indicates whether
-/// the function's behavior is monotonic, or non-monotonic/unknown for that argument, namely:
-/// - `None` signifies unknown monotonicity or non-monotonicity.
-/// - `Some(true)` indicates that the function is monotonically increasing w.r.t. the argument in question.
-/// - Some(false) indicates that the function is monotonically decreasing w.r.t. the argument in question.
-pub type FuncMonotonicity = Vec<Option<bool>>;
+#[derive(Debug, Clone)]
+enum FuncMonotonicityPartial {
+    /// not monotonic or unknown monotonicity
+    None,
+    /// Increasing with respect to all of its arguments
+    Increasing,
+    /// Decreasing with respect to all of its arguments
+    Decreasing,
+    /// Each element of this vector corresponds to an argument and indicates whether
+    /// the function's behavior is monotonic, or non-monotonic/unknown for that argument, namely:
+    /// - `None` signifies unknown monotonicity or non-monotonicity.
+    /// - `Some(true)` indicates that the function is monotonically increasing w.r.t. the argument in question.
+    /// - Some(false) indicates that the function is monotonically decreasing w.r.t. the argument in question.
+    Mixed(Vec<Option<bool>>),
+}
+
+/// Monotonicity of a function with respect to its arguments.
+///
+/// A function is [monotonic] if it preserves the relative order of its inputs.
+///
+/// [monotonic]: https://en.wikipedia.org/wiki/Monotonic_function
+#[derive(Debug, Clone)]
+pub struct FuncMonotonicity(FuncMonotonicityPartial);
+
+impl FuncMonotonicity {
+    pub fn new_none() -> Self {
+        Self(FuncMonotonicityPartial::None)
+    }
+    pub fn new_increasing() -> Self {
+        Self(FuncMonotonicityPartial::Increasing)
+    }
+    pub fn new_decreasing() -> Self {
+        Self(FuncMonotonicityPartial::Decreasing)
+    }
+    pub fn new_mixed(inner: Vec<Option<bool>>) -> Self {
+        Self(FuncMonotonicityPartial::Mixed(inner))
+    }
+
+    /// returns true if this function is monotonically increasing with respect to argument number arg
+    pub fn arg_increasing(&self, arg: usize) -> bool {
+        match &self.0 {
+            FuncMonotonicityPartial::None => false,
+            FuncMonotonicityPartial::Increasing => true,
+            FuncMonotonicityPartial::Decreasing => false,
+            FuncMonotonicityPartial::Mixed(inner) => inner[arg].unwrap_or(false),
+        }
+    }
+
+    /// returns true if this function is monotonically decreasing with respect to argument number arg
+    pub fn arg_decreasing(&self, arg: usize) -> bool {
+        match &self.0 {
+            FuncMonotonicityPartial::None => false,
+            FuncMonotonicityPartial::Increasing => false,
+            FuncMonotonicityPartial::Decreasing => true,
+            FuncMonotonicityPartial::Mixed(inner) => inner[arg].unwrap_or(false),
+        }
+    }
+}
+
+impl From<&FuncMonotonicity> for Vec<Option<bool>> {
+    fn from(val: &FuncMonotonicity) -> Self {
+        match &val.0 {
+            FuncMonotonicityPartial::None => vec![None],
+            FuncMonotonicityPartial::Increasing => vec![Some(true)],
+            FuncMonotonicityPartial::Decreasing => vec![Some(false)],
+            FuncMonotonicityPartial::Mixed(inner) => inner.to_vec(),
+        }
+    }
+}
+
+impl PartialEq for FuncMonotonicity {
+    fn eq(&self, other: &Self) -> bool {
+        Into::<Vec<Option<bool>>>::into(self) == Into::<Vec<Option<bool>>>::into(other)
+    }
+}
 
 #[cfg(test)]
 mod tests {

datafusion/functions/src/datetime/date_bin.rs

@@ -147,7 +147,7 @@ impl ScalarUDFImpl for DateBinFunc {
     }
 
     fn monotonicity(&self) -> Result<Option<FuncMonotonicity>> {
-        Ok(Some(vec![None, Some(true)]))
+        Ok(Some(FuncMonotonicity::new_mixed(vec![None, Some(true)])))
     }
 }
 

datafusion/functions/src/datetime/date_trunc.rs

@@ -206,7 +206,7 @@ impl ScalarUDFImpl for DateTruncFunc {
     }
 
     fn monotonicity(&self) -> Result<Option<FuncMonotonicity>> {
-        Ok(Some(vec![None, Some(true)]))
+        Ok(Some(FuncMonotonicity::new_mixed(vec![None, Some(true)])))
     }
 }
 

datafusion/functions/src/math/log.rs

@@ -84,7 +84,10 @@ impl ScalarUDFImpl for LogFunc {
     }
 
     fn monotonicity(&self) -> Result<Option<FuncMonotonicity>> {
-        Ok(Some(vec![Some(true), Some(false)]))
+        Ok(Some(FuncMonotonicity::new_mixed(vec![
+            Some(true),
+            Some(false),
+        ])))
     }
 
     // Support overloaded log(base, x) and log(x) which defaults to log(10, x)

datafusion/functions/src/math/mod.rs

@@ -38,29 +38,89 @@ pub mod trunc;
 // Create UDFs
 make_udf_function!(abs::AbsFunc, ABS, abs);
 make_math_unary_udf!(AcosFunc, ACOS, acos, acos, None);
-make_math_unary_udf!(AcoshFunc, ACOSH, acosh, acosh, Some(vec![Some(true)]));
+make_math_unary_udf!(
+    AcoshFunc,
+    ACOSH,
+    acosh,
+    acosh,
+    Some(FuncMonotonicity::new_increasing())
+);
 make_math_unary_udf!(AsinFunc, ASIN, asin, asin, None);
-make_math_unary_udf!(AsinhFunc, ASINH, asinh, asinh, Some(vec![Some(true)]));
-make_math_unary_udf!(AtanFunc, ATAN, atan, atan, Some(vec![Some(true)]));
-make_math_unary_udf!(AtanhFunc, ATANH, atanh, atanh, Some(vec![Some(true)]));
-make_math_binary_udf!(Atan2, ATAN2, atan2, atan2, Some(vec![Some(true)]));
+make_math_unary_udf!(
+    AsinhFunc,
+    ASINH,
+    asinh,
+    asinh,
+    Some(FuncMonotonicity::new_increasing())
+);
+make_math_unary_udf!(
+    AtanFunc,
+    ATAN,
+    atan,
+    atan,
+    Some(FuncMonotonicity::new_increasing())
+);
+make_math_unary_udf!(
+    AtanhFunc,
+    ATANH,
+    atanh,
+    atanh,
+    Some(FuncMonotonicity::new_increasing())
+);
+make_math_binary_udf!(
+    Atan2,
+    ATAN2,
+    atan2,
+    atan2,
+    Some(FuncMonotonicity::new_increasing())
+);
 make_math_unary_udf!(CbrtFunc, CBRT, cbrt, cbrt, None);
-make_math_unary_udf!(CeilFunc, CEIL, ceil, ceil, Some(vec![Some(true)]));
+make_math_unary_udf!(
+    CeilFunc,
+    CEIL,
+    ceil,
+    ceil,
+    Some(FuncMonotonicity::new_increasing())
+);
 make_math_unary_udf!(CosFunc, COS, cos, cos, None);
 make_math_unary_udf!(CoshFunc, COSH, cosh, cosh, None);
 make_udf_function!(cot::CotFunc, COT, cot);
 make_math_unary_udf!(DegreesFunc, DEGREES, degrees, to_degrees, None);
-make_math_unary_udf!(ExpFunc, EXP, exp, exp, Some(vec![Some(true)]));
+make_math_unary_udf!(
+    ExpFunc,
+    EXP,
+    exp,
+    exp,
+    Some(FuncMonotonicity::new_increasing())
+);
 make_udf_function!(factorial::FactorialFunc, FACTORIAL, factorial);
-make_math_unary_udf!(FloorFunc, FLOOR, floor, floor, Some(vec![Some(true)]));
+make_math_unary_udf!(
+    FloorFunc,
+    FLOOR,
+    floor,
+    floor,
+    Some(FuncMonotonicity::new_increasing())
+);
 make_udf_function!(log::LogFunc, LOG, log);
 make_udf_function!(gcd::GcdFunc, GCD, gcd);
 make_udf_function!(nans::IsNanFunc, ISNAN, isnan);
 make_udf_function!(iszero::IsZeroFunc, ISZERO, iszero);
 make_udf_function!(lcm::LcmFunc, LCM, lcm);
-make_math_unary_udf!(LnFunc, LN, ln, ln, Some(vec![Some(true)]));
-make_math_unary_udf!(Log2Func, LOG2, log2, log2, Some(vec![Some(true)]));
-make_math_unary_udf!(Log10Func, LOG10, log10, log10, Some(vec![Some(true)]));
+make_math_unary_udf!(LnFunc, LN, ln, ln, Some(FuncMonotonicity::new_increasing()));
+make_math_unary_udf!(
+    Log2Func,
+    LOG2,
+    log2,
+    log2,
+    Some(FuncMonotonicity::new_increasing())
+);
+make_math_unary_udf!(
+    Log10Func,
+    LOG10,
+    log10,
+    log10,
+    Some(FuncMonotonicity::new_increasing())
+);
 make_udf_function!(nanvl::NanvlFunc, NANVL, nanvl);
 make_udf_function!(pi::PiFunc, PI, pi);
 make_udf_function!(power::PowerFunc, POWER, power);

datafusion/functions/src/math/pi.rs

@@ -71,6 +71,6 @@ impl ScalarUDFImpl for PiFunc {
     }
 
     fn monotonicity(&self) -> Result<Option<FuncMonotonicity>> {
-        Ok(Some(vec![Some(true)]))
+        Ok(Some(FuncMonotonicity::new_increasing()))
     }
 }

datafusion/functions/src/math/round.rs

@@ -81,7 +81,7 @@ impl ScalarUDFImpl for RoundFunc {
     }
 
     fn monotonicity(&self) -> Result<Option<FuncMonotonicity>> {
-        Ok(Some(vec![Some(true)]))
+        Ok(Some(FuncMonotonicity::new_increasing()))
     }
 }
 

datafusion/functions/src/math/trunc.rs

@@ -87,7 +87,7 @@ impl ScalarUDFImpl for TruncFunc {
     }
 
     fn monotonicity(&self) -> Result<Option<FuncMonotonicity>> {
-        Ok(Some(vec![Some(true)]))
+        Ok(Some(FuncMonotonicity::new_increasing()))
     }
 }
 

datafusion/physical-expr/src/functions.rs

@@ -171,7 +171,8 @@ pub fn out_ordering(
     func: &FuncMonotonicity,
     arg_orderings: &[SortProperties],
 ) -> SortProperties {
-    func.iter().zip(arg_orderings).fold(
+    let monotonicity_vec: Vec<Option<bool>> = func.into();
+    monotonicity_vec.iter().zip(arg_orderings).fold(
         SortProperties::Singleton,
         |prev_sort, (item, arg)| {
             let current_sort = func_order_in_one_dimension(item, arg);

datafusion/physical-expr/src/udf.rs

@@ -65,7 +65,7 @@ mod tests {
     use arrow_schema::Schema;
 
     use datafusion_common::{DFSchema, Result};
-    use datafusion_expr::ScalarUDF;
+    use datafusion_expr::{FuncMonotonicity, ScalarUDF};
 
     use crate::utils::tests::TestScalarUDF;
     use crate::ScalarFunctionExpr;
@@ -87,7 +87,7 @@ mod tests {
                 .downcast_ref::<ScalarFunctionExpr>()
                 .unwrap()
                 .monotonicity(),
-            &Some(vec![Some(true)])
+            &Some(FuncMonotonicity::new_increasing())
         );
 
         Ok(())

datafusion/physical-expr/src/utils/mod.rs

@@ -310,7 +310,7 @@ pub(crate) mod tests {
         }
 
         fn monotonicity(&self) -> Result<Option<FuncMonotonicity>> {
-            Ok(Some(vec![Some(true)]))
+            Ok(Some(FuncMonotonicity::new_increasing()))
         }
 
         fn invoke(&self, args: &[ColumnarValue]) -> Result<ColumnarValue> {