FillValue
=========

.. cpp:class:: pandas::FillValue

   pandas C++ class.

Example
-------

.. code-block:: cpp

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

   // Use FillValue
   FillValue obj;
   // ... operations ...

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

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

   * - Signature
     - Return Type
     - Location
     - Example
   * - ``static FillValue na()``
     - static FillValue
     - pd_func_dispatch.h:329
     - :ref:`View <example-fillvalue-na-0>`
   * - ``static FillValue nan()``
     - static FillValue
     - pd_func_dispatch.h:328
     - :ref:`View <example-fillvalue-nan-1>`
   * - ``static FillValue nat()``
     - static FillValue
     - pd_func_dispatch.h:330
     - :ref:`View <example-fillvalue-nat-2>`
   * - ``static FillValue none()``
     - static FillValue
     - pd_func_dispatch.h:331
     - :ref:`View <example-fillvalue-none-3>`
   * - ``static FillValue of_bool(bool v)``
     - static FillValue
     - pd_func_dispatch.h:324
     - :ref:`View <example-fillvalue-of_bool-4>`
   * - ``static FillValue of_numeric(double v)``
     - static FillValue
     - pd_func_dispatch.h:318
     - :ref:`View <example-fillvalue-of_numeric-5>`
   * - ``static FillValue of_numeric_int(double v)``
     - static FillValue
     - pd_func_dispatch.h:323
     - :ref:`View <example-fillvalue-of_numeric_int-6>`
   * - ``static FillValue of_string(std::string v) { FillValue fv``
     - static FillValue
     - pd_func_dispatch.h:325
     - :ref:`View <example-fillvalue-of_string-7>`
   * - ``static FillValue of_timedelta_ns(std::int64_t v)``
     - static FillValue
     - pd_func_dispatch.h:327
     - :ref:`View <example-fillvalue-of_timedelta_ns-8>`
   * - ``static FillValue of_timestamp_ns(std::int64_t v)``
     - static FillValue
     - pd_func_dispatch.h:326
     - :ref:`View <example-fillvalue-of_timestamp_ns-9>`


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

The following examples are extracted from the test suite.

.. _example-fillvalue-na-0:

.. dropdown:: na (pd_test_1_all.cpp:84)
   :class-title: example-dropdown

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

          void pd_test_boolean_array_kleene_and() {
              std::cout << "========= BooleanArray: Kleene AND ======================= ";
      
              // Kleene AND truth table:
              // T & T = T, T & F = F, T & NA = NA
              // F & T = F, F & F = F, F & NA = F (False dominates)
              // NA & T = NA, NA & F = F, NA & NA = NA
      
              pandas::BooleanArray t({std::optional<bool>(true)});
              pandas::BooleanArray f({std::optional<bool>(false)});
              pandas::BooleanArray na({std::nullopt});
      
              // T & T = T
              auto tt = (t & t);
              if (!tt[0].has_value() || !tt[0].value()) {
                  std::cout << "  [FAIL] : in pd_test_boolean_array_kleene_and() : T & T should be T" << std::endl;
                  throw std::runtime_error("pd_test_boolean_array_kleene_and failed: T & T");
              }
      
              // T & F = F
              auto tf = (t & f);

.. _example-fillvalue-nan-1:

.. dropdown:: nan (pd_test_1_all.cpp:1556)
   :class-title: example-dropdown

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

      
              std::cout << " -> tests passed" << std::endl;
          }
      
          void pd_test_floating_array_nan_conversion() {
              std::cout << "========= FloatingArray: NaN to NA conversion ======================= ";
      
              // NaN values should be automatically converted to NA
              pandas::FloatingArray<double> arr({
                  std::optional<double>(1.0),
                  std::optional<double>(std::nan("")),  // NaN
                  std::optional<double>(3.0)
              });
      
              if (!arr.is_na(1)) {
                  std::cout << "  [FAIL] : in pd_test_floating_array_nan_conversion() : NaN should be converted to NA" << std::endl;
                  throw std::runtime_error("pd_test_floating_array_nan_conversion failed: NaN should be NA");
              }
      
              if (arr.is_na(0) || arr.is_na(2)) {
                  std::cout << "  [FAIL] : in pd_test_floating_array_nan_conversion() : non-NaN should not be NA" << std::endl;

.. _example-fillvalue-nat-2:

.. dropdown:: nat (pd_test_5_all.cpp:97717)
   :class-title: example-dropdown

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

          std::string result_override;
          std::string variant_label;
      };
      
      static pandas::FillValue fv_none()         { return pandas::FillValue::none(); }
      
      static pandas::FillValue fv_nan()          { return pandas::FillValue::nan(); }
      
      static pandas::FillValue fv_na()           { return pandas::FillValue::na(); }
      
      static pandas::FillValue fv_nat()          { return pandas::FillValue::nat(); }
      
      static pandas::FillValue fv_bool_false()   { return pandas::FillValue::of_bool(false); }
      
      static pandas::FillValue fv_num_zero()     { return pandas::FillValue::of_numeric(0.0); }
      
      static pandas::FillValue fv_string_x()     { return pandas::FillValue::of_string("x"); }
      
      static Probe probe_result(pandas::Result& r) {
          Probe p;
          std::visit([&](auto& alt) {

.. _example-fillvalue-none-3:

.. dropdown:: none (pd_test_5_all.cpp:90413)
   :class-title: example-dropdown

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

                                          pandas::FillValue::of_bool(true));
              (void)r;
          }, local_fail);
      }
      
      static void f_20_847312_dispatch_complex_none(int& local_fail) {
          std::cout << "-- f_20_847312_dispatch_complex_none\n";
          expect_value_error_duplicate("c12_dispatch_complex_none", [] {
              auto s = make_series<cplx>({{1, 2}, {3, 4}, {5, 6}}, {"c1", "c1", "c2"});
              auto r = s.reindex_dispatch({"c1", "c2", "c3"}, "",
                                          pandas::FillValue::none());
              (void)r;
          }, local_fail);
      }
      
      static void f_20_847313_df_dup_rows_axis0(int& local_fail) {
          std::cout << "-- f_20_847313_df_dup_rows_axis0\n";
          expect_value_error_duplicate("c13_df_dup_rows_axis0", [] {
              std::vector<pandas::Series<std::int64_t>> cols;
              cols.emplace_back(std::vector<std::int64_t>{10, 20, 30});
              cols.emplace_back(std::vector<std::int64_t>{40, 50, 60});

.. _example-fillvalue-of_bool-4:

.. dropdown:: of_bool (pd_test_5_all.cpp:90403)
   :class-title: example-dropdown

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

                                          pandas::FillValue::of_numeric(nan));
              (void)r;
          }, local_fail);
      }
      
      static void f_20_847311_dispatch_int64_bool_fill(int& local_fail) {
          std::cout << "-- f_20_847311_dispatch_int64_bool_fill\n";
          expect_value_error_duplicate("c11_dispatch_int64_bool", [] {
              auto s = make_series<std::int64_t>({1, 2, 3}, {"a", "a", "b"});
              auto r = s.reindex_dispatch({"a", "b", "c"}, "",
                                          pandas::FillValue::of_bool(true));
              (void)r;
          }, local_fail);
      }
      
      static void f_20_847312_dispatch_complex_none(int& local_fail) {
          std::cout << "-- f_20_847312_dispatch_complex_none\n";
          expect_value_error_duplicate("c12_dispatch_complex_none", [] {
              auto s = make_series<cplx>({{1, 2}, {3, 4}, {5, 6}}, {"c1", "c1", "c2"});
              auto r = s.reindex_dispatch({"c1", "c2", "c3"}, "",
                                          pandas::FillValue::none());

.. _example-fillvalue-of_numeric-5:

.. dropdown:: of_numeric (pd_test_5_all.cpp:61047)
   :class-title: example-dropdown

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

          return out;
      }
      
      template <typename T>
      static std::pair<std::string, std::string>
      run_numeric_fill_lt29(const std::vector<T>& vals,
                            const std::vector<std::string>& new_idx,
                            double fill) {
          auto s = make_series_with_idx_lt29<T>(vals, src_idx_for_lt29(vals.size()));
          pandas::Result r = s.reindex_dispatch(
              new_idx, "", pandas::FillValue::of_numeric(fill));
      
          if (std::holds_alternative<
                  std::unique_ptr<pandas::Series<std::string>>>(r.value)) {
              auto& sp = std::get<
                  std::unique_ptr<pandas::Series<std::string>>>(r.value);
              auto df = sp->to_frame(std::optional<std::string>("v"));
              auto dts = df.dtypes();
              return {df.to_string(),
                      dts.empty() ? std::string("<no col>") : dts[0]};
          }

.. _example-fillvalue-of_numeric_int-6:

.. dropdown:: of_numeric_int (pd_test_5_all.cpp:97549)
   :class-title: example-dropdown

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

          // Nullable string EA — preserve.
          if (src == "string" || src.rfind("string[", 0) == 0)
              return std::string(src);
      
          // Fallback.
          return "object";
      }
      
      static std::vector<FillSpec> all_fills() {
          std::vector<FillSpec> v;
          v.push_back({"pi_0",    pandas::FillValue::of_numeric_int(0.0)});
          v.push_back({"pi_1",    pandas::FillValue::of_numeric_int(1.0)});
          v.push_back({"pi_neg5", pandas::FillValue::of_numeric_int(-5.0)});
          v.push_back({"pi_42",   pandas::FillValue::of_numeric_int(42.0)});
          v.push_back({"pf_0p0",  pandas::FillValue::of_numeric(0.0)});
          v.push_back({"pf_1p0",  pandas::FillValue::of_numeric(1.0)});
          v.push_back({"pf_neg5p0", pandas::FillValue::of_numeric(-5.0)});
          v.push_back({"pf_0p5",  pandas::FillValue::of_numeric(0.5)});
          v.push_back({"pf_1p5",  pandas::FillValue::of_numeric(1.5)});
          v.push_back({"pf_nan",  pandas::FillValue::of_numeric(std::numeric_limits<double>::quiet_NaN())});
          v.push_back({"pf_pinf", pandas::FillValue::of_numeric(std::numeric_limits<double>::infinity())});

.. _example-fillvalue-of_string-7:

.. dropdown:: of_string (pd_test_5_all.cpp:93146)
   :class-title: example-dropdown

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

              local_fail);
          char k = pandas::cell_to_dtype_kind(r);
          pandas_tests::check(k == 'b',
              "C_26_apply_cell_result_case_3_of_bool()_dtype_kind",
              local_fail);
          if (k != 'b') std::cout << "  got=[" << k << "] expected=[b]\n";
      }
      
      void case_4_of_string(int& local_fail) {
          std::cout << "-- case_4_of_string\n";
          pandas::ApplyCellResult r = pandas::ApplyCellResult::of_string(
              std::string("hello"));
          pandas_tests::check(r.kind == pandas::ApplyCellResult::Kind::String,
              "C_26_apply_cell_result_case_4_of_string()_kind",
              local_fail);
          pandas_tests::check(r.s == "hello",
              "C_26_apply_cell_result_case_4_of_string()_payload",
              local_fail);
          char k = pandas::cell_to_dtype_kind(r);
          pandas_tests::check(k == 'O',
              "C_26_apply_cell_result_case_4_of_string()_dtype_kind",

.. _example-fillvalue-of_timedelta_ns-8:

.. dropdown:: of_timedelta_ns (pd_test_5_all.cpp:93186)
   :class-title: example-dropdown

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

              "C_26_apply_cell_result_case_5_of_timestamp_ns()_dtype_kind",
              local_fail);
          if (k != 'M') std::cout << "  got=[" << k << "] expected=[M]\n";
      }
      
      void case_6_of_timedelta_ns(int& local_fail) {
          std::cout << "-- case_6_of_timedelta_ns\n";
          const int64_t ns = static_cast<int64_t>(86400) *
                             static_cast<int64_t>(1000000000);  // 1 day
          pandas::ApplyCellResult r =
              pandas::ApplyCellResult::of_timedelta_ns(ns);
          pandas_tests::check(
              r.kind == pandas::ApplyCellResult::Kind::Timedelta_ns,
              "C_26_apply_cell_result_case_6_of_timedelta_ns()_kind",
              local_fail);
          pandas_tests::check(r.td_ns == ns,
              "C_26_apply_cell_result_case_6_of_timedelta_ns()_payload",
              local_fail);
          char k = pandas::cell_to_dtype_kind(r);
          pandas_tests::check(k == 'm',
              "C_26_apply_cell_result_case_6_of_timedelta_ns()_dtype_kind",

.. _example-fillvalue-of_timestamp_ns-9:

.. dropdown:: of_timestamp_ns (pd_test_5_all.cpp:93166)
   :class-title: example-dropdown

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

              "C_26_apply_cell_result_case_4_of_string()_dtype_kind",
              local_fail);
          if (k != 'O') std::cout << "  got=[" << k << "] expected=[O]\n";
      }
      
      void case_5_of_timestamp_ns(int& local_fail) {
          std::cout << "-- case_5_of_timestamp_ns\n";
          const int64_t ns = static_cast<int64_t>(1700000000) *
                             static_cast<int64_t>(1000000000);
          pandas::ApplyCellResult r =
              pandas::ApplyCellResult::of_timestamp_ns(ns);
          pandas_tests::check(
              r.kind == pandas::ApplyCellResult::Kind::Timestamp_ns,
              "C_26_apply_cell_result_case_5_of_timestamp_ns()_kind",
              local_fail);
          pandas_tests::check(r.ts_ns == ns,
              "C_26_apply_cell_result_case_5_of_timestamp_ns()_payload",
              local_fail);
          char k = pandas::cell_to_dtype_kind(r);
          pandas_tests::check(k == 'M',
              "C_26_apply_cell_result_case_5_of_timestamp_ns()_dtype_kind",