mongory 0.7.2-x86_64-linux

data/ext/mongory_ext/mongory-core/src/matchers/composite_matcher.h

@@ -0,0 +1,125 @@
+#ifndef MONGORY_MATCHER_COMPOSITE_H
+#define MONGORY_MATCHER_COMPOSITE_H
+
+/**
+ * @file composite_matcher.h
+ * @brief Defines structures and constructors for composite matchers.
+ * This is an internal header for the matcher module.
+ *
+ * Composite matchers combine other matchers, such as logical AND/OR,
+ * or apply a matcher to elements of an array or fields of a table.
+ */
+
+#include "base_matcher.h"
+#include "mongory-core/foundations/array.h"
+#include "mongory-core/foundations/memory_pool.h"
+#include "mongory-core/foundations/value.h"
+#include "mongory-core/matchers/matcher.h" // For mongory_matcher structure
+
+/**
+ * @struct mongory_composite_matcher
+ * @brief Represents a matcher composed of other matchers.
+ *
+ * Typically has a `left` and/or `right` child matcher. The interpretation
+ * of these children depends on the specific composite matcher type (e.g., for
+ * AND/OR, both are used; for $elemMatch, `left` might be the sub-matcher for
+ * elements).
+ */
+typedef struct mongory_composite_matcher {
+  mongory_matcher base;   /**< Base matcher structure. */
+  mongory_array *children; /**< Children matchers. */
+} mongory_composite_matcher;
+
+/** @name Composite Matcher Constructors
+ *  Functions to create instances of various composite matchers.
+ * @{
+ */
+
+/**
+ * @brief Creates an "AND" ($and) matcher.
+ * Matches if all conditions specified in an array of condition tables are met.
+ * @param pool Memory pool for allocation.
+ * @param condition A `mongory_value` of type `MONGORY_TYPE_ARRAY`, where each
+ * element is a `MONGORY_TYPE_TABLE` representing a sub-condition.
+ * @return A new `$and` matcher, or NULL on failure or if condition is invalid.
+ */
+mongory_matcher *mongory_matcher_and_new(mongory_memory_pool *pool, mongory_value *condition, void *extern_ctx);
+
+/**
+ * @brief Creates an "OR" ($or) matcher.
+ * Matches if any condition specified in an array of condition tables is met.
+ * @param pool Memory pool for allocation.
+ * @param condition A `mongory_value` of type `MONGORY_TYPE_ARRAY`, where each
+ * element is a `MONGORY_TYPE_TABLE` representing a sub-condition.
+ * @return A new `$or` matcher, or NULL on failure or if condition is invalid.
+ */
+mongory_matcher *mongory_matcher_or_new(mongory_memory_pool *pool, mongory_value *condition, void *extern_ctx);
+
+/**
+ * @brief Creates an "element match" ($elemMatch) matcher.
+ * Matches an array field if at least one element in the array matches the given
+ * condition table.
+ * @param pool Memory pool for allocation.
+ * @param condition A `mongory_value` of type `MONGORY_TYPE_TABLE` representing
+ * the condition to apply to array elements.
+ * @return A new `$elemMatch` matcher, or NULL on failure.
+ */
+mongory_matcher *mongory_matcher_elem_match_new(mongory_memory_pool *pool, mongory_value *condition, void *extern_ctx);
+
+/**
+ * @brief Creates an "every element matches" ($every) matcher.
+ * Matches an array field if ALL elements in the array match the given condition
+ * table. (Note: This is a common pattern, though MongoDB's $all has more
+ * complex behavior. This $every is simpler.)
+ * @param pool Memory pool for allocation.
+ * @param condition A `mongory_value` of type `MONGORY_TYPE_TABLE` representing
+ * the condition to apply to array elements.
+ * @return A new `$every` matcher, or NULL on failure.
+ */
+mongory_matcher *mongory_matcher_every_new(mongory_memory_pool *pool, mongory_value *condition, void *extern_ctx);
+
+/**
+ * @brief Creates a "table condition" matcher.
+ * This is a core matcher that parses a condition table (similar to a MongoDB
+ * query document) and builds a tree of sub-matchers based on its keys and
+ * values. Field names imply field matchers, and `$`-prefixed keys imply
+ * operator matchers. These are implicitly ANDed together.
+ * @param pool Memory pool for allocation.
+ * @param condition A `mongory_value` of type `MONGORY_TYPE_TABLE`.
+ * @return A new table condition matcher, or NULL on failure/invalid condition.
+ */
+mongory_matcher *mongory_matcher_table_cond_new(mongory_memory_pool *pool, mongory_value *condition, void *extern_ctx);
+/** @} */
+
+/**
+ * @brief Allocates and initializes a base `mongory_composite_matcher`
+ * structure.
+ *
+ * Sets up the base `mongory_matcher` fields within the composite structure.
+ * Child matchers (`left`, `right`) and the specific `match` function must be
+ * set by the caller.
+ *
+ * @param pool Memory pool for allocation.
+ * @param condition The condition associated with this composite matcher (can be
+ * NULL if the condition is implicitly defined by children).
+ * @return mongory_composite_matcher* Pointer to the new composite matcher
+ * structure, or NULL on failure.
+ */
+mongory_composite_matcher *mongory_matcher_composite_new(mongory_memory_pool *pool, mongory_value *condition, void *extern_ctx);
+
+/**
+ * @brief The actual match logic for an OR operation on a composite matcher.
+ *
+ * This function is typically assigned to the `match` field of an OR composite
+ * matcher. It checks if either the `left` or `right` child matcher matches the
+ * given value.
+ *
+ * @param matcher A pointer to the `mongory_matcher` (which is expected to be a
+ * `mongory_composite_matcher` for OR).
+ * @param value The `mongory_value` to evaluate.
+ * @return bool True if `left->match()` or `right->match()` returns true, false
+ * otherwise. Returns false if children are NULL or if their match calls fail.
+ */
+bool mongory_matcher_or_match(mongory_matcher *matcher, mongory_value *value);
+
+#endif /* MONGORY_MATCHER_COMPOSITE_H */

data/ext/mongory_ext/mongory-core/src/matchers/existance_matcher.c

@@ -0,0 +1,147 @@
+/**
+ * @file existance_matcher.c
+ * @brief Implements $exists and $present matchers.
+ * This is an internal implementation file for the matcher module.
+ */
+#include "existance_matcher.h"
+#include "base_matcher.h"                   // For mongory_matcher_base_new
+#include "mongory-core/foundations/array.h" // For value->data.a->count
+#include "mongory-core/foundations/error.h" // For mongory_error types
+#include "mongory-core/foundations/table.h" // For value->data.t->count
+#include "mongory-core/foundations/value.h" // For mongory_value types
+#include <mongory-core.h>                   // General include
+#include "../foundations/utils.h"
+
+/**
+ * @brief Validates that the condition for an existence/presence matcher is a
+ * boolean.
+ * @param condition The `mongory_value` condition to validate.
+ * @return True if `condition` is not NULL and is of type `MONGORY_TYPE_BOOL`,
+ * false otherwise.
+ */
+static bool mongory_matcher_validate_bool_condition(mongory_value *condition) {
+  if (condition == NULL) {
+    return false; // Condition itself must exist.
+  }
+  if (condition->type != MONGORY_TYPE_BOOL) {
+    return false; // Condition must be a boolean value.
+  }
+  return true;
+}
+
+/**
+ * @brief Match function for the $exists matcher.
+ *
+ * Compares the existence of the input `value` (i.e., `value != NULL`)
+ * with the boolean `matcher->condition->data.b`.
+ * - If `condition` is true, matches if `value` is not NULL.
+ * - If `condition` is false, matches if `value` is NULL.
+ *
+ * @param matcher The $exists matcher instance. Its condition must be boolean.
+ * @param value The value whose existence is being checked. This is typically
+ *              the result of a field lookup.
+ * @return True if the existence matches the condition, false otherwise.
+ */
+static inline bool mongory_matcher_exists_match(mongory_matcher *matcher, mongory_value *value) {
+  // The condition for $exists is a boolean (e.g., field: {$exists: true})
+  bool condition_expects_existence = matcher->condition->data.b;
+  bool actual_value_exists = (value != NULL);
+
+  return condition_expects_existence == actual_value_exists;
+}
+
+mongory_matcher *mongory_matcher_exists_new(mongory_memory_pool *pool, mongory_value *condition, void *extern_ctx) {
+  if (!mongory_matcher_validate_bool_condition(condition)) {
+    pool->error = MG_ALLOC_PTR(pool, mongory_error);
+    if (pool->error) {
+      pool->error->type = MONGORY_ERROR_INVALID_ARGUMENT;
+      pool->error->message = "$exists condition must be a boolean value.";
+    }
+    return NULL;
+  }
+  mongory_matcher *matcher = mongory_matcher_base_new(pool, condition, extern_ctx);
+  if (!matcher) {
+    return NULL;
+  }
+  matcher->match = mongory_matcher_exists_match;
+  matcher->original_match = mongory_matcher_exists_match;
+  matcher->name = mongory_string_cpy(pool, "Exists");
+  matcher->priority = 2.0;
+  return matcher;
+}
+
+/**
+ * @brief Match function for the $present matcher.
+ *
+ * Determines if a `value` is "present" based on its type and content,
+ * and compares this with the boolean `matcher->condition->data.b`.
+ * - NULL value: Present if condition is false.
+ * - Array: Present if non-empty and condition is true.
+ * - Table: Present if non-empty and condition is true.
+ * - String: Present if non-NULL, non-empty, and condition is true.
+ * - MONGORY_TYPE_NULL: Not present (matches if condition is false).
+ * - Boolean: Present if its value matches the condition.
+ * - Other non-NULL types: Considered present if condition is true.
+ *
+ * @param matcher The $present matcher. Its condition must be boolean.
+ * @param value The value to check for presence.
+ * @return True if the presence status matches the condition, false otherwise.
+ */
+static inline bool mongory_matcher_present_match(mongory_matcher *matcher, mongory_value *value) {
+  bool condition_expects_presence = matcher->condition->data.b;
+
+  if (value == NULL) {
+    // A NULL value (field does not exist) is "present" if condition_expects_presence is false.
+    return !condition_expects_presence;
+  }
+
+  bool actual_value_is_present;
+  switch (value->type) {
+  case MONGORY_TYPE_ARRAY:
+    actual_value_is_present = (value->data.a != NULL && value->data.a->count > 0);
+    break;
+  case MONGORY_TYPE_TABLE:
+    actual_value_is_present = (value->data.t != NULL && value->data.t->count > 0);
+    break;
+  case MONGORY_TYPE_STRING:
+    actual_value_is_present = (value->data.s != NULL && *(value->data.s) != '\0');
+    break;
+  case MONGORY_TYPE_NULL:
+    actual_value_is_present = false; // An explicit BSON-style Null is not "present".
+    break;
+  case MONGORY_TYPE_BOOL:
+    // For a boolean value, "present" means its own value matches the condition.
+    // e.g. {$present: true} on a true boolean is true.
+    //      {$present: false} on a true boolean is false.
+    //      {$present: true} on a false boolean is false.
+    //      {$present: false} on a false boolean is true.
+    return value->data.b == condition_expects_presence;
+  default:
+    // For other types (int, double, pointer, regex, unsupported), if they are
+    // not NULL (checked above), they are considered "present".
+    actual_value_is_present = true;
+    break;
+  }
+
+  return condition_expects_presence == actual_value_is_present;
+}
+
+mongory_matcher *mongory_matcher_present_new(mongory_memory_pool *pool, mongory_value *condition, void *extern_ctx) {
+  if (!mongory_matcher_validate_bool_condition(condition)) {
+    pool->error = MG_ALLOC_PTR(pool, mongory_error);
+    if (pool->error) {
+      pool->error->type = MONGORY_ERROR_INVALID_ARGUMENT;
+      pool->error->message = "$present condition must be a boolean value.";
+    }
+    return NULL;
+  }
+  mongory_matcher *matcher = mongory_matcher_base_new(pool, condition, extern_ctx);
+  if (!matcher) {
+    return NULL;
+  }
+  matcher->match = mongory_matcher_present_match;
+  matcher->original_match = mongory_matcher_present_match;
+  matcher->name = mongory_string_cpy(pool, "Present");
+  matcher->priority = 2.0;
+  return matcher;
+}

data/ext/mongory_ext/mongory-core/src/matchers/existance_matcher.h

@@ -0,0 +1,48 @@
+#ifndef MONGORY_MATCHER_EXISTANCE_H
+#define MONGORY_MATCHER_EXISTANCE_H
+
+/**
+ * @file existance_matcher.h
+ * @brief Defines constructors for existence and presence matchers ($exists,
+ * $present). This is an internal header for the matcher module.
+ */
+
+#include "base_matcher.h"
+#include "mongory-core/foundations/memory_pool.h"
+#include "mongory-core/foundations/value.h"
+#include "mongory-core/matchers/matcher.h" // For mongory_matcher structure
+
+/**
+ * @brief Creates an "exists" ($exists) matcher.
+ *
+ * This matcher checks for the existence of a field (i.e., if a value is
+ * non-NULL when retrieved from a table or array). The `condition` for this
+ * matcher must be a boolean `mongory_value`.
+ * - If `condition` is true, it matches if the field exists (value is not NULL).
+ * - If `condition` is false, it matches if the field does not exist (value is
+ * NULL).
+ *
+ * @param pool Memory pool for allocation.
+ * @param condition A `mongory_value` of type `MONGORY_TYPE_BOOL`.
+ * @return A new `$exists` matcher, or NULL on failure or invalid condition.
+ */
+mongory_matcher *mongory_matcher_exists_new(mongory_memory_pool *pool, mongory_value *condition, void *extern_ctx);
+
+/**
+ * @brief Creates a "present" ($present) matcher.
+ *
+ * This matcher provides a more nuanced check than `$exists`. It considers a
+ * value "present" based on its type and content (e.g., non-empty array/table,
+ * non-empty string). The `condition` for this matcher must be a boolean
+ * `mongory_value`.
+ * - If `condition` is true, it matches if the value is considered "present".
+ * - If `condition` is false, it matches if the value is not "present" (e.g.,
+ * NULL, empty array/table/string).
+ *
+ * @param pool Memory pool for allocation.
+ * @param condition A `mongory_value` of type `MONGORY_TYPE_BOOL`.
+ * @return A new `$present` matcher, or NULL on failure or invalid condition.
+ */
+mongory_matcher *mongory_matcher_present_new(mongory_memory_pool *pool, mongory_value *condition, void *extern_ctx);
+
+#endif /* MONGORY_MATCHER_EXISTANCE_H */

data/ext/mongory_ext/mongory-core/src/matchers/external_matcher.c

@@ -0,0 +1,124 @@
+/**
+ * @file external_matcher.c
+ * @brief Implements the $regex matcher.
+ * This is an internal implementation file for the matcher module.
+ */
+#include "external_matcher.h"
+#include "../foundations/config_private.h"   // For mongory_internal_regex_adapter
+#include "base_matcher.h"                    // For mongory_matcher_base_new
+#include "mongory-core/foundations/config.h"
+#include "../foundations/utils.h"            // For mongory_string_cpy
+#include "mongory-core/foundations/error.h"  // For MONGORY_ERROR_INVALID_ARGUMENT
+#include "mongory-core/foundations/memory_pool.h"
+#include "mongory-core/foundations/value.h"
+#include "matcher_explainable.h"
+#include "matcher_traversable.h"
+
+/**
+ * @brief Match function for the $regex matcher.
+ *
+ * Checks if the input `value` (which must be a string) matches the regex
+ * pattern stored in `matcher->condition`. The actual regex matching is
+ * performed by the function pointed to by
+ * `mongory_internal_regex_adapter->match_func`.
+ *
+ * @param matcher The $regex matcher instance.
+ * @param value The `mongory_value` to test; must be of type
+ * `MONGORY_TYPE_STRING`.
+ * @return True if the string value matches the regex, false otherwise or if
+ * input is not a string.
+ */
+static inline bool mongory_matcher_regex_match(mongory_matcher *matcher, mongory_value *value) {
+  if (!value || value->type != MONGORY_TYPE_STRING) {
+    return false; // Regex matching applies only to strings.
+  }
+  if (!mongory_internal_regex_adapter.match_func) {
+    return false; // Regex adapter or function not configured.
+  }
+
+  // Delegate to the configured regex function.
+  return mongory_internal_regex_adapter.match_func(matcher->pool, matcher->condition, value);
+}
+
+/**
+ * @brief Validates that the condition for a $regex matcher is valid.
+ * The condition must be non-NULL and either a `MONGORY_TYPE_STRING` (pattern)
+ * or `MONGORY_TYPE_REGEX` (pre-compiled regex object).
+ * @param condition The `mongory_value` condition to validate.
+ * @return True if the condition is valid for a regex matcher, false otherwise.
+ */
+static inline bool mongory_matcher_regex_condition_validate(mongory_value *condition) {
+  return condition != NULL && (condition->type == MONGORY_TYPE_STRING || condition->type == MONGORY_TYPE_REGEX);
+}
+
+mongory_matcher *mongory_matcher_regex_new(mongory_memory_pool *pool, mongory_value *condition, void *extern_ctx) {
+  if (!mongory_matcher_regex_condition_validate(condition)) {
+    pool->error = MG_ALLOC_PTR(pool, mongory_error);
+    if (pool->error) {
+      pool->error->type = MONGORY_ERROR_INVALID_ARGUMENT;
+      pool->error->message = "$regex condition must be a string or a regex object.";
+    }
+    return NULL;
+  }
+
+  mongory_matcher *matcher = mongory_matcher_base_new(pool, condition, extern_ctx);
+  if (!matcher) {
+    return NULL;
+  }
+  matcher->match = mongory_matcher_regex_match;
+  matcher->original_match = mongory_matcher_regex_match;
+  matcher->name = mongory_string_cpy(pool, "Regex");
+  matcher->priority = 20.0;
+  return matcher;
+}
+
+typedef struct mongory_custom_matcher {
+  mongory_matcher base;
+  void *external_matcher;
+} mongory_custom_matcher;
+
+/**
+ * @brief The match function for a custom matcher.
+ * @param matcher The matcher to match against.
+ * @param value The value to match.
+ * @return True if the value matches the matcher, false otherwise.
+ */
+bool mongory_matcher_custom_match(mongory_matcher *matcher, mongory_value *value) {
+  if (mongory_custom_matcher_adapter.match == NULL) {
+    return false; // Custom matcher adapter not initialized.
+  }
+  mongory_custom_matcher *custom_matcher = (mongory_custom_matcher *)matcher;
+  return mongory_custom_matcher_adapter.match(custom_matcher->external_matcher, value);
+}
+
+/**
+ * @brief Creates a new custom matcher instance.
+ *
+ * @param pool The memory pool to use for the matcher's allocations.
+ * @param key The key for the custom matcher.
+ * @param condition The `mongory_value` representing the condition for this
+ * matcher.
+ * @return mongory_matcher* A pointer to the newly created custom matcher, or
+ * NULL on failure.
+ */
+mongory_matcher *mongory_matcher_custom_new(mongory_memory_pool *pool, char *key, mongory_value *condition, void *extern_ctx) {
+  if (mongory_custom_matcher_adapter.build == NULL)
+    return NULL; // Custom matcher adapter not initialized.
+  mongory_custom_matcher *matcher = MG_ALLOC_PTR(pool, mongory_custom_matcher);
+  if (matcher == NULL)
+    return NULL;
+  mongory_matcher_custom_context *context = mongory_custom_matcher_adapter.build(key, condition, extern_ctx);
+  if (context == NULL)
+    return NULL;
+  matcher->base.pool = pool;
+  matcher->base.condition = condition;
+  matcher->base.name = context->name;
+  matcher->base.match = mongory_matcher_custom_match;
+  matcher->base.original_match = mongory_matcher_custom_match;
+  matcher->base.explain = mongory_matcher_base_explain;
+  matcher->base.traverse = mongory_matcher_leaf_traverse;
+  matcher->base.extern_ctx = extern_ctx;
+  matcher->external_matcher = context->external_matcher;
+  matcher->base.priority = 20.0;
+  return (mongory_matcher *)matcher;
+}

data/ext/mongory_ext/mongory-core/src/matchers/external_matcher.h

@@ -0,0 +1,46 @@
+#ifndef MONGORY_MATCHER_EXTERNAL_H
+#define MONGORY_MATCHER_EXTERNAL_H
+
+/**
+ * @file external_matcher.h
+ * @brief Defines the constructor for matchers that are not built-in.
+ * This is an internal header for the matcher module.
+ */
+
+#include "base_matcher.h"
+#include "mongory-core/foundations/memory_pool.h"
+#include "mongory-core/foundations/value.h"
+#include "mongory-core/matchers/matcher.h" // For mongory_matcher structure
+
+/**
+ * @brief Creates a regular expression ($regex) matcher.
+ *
+ * This matcher tests if an input string `mongory_value` matches a given regular
+ * expression. The regular expression itself is provided in the `condition`
+ * value, which can be either a `MONGORY_TYPE_STRING` (the pattern) or a
+ * `MONGORY_TYPE_REGEX` (a pre-compiled regex object, if the underlying regex
+ * engine supports it and it's wrapped). The actual regex matching logic is
+ * delegated to a function provided via `mongory_regex_func_set` (see
+ * `foundations/config.h`).
+ *
+ * @param pool Memory pool for allocation.
+ * @param condition A `mongory_value` representing the regex pattern. This
+ * should be of type `MONGORY_TYPE_STRING` or `MONGORY_TYPE_REGEX`.
+ * @return A new $regex matcher, or NULL on failure or if the condition is
+ * invalid.
+ */
+mongory_matcher *mongory_matcher_regex_new(mongory_memory_pool *pool, mongory_value *condition, void *extern_ctx);
+
+/**
+ * @brief Creates a new custom matcher instance.
+ *
+ * @param pool The memory pool to use for the matcher's allocations.
+ * @param key The key for the custom matcher.
+ * @param condition The `mongory_value` representing the condition for this
+ * matcher.
+ * @return mongory_matcher* A pointer to the newly created custom matcher, or
+ * NULL on failure.
+ */
+mongory_matcher *mongory_matcher_custom_new(mongory_memory_pool *pool, char *key, mongory_value *condition, void *extern_ctx);
+
+#endif /* MONGORY_MATCHER_EXTERNAL_H */

data/ext/mongory_ext/mongory-core/src/matchers/inclusion_matcher.c

@@ -0,0 +1,126 @@
+/**
+ * @file inclusion_matcher.c
+ * @brief Implements $in and $nin matchers for checking value inclusion in an
+ * array. This is an internal implementation file for the matcher module.
+ */
+#include "inclusion_matcher.h"
+#include "base_matcher.h"                   // For mongory_matcher_base_new
+#include "../foundations/array_private.h"   // For mongory_array_includes
+#include "mongory-core/foundations/array.h" // For mongory_array operations
+#include "mongory-core/foundations/error.h" // For mongory_error
+#include "mongory-core/foundations/value.h" // For mongory_value
+#include <mongory-core.h>                   // General include
+#include "../foundations/utils.h"            // For mongory_string_cpy
+
+/**
+ * @brief Validates that the condition for an inclusion matcher is a valid
+ * array.
+ * @param condition The `mongory_value` condition to validate.
+ * @return True if `condition` is not NULL, is of type `MONGORY_TYPE_ARRAY`,
+ * and its internal array data `condition->data.a` is not NULL. False otherwise.
+ */
+static inline bool mongory_matcher_validate_array_condition(mongory_value *condition) {
+  if (condition == NULL) {
+    return false; // Condition must exist.
+  }
+  if (condition->type != MONGORY_TYPE_ARRAY) {
+    return false; // Condition must be an array.
+  }
+  if (condition->data.a == NULL) {
+    return false; // The array data within the condition must be valid.
+  }
+  return true;
+}
+
+/**
+ * @brief Match function for the $in matcher.
+ *
+ * If `value_to_check` is a scalar, it checks if `value_to_check` is present in
+ * `matcher->condition` (which must be an array).
+ * If `value_to_check` is an array, it checks if any element of `value_to_check`
+ * is present in `matcher->condition` (array intersection).
+ *
+ * @param matcher The $in matcher instance.
+ * @param value_to_check The value to check for inclusion.
+ * @return True if `value_to_check` (or one of its elements) is found in the
+ * condition array, false otherwise.
+ */
+static inline bool mongory_matcher_in_match(mongory_matcher *matcher, mongory_value *value_to_check) {
+  if (!value_to_check || !matcher->condition || !matcher->condition->data.a) {
+    // Invalid inputs or condition is not a proper array.
+    return false;
+  }
+
+  mongory_array *condition_array = matcher->condition->data.a;
+
+  if (value_to_check->type != MONGORY_TYPE_ARRAY) {
+    return mongory_array_includes(condition_array, value_to_check);
+  }
+
+  mongory_array *input_array = value_to_check->data.a;
+  if (!input_array) {
+    return false;
+  }
+
+  for (size_t i = 0; i < input_array->count; i++) {
+    mongory_value *input_item = input_array->get(input_array, i);
+    if (mongory_array_includes(condition_array, input_item)) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+mongory_matcher *mongory_matcher_in_new(mongory_memory_pool *pool, mongory_value *condition, void *extern_ctx) {
+  if (!mongory_matcher_validate_array_condition(condition)) {
+    pool->error = MG_ALLOC_PTR(pool, mongory_error);
+    if (pool->error) {
+      pool->error->type = MONGORY_ERROR_INVALID_ARGUMENT;
+      pool->error->message = "$in condition must be a valid array.";
+    }
+    return NULL;
+  }
+  mongory_matcher *matcher = mongory_matcher_base_new(pool, condition, extern_ctx);
+  if (!matcher) {
+    return NULL;
+  }
+  matcher->match = mongory_matcher_in_match;
+  matcher->original_match = mongory_matcher_in_match;
+  matcher->name = mongory_string_cpy(pool, "In");
+  matcher->priority = 1.0 + mongory_log((double)condition->data.a->count + 1.0, 1.5);
+  return matcher;
+}
+
+/**
+ * @brief Match function for the $nin (not in) matcher.
+ * Simply negates the result of the $in logic.
+ * @param matcher The $nin matcher instance.
+ * @param value The value to check.
+ * @return True if the value is NOT found according to $in logic, false
+ * otherwise.
+ */
+static inline bool mongory_matcher_not_in_match(mongory_matcher *matcher, mongory_value *value) {
+  // $nin is true if $in is false.
+  return !mongory_matcher_in_match(matcher, value);
+}
+
+mongory_matcher *mongory_matcher_not_in_new(mongory_memory_pool *pool, mongory_value *condition, void *extern_ctx) {
+  if (!mongory_matcher_validate_array_condition(condition)) {
+    pool->error = MG_ALLOC_PTR(pool, mongory_error);
+    if (pool->error) {
+      pool->error->type = MONGORY_ERROR_INVALID_ARGUMENT;
+      pool->error->message = "$nin condition must be a valid array.";
+    }
+    return NULL;
+  }
+  mongory_matcher *matcher = mongory_matcher_base_new(pool, condition, extern_ctx);
+  if (!matcher) {
+    return NULL;
+  }
+  matcher->match = mongory_matcher_not_in_match;
+  matcher->original_match = mongory_matcher_not_in_match;
+  matcher->name = mongory_string_cpy(pool, "Nin");
+  matcher->priority = 1.0 + mongory_log((double)condition->data.a->count + 1.0, 1.5);
+  return matcher;
+}

data/ext/mongory_ext/mongory-core/src/matchers/inclusion_matcher.h

@@ -0,0 +1,46 @@
+#ifndef MONGORY_MATCHER_INCLUSION_H
+#define MONGORY_MATCHER_INCLUSION_H
+
+/**
+ * @file inclusion_matcher.h
+ * @brief Defines constructors for inclusion matchers ($in, $nin).
+ * This is an internal header for the matcher module.
+ *
+ * These matchers check if a value is present or not present in a given array
+ * of values.
+ */
+
+#include "base_matcher.h"
+#include "mongory-core/foundations/memory_pool.h"
+#include "mongory-core/foundations/value.h"
+#include "mongory-core/matchers/matcher.h" // For mongory_matcher structure
+
+/**
+ * @brief Creates an "in" ($in) matcher.
+ *
+ * Matches if the input value is equal to any of the values in the `condition`
+ * array. If the input value itself is an array, it matches if any element of
+ * the input array is found in the `condition` array (set intersection).
+ *
+ * @param pool Memory pool for allocation.
+ * @param condition A `mongory_value` of type `MONGORY_TYPE_ARRAY` containing
+ * the set of values to check against.
+ * @return A new `$in` matcher, or NULL on failure or invalid condition.
+ */
+mongory_matcher *mongory_matcher_in_new(mongory_memory_pool *pool, mongory_value *condition, void *extern_ctx);
+
+/**
+ * @brief Creates a "not in" ($nin) matcher.
+ *
+ * Matches if the input value is not equal to any of the values in the
+ * `condition` array. If the input value itself is an array, it matches if no
+ * element of the input array is found in the `condition` array.
+ *
+ * @param pool Memory pool for allocation.
+ * @param condition A `mongory_value` of type `MONGORY_TYPE_ARRAY` containing
+ * the set of values to check against.
+ * @return A new `$nin` matcher, or NULL on failure or invalid condition.
+ */
+mongory_matcher *mongory_matcher_not_in_new(mongory_memory_pool *pool, mongory_value *condition, void *extern_ctx);
+
+#endif /* MONGORY_MATCHER_INCLUSION_H */