view release on metacpan or  search on metacpan

xs/util/util_callbacks.h  view on Meta::CPAN

/*
 * Register a C mapper function for map operations.
 */
PERL_CALLCONV void util_register_mapper_xs(pTHX_ const char *name,
                                            UtilMapFunc func);

/*
 * Register a C reducer function for reduce/fold operations.
 */
PERL_CALLCONV void util_register_reducer_xs(pTHX_ const char *name,
                                             UtilReduceFunc func);

/* ============================================
   Available loop functions
   ============================================ */

/*
 * The following loop functions support named callbacks:
 *
 *   any_cb(\@list, $name)        - true if any element matches
 *   all_cb(\@list, $name)        - true if all elements match
 *   none_cb(\@list, $name)       - true if no element matches
 *   first_cb(\@list, $name)      - first matching element
 *   final_cb(\@list, $name)      - last matching element
 *   grep_cb(\@list, $name)       - all matching elements
 *   count_cb(\@list, $name)      - count of matching elements
 *   partition_cb(\@list, $name)  - split into [matches], [non-matches]
 */

/* ============================================
   Performance notes
   ============================================ */

/*
 * Callback overhead comparison:
 *
 *   Built-in C predicate (:is_positive)  ~5-10 cycles per element
 *   Registered C predicate               ~5-10 cycles per element
 *   Perl callback via register_callback  ~100+ cycles per element
 *   Block callback via any { ... }       ~20-30 cycles (MULTICALL)
 *                                        ~100+ cycles (call_sv fallback)
 *
 * For hot loops processing millions of elements, C predicates provide
 * 10-20x speedup over Perl callbacks.
 */

/* ============================================
   Built-in predicates reference
   ============================================ */

/*
 * The following built-in predicates are available:
 *
 * Type checks:
 *   :is_defined   - SvOK(elem)
 *   :is_ref       - SvROK(elem)
 *   :is_array     - arrayref
 *   :is_hash      - hashref
 *   :is_code      - coderef
 *   :is_string    - plain scalar (not ref, not number)
 *   :is_number    - numeric (IV, NV, or looks_like_number)
 *   :is_integer   - integer value (no fractional part)
 *
 * Boolean checks:
 *   :is_true      - SvTRUE(elem)
 *   :is_false     - !SvTRUE(elem)
 *
 * Numeric checks:
 *   :is_positive  - value > 0
 *   :is_negative  - value < 0
 *   :is_zero      - value == 0
 *   :is_even      - value % 2 == 0
 *   :is_odd       - value % 2 != 0
 *
 * Empty checks:
 *   :is_empty     - empty string, empty array/hash, or undef
 *   :is_nonempty  - not empty
 */

#endif /* UTIL_CALLBACKS_H */