GH-48484: [GLib][Ruby] Add GArrowJoinOptions (#48485)

### Rationale for this change

The `JoinOptions` class is not available in GLib/Ruby, and it is used together with the `binary_join_element_wise` compute function.

### What changes are included in this PR?

This adds the `JoinOptions` class to GLib.

### Are these changes tested?

Yes, with Ruby unit tests.

### Are there any user-facing changes?

Yes, a new class.
* GitHub Issue: #48484

Authored-by: Sten Larsson <[email protected]>
Signed-off-by: Sutou Kouhei <[email protected]>

Author: stenlarsson

c_glib/arrow-glib/compute.cpp

@@ -273,6 +273,9 @@ G_BEGIN_DECLS
  * #GArrowExtractRegexSpanOptions is a class to customize the `extract_regex_span`
  * function.
  *
+ * #GArrowJoinOptions is a class to customize the `binary_join_element_wise`
+ * function.
+ *
  * There are many functions to compute data on an array.
  */
 
@@ -7278,6 +7281,125 @@ garrow_extract_regex_span_options_new(void)
   return GARROW_EXTRACT_REGEX_SPAN_OPTIONS(options);
 }
 
+enum {
+  PROP_JOIN_OPTIONS_NULL_HANDLING = 1,
+  PROP_JOIN_OPTIONS_NULL_REPLACEMENT,
+};
+
+G_DEFINE_TYPE(GArrowJoinOptions, garrow_join_options, GARROW_TYPE_FUNCTION_OPTIONS)
+
+static void
+garrow_join_options_set_property(GObject *object,
+                                 guint prop_id,
+                                 const GValue *value,
+                                 GParamSpec *pspec)
+{
+  auto options = garrow_join_options_get_raw(GARROW_JOIN_OPTIONS(object));
+
+  switch (prop_id) {
+  case PROP_JOIN_OPTIONS_NULL_HANDLING:
+    options->null_handling =
+      static_cast<arrow::compute::JoinOptions::NullHandlingBehavior>(
+        g_value_get_enum(value));
+    break;
+  case PROP_JOIN_OPTIONS_NULL_REPLACEMENT:
+    options->null_replacement = g_value_get_string(value);
+    break;
+  default:
+    G_OBJECT_WARN_INVALID_PROPERTY_ID(object, prop_id, pspec);
+    break;
+  }
+}
+
+static void
+garrow_join_options_get_property(GObject *object,
+                                 guint prop_id,
+                                 GValue *value,
+                                 GParamSpec *pspec)
+{
+  auto options = garrow_join_options_get_raw(GARROW_JOIN_OPTIONS(object));
+
+  switch (prop_id) {
+  case PROP_JOIN_OPTIONS_NULL_HANDLING:
+    g_value_set_enum(value,
+                     static_cast<GArrowJoinNullHandlingBehavior>(options->null_handling));
+    break;
+  case PROP_JOIN_OPTIONS_NULL_REPLACEMENT:
+    g_value_set_string(value, options->null_replacement.c_str());
+    break;
+  default:
+    G_OBJECT_WARN_INVALID_PROPERTY_ID(object, prop_id, pspec);
+    break;
+  }
+}
+
+static void
+garrow_join_options_init(GArrowJoinOptions *object)
+{
+  auto priv = GARROW_FUNCTION_OPTIONS_GET_PRIVATE(object);
+  priv->options =
+    static_cast<arrow::compute::FunctionOptions *>(new arrow::compute::JoinOptions());
+}
+
+static void
+garrow_join_options_class_init(GArrowJoinOptionsClass *klass)
+{
+  auto gobject_class = G_OBJECT_CLASS(klass);
+
+  gobject_class->set_property = garrow_join_options_set_property;
+  gobject_class->get_property = garrow_join_options_get_property;
+
+  arrow::compute::JoinOptions options;
+
+  GParamSpec *spec;
+  /**
+   * GArrowJoinOptions:null-handling:
+   *
+   * How to handle null values. (A null separator always results in a null output.)
+   *
+   * Since: 23.0.0
+   */
+  spec =
+    g_param_spec_enum("null-handling",
+                      "Null handling",
+                      "How to handle null values",
+                      GARROW_TYPE_JOIN_NULL_HANDLING_BEHAVIOR,
+                      static_cast<GArrowJoinNullHandlingBehavior>(options.null_handling),
+                      static_cast<GParamFlags>(G_PARAM_READWRITE));
+  g_object_class_install_property(gobject_class, PROP_JOIN_OPTIONS_NULL_HANDLING, spec);
+
+  /**
+   * GArrowJoinOptions:null-replacement:
+   *
+   * Replacement string for null values when null-handling is REPLACE.
+   *
+   * Since: 23.0.0
+   */
+  spec = g_param_spec_string(
+    "null-replacement",
+    "Null replacement",
+    "Replacement string for null values when null-handling is REPLACE",
+    options.null_replacement.c_str(),
+    static_cast<GParamFlags>(G_PARAM_READWRITE));
+  g_object_class_install_property(gobject_class,
+                                  PROP_JOIN_OPTIONS_NULL_REPLACEMENT,
+                                  spec);
+}
+
+/**
+ * garrow_join_options_new:
+ *
+ * Returns: A newly created #GArrowJoinOptions.
+ *
+ * Since: 23.0.0
+ */
+GArrowJoinOptions *
+garrow_join_options_new(void)
+{
+  auto options = g_object_new(GARROW_TYPE_JOIN_OPTIONS, nullptr);
+  return GARROW_JOIN_OPTIONS(options);
+}
+
 G_END_DECLS
 
 arrow::Result<arrow::FieldRef>
@@ -7447,6 +7569,11 @@ garrow_function_options_new_raw(const arrow::compute::FunctionOptions *arrow_opt
     auto options =
       garrow_extract_regex_span_options_new_raw(arrow_extract_regex_span_options);
     return GARROW_FUNCTION_OPTIONS(options);
+  } else if (arrow_type_name == "JoinOptions") {
+    const auto arrow_join_options =
+      static_cast<const arrow::compute::JoinOptions *>(arrow_options);
+    auto options = garrow_join_options_new_raw(arrow_join_options);
+    return GARROW_FUNCTION_OPTIONS(options);
   } else {
     auto options = g_object_new(GARROW_TYPE_FUNCTION_OPTIONS, NULL);
     return GARROW_FUNCTION_OPTIONS(options);
@@ -8104,3 +8231,22 @@ garrow_extract_regex_span_options_get_raw(GArrowExtractRegexSpanOptions *options
   return static_cast<arrow::compute::ExtractRegexSpanOptions *>(
     garrow_function_options_get_raw(GARROW_FUNCTION_OPTIONS(options)));
 }
+
+GArrowJoinOptions *
+garrow_join_options_new_raw(const arrow::compute::JoinOptions *arrow_options)
+{
+  return GARROW_JOIN_OPTIONS(g_object_new(
+    GARROW_TYPE_JOIN_OPTIONS,
+    "null-handling",
+    static_cast<GArrowJoinNullHandlingBehavior>(arrow_options->null_handling),
+    "null-replacement",
+    arrow_options->null_replacement.c_str(),
+    nullptr));
+}
+
+arrow::compute::JoinOptions *
+garrow_join_options_get_raw(GArrowJoinOptions *options)
+{
+  return static_cast<arrow::compute::JoinOptions *>(
+    garrow_function_options_get_raw(GARROW_FUNCTION_OPTIONS(options)));
+}

c_glib/arrow-glib/compute.h

@@ -1290,4 +1290,36 @@ GARROW_AVAILABLE_IN_23_0
 GArrowExtractRegexSpanOptions *
 garrow_extract_regex_span_options_new(void);
 
+/**
+ * GArrowJoinNullHandlingBehavior:
+ * @GARROW_JOIN_NULL_HANDLING_EMIT_NULL: A null in any input results in a null in the
+ * output.
+ * @GARROW_JOIN_NULL_HANDLING_SKIP: Nulls in inputs are skipped.
+ * @GARROW_JOIN_NULL_HANDLING_REPLACE: Nulls in inputs are replaced with the replacement
+ * string.
+ *
+ * They correspond to the values of
+ * `arrow::compute::JoinOptions::NullHandlingBehavior`.
+ *
+ * Since: 23.0.0
+ */
+typedef enum {
+  GARROW_JOIN_NULL_HANDLING_EMIT_NULL,
+  GARROW_JOIN_NULL_HANDLING_SKIP,
+  GARROW_JOIN_NULL_HANDLING_REPLACE,
+} GArrowJoinNullHandlingBehavior;
+
+#define GARROW_TYPE_JOIN_OPTIONS (garrow_join_options_get_type())
+GARROW_AVAILABLE_IN_23_0
+G_DECLARE_DERIVABLE_TYPE(
+  GArrowJoinOptions, garrow_join_options, GARROW, JOIN_OPTIONS, GArrowFunctionOptions)
+struct _GArrowJoinOptionsClass
+{
+  GArrowFunctionOptionsClass parent_class;
+};
+
+GARROW_AVAILABLE_IN_23_0
+GArrowJoinOptions *
+garrow_join_options_new(void);
+
 G_END_DECLS

c_glib/arrow-glib/compute.hpp

@@ -215,3 +215,8 @@ garrow_extract_regex_span_options_new_raw(
   const arrow::compute::ExtractRegexSpanOptions *arrow_options);
 arrow::compute::ExtractRegexSpanOptions *
 garrow_extract_regex_span_options_get_raw(GArrowExtractRegexSpanOptions *options);
+
+GArrowJoinOptions *
+garrow_join_options_new_raw(const arrow::compute::JoinOptions *arrow_options);
+arrow::compute::JoinOptions *
+garrow_join_options_get_raw(GArrowJoinOptions *options);

c_glib/test/test-join-options.rb

@@ -0,0 +1,63 @@
+# 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 TestJoinOptions < Test::Unit::TestCase
+  include Helper::Buildable
+
+  def setup
+    @options = Arrow::JoinOptions.new
+  end
+
+  def test_null_handling_property
+    assert_equal(Arrow::JoinNullHandlingBehavior::EMIT_NULL, @options.null_handling)
+    @options.null_handling = :skip
+    assert_equal(Arrow::JoinNullHandlingBehavior::SKIP, @options.null_handling)
+    @options.null_handling = :replace
+    assert_equal(Arrow::JoinNullHandlingBehavior::REPLACE, @options.null_handling)
+  end
+
+  def test_null_replacement_property
+    assert_equal("", @options.null_replacement)
+    @options.null_replacement = "NULL"
+    assert_equal("NULL", @options.null_replacement)
+  end
+
+  def test_binary_join_element_wise_function
+    args = [
+      Arrow::ArrayDatum.new(build_string_array(["a", "b", nil])),
+      Arrow::ArrayDatum.new(build_string_array(["x", "y", "z"])),
+      Arrow::ScalarDatum.new(Arrow::StringScalar.new(Arrow::Buffer.new("-"))),
+    ]
+    binary_join_element_wise_function = Arrow::Function.find("binary_join_element_wise")
+
+    @options.null_handling = :emit_null
+    result = binary_join_element_wise_function.execute(args, @options).value
+    assert_equal(build_string_array(["a-x", "b-y", nil]),
+                 result)
+
+    @options.null_handling = :skip
+    result = binary_join_element_wise_function.execute(args, @options).value
+    assert_equal(build_string_array(["a-x", "b-y", "z"]),
+                 result)
+
+    @options.null_handling = :replace
+    @options.null_replacement = "NULL"
+    result = binary_join_element_wise_function.execute(args, @options).value
+    assert_equal(build_string_array(["a-x", "b-y", "NULL-z"]),
+                 result)
+  end
+end