GH-48492: [GLib][Ruby] Add MapLookupOptions (#48513)

stenlarsson · web-flow · commit 5fbefaea0093 · 2025-12-22T09:58:19.000+09:00
### Rationale for this change The `MapLookupOptions` class is not available in GLib/Ruby, and it is used together with the `map_lookup` compute function. ### What changes are included in this PR? This adds the `MapLookupOptions` class to GLib. ### Are these changes tested? Yes, with Ruby unit tests. ### Are there any user-facing changes? Yes, a new class. * GitHub Issue: #48492 Authored-by: Sten Larsson <sten@burtcorp.com> Signed-off-by: Sutou Kouhei <kou@clear-code.com>
diff --git a/c_glib/arrow-glib/compute.cpp b/c_glib/arrow-glib/compute.cpp
@@ -279,6 +279,9 @@ G_BEGIN_DECLS
  * #GArrowListFlattenOptions is a class to customize the `list_flatten`
  * function.
  *
+ * #GArrowMapLookupOptions is a class to customize the `map_lookup`
+ * function.
+ *
  * There are many functions to compute data on an array.
  */
 
@@ -7498,6 +7501,169 @@ garrow_list_flatten_options_new(void)
   return GARROW_LIST_FLATTEN_OPTIONS(options);
 }
 
+typedef struct GArrowMapLookupOptionsPrivate_
+{
+  GArrowScalar *query_key;
+} GArrowMapLookupOptionsPrivate;
+
+enum {
+  PROP_MAP_LOOKUP_OPTIONS_QUERY_KEY = 1,
+  PROP_MAP_LOOKUP_OPTIONS_OCCURRENCE,
+};
+
+G_DEFINE_TYPE_WITH_PRIVATE(GArrowMapLookupOptions,
+                           garrow_map_lookup_options,
+                           GARROW_TYPE_FUNCTION_OPTIONS)
+
+#define GARROW_MAP_LOOKUP_OPTIONS_GET_PRIVATE(object)                                    \
+  static_cast<GArrowMapLookupOptionsPrivate *>(                                          \
+    garrow_map_lookup_options_get_instance_private(GARROW_MAP_LOOKUP_OPTIONS(object)))
+
+static void
+garrow_map_lookup_options_dispose(GObject *object)
+{
+  auto priv = GARROW_MAP_LOOKUP_OPTIONS_GET_PRIVATE(object);
+
+  if (priv->query_key) {
+    g_object_unref(priv->query_key);
+    priv->query_key = NULL;
+  }
+
+  G_OBJECT_CLASS(garrow_map_lookup_options_parent_class)->dispose(object);
+}
+
+static void
+garrow_map_lookup_options_set_property(GObject *object,
+                                       guint prop_id,
+                                       const GValue *value,
+                                       GParamSpec *pspec)
+{
+  auto priv = GARROW_MAP_LOOKUP_OPTIONS_GET_PRIVATE(object);
+  auto options = garrow_map_lookup_options_get_raw(GARROW_MAP_LOOKUP_OPTIONS(object));
+
+  switch (prop_id) {
+  case PROP_MAP_LOOKUP_OPTIONS_QUERY_KEY:
+    {
+      auto query_key = g_value_get_object(value);
+      if (priv->query_key != query_key) {
+        if (priv->query_key) {
+          g_object_unref(priv->query_key);
+        }
+        priv->query_key = GARROW_SCALAR(query_key);
+        if (priv->query_key) {
+          g_object_ref(priv->query_key);
+          options->query_key = garrow_scalar_get_raw(priv->query_key);
+        } else {
+          options->query_key = nullptr;
+        }
+      }
+    }
+    break;
+  case PROP_MAP_LOOKUP_OPTIONS_OCCURRENCE:
+    options->occurrence =
+      static_cast<arrow::compute::MapLookupOptions::Occurrence>(g_value_get_enum(value));
+    break;
+  default:
+    G_OBJECT_WARN_INVALID_PROPERTY_ID(object, prop_id, pspec);
+    break;
+  }
+}
+
+static void
+garrow_map_lookup_options_get_property(GObject *object,
+                                       guint prop_id,
+                                       GValue *value,
+                                       GParamSpec *pspec)
+{
+  auto priv = GARROW_MAP_LOOKUP_OPTIONS_GET_PRIVATE(object);
+  auto options = garrow_map_lookup_options_get_raw(GARROW_MAP_LOOKUP_OPTIONS(object));
+
+  switch (prop_id) {
+  case PROP_MAP_LOOKUP_OPTIONS_QUERY_KEY:
+    g_value_set_object(value, priv->query_key);
+    break;
+  case PROP_MAP_LOOKUP_OPTIONS_OCCURRENCE:
+    g_value_set_enum(value, static_cast<GArrowMapLookupOccurrence>(options->occurrence));
+    break;
+  default:
+    G_OBJECT_WARN_INVALID_PROPERTY_ID(object, prop_id, pspec);
+    break;
+  }
+}
+
+static void
+garrow_map_lookup_options_init(GArrowMapLookupOptions *object)
+{
+  auto priv = GARROW_FUNCTION_OPTIONS_GET_PRIVATE(object);
+  priv->options = static_cast<arrow::compute::FunctionOptions *>(
+    new arrow::compute::MapLookupOptions());
+}
+
+static void
+garrow_map_lookup_options_class_init(GArrowMapLookupOptionsClass *klass)
+{
+  auto gobject_class = G_OBJECT_CLASS(klass);
+
+  gobject_class->dispose = garrow_map_lookup_options_dispose;
+  gobject_class->set_property = garrow_map_lookup_options_set_property;
+  gobject_class->get_property = garrow_map_lookup_options_get_property;
+
+  arrow::compute::MapLookupOptions options;
+
+  GParamSpec *spec;
+  /**
+   * GArrowMapLookupOptions:query-key:
+   *
+   * The key to lookup in the map.
+   *
+   * Since: 23.0.0
+   */
+  spec = g_param_spec_object("query-key",
+                             "Query key",
+                             "The key to lookup in the map",
+                             GARROW_TYPE_SCALAR,
+                             static_cast<GParamFlags>(G_PARAM_READWRITE));
+  g_object_class_install_property(gobject_class, PROP_MAP_LOOKUP_OPTIONS_QUERY_KEY, spec);
+
+  /**
+   * GArrowMapLookupOptions:occurrence:
+   *
+   * Whether to return the first, last, or all matching values.
+   *
+   * Since: 23.0.0
+   */
+  spec = g_param_spec_enum("occurrence",
+                           "Occurrence",
+                           "Whether to return the first, last, or all matching values",
+                           GARROW_TYPE_MAP_LOOKUP_OCCURRENCE,
+                           static_cast<GArrowMapLookupOccurrence>(options.occurrence),
+                           static_cast<GParamFlags>(G_PARAM_READWRITE));
+  g_object_class_install_property(gobject_class,
+                                  PROP_MAP_LOOKUP_OPTIONS_OCCURRENCE,
+                                  spec);
+}
+
+/**
+ * garrow_map_lookup_options_new:
+ * @query_key: (nullable): A #GArrowScalar to be looked up.
+ * @occurrence: A #GArrowMapLookupOccurrence.
+ *
+ * Returns: A newly created #GArrowMapLookupOptions.
+ *
+ * Since: 23.0.0
+ */
+GArrowMapLookupOptions *
+garrow_map_lookup_options_new(GArrowScalar *query_key,
+                              GArrowMapLookupOccurrence occurrence)
+{
+  return GARROW_MAP_LOOKUP_OPTIONS(g_object_new(GARROW_TYPE_MAP_LOOKUP_OPTIONS,
+                                                "query-key",
+                                                query_key,
+                                                "occurrence",
+                                                occurrence,
+                                                NULL));
+}
+
 G_END_DECLS
 
 arrow::Result<arrow::FieldRef>
@@ -7677,6 +7843,11 @@ garrow_function_options_new_raw(const arrow::compute::FunctionOptions *arrow_opt
       static_cast<const arrow::compute::ListFlattenOptions *>(arrow_options);
     auto options = garrow_list_flatten_options_new_raw(arrow_list_flatten_options);
     return GARROW_FUNCTION_OPTIONS(options);
+  } else if (arrow_type_name == "MapLookupOptions") {
+    const auto arrow_map_lookup_options =
+      static_cast<const arrow::compute::MapLookupOptions *>(arrow_options);
+    auto options = garrow_map_lookup_options_new_raw(arrow_map_lookup_options);
+    return GARROW_FUNCTION_OPTIONS(options);
   } else {
     auto options = g_object_new(GARROW_TYPE_FUNCTION_OPTIONS, NULL);
     return GARROW_FUNCTION_OPTIONS(options);
@@ -8370,3 +8541,28 @@ garrow_list_flatten_options_get_raw(GArrowListFlattenOptions *options)
   return static_cast<arrow::compute::ListFlattenOptions *>(
     garrow_function_options_get_raw(GARROW_FUNCTION_OPTIONS(options)));
 }
+
+GArrowMapLookupOptions *
+garrow_map_lookup_options_new_raw(const arrow::compute::MapLookupOptions *arrow_options)
+{
+  GArrowScalar *query_key = nullptr;
+  if (arrow_options->query_key) {
+    auto arrow_query_key = arrow_options->query_key;
+    query_key = garrow_scalar_new_raw(&arrow_query_key);
+  }
+  GArrowMapLookupOccurrence occurrence =
+    static_cast<GArrowMapLookupOccurrence>(arrow_options->occurrence);
+  return GARROW_MAP_LOOKUP_OPTIONS(g_object_new(GARROW_TYPE_MAP_LOOKUP_OPTIONS,
+                                                "query-key",
+                                                query_key,
+                                                "occurrence",
+                                                occurrence,
+                                                NULL));
+}
+
+arrow::compute::MapLookupOptions *
+garrow_map_lookup_options_get_raw(GArrowMapLookupOptions *options)
+{
+  return static_cast<arrow::compute::MapLookupOptions *>(
+    garrow_function_options_get_raw(GARROW_FUNCTION_OPTIONS(options)));
+}
diff --git a/c_glib/arrow-glib/compute.h b/c_glib/arrow-glib/compute.h
@@ -1338,4 +1338,38 @@ GARROW_AVAILABLE_IN_23_0
 GArrowListFlattenOptions *
 garrow_list_flatten_options_new(void);
 
+/**
+ * GArrowMapLookupOccurrence:
+ * @GARROW_MAP_LOOKUP_OCCURRENCE_FIRST: Return the first matching value.
+ * @GARROW_MAP_LOOKUP_OCCURRENCE_LAST: Return the last matching value.
+ * @GARROW_MAP_LOOKUP_OCCURRENCE_ALL: Return all matching values.
+ *
+ * They correspond to the values of
+ * `arrow::compute::MapLookupOptions::Occurrence`.
+ *
+ * Since: 23.0.0
+ */
+typedef enum {
+  GARROW_MAP_LOOKUP_OCCURRENCE_FIRST,
+  GARROW_MAP_LOOKUP_OCCURRENCE_LAST,
+  GARROW_MAP_LOOKUP_OCCURRENCE_ALL,
+} GArrowMapLookupOccurrence;
+
+#define GARROW_TYPE_MAP_LOOKUP_OPTIONS (garrow_map_lookup_options_get_type())
+GARROW_AVAILABLE_IN_23_0
+G_DECLARE_DERIVABLE_TYPE(GArrowMapLookupOptions,
+                         garrow_map_lookup_options,
+                         GARROW,
+                         MAP_LOOKUP_OPTIONS,
+                         GArrowFunctionOptions)
+struct _GArrowMapLookupOptionsClass
+{
+  GArrowFunctionOptionsClass parent_class;
+};
+
+GARROW_AVAILABLE_IN_23_0
+GArrowMapLookupOptions *
+garrow_map_lookup_options_new(GArrowScalar *query_key,
+                              GArrowMapLookupOccurrence occurrence);
+
 G_END_DECLS
diff --git a/c_glib/arrow-glib/compute.hpp b/c_glib/arrow-glib/compute.hpp
@@ -226,3 +226,8 @@ garrow_list_flatten_options_new_raw(
   const arrow::compute::ListFlattenOptions *arrow_options);
 arrow::compute::ListFlattenOptions *
 garrow_list_flatten_options_get_raw(GArrowListFlattenOptions *options);
+
+GArrowMapLookupOptions *
+garrow_map_lookup_options_new_raw(const arrow::compute::MapLookupOptions *arrow_options);
+arrow::compute::MapLookupOptions *
+garrow_map_lookup_options_get_raw(GArrowMapLookupOptions *options);
diff --git a/c_glib/test/test-map-lookup-options.rb b/c_glib/test/test-map-lookup-options.rb
@@ -0,0 +1,73 @@
+# 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.
+
+class TestMapLookupOptions < Test::Unit::TestCase
+  include Helper::Buildable
+
+  def setup
+    @query_key = Arrow::Int32Scalar.new(1)
+    @options = Arrow::MapLookupOptions.new(@query_key,
+                                           Arrow::MapLookupOccurrence::FIRST)
+  end
+
+  def test_query_key_property
+    assert_equal(@query_key, @options.query_key)
+    new_query_key = Arrow::Int32Scalar.new(2)
+    @options.query_key = new_query_key
+    assert_equal(new_query_key, @options.query_key)
+  end
+
+  def test_occurrence_property
+    assert_equal(Arrow::MapLookupOccurrence::FIRST, @options.occurrence)
+    @options.occurrence = :last
+    assert_equal(Arrow::MapLookupOccurrence::LAST, @options.occurrence)
+    @options.occurrence = :all
+    assert_equal(Arrow::MapLookupOccurrence::ALL, @options.occurrence)
+    @options.occurrence = :first
+    assert_equal(Arrow::MapLookupOccurrence::FIRST, @options.occurrence)
+  end
+
+  def test_map_lookup_function
+    map_array = build_map_array(Arrow::Int32DataType.new,
+                                Arrow::StringDataType.new,
+                                [[
+                                  [1, "first_one"],
+                                  [2, "two"],
+                                  [1, nil],
+                                  [3, "three"],
+                                  [1, "second_one"],
+                                  [1, "last_one"],
+                                ]])
+    args = [Arrow::ArrayDatum.new(map_array)]
+    map_lookup_function = Arrow::Function.find("map_lookup")
+    @options.query_key = Arrow::Int32Scalar.new(1)
+
+    @options.occurrence = :first
+    result = map_lookup_function.execute(args, @options).value
+    assert_equal(build_string_array(["first_one"]), result)
+
+    @options.occurrence = :last
+    result = map_lookup_function.execute(args, @options).value
+    assert_equal(build_string_array(["last_one"]), result)
+
+    @options.occurrence = :all
+    result = map_lookup_function.execute(args, @options).value
+    assert_equal(build_list_array(Arrow::StringDataType.new,
+                                  [["first_one", nil, "second_one", "last_one"]]),
+                 result)
+  end
+end
