stride-align 0.6.0

data/ext/stride_align/backend_impl.hpp

@@ -0,0 +1,983 @@
+#pragma once
+
+#include <algorithm>
+#include <array>
+#include <cmath>
+#include <cstddef>
+#include <cstdint>
+#include <cstdio>
+#include <limits>
+#include <optional>
+#include <span>
+#include <stdexcept>
+#include <string>
+#include <string_view>
+#include <unordered_map>
+#include <utility>
+#include <vector>
+
+#include <ruby.h>
+#include <ruby/encoding.h>
+
+// Ruby 2.6's compatibility header defines these C99 names as macros.  They
+// otherwise rewrite qualified C++ calls such as std::isfinite.
+#ifdef isfinite
+#undef isfinite
+#endif
+#ifdef isnan
+#undef isnan
+#endif
+#ifdef isinf
+#undef isinf
+#endif
+
+#include "target_profile.hpp"
+#include "stride_align/core.hpp"
+
+#if defined(STRIDE_ALIGN_RUBY_PRIMARY)
+#include "cpu_detect.hpp"
+#include "stride_align/alignment.hpp"
+#include "stride_align/beider_morse.hpp"
+#include "stride_align/caverphone.hpp"
+#include "stride_align/cologne_phonetic.hpp"
+#include "stride_align/daitch_mokotoff.hpp"
+#include "stride_align/double_metaphone.hpp"
+#include "stride_align/dtw.hpp"
+#include "stride_align/lcs.hpp"
+#include "stride_align/match_rating.hpp"
+#include "stride_align/metaphone.hpp"
+#include "stride_align/ngram.hpp"
+#include "stride_align/nysiis.hpp"
+#include "stride_align/partial_ratio.hpp"
+#include "stride_align/ratcliff_obershelp.hpp"
+#include "stride_align/soundex.hpp"
+#include "stride_align/token_ratios.hpp"
+#include "stride_align/wratio.hpp"
+#endif
+
+#if defined(STRIDE_ALIGN_RUBY_TARGET_GENERIC)
+#define STRIDE_ALIGN_RUBY_INIT Init__generic
+#define STRIDE_ALIGN_RUBY_MODULE "Generic"
+#elif defined(STRIDE_ALIGN_RUBY_TARGET_SSE41)
+#define STRIDE_ALIGN_RUBY_INIT Init__sse41
+#define STRIDE_ALIGN_RUBY_MODULE "Sse41"
+#elif defined(STRIDE_ALIGN_RUBY_TARGET_AVX2)
+#define STRIDE_ALIGN_RUBY_INIT Init__avx2
+#define STRIDE_ALIGN_RUBY_MODULE "Avx2"
+#elif defined(STRIDE_ALIGN_RUBY_TARGET_AVX512BWVL)
+#define STRIDE_ALIGN_RUBY_INIT Init__avx512bwvl
+#define STRIDE_ALIGN_RUBY_MODULE "Avx512bwvl"
+#elif defined(STRIDE_ALIGN_RUBY_TARGET_NEON)
+#define STRIDE_ALIGN_RUBY_INIT Init__neon
+#define STRIDE_ALIGN_RUBY_MODULE "Neon"
+#elif defined(STRIDE_ALIGN_RUBY_TARGET_SVE)
+#define STRIDE_ALIGN_RUBY_INIT Init__sve
+#define STRIDE_ALIGN_RUBY_MODULE "Sve"
+#elif defined(STRIDE_ALIGN_RUBY_TARGET_SVE2)
+#define STRIDE_ALIGN_RUBY_INIT Init__sve2
+#define STRIDE_ALIGN_RUBY_MODULE "Sve2"
+#elif defined(STRIDE_ALIGN_RUBY_TARGET_LSX)
+#define STRIDE_ALIGN_RUBY_INIT Init__lsx
+#define STRIDE_ALIGN_RUBY_MODULE "Lsx"
+#elif defined(STRIDE_ALIGN_RUBY_TARGET_LASX)
+#define STRIDE_ALIGN_RUBY_INIT Init__lasx
+#define STRIDE_ALIGN_RUBY_MODULE "Lasx"
+#elif defined(STRIDE_ALIGN_RUBY_TARGET_VSX)
+#define STRIDE_ALIGN_RUBY_INIT Init__vsx
+#define STRIDE_ALIGN_RUBY_MODULE "Vsx"
+#elif defined(STRIDE_ALIGN_RUBY_TARGET_RVV)
+#define STRIDE_ALIGN_RUBY_INIT Init__rvv
+#define STRIDE_ALIGN_RUBY_MODULE "Rvv"
+#endif
+
+namespace {
+
+template <typename Function>
+VALUE guarded(Function&& function) {
+  std::array<char, 1024> message{};
+  VALUE exception = rb_eRuntimeError;
+  try {
+    return function();
+  } catch (const std::invalid_argument& error) {
+    ruby_snprintf(message.data(), message.size(), "%s", error.what());
+    exception = rb_eArgError;
+  } catch (const std::exception& error) {
+    ruby_snprintf(message.data(), message.size(), "%s", error.what());
+  } catch (...) {
+    ruby_snprintf(message.data(), message.size(), "%s", "unknown C++ exception");
+  }
+  rb_raise(exception, "stride-align: %s", message.data());
+  return Qnil;
+}
+
+std::string ruby_string(VALUE value, const char* name) {
+  if (!RB_TYPE_P(value, T_STRING)) {
+    throw std::invalid_argument(std::string(name) + " must be a String");
+  }
+  return std::string(
+      RSTRING_PTR(value), static_cast<std::size_t>(RSTRING_LEN(value)));
+}
+
+#if defined(STRIDE_ALIGN_RUBY_PRIMARY)
+VALUE utf8_string(const std::string& value) {
+  return rb_enc_str_new(
+      value.data(), static_cast<long>(value.size()), rb_utf8_encoding());
+}
+#endif
+
+bool is_numeric(VALUE value) noexcept {
+  const int type = TYPE(value);
+  return type == T_FIXNUM || type == T_BIGNUM || type == T_FLOAT;
+}
+
+double numeric_value(VALUE value, const char* name) {
+  if (!is_numeric(value)) {
+    throw std::invalid_argument(std::string(name) + " must be numeric");
+  }
+  const double result = NUM2DBL(value);
+  if (!std::isfinite(result)) {
+    throw std::invalid_argument(std::string(name) + " must be finite");
+  }
+  return result;
+}
+
+::stride_align::Score score_value(VALUE value, const char* name) {
+  const double result = numeric_value(value, name);
+  constexpr double kLargestExactInteger = 9007199254740991.0;
+  if (std::trunc(result) != result || std::abs(result) > kLargestExactInteger) {
+    throw std::invalid_argument(
+        std::string(name) + " must be an exactly representable integer");
+  }
+  return static_cast<::stride_align::Score>(result);
+}
+
+std::size_t size_value(VALUE value, const char* name) {
+  const double result = numeric_value(value, name);
+  constexpr double kLargestExactInteger = 9007199254740991.0;
+  if (std::trunc(result) != result || result < 0.0 ||
+      result > kLargestExactInteger) {
+    throw std::invalid_argument(std::string(name) + " must be a non-negative integer");
+  }
+  return static_cast<std::size_t>(result);
+}
+
+#if defined(STRIDE_ALIGN_RUBY_PRIMARY)
+bool boolean_value(VALUE value, const char* name) {
+  if (value != Qtrue && value != Qfalse) {
+    throw std::invalid_argument(std::string(name) + " must be true or false");
+  }
+  return value == Qtrue;
+}
+#endif
+
+::stride_align::utf8::PreparedPair prepare_pair(
+    const std::string& query,
+    const std::string& target) {
+  if (!::stride_align::utf8::is_ascii(query) ||
+      !::stride_align::utf8::is_ascii(target)) {
+    return ::stride_align::utf8::prepare_pair(query, target);
+  }
+  const auto as_bytes = [](const std::string& value) {
+    return std::span<const std::uint8_t>(
+        reinterpret_cast<const std::uint8_t*>(value.data()), value.size());
+  };
+  return {
+      ::stride_align::utf8::TokenWidth::u8,
+      true,
+      false,
+      as_bytes(query),
+      as_bytes(target),
+  };
+}
+
+template <typename Scorer, typename Converter>
+VALUE apply_pair(VALUE query, VALUE target, Scorer&& scorer, Converter&& converter) {
+  if (NIL_P(query) || NIL_P(target)) return Qnil;
+  const std::string left = ruby_string(query, "query");
+  const std::string right = ruby_string(target, "target");
+  const auto pair = prepare_pair(left, right);
+  return converter(scorer(pair));
+}
+
+template <typename Scorer>
+VALUE apply_integer_pair(VALUE query, VALUE target, Scorer&& scorer) {
+  return apply_pair(
+      query, target, std::forward<Scorer>(scorer),
+      [](auto value) { return LL2NUM(static_cast<long long>(value)); });
+}
+
+template <typename Scorer>
+VALUE apply_float_pair(VALUE query, VALUE target, Scorer&& scorer) {
+  return apply_pair(
+      query, target, std::forward<Scorer>(scorer),
+      [](auto value) { return DBL2NUM(static_cast<double>(value)); });
+}
+
+VALUE rb_levenshtein(VALUE, VALUE query, VALUE target) {
+  return guarded([&] {
+    return apply_integer_pair(query, target, [](const auto& pair) {
+      return ::stride_align::core::levenshtein_distance(pair);
+    });
+  });
+}
+
+VALUE rb_levenshtein_similarity(VALUE, VALUE query, VALUE target) {
+  return guarded([&] {
+    return apply_float_pair(query, target, [](const auto& pair) {
+      return ::stride_align::core::levenshtein_similarity(pair);
+    });
+  });
+}
+
+VALUE rb_osa(VALUE, VALUE query, VALUE target) {
+  return guarded([&] {
+    return apply_integer_pair(query, target, [](const auto& pair) {
+      return ::stride_align::core::osa_distance(pair);
+    });
+  });
+}
+
+VALUE rb_osa_similarity(VALUE, VALUE query, VALUE target) {
+  return guarded([&] {
+    return apply_float_pair(query, target, [](const auto& pair) {
+      return ::stride_align::core::osa_similarity(pair);
+    });
+  });
+}
+
+VALUE rb_true_damerau(VALUE, VALUE query, VALUE target) {
+  return guarded([&] {
+    return apply_integer_pair(query, target, [](const auto& pair) {
+      return ::stride_align::core::true_damerau_levenshtein_distance(pair);
+    });
+  });
+}
+
+VALUE rb_true_damerau_similarity(VALUE, VALUE query, VALUE target) {
+  return guarded([&] {
+    return apply_float_pair(query, target, [](const auto& pair) {
+      return ::stride_align::core::true_damerau_levenshtein_similarity(pair);
+    });
+  });
+}
+
+VALUE rb_indel(VALUE, VALUE query, VALUE target) {
+  return guarded([&] {
+    return apply_integer_pair(query, target, [](const auto& pair) {
+      return ::stride_align::core::indel_distance(pair);
+    });
+  });
+}
+
+VALUE rb_indel_similarity(VALUE, VALUE query, VALUE target) {
+  return guarded([&] {
+    return apply_float_pair(query, target, [](const auto& pair) {
+      return ::stride_align::core::indel_similarity(pair);
+    });
+  });
+}
+
+VALUE rb_hamming(VALUE, VALUE query, VALUE target) {
+  return guarded([&] {
+    return apply_integer_pair(query, target, [](const auto& pair) {
+      return ::stride_align::core::hamming_distance(pair);
+    });
+  });
+}
+
+VALUE rb_hamming_similarity(VALUE, VALUE query, VALUE target) {
+  return guarded([&] {
+    return apply_float_pair(query, target, [](const auto& pair) {
+      return ::stride_align::core::hamming_similarity(pair);
+    });
+  });
+}
+
+VALUE rb_jaro(VALUE, VALUE query, VALUE target) {
+  return guarded([&] {
+    return apply_float_pair(query, target, [](const auto& pair) {
+      return ::stride_align::core::jaro_similarity(pair);
+    });
+  });
+}
+
+VALUE rb_jaro_winkler(
+    VALUE, VALUE query, VALUE target, VALUE weight, VALUE threshold, VALUE cap) {
+  return guarded([&] {
+    const double prefix_weight = numeric_value(weight, "prefix_weight");
+    const double prefix_threshold = numeric_value(threshold, "prefix_threshold");
+    const std::size_t prefix_cap = size_value(cap, "prefix_cap");
+    return apply_float_pair(query, target, [&](const auto& pair) {
+      return ::stride_align::core::jaro_winkler_similarity(
+          pair, prefix_weight, prefix_threshold, prefix_cap);
+    });
+  });
+}
+
+VALUE rb_smith_waterman(
+    VALUE, VALUE query, VALUE target, VALUE match, VALUE mismatch, VALUE gap) {
+  return guarded([&] {
+    const auto match_score = score_value(match, "match_score");
+    const auto mismatch_score = score_value(mismatch, "mismatch_score");
+    const auto gap_score = score_value(gap, "gap_score");
+    return apply_integer_pair(query, target, [&](const auto& pair) {
+      return ::stride_align::core::smith_waterman_score(
+          pair, match_score, mismatch_score, gap_score);
+    });
+  });
+}
+
+VALUE rb_needleman_wunsch(
+    VALUE, VALUE query, VALUE target, VALUE match, VALUE mismatch, VALUE gap) {
+  return guarded([&] {
+    const auto match_score = score_value(match, "match_score");
+    const auto mismatch_score = score_value(mismatch, "mismatch_score");
+    const auto gap_score = score_value(gap, "gap_score");
+    return apply_integer_pair(query, target, [&](const auto& pair) {
+      return ::stride_align::core::needleman_wunsch_score(
+          pair, match_score, mismatch_score, gap_score);
+    });
+  });
+}
+
+VALUE rb_smith_waterman_affine(
+    VALUE, VALUE query, VALUE target, VALUE match, VALUE mismatch,
+    VALUE gap_open, VALUE gap_extend) {
+  return guarded([&] {
+    const auto match_score = score_value(match, "match_score");
+    const auto mismatch_score = score_value(mismatch, "mismatch_score");
+    const auto open_score = score_value(gap_open, "gap_open_score");
+    const auto extend_score = score_value(gap_extend, "gap_extend_score");
+    return apply_integer_pair(query, target, [&](const auto& pair) {
+      return ::stride_align::core::smith_waterman_affine_score(
+          pair, match_score, mismatch_score, open_score, extend_score);
+    });
+  });
+}
+
+VALUE rb_needleman_wunsch_affine(
+    VALUE, VALUE query, VALUE target, VALUE match, VALUE mismatch,
+    VALUE gap_open, VALUE gap_extend) {
+  return guarded([&] {
+    const auto match_score = score_value(match, "match_score");
+    const auto mismatch_score = score_value(mismatch, "mismatch_score");
+    const auto open_score = score_value(gap_open, "gap_open_score");
+    const auto extend_score = score_value(gap_extend, "gap_extend_score");
+    return apply_integer_pair(query, target, [&](const auto& pair) {
+      return ::stride_align::core::needleman_wunsch_affine_score(
+          pair, match_score, mismatch_score, open_score, extend_score);
+    });
+  });
+}
+
+#if defined(STRIDE_ALIGN_RUBY_PRIMARY)
+
+std::vector<std::uint32_t> codepoints(const std::string& input) {
+  return ::stride_align::utf8::prepare_streaming(input);
+}
+
+std::string encode_utf8(std::span<const std::uint32_t> input) {
+  std::string output;
+  output.reserve(input.size());
+  for (const std::uint32_t value : input) {
+    if (value <= 0x7fU) {
+      output.push_back(static_cast<char>(value));
+    } else if (value <= 0x7ffU) {
+      output.push_back(static_cast<char>(0xc0U | (value >> 6U)));
+      output.push_back(static_cast<char>(0x80U | (value & 0x3fU)));
+    } else if (value <= 0xffffU) {
+      output.push_back(static_cast<char>(0xe0U | (value >> 12U)));
+      output.push_back(static_cast<char>(0x80U | ((value >> 6U) & 0x3fU)));
+      output.push_back(static_cast<char>(0x80U | (value & 0x3fU)));
+    } else {
+      output.push_back(static_cast<char>(0xf0U | (value >> 18U)));
+      output.push_back(static_cast<char>(0x80U | ((value >> 12U) & 0x3fU)));
+      output.push_back(static_cast<char>(0x80U | ((value >> 6U) & 0x3fU)));
+      output.push_back(static_cast<char>(0x80U | (value & 0x3fU)));
+    }
+  }
+  return output;
+}
+
+template <typename Function, typename Converter>
+VALUE apply_codepoint_pair(
+    VALUE query, VALUE target, Function&& function, Converter&& converter) {
+  if (NIL_P(query) || NIL_P(target)) return Qnil;
+  const auto left = codepoints(ruby_string(query, "query"));
+  const auto right = codepoints(ruby_string(target, "target"));
+  return converter(function(left, right));
+}
+
+VALUE rb_lcs_length(VALUE, VALUE query, VALUE target) {
+  return guarded([&] {
+    return apply_codepoint_pair(
+        query, target,
+        [](const auto& left, const auto& right) {
+          return ::stride_align::lcs::lcs_length(left, right);
+        },
+        [](auto value) { return ULL2NUM(static_cast<unsigned long long>(value)); });
+  });
+}
+
+VALUE rb_lcs_substring_length(VALUE, VALUE query, VALUE target) {
+  return guarded([&] {
+    return apply_codepoint_pair(
+        query, target,
+        [](const auto& left, const auto& right) {
+          return ::stride_align::lcs::lcs_substring_length(left, right);
+        },
+        [](auto value) { return ULL2NUM(static_cast<unsigned long long>(value)); });
+  });
+}
+
+VALUE rb_lcs_substring(VALUE, VALUE query, VALUE target) {
+  return guarded([&] {
+    return apply_codepoint_pair(
+        query, target,
+        [](const auto& left, const auto& right) {
+          return ::stride_align::lcs::lcs_substring(left, right);
+        },
+        [](const auto& value) { return utf8_string(encode_utf8(value)); });
+  });
+}
+
+enum class NgramMetric { jaccard, dice, cosine, overlap };
+
+VALUE rb_ngram(VALUE query, VALUE target, VALUE n, NgramMetric metric) {
+  const std::size_t size = size_value(n, "n");
+  if (size == 0U) throw std::invalid_argument("n must be positive");
+  return apply_codepoint_pair(
+      query, target,
+      [&](const auto& left, const auto& right) {
+        switch (metric) {
+          case NgramMetric::jaccard:
+            return ::stride_align::ngram::jaccard(left, right, size);
+          case NgramMetric::dice:
+            return ::stride_align::ngram::dice(left, right, size);
+          case NgramMetric::cosine:
+            return ::stride_align::ngram::cosine(left, right, size);
+          case NgramMetric::overlap:
+            return ::stride_align::ngram::overlap(left, right, size);
+        }
+        return 0.0;
+      },
+      [](double value) { return DBL2NUM(value); });
+}
+
+VALUE rb_jaccard(VALUE, VALUE query, VALUE target, VALUE n) {
+  return guarded([&] { return rb_ngram(query, target, n, NgramMetric::jaccard); });
+}
+VALUE rb_dice(VALUE, VALUE query, VALUE target, VALUE n) {
+  return guarded([&] { return rb_ngram(query, target, n, NgramMetric::dice); });
+}
+VALUE rb_cosine(VALUE, VALUE query, VALUE target, VALUE n) {
+  return guarded([&] { return rb_ngram(query, target, n, NgramMetric::cosine); });
+}
+VALUE rb_overlap(VALUE, VALUE query, VALUE target, VALUE n) {
+  return guarded([&] { return rb_ngram(query, target, n, NgramMetric::overlap); });
+}
+
+VALUE rb_ratcliff_obershelp(VALUE, VALUE query, VALUE target) {
+  return guarded([&] {
+    return apply_codepoint_pair(
+        query, target,
+        [](const auto& left, const auto& right) {
+          return ::stride_align::ratcliff_obershelp::
+              ratcliff_obershelp_similarity(left, right);
+        },
+        [](double value) { return DBL2NUM(value); });
+  });
+}
+
+enum class TokenMetric {
+  partial,
+  token_sort,
+  token_set,
+  partial_token_sort,
+  partial_token_set,
+  weighted,
+};
+
+VALUE rb_token_metric(VALUE query, VALUE target, TokenMetric metric) {
+  return apply_codepoint_pair(
+      query, target,
+      [&](const auto& left, const auto& right) {
+        const auto left_span =
+            std::span<const std::uint32_t>(left.data(), left.size());
+        const auto right_span =
+            std::span<const std::uint32_t>(right.data(), right.size());
+        switch (metric) {
+          case TokenMetric::partial:
+            return ::stride_align::partial_ratio::partial_ratio(left, right);
+          case TokenMetric::token_sort:
+            return ::stride_align::token_ratios::token_sort_ratio(left, right);
+          case TokenMetric::token_set:
+            return ::stride_align::token_ratios::token_set_ratio(left, right);
+          case TokenMetric::partial_token_sort:
+            return ::stride_align::wratio::
+                partial_token_sort_ratio_engine<std::uint32_t>(left_span, right_span);
+          case TokenMetric::partial_token_set:
+            return ::stride_align::wratio::
+                partial_token_set_ratio_engine<std::uint32_t>(left_span, right_span);
+          case TokenMetric::weighted:
+            return ::stride_align::wratio::native_wratio(left, right);
+        }
+        return 0.0;
+      },
+      [](double value) { return DBL2NUM(value); });
+}
+
+#define STRIDE_ALIGN_RUBY_TOKEN_METHOD(name, kind)                    \
+  VALUE name(VALUE, VALUE query, VALUE target) {                      \
+    return guarded([&] { return rb_token_metric(query, target, kind); }); \
+  }
+
+STRIDE_ALIGN_RUBY_TOKEN_METHOD(rb_partial_ratio, TokenMetric::partial)
+STRIDE_ALIGN_RUBY_TOKEN_METHOD(rb_token_sort_ratio, TokenMetric::token_sort)
+STRIDE_ALIGN_RUBY_TOKEN_METHOD(rb_token_set_ratio, TokenMetric::token_set)
+STRIDE_ALIGN_RUBY_TOKEN_METHOD(
+    rb_partial_token_sort_ratio, TokenMetric::partial_token_sort)
+STRIDE_ALIGN_RUBY_TOKEN_METHOD(
+    rb_partial_token_set_ratio, TokenMetric::partial_token_set)
+STRIDE_ALIGN_RUBY_TOKEN_METHOD(rb_wratio, TokenMetric::weighted)
+
+#undef STRIDE_ALIGN_RUBY_TOKEN_METHOD
+
+template <typename Function>
+VALUE apply_unary_string(VALUE input, Function&& function) {
+  if (NIL_P(input)) return Qnil;
+  return utf8_string(function(ruby_string(input, "input")));
+}
+
+VALUE rb_soundex(VALUE, VALUE input) {
+  return guarded([&] {
+    return apply_unary_string(input, [](const std::string& value) {
+      return ::stride_align::phonetic::soundex(value);
+    });
+  });
+}
+
+VALUE rb_soundex_equal(VALUE, VALUE query, VALUE target) {
+  return guarded([&] {
+    if (NIL_P(query) || NIL_P(target)) return Qnil;
+    return ::stride_align::phonetic::soundex(ruby_string(query, "query")) ==
+            ::stride_align::phonetic::soundex(ruby_string(target, "target"))
+        ? Qtrue
+        : Qfalse;
+  });
+}
+
+::stride_align::phonetic::MetaphoneVariant metaphone_variant(VALUE value) {
+  const auto variant = static_cast<::stride_align::phonetic::MetaphoneVariant>(
+      size_value(value, "variant"));
+  if (variant != ::stride_align::phonetic::MetaphoneVariant::kPhilips &&
+      variant != ::stride_align::phonetic::MetaphoneVariant::kJellyfish) {
+    throw std::invalid_argument("variant must be 0 or 1");
+  }
+  return variant;
+}
+
+VALUE rb_metaphone(VALUE, VALUE input, VALUE variant) {
+  return guarded([&] {
+    const auto selected = metaphone_variant(variant);
+    return apply_unary_string(input, [&](const std::string& value) {
+      return ::stride_align::phonetic::metaphone(value, selected);
+    });
+  });
+}
+
+VALUE rb_metaphone_equal(VALUE, VALUE query, VALUE target, VALUE variant) {
+  return guarded([&] {
+    if (NIL_P(query) || NIL_P(target)) return Qnil;
+    const auto selected = metaphone_variant(variant);
+    return ::stride_align::phonetic::metaphone(
+               ruby_string(query, "query"), selected) ==
+            ::stride_align::phonetic::metaphone(
+               ruby_string(target, "target"), selected)
+        ? Qtrue
+        : Qfalse;
+  });
+}
+
+VALUE rb_nysiis(VALUE, VALUE input) {
+  return guarded([&] {
+    return apply_unary_string(input, [](const std::string& value) {
+      return ::stride_align::phonetic::nysiis(value);
+    });
+  });
+}
+
+VALUE rb_nysiis_equal(VALUE, VALUE query, VALUE target) {
+  return guarded([&] {
+    if (NIL_P(query) || NIL_P(target)) return Qnil;
+    return ::stride_align::phonetic::nysiis(ruby_string(query, "query")) ==
+            ::stride_align::phonetic::nysiis(ruby_string(target, "target"))
+        ? Qtrue
+        : Qfalse;
+  });
+}
+
+VALUE rb_match_rating_codex(VALUE, VALUE input) {
+  return guarded([&] {
+    return apply_unary_string(input, [](const std::string& value) {
+      return ::stride_align::phonetic::match_rating_codex(value);
+    });
+  });
+}
+
+VALUE rb_match_rating_compare(VALUE, VALUE query, VALUE target) {
+  return guarded([&] {
+    if (NIL_P(query) || NIL_P(target)) return Qnil;
+    return ::stride_align::phonetic::match_rating_compare(
+               ruby_string(query, "query"), ruby_string(target, "target"))
+        ? Qtrue
+        : Qfalse;
+  });
+}
+
+VALUE rb_caverphone(VALUE, VALUE input) {
+  return guarded([&] {
+    return apply_unary_string(input, [](const std::string& value) {
+      return ::stride_align::phonetic::caverphone(value);
+    });
+  });
+}
+
+VALUE rb_cologne_phonetic(VALUE, VALUE input) {
+  return guarded([&] {
+    if (NIL_P(input)) return Qnil;
+    return utf8_string(::stride_align::phonetic::cologne_phonetic(
+        codepoints(ruby_string(input, "input"))));
+  });
+}
+
+VALUE rb_daitch_mokotoff(
+    VALUE, VALUE input, VALUE branching, VALUE folding) {
+  return guarded([&] {
+    if (NIL_P(input)) return Qnil;
+    return utf8_string(::stride_align::phonetic::daitch_mokotoff(
+        codepoints(ruby_string(input, "input")),
+        boolean_value(branching, "branching"),
+        boolean_value(folding, "folding")));
+  });
+}
+
+VALUE rb_double_metaphone(
+    VALUE, VALUE input, VALUE max_length, VALUE variant) {
+  return guarded([&] {
+    if (NIL_P(input)) return Qnil;
+    const auto selected =
+        static_cast<::stride_align::phonetic::DoubleMetaphoneVariant>(
+            size_value(variant, "variant"));
+    if (selected !=
+            ::stride_align::phonetic::DoubleMetaphoneVariant::kCommons &&
+        selected !=
+            ::stride_align::phonetic::DoubleMetaphoneVariant::kPython) {
+      throw std::invalid_argument("variant must be 0 or 1");
+    }
+    const auto result = ::stride_align::phonetic::double_metaphone(
+        ruby_string(input, "input"), size_value(max_length, "max_length"), selected);
+    return rb_ary_new_from_args(
+        2, utf8_string(result.primary), utf8_string(result.alternate));
+  });
+}
+
+VALUE rb_bmpm_register(VALUE, VALUE resources) {
+  return guarded([&] {
+    if (!RB_TYPE_P(resources, T_HASH)) {
+      throw std::invalid_argument("BMPM resources must be a Hash");
+    }
+    const ID keys_method = rb_intern("keys");
+    VALUE keys = rb_funcall(resources, keys_method, 0);
+    std::unordered_map<std::string, std::string> table;
+    table.reserve(static_cast<std::size_t>(RARRAY_LEN(keys)));
+    for (long index = 0; index < RARRAY_LEN(keys); ++index) {
+      VALUE key = rb_ary_entry(keys, index);
+      VALUE value = rb_hash_aref(resources, key);
+      table.emplace(
+          ruby_string(key, "BMPM resource name"),
+          ruby_string(value, "BMPM resource value"));
+    }
+    ::stride_align::phonetic::bmpm_register_resources(table);
+    return Qnil;
+  });
+}
+
+VALUE rb_beider_morse(
+    VALUE, VALUE input, VALUE rule_type, VALUE concat, VALUE max_phonemes) {
+  return guarded([&] {
+    if (NIL_P(input)) return Qnil;
+    const auto rule = static_cast<::stride_align::phonetic::BmpmRuleType>(
+        size_value(rule_type, "rule_type"));
+    if (rule != ::stride_align::phonetic::BmpmRuleType::kApprox &&
+        rule != ::stride_align::phonetic::BmpmRuleType::kExact) {
+      throw std::invalid_argument("rule_type must be 0 or 1");
+    }
+    return utf8_string(::stride_align::phonetic::beider_morse(
+        codepoints(ruby_string(input, "input")), rule,
+        boolean_value(concat, "concat"),
+        size_value(max_phonemes, "max_phonemes")));
+  });
+}
+
+std::vector<double> numeric_sequence(VALUE value, const char* name) {
+  if (!RB_TYPE_P(value, T_ARRAY)) {
+    throw std::invalid_argument(std::string(name) + " must be an Array of numbers");
+  }
+  const long length = RARRAY_LEN(value);
+  if (length == 0) {
+    throw std::invalid_argument(std::string(name) + " must be non-empty");
+  }
+  std::vector<double> output(static_cast<std::size_t>(length));
+  for (long index = 0; index < length; ++index) {
+    output[static_cast<std::size_t>(index)] =
+        numeric_value(rb_ary_entry(value, index), name);
+  }
+  return output;
+}
+
+std::optional<std::size_t> dtw_window(
+    VALUE value, std::size_t query_size, std::size_t target_size) {
+  if (NIL_P(value)) return std::nullopt;
+  const double number = numeric_value(value, "window");
+  if (number < 0.0) throw std::invalid_argument("window must be non-negative");
+  if (number > 0.0 && number < 1.0) {
+    return static_cast<std::size_t>(std::ceil(
+        number * static_cast<double>(std::max(query_size, target_size))));
+  }
+  if (std::trunc(number) != number) {
+    throw std::invalid_argument(
+        "window must be an integer radius or a fraction in (0, 1)");
+  }
+  return static_cast<std::size_t>(number);
+}
+
+VALUE rb_dtw(
+    VALUE, VALUE query, VALUE target, VALUE window, VALUE distance,
+    VALUE score_cutoff) {
+  return guarded([&] {
+    const auto left = numeric_sequence(query, "query");
+    const auto right = numeric_sequence(target, "target");
+    const std::string metric = ruby_string(distance, "distance");
+    if (metric != "l1" && metric != "l2_squared") {
+      throw std::invalid_argument("distance must be 'l1' or 'l2_squared'");
+    }
+    const auto kind = metric == "l1"
+        ? ::stride_align::dtw::DistanceKind::kL1
+        : ::stride_align::dtw::DistanceKind::kL2Squared;
+    std::optional<double> cutoff;
+    if (!NIL_P(score_cutoff)) {
+      cutoff = numeric_value(score_cutoff, "score_cutoff");
+      if (*cutoff < 0.0) {
+        throw std::invalid_argument("score_cutoff must be non-negative");
+      }
+    }
+    const double result = ::stride_align::dtw::dtw_score_scalar<double, double>(
+        left, right, kind, dtw_window(window, left.size(), right.size()), cutoff);
+    return DBL2NUM(result);
+  });
+}
+
+VALUE hash_set(VALUE hash, const char* name, VALUE value) {
+  const ID name_id = rb_intern(name);
+  rb_hash_aset(hash, ID2SYM(name_id), value);
+  return hash;
+}
+
+VALUE alignment_path_to_ruby(
+    const ::stride_align::AlignmentPath& path,
+    std::span<const std::uint32_t> query,
+    std::span<const std::uint32_t> target) {
+  VALUE result = rb_hash_new();
+  hash_set(result, "score", LL2NUM(static_cast<long long>(path.score)));
+  hash_set(result, "query_start", ULL2NUM(path.query_start));
+  hash_set(result, "query_end", ULL2NUM(path.query_end));
+  hash_set(result, "target_start", ULL2NUM(path.target_start));
+  hash_set(result, "target_end", ULL2NUM(path.target_end));
+  hash_set(result, "operations", utf8_string(path.operations));
+  hash_set(result, "cigar", utf8_string(path.cigar));
+  hash_set(result, "matches", ULL2NUM(path.matches));
+  hash_set(result, "mismatches", ULL2NUM(path.mismatches));
+  hash_set(result, "insertions", ULL2NUM(path.insertions));
+  hash_set(result, "deletions", ULL2NUM(path.deletions));
+  hash_set(result, "aligned_length", ULL2NUM(path.aligned_length));
+
+  std::vector<std::uint32_t> aligned_query;
+  std::vector<std::uint32_t> aligned_target;
+  aligned_query.reserve(path.operations.size());
+  aligned_target.reserve(path.operations.size());
+  std::size_t query_index = path.query_start;
+  std::size_t target_index = path.target_start;
+  constexpr std::uint32_t kGap = static_cast<std::uint32_t>('-');
+  for (const char operation : path.operations) {
+    if (operation == '=' || operation == 'X') {
+      aligned_query.push_back(query[query_index++]);
+      aligned_target.push_back(target[target_index++]);
+    } else if (operation == 'D') {
+      aligned_query.push_back(query[query_index++]);
+      aligned_target.push_back(kGap);
+    } else {
+      aligned_query.push_back(kGap);
+      aligned_target.push_back(target[target_index++]);
+    }
+  }
+  VALUE aligned = rb_hash_new();
+  hash_set(aligned, "query", utf8_string(encode_utf8(aligned_query)));
+  hash_set(aligned, "target", utf8_string(encode_utf8(aligned_target)));
+  hash_set(result, "aligned", aligned);
+  return result;
+}
+
+VALUE rb_alignment_path(
+    VALUE, VALUE query, VALUE target, VALUE local, VALUE match,
+    VALUE mismatch, VALUE gap_open, VALUE gap_extend) {
+  return guarded([&] {
+    const std::string left = ruby_string(query, "query");
+    const std::string right = ruby_string(target, "target");
+    const auto pair = prepare_pair(left, right);
+    const bool is_local = boolean_value(local, "local");
+    const auto match_score = score_value(match, "match_score");
+    const auto mismatch_score = score_value(mismatch, "mismatch_score");
+    const auto open_score = score_value(gap_open, "gap_open_score");
+    const auto extend_score = score_value(gap_extend, "gap_extend_score");
+    ::stride_align::AlignmentPath path;
+    if (open_score == extend_score) {
+      path = is_local
+          ? ::stride_align::core::smith_waterman_path(
+                pair, match_score, mismatch_score, open_score)
+          : ::stride_align::core::needleman_wunsch_path(
+                pair, match_score, mismatch_score, open_score);
+    } else {
+      path = is_local
+          ? ::stride_align::core::smith_waterman_affine_path(
+                pair, match_score, mismatch_score, open_score, extend_score)
+          : ::stride_align::core::needleman_wunsch_affine_path(
+                pair, match_score, mismatch_score, open_score, extend_score);
+    }
+    const auto left_points = codepoints(left);
+    const auto right_points = codepoints(right);
+    return alignment_path_to_ruby(path, left_points, right_points);
+  });
+}
+
+VALUE rb_backend_candidates(VALUE) {
+  return guarded([&] {
+    const auto candidates = stride_align_ruby_backend_candidates();
+    VALUE result = rb_ary_new_capa(static_cast<long>(candidates.size()));
+    for (const auto& candidate : candidates) {
+      rb_ary_push(result, utf8_string(candidate));
+    }
+    return result;
+  });
+}
+
+#endif  // STRIDE_ALIGN_RUBY_PRIMARY
+
+void define_backend_methods(VALUE backend) {
+  rb_define_singleton_method(backend, "levenshtein", RUBY_METHOD_FUNC(rb_levenshtein), 2);
+  rb_define_singleton_method(
+      backend, "levenshtein_similarity",
+      RUBY_METHOD_FUNC(rb_levenshtein_similarity), 2);
+  rb_define_singleton_method(backend, "osa", RUBY_METHOD_FUNC(rb_osa), 2);
+  rb_define_singleton_method(
+      backend, "osa_similarity", RUBY_METHOD_FUNC(rb_osa_similarity), 2);
+  rb_define_singleton_method(
+      backend, "true_damerau_levenshtein", RUBY_METHOD_FUNC(rb_true_damerau), 2);
+  rb_define_singleton_method(
+      backend, "true_damerau_levenshtein_similarity",
+      RUBY_METHOD_FUNC(rb_true_damerau_similarity), 2);
+  rb_define_singleton_method(backend, "indel", RUBY_METHOD_FUNC(rb_indel), 2);
+  rb_define_singleton_method(
+      backend, "indel_similarity", RUBY_METHOD_FUNC(rb_indel_similarity), 2);
+  rb_define_singleton_method(backend, "hamming", RUBY_METHOD_FUNC(rb_hamming), 2);
+  rb_define_singleton_method(
+      backend, "hamming_similarity", RUBY_METHOD_FUNC(rb_hamming_similarity), 2);
+  rb_define_singleton_method(backend, "jaro", RUBY_METHOD_FUNC(rb_jaro), 2);
+  rb_define_singleton_method(
+      backend, "jaro_winkler", RUBY_METHOD_FUNC(rb_jaro_winkler), 5);
+  rb_define_singleton_method(
+      backend, "smith_waterman", RUBY_METHOD_FUNC(rb_smith_waterman), 5);
+  rb_define_singleton_method(
+      backend, "needleman_wunsch", RUBY_METHOD_FUNC(rb_needleman_wunsch), 5);
+  rb_define_singleton_method(
+      backend, "smith_waterman_affine",
+      RUBY_METHOD_FUNC(rb_smith_waterman_affine), 6);
+  rb_define_singleton_method(
+      backend, "needleman_wunsch_affine",
+      RUBY_METHOD_FUNC(rb_needleman_wunsch_affine), 6);
+}
+
+#if defined(STRIDE_ALIGN_RUBY_PRIMARY)
+void define_primary_methods(VALUE backend) {
+  rb_define_singleton_method(
+      backend, "backend_candidates", RUBY_METHOD_FUNC(rb_backend_candidates), 0);
+  rb_define_singleton_method(backend, "lcs_length", RUBY_METHOD_FUNC(rb_lcs_length), 2);
+  rb_define_singleton_method(
+      backend, "lcs_substring_length", RUBY_METHOD_FUNC(rb_lcs_substring_length), 2);
+  rb_define_singleton_method(
+      backend, "lcs_substring", RUBY_METHOD_FUNC(rb_lcs_substring), 2);
+  rb_define_singleton_method(backend, "jaccard", RUBY_METHOD_FUNC(rb_jaccard), 3);
+  rb_define_singleton_method(backend, "dice", RUBY_METHOD_FUNC(rb_dice), 3);
+  rb_define_singleton_method(backend, "cosine", RUBY_METHOD_FUNC(rb_cosine), 3);
+  rb_define_singleton_method(backend, "overlap", RUBY_METHOD_FUNC(rb_overlap), 3);
+  rb_define_singleton_method(
+      backend, "ratcliff_obershelp", RUBY_METHOD_FUNC(rb_ratcliff_obershelp), 2);
+  rb_define_singleton_method(
+      backend, "partial_ratio", RUBY_METHOD_FUNC(rb_partial_ratio), 2);
+  rb_define_singleton_method(
+      backend, "token_sort_ratio", RUBY_METHOD_FUNC(rb_token_sort_ratio), 2);
+  rb_define_singleton_method(
+      backend, "token_set_ratio", RUBY_METHOD_FUNC(rb_token_set_ratio), 2);
+  rb_define_singleton_method(
+      backend, "partial_token_sort_ratio",
+      RUBY_METHOD_FUNC(rb_partial_token_sort_ratio), 2);
+  rb_define_singleton_method(
+      backend, "partial_token_set_ratio",
+      RUBY_METHOD_FUNC(rb_partial_token_set_ratio), 2);
+  rb_define_singleton_method(backend, "wratio", RUBY_METHOD_FUNC(rb_wratio), 2);
+  rb_define_singleton_method(backend, "soundex", RUBY_METHOD_FUNC(rb_soundex), 1);
+  rb_define_singleton_method(
+      backend, "soundex_equal", RUBY_METHOD_FUNC(rb_soundex_equal), 2);
+  rb_define_singleton_method(backend, "metaphone", RUBY_METHOD_FUNC(rb_metaphone), 2);
+  rb_define_singleton_method(
+      backend, "metaphone_equal", RUBY_METHOD_FUNC(rb_metaphone_equal), 3);
+  rb_define_singleton_method(backend, "nysiis", RUBY_METHOD_FUNC(rb_nysiis), 1);
+  rb_define_singleton_method(
+      backend, "nysiis_equal", RUBY_METHOD_FUNC(rb_nysiis_equal), 2);
+  rb_define_singleton_method(
+      backend, "match_rating_codex", RUBY_METHOD_FUNC(rb_match_rating_codex), 1);
+  rb_define_singleton_method(
+      backend, "match_rating_compare", RUBY_METHOD_FUNC(rb_match_rating_compare), 2);
+  rb_define_singleton_method(backend, "caverphone", RUBY_METHOD_FUNC(rb_caverphone), 1);
+  rb_define_singleton_method(
+      backend, "cologne_phonetic", RUBY_METHOD_FUNC(rb_cologne_phonetic), 1);
+  rb_define_singleton_method(
+      backend, "daitch_mokotoff", RUBY_METHOD_FUNC(rb_daitch_mokotoff), 3);
+  rb_define_singleton_method(
+      backend, "double_metaphone", RUBY_METHOD_FUNC(rb_double_metaphone), 3);
+  rb_define_singleton_method(
+      backend, "bmpm_register", RUBY_METHOD_FUNC(rb_bmpm_register), 1);
+  rb_define_singleton_method(
+      backend, "beider_morse", RUBY_METHOD_FUNC(rb_beider_morse), 4);
+  rb_define_singleton_method(backend, "dtw", RUBY_METHOD_FUNC(rb_dtw), 5);
+  rb_define_singleton_method(
+      backend, "alignment_path", RUBY_METHOD_FUNC(rb_alignment_path), 7);
+}
+#endif
+
+}  // namespace
+
+extern "C" {
+RUBY_FUNC_EXPORTED void STRIDE_ALIGN_RUBY_INIT() {
+  VALUE stride_align = rb_define_module("StrideAlign");
+  VALUE native = rb_define_module_under(stride_align, "Native");
+  VALUE backend = rb_define_module_under(native, STRIDE_ALIGN_RUBY_MODULE);
+  define_backend_methods(backend);
+#if defined(STRIDE_ALIGN_RUBY_PRIMARY)
+  define_primary_methods(backend);
+#endif
+}
+}  // extern "C"
+
+#undef STRIDE_ALIGN_RUBY_INIT
+#undef STRIDE_ALIGN_RUBY_MODULE