FuncDispatcher
==============

.. cpp:class:: pandas::FuncDispatcher

   pandas C++ class.

Example
-------

.. code-block:: cpp

   #include <pandas/pandas.h>
   using namespace pandas;

   // Use FuncDispatcher
   FuncDispatcher obj;
   // ... operations ...

Other Methods
-------------

.. list-table::
   :widths: 40 20 15 25
   :header-rows: 1

   * - Signature
     - Return Type
     - Location
     - Example
   * - ``throw IncompatibleFuncArgError( "FuncDispatcher: no registered arm for FuncArg::kind=" + std::to_string(static_cast<int>(arg.kind)) + (arg.source_repr.empty() ? "" : (" (source: " + arg.source_repr + ")")))``
     - throw
     - pd_func_dispatch.h:489
     - :ref:`View <example-funcdispatcher-incompatiblefuncargerror-0>`
   * - ``Result call(const FuncArg& arg) const``
     - Result
     - pd_func_dispatch.h:448
     - :ref:`View <example-funcdispatcher-call-1>`
   * - ``FuncDispatcher& on_array(ArrayFn fn) { array_fn_ = std::move(fn)``
     - FuncDispatcher&
     - pd_func_dispatch.h:444
     - 
   * - ``FuncDispatcher& on_callable(CallableFn fn) { callable_fn_ = std::move(fn)``
     - FuncDispatcher&
     - pd_func_dispatch.h:438
     - :ref:`View <example-funcdispatcher-on_callable-2>`
   * - ``FuncDispatcher& on_callable_list(CallableListFn fn) { callable_list_fn_= std::move(fn)``
     - FuncDispatcher&
     - pd_func_dispatch.h:439
     - 
   * - ``FuncDispatcher& on_dict(DictFn fn) { dict_fn_ = std::move(fn)``
     - FuncDispatcher&
     - pd_func_dispatch.h:440
     - 
   * - ``FuncDispatcher& on_index(IndexFn fn) { index_fn_ = std::move(fn)``
     - FuncDispatcher&
     - pd_func_dispatch.h:443
     - 
   * - ``FuncDispatcher& on_named_agg(NamedAggFn fn) { named_agg_fn_ = std::move(fn)``
     - FuncDispatcher&
     - pd_func_dispatch.h:441
     - 
   * - ``FuncDispatcher& on_series(SeriesFn fn) { series_fn_ = std::move(fn)``
     - FuncDispatcher&
     - pd_func_dispatch.h:442
     - 
   * - ``FuncDispatcher& on_string(StringFn fn) { string_fn_ = std::move(fn)``
     - FuncDispatcher&
     - pd_func_dispatch.h:436
     - :ref:`View <example-funcdispatcher-on_string-3>`
   * - ``FuncDispatcher& on_string_list(StringListFn fn) { string_list_fn_ = std::move(fn)``
     - FuncDispatcher&
     - pd_func_dispatch.h:437
     - :ref:`View <example-funcdispatcher-on_string_list-4>`


Code Examples
-------------

The following examples are extracted from the test suite.

.. _example-funcdispatcher-incompatiblefuncargerror-0:

.. dropdown:: IncompatibleFuncArgError (pd_test_5_all.cpp:75705)
   :class-title: example-dropdown

   .. code-block:: cpp
      :linenos:
      :lineno-start: 75695
      :emphasize-lines: 11

              throw std::runtime_error("f_test_value_error_messages_3 failed");
          }
          std::cout << " -> tests passed" << std::endl;
      }
      
      // --- f_test_dispatch_sentinels_3.cpp ---
      
      namespace f_test_dispatch_sentinels_3_ns {
      
      static void dispatch_call_emulator(const std::string& method) {
          throw pandas::IncompatibleFuncArgError(
              std::string("FuncDispatcher::call: no registered implementation for '") + method + "'");
      }
      
      void case_1_exists_in_pd_exceptions_h() {
          std::cout << "----- case_1_exists_in_pd_exceptions_h -----\n";
          int local_fail = 0;
      
          bool caught_func = false;
          try {
              throw pandas::IncompatibleFuncArgError("from pd_exceptions.h");

.. _example-funcdispatcher-call-1:

.. dropdown:: call (pd_test_2_all.cpp:21645)
   :class-title: example-dropdown

   .. code-block:: cpp
      :linenos:
      :lineno-start: 21635
      :emphasize-lines: 11

              std::map<std::string, std::string> dtype_map = {};
              std::vector<int> parse_dates = {};
              bool parse_dates_bool = false;
              bool dayfirst = false;
              std::set<int> skiprows_set = {};
              std::vector<int> usecols_positions = {};
              std::vector<int> header_rows = {};
              std::vector<std::string> index_col_list = {};
              std::vector<int> index_col_pos_list = {};
      
              pandas::DataFrame call() const {
                  return pandas::DataFrame::read_csv(
                      data, sep, header, index_col, index_col_pos,
                      true, std::nullopt, "", "infer", {}, "", nullptr,
                      dayfirst, ".", false, "", true, dtype, "",
                      "utf-8", "strict", "", true, "",
                      false_values, true, false, false, false,
                      keep_default_na, lineterminator, true, false,
                      na_filter, na_values, names,
                      nrows, on_bad_lines, parse_dates, "\"", 0,
                      skip_blank_lines, std::nullopt, skipinitialspace,

.. _example-funcdispatcher-on_callable-2:

.. dropdown:: on_callable (pd_test_func_dispatch_5.cpp:114)
   :class-title: example-dropdown

   .. code-block:: cpp
      :linenos:
      :lineno-start: 104
      :emphasize-lines: 11

      }
      
      static void test_dispatcher_arms(int& fail) {
          pandas::FuncDispatcher disp;
          disp.on_string([](const std::string& name) {
              return pandas::Result::of_scalar(static_cast<std::int64_t>(name.size()));
          });
          disp.on_string_list([](const std::vector<std::string>& names) {
              return pandas::Result::of_scalar(static_cast<std::int64_t>(names.size()));
          });
          disp.on_callable([](const pandas::CallableHandle& h) {
              pandas::MapCellInput in;
              in.kind = pandas::MapCellInput::Float;
              in.f = 0.0;
              auto cell = h->invoke_cell(in);
              return pandas::Result::of_scalar(cell.f);
          });
      
          auto r1 = disp.call(pandas::FuncArg::from_string_name("sum"));
          pandas_tests::check(r1.is_scalar(), "string arm returns scalar", fail);
          pandas_tests::check(std::get<std::int64_t>(r1.value) == 3,

.. _example-funcdispatcher-on_string-3:

.. dropdown:: on_string (pd_test_5_all.cpp:113936)
   :class-title: example-dropdown

   .. code-block:: cpp
      :linenos:
      :lineno-start: 113926
      :emphasize-lines: 11

          std::cout << "-- case_H3_dispatch_with_axis_param\n";
          std::vector<pandas::FuncArg> inputs;  // empty -> empty frame
          pandas::Result r = pandas::concat_dispatch(inputs, /*axis=*/1, /*ignore_index=*/false);
          bool got = std::holds_alternative<std::unique_ptr<pandas::DataFrame>>(r.value);
          pandas_tests::check(got, "case_H3.empty_axis1_returns_dataframe", local_fail);
      }
      
      static void f_concat_dispatch_q3r4s5_case_H4_dispatcher_smoke(int& local_fail) {
          std::cout << "-- case_H4_dispatcher_smoke\n";
          pandas::FuncDispatcher disp;
          disp.on_string([](const std::string& name) -> pandas::Result {
              pandas::Result r;
              r.value = name + ":seen";
              return r;
          });
          auto fa = pandas::FuncArg::from_string_name("axis0");
          pandas::Result r = disp.call(fa);
          bool got_str = std::holds_alternative<std::string>(r.value);
          pandas_tests::check(got_str, "case_H4.dispatcher_returns_string", local_fail);
          if (got_str) {
              pandas_tests::check(std::get<std::string>(r.value) == "axis0:seen", "case_H4.value", local_fail);

.. _example-funcdispatcher-on_string_list-4:

.. dropdown:: on_string_list (pd_test_func_dispatch_5.cpp:111)
   :class-title: example-dropdown

   .. code-block:: cpp
      :linenos:
      :lineno-start: 101
      :emphasize-lines: 11

          auto fa5 = pandas::FuncArg::from_dict_spec(std::move(dict_specs));
          pandas_tests::check(fa5.kind == pandas::FuncArgKind::DictSpec,
                              "from_dict_spec -> DictSpec", fail);
      }
      
      static void test_dispatcher_arms(int& fail) {
          pandas::FuncDispatcher disp;
          disp.on_string([](const std::string& name) {
              return pandas::Result::of_scalar(static_cast<std::int64_t>(name.size()));
          });
          disp.on_string_list([](const std::vector<std::string>& names) {
              return pandas::Result::of_scalar(static_cast<std::int64_t>(names.size()));
          });
          disp.on_callable([](const pandas::CallableHandle& h) {
              pandas::MapCellInput in;
              in.kind = pandas::MapCellInput::Float;
              in.f = 0.0;
              auto cell = h->invoke_cell(in);
              return pandas::Result::of_scalar(cell.f);
          });