.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Data::Util 3pm"
.TH Data::Util 3pm "2011-10-20" "perl v5.14.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Data::Util \- A selection of utilities for data and data types
.SH "VERSION"
.IX Header "VERSION"
This document describes Data::Util version 0.59
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&        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, \*(AqFoo\*(Aq);
\&                # ...
\&        }
\&
\&        use Data::Util qw(:check);
\&
\&        sub bar{
\&                my $x = shift;
\&                if(is_scalar_ref $x){
\&                        # $x is an array reference
\&                }
\&                # ...
\&                elsif(is_instance $x, \*(AqFoo\*(Aq){
\&                        # $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(\*(AqFoo\*(Aq);
\&
\&        install_subroutine(\*(AqFoo\*(Aq,
\&                hello  => sub{ "Hello!\en" },
\&                goodby => sub{ "Goodby!\en" },
\&        );
\&
\&        print Foo::hello(); # Hello!
\&
\&        my($pkg, $name) = get_code_info(\e&Foo::hello); # => (\*(AqFoo\*(Aq, \*(Aqhello\*(Aq)
\&        my $fqn         = get_code_info(\e&Foo::hello); # =>  \*(AqFoo::hello\*(Aq
\&        my $code        = get_code_ref(\*(AqFoo::hello\*(Aq);  # => \e&Foo::hello
\&
\&        uninstall_subroutine(\*(AqFoo\*(Aq, qw(hello goodby));
\&
\&        print neat("Hello!\en"); # => "Hello!\en"
\&        print neat(3.14);       # => 3.14
\&        print neat(undef);      # => undef
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module provides utility functions for data and data types,
including functions for subroutines and symbol table hashes (stashes).
.PP
The implementation of this module is both Pure Perl and \s-1XS\s0, so if you have a C
compiler, all the functions this module provides are really faster.
.PP
There are many benchmarks in the \fIDIST\-DIR/benchmark/\fR directory.
.SH "INTERFACE"
.IX Header "INTERFACE"
.SS "Check functions"
.IX Subsection "Check functions"
Check functions are introduced by the \f(CW\*(C`:check\*(C'\fR import tag, which check
the argument type and return a bool.
.PP
These functions also checks overloading magic, e.g. \f(CW\*(C`${}\*(C'\fR for a \s-1SCALAR\s0 reference.
.IP "is_scalar_ref(value)" 4
.IX Item "is_scalar_ref(value)"
For a \s-1SCALAR\s0 reference.
.IP "is_array_ref(value)" 4
.IX Item "is_array_ref(value)"
For an \s-1ARRAY\s0 reference.
.IP "is_hash_ref(value)" 4
.IX Item "is_hash_ref(value)"
For a \s-1HASH\s0 reference.
.IP "is_code_ref(value)" 4
.IX Item "is_code_ref(value)"
For a \s-1CODE\s0 reference.
.IP "is_glob_ref(value)" 4
.IX Item "is_glob_ref(value)"
For a \s-1GLOB\s0 reference.
.IP "is_rx(value)" 4
.IX Item "is_rx(value)"
For a regular expression reference generated by the \f(CW\*(C`qr//\*(C'\fR operator.
.IP "is_instance(value, class)" 4
.IX Item "is_instance(value, class)"
For an instance of \fIclass\fR.
.Sp
It is equivalent to something like
\&\f(CW\*(C`Scalar::Util::blessed($value) && $value\->isa($class)\*(C'\fR.
.IP "is_invocant(value)" 4
.IX Item "is_invocant(value)"
For an invocant, i.e. a blessed reference or existent package name.
.Sp
If \fIvalue\fR is a valid class name but does not exist, it will return false.
.IP "is_value(value)" 4
.IX Item "is_value(value)"
Checks whether \fIvalue\fR is a primitive value, i.e. a defined, non-ref, and
non-type-glob value.
.Sp
This function has no counterpart for validation.
.IP "is_string(value)" 4
.IX Item "is_string(value)"
Checks whether \fIvalue\fR is a string with non-zero-length contents,
equivalent to \f(CW\*(C`is_value($value) && length($value) > 0\*(C'\fR.
.Sp
This function has no counterpart for validation.
.IP "is_number(value)" 4
.IX Item "is_number(value)"
Checks whether \fIvalue\fR is a number.
Here, a \fBnumber\fR means that the perl parser can understand it and that
the perl numeric converter (e.g. invoked by \f(CW\*(C`sprintf \*(Aq%g\*(Aq, $value\*(C'\fR)
doesn't complain about it.
.Sp
It is similar to \f(CW\*(C`Scalar::Util::looks_like_number()\*(C'\fR
but refuses \f(CW\*(C`infinity\*(C'\fR, \f(CW\*(C`not a number\*(C'\fR and \f(CW"0 but true"\fR.
Note that \f(CW\*(C`9**9**9\*(C'\fR makes \f(CW\*(C`infinity\*(C'\fR and \f(CW\*(C`9**9**9 \- 9**9**9\*(C'\fR makes
\&\f(CW\*(C`not a number\*(C'\fR.
.Sp
This function has no counterpart for validation.
.IP "is_integer(value)" 4
.IX Item "is_integer(value)"
Checks whether \fIvalue\fR is an integer.
An \fBinteger\fR is also a \fBnumber\fR, so this function
refuses \f(CW\*(C`infinity\*(C'\fR and \f(CW\*(C`not a number\*(C'\fR. See also \f(CW\*(C`is_number()\*(C'\fR.
.Sp
This function has no counterpart for validation.
.SS "Validating functions"
.IX Subsection "Validating functions"
Validating functions are introduced by the \f(CW\*(C`:validate\*(C'\fR tag which check the
argument and returns the first argument.
These are like the \f(CW\*(C`:check\*(C'\fR functions but dies if the argument type
is invalid.
.PP
These functions also checks overloading magic, e.g. \f(CW\*(C`${}\*(C'\fR for a \s-1SCALAR\s0 reference.
.IP "scalar_ref(value)" 4
.IX Item "scalar_ref(value)"
For a \s-1SCALAR\s0 reference.
.IP "array_ref(value)" 4
.IX Item "array_ref(value)"
For an \s-1ARRAY\s0 reference.
.IP "hash_ref(value)" 4
.IX Item "hash_ref(value)"
For a \s-1HASH\s0 reference.
.IP "code_ref(value)" 4
.IX Item "code_ref(value)"
For a \s-1CODE\s0 reference.
.IP "glob_ref(value)" 4
.IX Item "glob_ref(value)"
For a \s-1GLOB\s0 reference.
.IP "rx(value)" 4
.IX Item "rx(value)"
For a regular expression reference.
.IP "instance(value, class)" 4
.IX Item "instance(value, class)"
For an instance of \fIclass\fR.
.IP "invocant(value)" 4
.IX Item "invocant(value)"
For an invocant, i.e. a blessed reference or existent package name.
.Sp
If \fIvalue\fR is a valid class name and the class exists, then it returns
the canonical class name, which is logically cleaned up. That is, it does
\&\f(CW\*(C`$value =~ s/^::(?:main::)*//;\*(C'\fR before returns it.
.Sp
\&\s-1NOTE:\s0
The canonization is because some versions of perl has an inconsistency
on package names:
.Sp
.Vb 3
\&        package ::Foo; # OK
\&        my $x = bless {}, \*(Aq::Foo\*(Aq; # OK
\&        ref($x)\->isa(\*(AqFoo\*(Aq); # Fatal
.Ve
.Sp
The last sentence causes a fatal error:
\&\f(CW\*(C`Can\*(Aqt call method "isa" without package or object reference\*(C'\fR.
However, \f(CW\*(C`invocant(ref $x)\->isa(\*(AqFoo\*(Aq)\*(C'\fR is always \s-1OK\s0.
.SS "Miscellaneous utilities"
.IX Subsection "Miscellaneous utilities"
There are some other utility functions you can import from this module.
.IP "\fIanon_scalar()\fR" 4
.IX Item "anon_scalar()"
Generates an anonymous scalar reference to \f(CW\*(C`undef\*(C'\fR.
.IP "anon_scalar(value)" 4
.IX Item "anon_scalar(value)"
Generates an anonymous scalar reference to the copy of \fIvalue\fR.
.Sp
It is equivalent to \f(CW\*(C`do{ my $tmp = $value; \e$tmp; }\*(C'\fR.
.IP "neat(value)" 4
.IX Item "neat(value)"
Returns a neat string that is suitable to display.
.Sp
This is a smart version of \f(CW\*(C`<do{ defined($value) ? qq{"$value"} : \*(Aqundef\*(Aq }\*(C'\fR>.
.IP "get_stash(invocant)" 4
.IX Item "get_stash(invocant)"
Returns the symbol table hash (also known as \fBstash\fR) of \fIinvocant\fR
if the stash exists.
.IP "install_subroutine(package, name => subr [, ...])" 4
.IX Item "install_subroutine(package, name => subr [, ...])"
Installs \fIsubr\fR into \fIpackage\fR as \fIname\fR.
.Sp
It is similar to
\&\f(CW\*(C`do{ no strict \*(Aqrefs\*(Aq; *{$package.\*(Aq::\*(Aq.$name} = \e&subr; }\*(C'\fR.
In addition, if \fIsubr\fR is an anonymous subroutine, it is located into
\&\fIpackage\fR as a named subroutine \fI&package::name\fR.
.Sp
For example:
.Sp
.Vb 5
\&        install_subroutine($pkg,   say => sub{ print @_, "\en" });
\&        install_subroutine($pkg,
\&                one => \e&_one,
\&                two => \e&_two,
\&        );
\&
\&        # accepts a HASH reference
\&        install_subroutine($pkg, { say => sub{ print @_, "\en" }); #
.Ve
.Sp
To re-install \fIsubr\fR, use \f(CW\*(C`no warnings \*(Aqredefine\*(Aq\*(C'\fR directive:
.Sp
.Vb 2
\&        no warnings \*(Aqredefine\*(Aq;
\&        install_subroutine($package, $name => $subr);
.Ve
.IP "uninstall_subroutine(package, names...)" 4
.IX Item "uninstall_subroutine(package, names...)"
Uninstalls \fInames\fR from \fIpackage\fR.
.Sp
It is similar to \f(CW\*(C`Sub::Delete::delete_sub()\*(C'\fR, but uninstall multiple
subroutines at a time.
.Sp
If you want to specify deleted subroutines, you can supply 
\&\f(CW\*(C`name => \e&subr\*(C'\fR pairs.
.Sp
For example:
.Sp
.Vb 1
\&        uninstall_subroutine(\*(AqFoo\*(Aq, \*(Aqhello\*(Aq);
\&
\&        uninstall_subroutine(\*(AqFoo\*(Aq, hello => \e&Bar::hello);
\&
\&        uninstall_subroutine($pkg,
\&                one => \e&_one,
\&                two => \e&_two,
\&        );
\&
\&        # accepts a HASH reference
\&        uninstall_subroutine(\e$pkg, { hello => \e&Bar::hello });
.Ve
.IP "get_code_info(subr)" 4
.IX Item "get_code_info(subr)"
Returns a pair of elements, the package name and the subroutine name of \fIsubr\fR.
.Sp
It is similar to \f(CW\*(C`Sub::Identify::get_code_info()\*(C'\fR, but it returns the fully
qualified name in scalar context.
.IP "get_code_ref(package, name, flag?)" 4
.IX Item "get_code_ref(package, name, flag?)"
Returns \fI&package::name\fR if it exists, not touching the symbol in the stash.
.Sp
if \fIflag\fR is a string \f(CW\*(C`\-create\*(C'\fR, it returns \fI&package::name\fR regardless of
its existence. That is, it is equivalent to
\&\f(CW\*(C`do{ no strict \*(Aqrefs\*(Aq; \e&{package . \*(Aq::\*(Aq . $name} }\*(C'\fR.
.Sp
For example:
.Sp
.Vb 2
\&        $code = get_code_ref($pkg, $name);          # like  *{$pkg.\*(Aq::\*(Aq.$name}{CODE}
\&        $code = get_code_ref($pkg, $name, \-create); # like \e&{$pkg.\*(Aq::\*(Aq.$name}
.Ve
.IP "curry(subr, args and/or placeholders)" 4
.IX Item "curry(subr, args and/or placeholders)"
Makes \fIsubr\fR curried and returns the curried subroutine.
.Sp
This is also considered as lightweight closures.
.Sp
See also Data::Util::Curry.
.IP "modify_subroutine(subr, ...)" 4
.IX Item "modify_subroutine(subr, ...)"
Modifies \fIsubr\fR with subroutine modifiers and returns the modified subroutine.
This is also considered as lightweight closures.
.Sp
\&\fIsubr\fR must be a code reference or callable object.
.Sp
Optional arguments:
\&\f(CW\*(C`before => [subroutine(s)]\*(C'\fR called before \fIsubr\fR.
\&\f(CW\*(C`around => [subroutine(s)]\*(C'\fR called around \fIsubr\fR.
\&\f(CW\*(C`after  => [subroutine(s)]\*(C'\fR called after  \fIsubr\fR.
.Sp
This seems a constructor of modified subroutines and
\&\f(CW\*(C`subroutine_modifier()\*(C'\fR is property accessors, but it does not bless the 
modified subroutines.
.IP "subroutine_modifier(subr)" 4
.IX Item "subroutine_modifier(subr)"
Returns whether \fIsubr\fR is a modified subroutine.
.IP "subroutine_modifier(modified_subr, property)" 4
.IX Item "subroutine_modifier(modified_subr, property)"
Gets \fIproperty\fR from \fImodified\fR.
.Sp
Valid properties are: \f(CW\*(C`before\*(C'\fR, \f(CW\*(C`around\*(C'\fR, \f(CW\*(C`after\*(C'\fR.
.IP "subroutine_modifier(modified_subr, modifier => [subroutine(s)])" 4
.IX Item "subroutine_modifier(modified_subr, modifier => [subroutine(s)])"
Adds subroutine \fImodifier\fR to \fImodified_subr\fR.
.Sp
Valid modifiers are: \f(CW\*(C`before\*(C'\fR, \f(CW\*(C`around\*(C'\fR, \f(CW\*(C`after\*(C'\fR.
.IP "mkopt(input, moniker, require_unique, must_be)" 4
.IX Item "mkopt(input, moniker, require_unique, must_be)"
Produces an array of an array reference from \fIinput\fR.
.Sp
It is compatible with \f(CW\*(C`Data::OptList::mkopt()\*(C'\fR. In addition to it,
\&\fImust_be\fR can be a \s-1HASH\s0 reference with \f(CW\*(C`name => type\*(C'\fR pairs.
.Sp
For example:
.Sp
.Vb 2
\&        my $optlist = mkopt([\*(Aqfoo\*(Aq, bar => [42]], $moniker, $uniq, { bar => \*(AqARRAY\*(Aq });
\&        # $optlist == [[foo => undef], [bar => [42]]
.Ve
.IP "mkopt_hash(input, moniker, must_be)" 4
.IX Item "mkopt_hash(input, moniker, must_be)"
Produces a hash reference from \fIinput\fR.
.Sp
It is compatible with \f(CW\*(C`Data::OptList::mkopt_hash()\*(C'\fR. In addition to it,
\&\fImust_be\fR can be a \s-1HASH\s0 reference with \f(CW\*(C`name => type\*(C'\fR pairs.
.Sp
For example:
.Sp
.Vb 2
\&        my $optlist = mkopt([\*(Aqfoo\*(Aq, bar => [42]], $moniker, { bar => \*(AqARRAY\*(Aq });
\&        # $optlist == {foo => undef, bar => [42]}
.Ve
.SH "ENVIRONMENT VARIABLES"
.IX Header "ENVIRONMENT VARIABLES"
.SS "\s-1DATA_UTIL_PUREPERL\s0"
.IX Subsection "DATA_UTIL_PUREPERL"
If true, \f(CW\*(C`Data::Util\*(C'\fR uses the Pure Perl implementation.
.SH "DEPENDENCIES"
.IX Header "DEPENDENCIES"
Perl 5.8.1 or later.
.PP
If you have a C compiler, you can use the \s-1XS\s0 backend,
but the Pure Perl backend is also available if you have no C compilers.
.SH "BUGS AND LIMITATIONS"
.IX Header "BUGS AND LIMITATIONS"
No bugs have been reported.
.PP
Please report any bugs or feature requests to the author.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Scalar::Util.
.PP
overload.
.PP
Params::Util.
.PP
Sub::Install.
.PP
Sub::Identify.
.PP
Sub::Delete.
.PP
Sub::Curry.
.PP
Class::MOP.
.PP
Class::Method::Modifiers.
.PP
Data::OptList.
.PP
Mouse
.SH "AUTHOR"
.IX Header "AUTHOR"
Goro Fuji(gfx) <gfuji(at)cpan.org>.
.SH "LICENSE AND COPYRIGHT"
.IX Header "LICENSE AND COPYRIGHT"
Copyright (c) 2008\-2010, Goro Fuji <gfuji(at)cpan.org>. All rights reserved.
.PP
This module is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.