Add empty scalar function (alias of array_empty), fix a small typo (#938

)

* feat: add `empty` function as alias of array_empty

* fix: correct typo in null_treatment parameter documentation

docs/source/user-guide/common-operations/expressions.rst

@@ -82,7 +82,7 @@ approaches.
     Indexing an element of an array via ``[]`` starts at index 0 whereas
     :py:func:`~datafusion.functions.array_element` starts at index 1.
 
-To check if an array is empty, you can use the function :py:func:`datafusion.functions.array_empty`.
+To check if an array is empty, you can use the function :py:func:`datafusion.functions.array_empty` or `datafusion.functions.empty`.
 This function returns a boolean indicating whether the array is empty.
 
 .. ipython:: python

python/datafusion/functions.py

@@ -125,6 +125,7 @@
     "decode",
     "degrees",
     "digest",
+    "empty",
     "encode",
     "ends_with",
     "exp",
@@ -1522,6 +1523,11 @@ def cardinality(array: Expr) -> Expr:
     return Expr(f.cardinality(array.expr))
 
 
+def empty(array: Expr) -> Expr:
+    """This is an alias for :py:func:`array_empty`."""
+    return array_empty(array)
+
+
 # aggregate functions
 def approx_distinct(
     expression: Expr,
@@ -2140,7 +2146,7 @@ def first_value(
         expression: Argument to perform bitwise calculation on
         filter: If provided, only compute against rows for which the filter is True
         order_by: Set the ordering of the expression to evaluate
-        null_treatment: Assign whether to respect or ignull null values.
+        null_treatment: Assign whether to respect or ignore null values.
     """
     order_by_raw = sort_list_to_raw_sort_list(order_by)
     filter_raw = filter.expr if filter is not None else None
@@ -2172,7 +2178,7 @@ def last_value(
         expression: Argument to perform bitwise calculation on
         filter: If provided, only compute against rows for which the filter is True
         order_by: Set the ordering of the expression to evaluate
-        null_treatment: Assign whether to respect or ignull null values.
+        null_treatment: Assign whether to respect or ignore null values.
     """
     order_by_raw = sort_list_to_raw_sort_list(order_by)
     filter_raw = filter.expr if filter is not None else None
@@ -2206,7 +2212,7 @@ def nth_value(
         n: Index of value to return. Starts at 1.
         filter: If provided, only compute against rows for which the filter is True
         order_by: Set the ordering of the expression to evaluate
-        null_treatment: Assign whether to respect or ignull null values.
+        null_treatment: Assign whether to respect or ignore null values.
     """
     order_by_raw = sort_list_to_raw_sort_list(order_by)
     filter_raw = filter.expr if filter is not None else None

python/tests/test_functions.py

@@ -313,6 +313,10 @@ def py_flatten(arr):
             lambda col: f.array_empty(col),
             lambda data: [len(r) == 0 for r in data],
         ],
+        [
+            lambda col: f.empty(col),
+            lambda data: [len(r) == 0 for r in data],
+        ],
         [
             lambda col: f.array_extract(col, literal(1)),
             lambda data: [r[0] for r in data],