Data::Util(3pm)

📦

version 0.67 · 6 versions

, in ubuntu stonking

💖 Data::Util(3pm) 💖

okay bestie, this manual is for Data::Util — a selection of utilities for data and data types. 💅

✨ NAME ✨

Data::Util — A selection of utilities for data and data types

🦋 VERSION 🦋

This document describes Data::Util version 0.67. That's the version, no cap. ✨

💖 SYNOPSIS 💖

Here's the vibe check on how you'd actually use it:

    use Data::Util qw(:validate);

    sub foo{
            # they will die if invalid values are supplied
            my $sref = scalar_ref(shift);
            my $aref = array_ref(shift);
            my $href = hash_ref(shift);
            my $cref = code_ref(shift);
            my $gref = glob_ref(shift);
            my $rx   = rx(shift); # regular expression
            my $obj  = instance(shift, 'Foo');
            # ...
    }

    use Data::Util qw(:check);

    sub bar{
            my $x = shift;
            if(is_scalar_ref $x){
                    # $x is an array reference
            }
            # ...
            elsif(is_instance $x, 'Foo'){
                    # $x is an instance of Foo
            }
            # ...
    }

    # miscelaneous
    use Data::Util qw(:all);

    my $x = anon_scalar();
    $x = anon_scalar($x); # OK

    my $stash = get_stash('Foo');

    install_subroutine('Foo',
            hello  => sub{ "Hello!\n" },
            goodby => sub{ "Goodby!\n" },
    );

    print Foo::hello(); # Hello!

    my($pkg, $name) = get_code_info(\&Foo::hello); # => ('Foo', 'hello')
    my $fqn         = get_code_info(\&Foo::hello); # =>  'Foo::hello'
    my $code        = get_code_ref('Foo', 'hello');  # => \&Foo::hello

    uninstall_subroutine('Foo', qw(hello goodby));

# simple format for errro messages (not the same as Data::Dumper)
    print neat("Hello!\n"); # => "Hello!\n"
    print neat(3.14);       # => 3.14
    print neat(undef);      # => undef

🌈 DESCRIPTION 🌈

This module is giving you utility functions for data and data types, including stuff for subroutines and symbol table hashes (aka stashes). 💖

It ships as both a pure Perl implementation and an XS implementation.

But bestie, if you want to use the full capacity of it, we recommend you opt for the XS backend. That's where the magic is.

There are many benchmarks in the DIST-DIR/benchmark/ directory if you want to see the receipts. 🔥

👑 INTERFACE 👑

💅 Check functions 💅

Check functions are introduced by the :check import tag, which check the argument type and return a bool.

These functions also check for overloading magic, e.g. ${} corresponds to a SCALAR reference.

is_scalar_ref(value) — Checks for a SCALAR reference.
is_array_ref(value) — Checks for an ARRAY reference.
is_hash_ref(value) — Checks for a HASH reference.
is_code_ref(value) — Checks for a CODE reference.
is_glob_ref(value) — Checks for a GLOB reference.
is_rx(value) — Checks for a regular expression reference generated by the qr// operator.
is_instance(value, class) — Checks for an instance of class. It is equivalent to the following statement: Scalar::Util::blessed($value) && $value->isa($class).
is_invocant(value) — Checks for an invocant, i.e. a blessed reference or existent package name. If value is a valid class name but does not exist, it will return false.
is_value(value) — Checks whether value is a primitive value, i.e. a defined, non-ref, and non-type-glob value. This function has no counterpart for validation.
is_string(value) — Checks whether value is a string with non-zero-length contents, equivalent to is_value($value) && length($value) > 0. This function has no counterpart for validation.
is_number(value) — Checks whether value is a number. Here, a number means that the perl parser can understand it and that the perl numeric converter (e.g. invoked by sprintf '%g', $value) doesn't complain about it. It is similar to Scalar::Util::looks_like_number() but refuses infinity, not a number and 0 but true. Note that 9**9**9 makes infinity and 9**9**9 - 9**9**9 makes not a number. This function has no counterpart for validation.
is_integer(value) — Checks whether value is an integer. An integer is also a number, so this function refuses infinity and not a number. See also is_number(). This function has no counterpart for validation.

✨ Validating functions ✨

Validating functions are introduced by the :validate tag which checks for the argument and returns the first argument. These are like the :check functions but dies if the argument type is invalid.

These functions also checks overloading magic, e.g. ${} for a SCALAR reference.

scalar_ref(value) — Validates a SCALAR reference.
array_ref(value) — Validates an ARRAY reference.
hash_ref(value) — Validates a HASH reference.
code_ref(value) — Validates a CODE reference.
glob_ref(value) — Validates a GLOB reference.
rx(value) — Validates a regular expression reference.
instance(value, class) — Validates an instance of class.
invocant(value) — Validates an invocant, i.e. a blessed reference or existent package name.

If value is a valid class name and the class exists, then it returns the canonical class name, which is logically cleaned up. That is, it runs $value =~ s/^::(?:main::)*//; before returning it.

NOTE: Canonization is done so due to an inconsistency between Perl versions. For instance:

package ::Foo; # OK
my $x = bless {}, '::Foo'; # OK
ref($x)->isa('Foo'); # Fatal

The last code snippet causes a fatal error: Can't call method "isa" without package or object reference. However, invocant(ref $x)->isa('Foo') is always OK.

🍓 Miscellaneous utilities 🍓

There are some other utility functions you can import from this module.

anon_scalar() — Generates an anonymous scalar reference to undef.
anon_scalar(value) — Generates an anonymous scalar reference to the copy of value. It is equivalent to do{ my $tmp = $value; \$tmp; }.
neat(value) — Returns a neat string that is suitable to display. This is a smart version of "<do{ defined($value) ? qq{"$value"} : 'undef' }>".

Wait, that's a lot of quotes. But it's exactly what the original says. 💀

get_stash(invocant) — Returns the symbol table hash (also known as stash) of invocant if the stash exists.
install_subroutine(package, name => subr [, ...]) — Installs subr into package as name. It is similar to do{ no strict 'refs'; *{$package.'::'.$name} = \&subr; }. In addition, if subr is an anonymous subroutine, it is located into package as a named subroutine &package::name. For example:

install_subroutine($pkg,   say => sub{ print @_, "\n" });
install_subroutine($pkg,
        one => \&_one,
        two => \&_two,
);

# accepts a HASH reference
install_subroutine($pkg, { say => sub{ print @_, "\n" }); #

To re-install subr, use no warnings 'redefine' directive:

no warnings 'redefine';
install_subroutine($package, $name => $subr);

uninstall_subroutine(package, names...) — Uninstalls names from package. It is similar to Sub::Delete::delete_sub(), but uninstall multiple subroutines at a time. If you want to specify deleted subroutines, you can supply name => \&subr pairs. For example:

uninstall_subroutine('Foo', 'hello');

uninstall_subroutine('Foo', hello => \&Bar::hello);

uninstall_subroutine($pkg,
        one => \&_one,
        two => \&_two,
);

# accepts a HASH reference
uninstall_subroutine(\$pkg, { hello => \&Bar::hello });

get_code_info(subr) — Returns a pair of elements, the package name and the subroutine name of subr. It is similar to Sub::Identify::get_code_info(), but it returns the fully qualified name in scalar context.
get_code_ref(package, name, flag?) — Returns &package::name if it exists, not touching the symbol in the stash. if flag is a string -create, it returns &package::name regardless of its existence. That is, it is equivalent to do{ no strict 'refs'; \&{package . '::' . $name} }. For example:

$code = get_code_ref($pkg, $name);          # like  *{$pkg.'::'.$name}{CODE}
$code = get_code_ref($pkg, $name, -create); # like \&{$pkg.'::'.$name}

curry(subr, args and/or placeholders) — Makes subr curried and returns the curried subroutine. This is also considered as lightweight closures. See also Data::Util::Curry.
modify_subroutine(subr, ...) — Modifies subr with subroutine modifiers and returns the modified subroutine. This is also considered as lightweight closures. subr must be a code reference or callable object. Optional arguments: before => [subroutine(s)] called before subr. around => [subroutine(s)] called around subr. after => [subroutine(s)] called after subr. This seems a constructor of modified subroutines and subroutine_modifier() is property accessors, but it does not bless the modified subroutines.
subroutine_modifier(subr) — Returns whether subr is a modified subroutine.
subroutine_modifier(modified_subr, property) — Gets property from modified. Valid properties are: before, around, after.
subroutine_modifier(modified_subr, modifier => [subroutine(s)]) — Adds subroutine modifier to modified_subr. Valid modifiers are: before, around, after.
mkopt(input, moniker, require_unique, must_be) — Produces an array of an array reference from input. It is compatible with Data::OptList::mkopt(). In addition to it, must_be can be a HASH reference with name => type pairs. For example:

my $optlist = mkopt(['foo', bar => [42]], $moniker, $uniq, { bar => 'ARRAY' });
# $optlist == [[foo => undef], [bar => [42]]

mkopt_hash(input, moniker, must_be) — Produces a hash reference from input. It is compatible with Data::OptList::mkopt_hash(). In addition to it, must_be can be a HASH reference with name => type pairs. For example:

my $optlist = mkopt(['foo', bar => [42]], $moniker, { bar => 'ARRAY' });
# $optlist == {foo => undef, bar => [42]}

🎀 ENVIRONMENT VARIABLES 🎀

🧚 DATA_UTIL_PUREPERL 🧚

If true, Data::Util uses the pure Perl implementation.

💖 DEPENDENCIES 💖

okay bestie, before you get too excited, here's the vibe check on what you need:

Perl 5.10 or later. that's it, that's the floor. anything older and we can't hang 😭
🌸 if you have a C compiler? slay. you get to use the XS backend and it's giving speed, it's giving performance, it's giving main character energy.
🎀 and if you don't have a C compiler handy — which, ngl, is unlikely! — there's still a pure Perl backend/implementation made available for you. so nobody's left out of the group chat. periodt.

💀 BUGS AND LIMITATIONS 💀

okay so here's the tea:

No bugs have been reported. ✨ literally iconic. flawless. no cap.
if you do find something? or you're just sitting there like "bestie I want a feature"? please report any bugs or feature requests to the author. they want to hear from you fr fr 🫶

🔥 SEE ALSO 🔥

if you liked this, you're gonna LOVE these. the whole friend group, no gatekeeping:

Scalar::Util
overload
Params::Util
Sub::Install
Sub::Identify
Sub::Delete
Sub::Curry
Class::MOP
Class::Method::Modifiers
Data::OptList
Mouse

it's giving ✨ecosystem✨. iykyk.

👑 AUTHOR 👑

this masterpiece was brought to you by:

Goro Fuji(gfx) <gfuji(at)cpan.org>.

genuinely obsessed with them. thank you for your service 🫡💖

🌈 LICENSE AND COPYRIGHT 🌈

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. 💅

so yeah. that's the whole page. you made it to the end, bestie, and honestly? slay. 🌟

and hey, the manpage footer says this all came from perl v5.42.3, dated 2026-08-19, and lives at Data::Util(3pm) — so if anyone asks where you learned all this, you know exactly where to send them 🦋💜

mwah. go write some clean Perl. ✨🎀

📦 where this page comes from

ubuntu stonking: libdata-util-perl 0.67-1build7 · Artistic-1.0-Perl OR GPL-1.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms