EIC code displayed by LXR master/​include/​arrow/​compute/​function.h	Source navigation Diff markup Identifier search General search
	Version: master test Revert   Change

File indexing completed on 2025-08-28 08:26:56

 // Licensed to the Apache Software Foundation (ASF) under one
 // or more contributor license agreements.  See the NOTICE file
 // distributed with this work for additional information
 // regarding copyright ownership.  The ASF licenses this file
 // to you under the Apache License, Version 2.0 (the
 // "License"); you may not use this file except in compliance
 // with the License.  You may obtain a copy of the License at
 //
 //   http://www.apache.org/licenses/LICENSE-2.0
 //
 // Unless required by applicable law or agreed to in writing,
 // software distributed under the License is distributed on an
 // "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 // KIND, either express or implied.  See the License for the
 // specific language governing permissions and limitations
 // under the License.
 
 // NOTE: API is EXPERIMENTAL and will change without going through a
 // deprecation cycle.
 
 #pragma once
 
 #include <string>
 #include <utility>
 #include <vector>
 
 #include "arrow/compute/kernel.h"
 #include "arrow/compute/type_fwd.h"
 #include "arrow/datum.h"
 #include "arrow/result.h"
 #include "arrow/status.h"
 #include "arrow/util/compare.h"
 #include "arrow/util/macros.h"
 #include "arrow/util/visibility.h"
 
 namespace arrow {
 namespace compute {
 
 /// \addtogroup compute-functions
 /// @{
 
 /// \brief Contains the number of required arguments for the function.
 ///
 /// Naming conventions taken from https://en.wikipedia.org/wiki/Arity.
 struct ARROW_EXPORT Arity {
   /// \brief A function taking no arguments
   static Arity Nullary() { return Arity(0, false); }
 
   /// \brief A function taking 1 argument
   static Arity Unary() { return Arity(1, false); }
 
   /// \brief A function taking 2 arguments
   static Arity Binary() { return Arity(2, false); }
 
   /// \brief A function taking 3 arguments
   static Arity Ternary() { return Arity(3, false); }
 
   /// \brief A function taking a variable number of arguments
   ///
   /// \param[in] min_args the minimum number of arguments required when
   /// invoking the function
   static Arity VarArgs(int min_args = 0) { return Arity(min_args, true); }
 
   // NOTE: the 0-argument form (default constructor) is required for Cython
   explicit Arity(int num_args = 0, bool is_varargs = false)
       : num_args(num_args), is_varargs(is_varargs) {}
 
   /// The number of required arguments (or the minimum number for varargs
   /// functions).
   int num_args;
 
   /// If true, then the num_args is the minimum number of required arguments.
   bool is_varargs = false;
 };
 
 struct ARROW_EXPORT FunctionDoc {
   /// \brief A one-line summary of the function, using a verb.
   ///
   /// For example, "Add two numeric arrays or scalars".
   std::string summary;
 
   /// \brief A detailed description of the function, meant to follow the summary.
   std::string description;
 
   /// \brief Symbolic names (identifiers) for the function arguments.
   ///
   /// Some bindings may use this to generate nicer function signatures.
   std::vector<std::string> arg_names;
 
   // TODO add argument descriptions?
 
   /// \brief Name of the options class, if any.
   std::string options_class;
 
   /// \brief Whether options are required for function execution
   ///
   /// If false, then either the function does not have an options class
   /// or there is a usable default options value.
   bool options_required;
 
   FunctionDoc() = default;
 
   FunctionDoc(std::string summary, std::string description,
               std::vector<std::string> arg_names, std::string options_class = "",
               bool options_required = false)
       : summary(std::move(summary)),
         description(std::move(description)),
         arg_names(std::move(arg_names)),
         options_class(std::move(options_class)),
         options_required(options_required) {}
 
   static const FunctionDoc& Empty();
 };
 
 /// \brief An executor of a function with a preconfigured kernel
 class ARROW_EXPORT FunctionExecutor {
  public:
   virtual ~FunctionExecutor() = default;
   /// \brief Initialize or re-initialize the preconfigured kernel
   ///
   /// This method may be called zero or more times. Depending on how
   /// the FunctionExecutor was obtained, it may already have been initialized.
   virtual Status Init(const FunctionOptions* options = NULLPTR,
                       ExecContext* exec_ctx = NULLPTR) = 0;
   /// \brief Execute the preconfigured kernel with arguments that must fit it
   ///
   /// The method requires the arguments be castable to the preconfigured types.
   ///
   /// \param[in] args Arguments to execute the function on
   /// \param[in] length Length of arguments batch or -1 to default it. If the
   /// function has no parameters, this determines the batch length, defaulting
   /// to 0. Otherwise, if the function is scalar, this must equal the argument
   /// batch's inferred length or be -1 to default to it. This is ignored for
   /// vector functions.
   virtual Result<Datum> Execute(const std::vector<Datum>& args, int64_t length = -1) = 0;
 };
 
 /// \brief Base class for compute functions. Function implementations contain a
 /// collection of "kernels" which are implementations of the function for
 /// specific argument types. Selecting a viable kernel for executing a function
 /// is referred to as "dispatching".
 class ARROW_EXPORT Function {
  public:
   /// \brief The kind of function, which indicates in what contexts it is
   /// valid for use.
   enum Kind {
     /// A function that performs scalar data operations on whole arrays of
     /// data. Can generally process Array or Scalar values. The size of the
     /// output will be the same as the size (or broadcasted size, in the case
     /// of mixing Array and Scalar inputs) of the input.
     SCALAR,
 
     /// A function with array input and output whose behavior depends on the
     /// values of the entire arrays passed, rather than the value of each scalar
     /// value.
     VECTOR,
 
     /// A function that computes scalar summary statistics from array input.
     SCALAR_AGGREGATE,
 
     /// A function that computes grouped summary statistics from array input
     /// and an array of group identifiers.
     HASH_AGGREGATE,
 
     /// A function that dispatches to other functions and does not contain its
     /// own kernels.
     META
   };
 
   virtual ~Function() = default;
 
   /// \brief The name of the kernel. The registry enforces uniqueness of names.
   const std::string& name() const { return name_; }
 
   /// \brief The kind of kernel, which indicates in what contexts it is valid
   /// for use.
   Function::Kind kind() const { return kind_; }
 
   /// \brief Contains the number of arguments the function requires, or if the
   /// function accepts variable numbers of arguments.
   const Arity& arity() const { return arity_; }
 
   /// \brief Return the function documentation
   const FunctionDoc& doc() const { return doc_; }
 
   /// \brief Returns the number of registered kernels for this function.
   virtual int num_kernels() const = 0;
 
   /// \brief Return a kernel that can execute the function given the exact
   /// argument types (without implicit type casts).
   ///
   /// NB: This function is overridden in CastFunction.
   virtual Result<const Kernel*> DispatchExact(const std::vector<TypeHolder>& types) const;
 
   /// \brief Return a best-match kernel that can execute the function given the argument
   /// types, after implicit casts are applied.
   ///
   /// \param[in,out] values Argument types. An element may be modified to
   /// indicate that the returned kernel only approximately matches the input
   /// value descriptors; callers are responsible for casting inputs to the type
   /// required by the kernel.
   virtual Result<const Kernel*> DispatchBest(std::vector<TypeHolder>* values) const;
 
   /// \brief Get a function executor with a best-matching kernel
   ///
   /// The returned executor will by default work with the default FunctionOptions
   /// and KernelContext. If you want to change that, call `FunctionExecutor::Init`.
   virtual Result<std::shared_ptr<FunctionExecutor>> GetBestExecutor(
       std::vector<TypeHolder> inputs) const;
 
   /// \brief Execute the function eagerly with the passed input arguments with
   /// kernel dispatch, batch iteration, and memory allocation details taken
   /// care of.
   ///
   /// If the `options` pointer is null, then `default_options()` will be used.
   ///
   /// This function can be overridden in subclasses.
   virtual Result<Datum> Execute(const std::vector<Datum>& args,
                                 const FunctionOptions* options, ExecContext* ctx) const;
 
   virtual Result<Datum> Execute(const ExecBatch& batch, const FunctionOptions* options,
                                 ExecContext* ctx) const;
 
   /// \brief Returns the default options for this function.
   ///
   /// Whatever option semantics a Function has, implementations must guarantee
   /// that default_options() is valid to pass to Execute as options.
   const FunctionOptions* default_options() const { return default_options_; }
 
   virtual Status Validate() const;
 
   /// \brief Returns the pure property for this function.
   ///
   /// Impure functions are those that may return different results for the same
   /// input arguments. For example, a function that returns a random number is
   /// not pure. An expression containing only pure functions can be simplified by
   /// pre-evaluating any sub-expressions that have constant arguments.
   virtual bool is_pure() const { return true; }
 
  protected:
   Function(std::string name, Function::Kind kind, const Arity& arity, FunctionDoc doc,
            const FunctionOptions* default_options)
       : name_(std::move(name)),
         kind_(kind),
         arity_(arity),
         doc_(std::move(doc)),
         default_options_(default_options) {}
 
   Status CheckArity(size_t num_args) const;
 
   std::string name_;
   Function::Kind kind_;
   Arity arity_;
   const FunctionDoc doc_;
   const FunctionOptions* default_options_ = NULLPTR;
 };
 
 namespace detail {
 
 template <typename KernelType>
 class FunctionImpl : public Function {
  public:
   /// \brief Return pointers to current-available kernels for inspection
   std::vector<const KernelType*> kernels() const {
     std::vector<const KernelType*> result;
     for (const auto& kernel : kernels_) {
       result.push_back(&kernel);
     }
     return result;
   }
 
   int num_kernels() const override { return static_cast<int>(kernels_.size()); }
 
  protected:
   FunctionImpl(std::string name, Function::Kind kind, const Arity& arity, FunctionDoc doc,
                const FunctionOptions* default_options)
       : Function(std::move(name), kind, arity, std::move(doc), default_options) {}
 
   std::vector<KernelType> kernels_;
 };
 
 /// \brief Look up a kernel in a function. If no Kernel is found, nullptr is returned.
 ARROW_EXPORT
 const Kernel* DispatchExactImpl(const Function* func, const std::vector<TypeHolder>&);
 
 /// \brief Return an error message if no Kernel is found.
 ARROW_EXPORT
 Status NoMatchingKernel(const Function* func, const std::vector<TypeHolder>&);
 
 }  // namespace detail
 
 /// \brief A function that executes elementwise operations on arrays or
 /// scalars, and therefore whose results generally do not depend on the order
 /// of the values in the arguments. Accepts and returns arrays that are all of
 /// the same size. These functions roughly correspond to the functions used in
 /// SQL expressions.
 class ARROW_EXPORT ScalarFunction : public detail::FunctionImpl<ScalarKernel> {
  public:
   using KernelType = ScalarKernel;
 
   ScalarFunction(std::string name, const Arity& arity, FunctionDoc doc,
                  const FunctionOptions* default_options = NULLPTR, bool is_pure = true)
       : detail::FunctionImpl<ScalarKernel>(std::move(name), Function::SCALAR, arity,
                                            std::move(doc), default_options),
         is_pure_(is_pure) {}
 
   /// \brief Add a kernel with given input/output types, no required state
   /// initialization, preallocation for fixed-width types, and default null
   /// handling (intersect validity bitmaps of inputs).
   Status AddKernel(std::vector<InputType> in_types, OutputType out_type,
                    ArrayKernelExec exec, KernelInit init = NULLPTR);
 
   /// \brief Add a kernel (function implementation). Returns error if the
   /// kernel's signature does not match the function's arity.
   Status AddKernel(ScalarKernel kernel);
 
   /// \brief Returns the pure property for this function.
   bool is_pure() const override { return is_pure_; }
 
  private:
   const bool is_pure_;
 };
 
 /// \brief A function that executes general array operations that may yield
 /// outputs of different sizes or have results that depend on the whole array
 /// contents. These functions roughly correspond to the functions found in
 /// non-SQL array languages like APL and its derivatives.
 class ARROW_EXPORT VectorFunction : public detail::FunctionImpl<VectorKernel> {
  public:
   using KernelType = VectorKernel;
 
   VectorFunction(std::string name, const Arity& arity, FunctionDoc doc,
                  const FunctionOptions* default_options = NULLPTR)
       : detail::FunctionImpl<VectorKernel>(std::move(name), Function::VECTOR, arity,
                                            std::move(doc), default_options) {}
 
   /// \brief Add a simple kernel with given input/output types, no required
   /// state initialization, no data preallocation, and no preallocation of the
   /// validity bitmap.
   Status AddKernel(std::vector<InputType> in_types, OutputType out_type,
                    ArrayKernelExec exec, KernelInit init = NULLPTR);
 
   /// \brief Add a kernel (function implementation). Returns error if the
   /// kernel's signature does not match the function's arity.
   Status AddKernel(VectorKernel kernel);
 };
 
 class ARROW_EXPORT ScalarAggregateFunction
     : public detail::FunctionImpl<ScalarAggregateKernel> {
  public:
   using KernelType = ScalarAggregateKernel;
 
   ScalarAggregateFunction(std::string name, const Arity& arity, FunctionDoc doc,
                           const FunctionOptions* default_options = NULLPTR)
       : detail::FunctionImpl<ScalarAggregateKernel>(std::move(name),
                                                     Function::SCALAR_AGGREGATE, arity,
                                                     std::move(doc), default_options) {}
 
   /// \brief Add a kernel (function implementation). Returns error if the
   /// kernel's signature does not match the function's arity.
   Status AddKernel(ScalarAggregateKernel kernel);
 };
 
 class ARROW_EXPORT HashAggregateFunction
     : public detail::FunctionImpl<HashAggregateKernel> {
  public:
   using KernelType = HashAggregateKernel;
 
   HashAggregateFunction(std::string name, const Arity& arity, FunctionDoc doc,
                         const FunctionOptions* default_options = NULLPTR)
       : detail::FunctionImpl<HashAggregateKernel>(std::move(name),
                                                   Function::HASH_AGGREGATE, arity,
                                                   std::move(doc), default_options) {}
 
   /// \brief Add a kernel (function implementation). Returns error if the
   /// kernel's signature does not match the function's arity.
   Status AddKernel(HashAggregateKernel kernel);
 };
 
 /// \brief A function that dispatches to other functions. Must implement
 /// MetaFunction::ExecuteImpl.
 ///
 /// For Array, ChunkedArray, and Scalar Datum kinds, may rely on the execution
 /// of concrete Function types, but must handle other Datum kinds on its own.
 class ARROW_EXPORT MetaFunction : public Function {
  public:
   int num_kernels() const override { return 0; }
 
   Result<Datum> Execute(const std::vector<Datum>& args, const FunctionOptions* options,
                         ExecContext* ctx) const override;
 
   Result<Datum> Execute(const ExecBatch& batch, const FunctionOptions* options,
                         ExecContext* ctx) const override;
 
  protected:
   virtual Result<Datum> ExecuteImpl(const std::vector<Datum>& args,
                                     const FunctionOptions* options,
                                     ExecContext* ctx) const = 0;
 
   MetaFunction(std::string name, const Arity& arity, FunctionDoc doc,
                const FunctionOptions* default_options = NULLPTR)
       : Function(std::move(name), Function::META, arity, std::move(doc),
                  default_options) {}
 };
 
 /// @}
 
 }  // namespace compute
 }  // namespace arrow

This page was automatically generated by the 2.3.7 LXR engine. The LXR team