view release on metacpan or  search on metacpan

lib/util.pm  view on Meta::CPAN

=head2 list_callbacks

    my $callbacks = list_callbacks();

Returns an arrayref of all registered callback names.

=head2 XS Callback Registration

External XS modules can register C-level callbacks for maximum performance.
Include the header in your XS code:

    #include "util_callbacks.h"

Then register callbacks:

    static bool my_is_valid(pTHX_ SV *elem) {
        return SvOK(elem) && SvIV(elem) > 0;
    }

    BOOT:
        util_register_predicate_xs("my_is_valid", my_is_valid);

The C callback avoids all Perl overhead - no call_sv, no stack manipulation.
See C<xs/util/util_callbacks.h> for the full API.

=head1 DATA MANIPULATION

These functions transform and extract data from arrays and hashes.

=head2 uniq

    my @unique = uniq(@list);

Returns a list with duplicate values removed, preserving order.
The first occurrence of each value is kept. Uses a hash for O(1) lookups.

=head2 partition

    my ($evens, $odds) = partition(sub { $_ % 2 == 0 }, \@numbers);

Splits an array into two arrayrefs based on a predicate. The first
contains elements for which the predicate returns true, the second
contains elements for which it returns false.

=head2 pick

    my $subset = pick(\%hash, @keys);

Returns a new hashref containing only the specified keys from the
source hash. Missing keys are silently ignored.

    my $user_info = pick(\%user, 'name', 'email');

=head2 omit

    my $filtered = omit(\%hash, @keys);

Returns a new hashref with the specified keys removed.
Opposite of C<pick>.

    my $safe = omit(\%user, 'password', 'secret_token');

=head2 pluck

    my @ids = pluck(\@users, 'id');

Extracts a single field from an array of hashes. Returns a list
of values for that field from each hash.

    my @names = pluck(\@employees, 'name');

=head2 defaults

    my $merged = defaults(\%hash, \%defaults);

Returns a new hashref with values from C<%defaults> filled in for
any missing keys in C<%hash>. Does not modify the original hashes.

    my $config = defaults(\%user_config, { timeout => 30, retries => 3 });

=head2 count

    my $n = count(sub { $_ > 10 }, \@numbers);

Counts how many elements in the list satisfy the predicate.
More efficient than C<scalar grep { ... } @list> because it
doesn't build an intermediate list.

=head2 replace_all

    my $result = replace_all($string, $search, $replace);

Replaces all occurrences of C<$search> in C<$string> with C<$replace>.
Faster than C<< $str =~ s/\Q$search\E/$replace/g >> for literal strings
because it avoids regex compilation.

=head2 negate

    my $not_even = negate(sub { $_ % 2 == 0 });

Returns a new function that negates the result of the given predicate.
Useful for inverting filters.

    my @odds = grep { negate(\&is_even)->($_) } @numbers;

=head2 once

    my $init_once = once(\&initialize);
    $init_once->();  # Runs initialize()
    $init_once->();  # Returns cached result, doesn't run again

Wraps a function to ensure it only executes once. Subsequent calls
return the cached result of the first call.

=head1 TYPE PREDICATES

These functions use custom ops and are replaced at compile time with
direct SV flag checks. They have zero function call overhead.

=head2 is_ref