.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" 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" ''
.    ds C`
.    ds C'
'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 >0, 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.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" 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 "Catmandu::Util 3pm"
.TH Catmandu::Util 3pm "2019-01-29" "perl v5.28.1" "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"
Catmandu::Util \- A collection of utility functions
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use Catmandu::Util qw(:string);
\&
\&    $str = trim($str);
.Ve
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
.SS "\s-1IO\s0 functions"
.IX Subsection "IO functions"
.Vb 1
\&    use Catmandu::Util qw(:io);
.Ve
.ie n .IP "io($io, %opts)" 4
.el .IP "io($io, \f(CW%opts\fR)" 4
.IX Item "io($io, %opts)"
Takes a file path, glob, glob reference, scalar reference or IO::Handle
object and returns an opened IO::Handle object.
.Sp
.Vb 1
\&    my $fh = io \*(Aq/path/to/file\*(Aq;
\&
\&    my $fh = io *STDIN;
\&
\&    my $fh = io \e*STDOUT, mode => \*(Aqw\*(Aq, binmode => \*(Aq:crlf\*(Aq;
\&
\&    my $write_cb = sub { my $str = $_[0]; ... };
\&
\&    my $fh = io $write_cb, mode => \*(Aqw\*(Aq;
\&
\&    my $scalar = "";
\&    my $fh = io \e$scalar, mode => \*(Aqw\*(Aq;
\&    $fh\->print("some text");
.Ve
.Sp
Options are:
.RS 4
.IP "mode" 12
.IX Item "mode"
Default is \f(CW"r"\fR.
.IP "binmode" 12
.IX Item "binmode"
Default is \f(CW":encoding(UTF\-8)"\fR.
.IP "encoding" 12
.IX Item "encoding"
Alias for \f(CW\*(C`binmode\*(C'\fR.
.RE
.RS 4
.RE
.IP "read_file($path);" 4
.IX Item "read_file($path);"
[deprecated]: use tools like Path::Tiny instead.
.Sp
Reads the file at \f(CW$path\fR into a string.
.Sp
.Vb 1
\&    my $str = read_file(\*(Aq/path/to/file.txt\*(Aq);
.Ve
.Sp
Throws a Catmandu::Error on failure.
.IP "read_io($io)" 4
.IX Item "read_io($io)"
Reads an IO::Handle into a string.
.Sp
.Vb 1
\&   my $str = read_file($fh);
.Ve
.ie n .IP "write_file($path, $str);" 4
.el .IP "write_file($path, \f(CW$str\fR);" 4
.IX Item "write_file($path, $str);"
[deprecated]: use tools like use tools like File::Slurp::Tiny instead.
.Sp
Writes the string \f(CW$str\fR to a file at \f(CW$path\fR.
.Sp
.Vb 1
\&    write_file(\*(Aq/path/to/file.txt\*(Aq, "contents");
.Ve
.Sp
Throws a Catmandu::Error on failure.
.IP "read_yaml($path);" 4
.IX Item "read_yaml($path);"
Reads the \s-1YAML\s0 file at \f(CW$path\fR into a Perl hash.
.Sp
.Vb 1
\&    my $cfg = read_yaml($path);
.Ve
.Sp
Dies on failure reading the file or parsing the \s-1YAML.\s0
.IP "read_json($path);" 4
.IX Item "read_json($path);"
Reads the \s-1JSON\s0 file at \f(CW$path\fR into a Perl hash.
.Sp
.Vb 1
\&    my $cfg = read_json($path);
.Ve
.Sp
Dies on failure reading the file or parsing the \s-1JSON.\s0
.IP "join_path(@path);" 4
.IX Item "join_path(@path);"
Joins relative paths into an absolute path.
.Sp
.Vb 2
\&    join_path(\*(Aq/path/..\*(Aq, \*(Aq./to\*(Aq, \*(Aqfile.txt\*(Aq);
\&    # => "/to/file.txt"
.Ve
.IP "normalize_path($path);" 4
.IX Item "normalize_path($path);"
Normalizes a relative path to an absolute path.
.Sp
.Vb 2
\&    normalize_path(\*(Aq/path/../to/./file.txt\*(Aq);
\&    # => "/to/file.txt"
.Ve
.IP "segmented_path($path);" 4
.IX Item "segmented_path($path);"
.Vb 5
\&    my $id = "FB41144C\-F0ED\-11E1\-A9DE\-61C894A0A6B4";
\&    segmented_path($id, segment_size => 4);
\&    # => "FB41/144C/F0ED/11E1/A9DE/61C8/94A0/A6B4"
\&    segmented_path($id, segment_size => 2, base_path => "/files");
\&    # => "/files/FB/41/14/4C/F0/ED/11/E1/A9/DE/61/C8/94/A0/A6/B4"
.Ve
.IP "content_type($filename);" 4
.IX Item "content_type($filename);"
Guess the content type of a file name.
.Sp
.Vb 2
\&    content_type("book.pdf");
\&    # => "application/pdf"
.Ve
.SS "Hash functions"
.IX Subsection "Hash functions"
.Vb 1
\&    use Catmandu::Util qw(:hash);
.Ve
.PP
A collection of functions that operate on hash references.
.ie n .IP "hash_merge($hash1, $hash2, ... , $hashN)" 4
.el .IP "hash_merge($hash1, \f(CW$hash2\fR, ... , \f(CW$hashN\fR)" 4
.IX Item "hash_merge($hash1, $hash2, ... , $hashN)"
Merge <hash1> through <hashN>,  with the nth-most (rightmost) hash taking precedence.
Returns a new hash reference representing the merge.
.Sp
.Vb 2
\&    hash_merge({a => 1}, {b => 2}, {a => 3});
\&    # => { a => 3 , b => 2}
.Ve
.SS "Array functions"
.IX Subsection "Array functions"
.Vb 1
\&    use Catmandu::Util qw(:array);
.Ve
.PP
A collection of functions that operate on array references.
.ie n .IP "array_exists($array, $index)" 4
.el .IP "array_exists($array, \f(CW$index\fR)" 4
.IX Item "array_exists($array, $index)"
Returns \f(CW1\fR if \f(CW$index\fR is in the bounds of \f(CW$array\fR
.Sp
.Vb 4
\&    array_exists(["a", "b"], 2);
\&    # => 0
\&    array_exists(["a", "b"], 1);
\&    # => 1
.Ve
.ie n .IP "array_group_by($array, $key)" 4
.el .IP "array_group_by($array, \f(CW$key\fR)" 4
.IX Item "array_group_by($array, $key)"
.Vb 7
\&    my $list = [{color => \*(Aqblack\*(Aq, id => 1},
\&                {color => \*(Aqwhite\*(Aq, id => 2},
\&                {id => 3},
\&                {color => \*(Aqblack\*(Aq, id => 4}];
\&    array_group_by($list, \*(Aqcolor\*(Aq);
\&    # => {black => [{color => \*(Aqblack\*(Aq, id => 1}, {color => \*(Aqblack\*(Aq, id => 4}],
\&    #     white => [{color => \*(Aqwhite\*(Aq, id => 2}]}
.Ve
.ie n .IP "array_pluck($array, $key)" 4
.el .IP "array_pluck($array, \f(CW$key\fR)" 4
.IX Item "array_pluck($array, $key)"
.Vb 3
\&    my $list = [{id => 1}, {}, {id => 3}];
\&    array_pluck($list, \*(Aqid\*(Aq);
\&    # => [1, undef, 3]
.Ve
.IP "array_to_sentence($array)" 4
.IX Item "array_to_sentence($array)"
.PD 0
.ie n .IP "array_to_sentence($array, $join)" 4
.el .IP "array_to_sentence($array, \f(CW$join\fR)" 4
.IX Item "array_to_sentence($array, $join)"
.ie n .IP "array_to_sentence($array, $join, $join_last)" 4
.el .IP "array_to_sentence($array, \f(CW$join\fR, \f(CW$join_last\fR)" 4
.IX Item "array_to_sentence($array, $join, $join_last)"
.PD
.Vb 6
\&    array_to_sentence([1,2,3]);
\&    # => "1, 2 and 3"
\&    array_to_sentence([1,2,3], ",");
\&    # => "1,2 and 3"
\&    array_to_sentence([1,2,3], ",", " & ");
\&    # => "1,2 & 3"
.Ve
.IP "array_sum($array)" 4
.IX Item "array_sum($array)"
.Vb 2
\&    array_sum([1,2,3]);
\&    # => 6
.Ve
.ie n .IP "array_includes($array, $val)" 4
.el .IP "array_includes($array, \f(CW$val\fR)" 4
.IX Item "array_includes($array, $val)"
Returns 1 if \f(CW$array\fR includes a value that is deeply equal to \f(CW$val\fR, 0
otherwise. Comparison is done with \f(CW\*(C`is_same()\*(C'\fR.
.Sp
.Vb 4
\&    array_includes([{color => \*(Aqblack\*(Aq}], {color => \*(Aqwhite\*(Aq});
\&    # => 0
\&    array_includes([{color => \*(Aqblack\*(Aq}], {color => \*(Aqblack\*(Aq});
\&    # => 1
.Ve
.IP "array_any($array, \e&sub)" 4
.IX Item "array_any($array, &sub)"
.Vb 2
\&    array_any(["green", "blue"], sub { my $color = $_[0]; $color eq "blue" });
\&    # => 1
.Ve
.IP "array_rest($array)" 4
.IX Item "array_rest($array)"
Returns a copy of \f(CW$array\fR without the head.
.Sp
.Vb 4
\&    array_rest([1,2,3,4]);
\&    # => [2,3,4]
\&    array_rest([1]);
\&    # => []
.Ve
.IP "array_uniq($array)" 4
.IX Item "array_uniq($array)"
Returns a copy of \f(CW$array\fR with all duplicates removed.
.ie n .IP "array_split($array | $string)" 4
.el .IP "array_split($array | \f(CW$string\fR)" 4
.IX Item "array_split($array | $string)"
Returns \f(CW$array\fR or a new array by splitting \f(CW$string\fR at commas.
.SS "String functions"
.IX Subsection "String functions"
.Vb 1
\&    use Catmandu::Util qw(:string);
.Ve
.IP "as_utf8($str)" 4
.IX Item "as_utf8($str)"
Returns a copy of \f(CW$str\fR flagged as \s-1UTF\-8.\s0
.IP "trim($str)" 4
.IX Item "trim($str)"
Returns a copy of \f(CW$str\fR with leading and trailing whitespace removed.
.IP "capitalize($str)" 4
.IX Item "capitalize($str)"
Equivalent to \f(CW\*(C`ucfirst lc as_utf8 $str\*(C'\fR.
.SS "Is functions"
.IX Subsection "Is functions"
.Vb 1
\&    use Catmandu::Util qw(:is);
\&
\&    is_number(42) ? "it\*(Aqs numeric" : "it\*(Aqs not numeric";
\&
\&    is_maybe_hash_ref({});
\&    # => 1
\&    is_maybe_hash_ref(undef);
\&    # => 1
\&    is_maybe_hash_ref([]);
\&    # => 0
.Ve
.PP
A collection of predicate functions that test the type or value of argument
\&\f(CW$val\fR.  Each function (except \f(CW\*(C`is_same()\*(C'\fR and \f(CW\*(C`is_different\*(C'\fR) also has a
\&\fImaybe\fR variant that also tests true if \f(CW$val\fR is undefined.
Returns \f(CW1\fR or \f(CW0\fR.
.IP "is_invocant($val)" 4
.IX Item "is_invocant($val)"
.PD 0
.IP "is_maybe_invocant($val)" 4
.IX Item "is_maybe_invocant($val)"
.PD
Tests if \f(CW$val\fR is callable (is an existing package or blessed object).
.ie n .IP "is_able($val, @method_names)" 4
.el .IP "is_able($val, \f(CW@method_names\fR)" 4
.IX Item "is_able($val, @method_names)"
.PD 0
.ie n .IP "is_maybe_able($val, @method_names)" 4
.el .IP "is_maybe_able($val, \f(CW@method_names\fR)" 4
.IX Item "is_maybe_able($val, @method_names)"
.PD
Tests if \f(CW$val\fR is callable and has all methods in \f(CW@method_names\fR.
.ie n .IP "is_instance($val, @class_names)" 4
.el .IP "is_instance($val, \f(CW@class_names\fR)" 4
.IX Item "is_instance($val, @class_names)"
.PD 0
.ie n .IP "is_maybe_instance($val, @class_names)" 4
.el .IP "is_maybe_instance($val, \f(CW@class_names\fR)" 4
.IX Item "is_maybe_instance($val, @class_names)"
.PD
Tests if \f(CW$val\fR is a blessed object and an instance of all the classes
in \f(CW@class_names\fR.
.IP "is_ref($val)" 4
.IX Item "is_ref($val)"
.PD 0
.IP "is_maybe_ref($val)" 4
.IX Item "is_maybe_ref($val)"
.PD
Tests if \f(CW$val\fR is a reference. Equivalent to \f(CW\*(C`ref $val ? 1 : 0\*(C'\fR.
.IP "is_scalar_ref($val)" 4
.IX Item "is_scalar_ref($val)"
.PD 0
.IP "is_maybe_scalar_ref($val)" 4
.IX Item "is_maybe_scalar_ref($val)"
.PD
Tests if \f(CW$val\fR is a scalar reference.
.IP "is_array_ref($val)" 4
.IX Item "is_array_ref($val)"
.PD 0
.IP "is_maybe_array_ref($val)" 4
.IX Item "is_maybe_array_ref($val)"
.PD
Tests if \f(CW$val\fR is an array reference.
.IP "is_hash_ref($val)" 4
.IX Item "is_hash_ref($val)"
.PD 0
.IP "is_maybe_hash_ref($val)" 4
.IX Item "is_maybe_hash_ref($val)"
.PD
Tests if \f(CW$val\fR is a hash reference.
.IP "is_code_ref($val)" 4
.IX Item "is_code_ref($val)"
.PD 0
.IP "is_maybe_code_ref($val)" 4
.IX Item "is_maybe_code_ref($val)"
.PD
Tests if \f(CW$val\fR is a subroutine reference.
.IP "is_regex_ref($val)" 4
.IX Item "is_regex_ref($val)"
.PD 0
.IP "is_maybe_regex_ref($val)" 4
.IX Item "is_maybe_regex_ref($val)"
.PD
Tests if \f(CW$val\fR is a regular expression reference generated by the \f(CW\*(C`qr//\*(C'\fR
operator.
.IP "is_glob_ref($val)" 4
.IX Item "is_glob_ref($val)"
.PD 0
.IP "is_maybe_glob_ref($val)" 4
.IX Item "is_maybe_glob_ref($val)"
.PD
Tests if \f(CW$val\fR is a glob reference.
.IP "is_value($val)" 4
.IX Item "is_value($val)"
.PD 0
.IP "is_maybe_value($val)" 4
.IX Item "is_maybe_value($val)"
.PD
Tests if \f(CW$val\fR is a real value (defined, not a reference and not a
glob.
.IP "is_string($val)" 4
.IX Item "is_string($val)"
.PD 0
.IP "is_maybe_string($val)" 4
.IX Item "is_maybe_string($val)"
.PD
Tests if \f(CW$val\fR is a non-empty string.
Equivalent to \f(CW\*(C`is_value($val) && length($val) > 0\*(C'\fR.
.IP "is_number($val)" 4
.IX Item "is_number($val)"
.PD 0
.IP "is_maybe_number($val)" 4
.IX Item "is_maybe_number($val)"
.PD
Tests if \f(CW$val\fR is a number.
.IP "is_integer($val)" 4
.IX Item "is_integer($val)"
.PD 0
.IP "is_maybe_integer($val)" 4
.IX Item "is_maybe_integer($val)"
.PD
Tests if \f(CW$val\fR is an integer.
.IP "is_natural($val)" 4
.IX Item "is_natural($val)"
.PD 0
.IP "is_maybe_natural($val)" 4
.IX Item "is_maybe_natural($val)"
.PD
Tests if \f(CW$val\fR is a non-negative integer.
Equivalent to \f(CW\*(C`is_integer($val) && $val >= 0\*(C'\fR.
.IP "is_positive($val)" 4
.IX Item "is_positive($val)"
.PD 0
.IP "is_maybe_positive($val)" 4
.IX Item "is_maybe_positive($val)"
.PD
Tests if \f(CW$val\fR is a positive integer.
Equivalent to \f(CW\*(C`is_integer($val) && $val >= 1\*(C'\fR.
.ie n .IP "is_same($val, $other_val)" 4
.el .IP "is_same($val, \f(CW$other_val\fR)" 4
.IX Item "is_same($val, $other_val)"
Tests if \f(CW$val\fR is deeply equal to \f(CW$other_val\fR.
.ie n .IP "is_different($val, $other_val)" 4
.el .IP "is_different($val, \f(CW$other_val\fR)" 4
.IX Item "is_different($val, $other_val)"
The opposite of \f(CW\*(C`is_same()\*(C'\fR.
.SS "Check functions"
.IX Subsection "Check functions"
.Vb 1
\&    use Catmandu::Util qw(:check);
\&
\&    check_hash_ref({color => \*(Aqred\*(Aq});
\&    # => {color => \*(Aqred\*(Aq}
\&    check_hash_ref([]);
\&    # dies
.Ve
.PP
A group of assert functions similar to the \f(CW\*(C`:is\*(C'\fR group, but instead of
returning true or false they return their argument or die.
.IP "check_invocant($val)" 4
.IX Item "check_invocant($val)"
.PD 0
.IP "check_maybe_invocant($val)" 4
.IX Item "check_maybe_invocant($val)"
.ie n .IP "check_able($val, @method_names)" 4
.el .IP "check_able($val, \f(CW@method_names\fR)" 4
.IX Item "check_able($val, @method_names)"
.ie n .IP "check_maybe_able($val, @method_names)" 4
.el .IP "check_maybe_able($val, \f(CW@method_names\fR)" 4
.IX Item "check_maybe_able($val, @method_names)"
.ie n .IP "check_instance($val, @class_names)" 4
.el .IP "check_instance($val, \f(CW@class_names\fR)" 4
.IX Item "check_instance($val, @class_names)"
.ie n .IP "check_maybe_instance($val, @class_names)" 4
.el .IP "check_maybe_instance($val, \f(CW@class_names\fR)" 4
.IX Item "check_maybe_instance($val, @class_names)"
.IP "check_ref($val)" 4
.IX Item "check_ref($val)"
.IP "check_maybe_ref($val)" 4
.IX Item "check_maybe_ref($val)"
.IP "check_scalar_ref($val)" 4
.IX Item "check_scalar_ref($val)"
.IP "check_maybe_scalar_ref($val)" 4
.IX Item "check_maybe_scalar_ref($val)"
.IP "check_array_ref($val)" 4
.IX Item "check_array_ref($val)"
.IP "check_maybe_array_ref($val)" 4
.IX Item "check_maybe_array_ref($val)"
.IP "check_hash_ref($val)" 4
.IX Item "check_hash_ref($val)"
.IP "check_maybe_hash_ref($val)" 4
.IX Item "check_maybe_hash_ref($val)"
.IP "check_code_ref($val)" 4
.IX Item "check_code_ref($val)"
.IP "check_maybe_code_ref($val)" 4
.IX Item "check_maybe_code_ref($val)"
.IP "check_regex_ref($val)" 4
.IX Item "check_regex_ref($val)"
.IP "check_maybe_regex_ref($val)" 4
.IX Item "check_maybe_regex_ref($val)"
.IP "check_glob_ref($val)" 4
.IX Item "check_glob_ref($val)"
.IP "check_maybe_glob_ref($val)" 4
.IX Item "check_maybe_glob_ref($val)"
.IP "check_value($val)" 4
.IX Item "check_value($val)"
.IP "check_maybe_value($val)" 4
.IX Item "check_maybe_value($val)"
.IP "check_string($val)" 4
.IX Item "check_string($val)"
.IP "check_maybe_string($val)" 4
.IX Item "check_maybe_string($val)"
.IP "check_number($val)" 4
.IX Item "check_number($val)"
.IP "check_maybe_number($val)" 4
.IX Item "check_maybe_number($val)"
.IP "check_integer($val)" 4
.IX Item "check_integer($val)"
.IP "check_maybe_integer($val)" 4
.IX Item "check_maybe_integer($val)"
.IP "check_natural($val)" 4
.IX Item "check_natural($val)"
.IP "check_maybe_natural($val)" 4
.IX Item "check_maybe_natural($val)"
.IP "check_positive($val)" 4
.IX Item "check_positive($val)"
.IP "check_maybe_positive($val)" 4
.IX Item "check_maybe_positive($val)"
.ie n .IP "check_same($val, $other_val)" 4
.el .IP "check_same($val, \f(CW$other_val\fR)" 4
.IX Item "check_same($val, $other_val)"
.ie n .IP "check_different($val, $other_val)" 4
.el .IP "check_different($val, \f(CW$other_val\fR)" 4
.IX Item "check_different($val, $other_val)"
.PD
.SS "Human output functions"
.IX Subsection "Human output functions"
.Vb 1
\&    use Catmandu::Util qw(:human);
.Ve
.IP "human_number($num)" 4
.IX Item "human_number($num)"
Insert a comma a 3\-digit intervals to make \f(CW$num\fR more readable. Only works
with \fIintegers\fR for now.
.Sp
.Vb 2
\&    human_number(64354);
\&    # => "64,354"
.Ve
.IP "human_byte_size($size)" 4
.IX Item "human_byte_size($size)"
.Vb 4
\&    human_byte_size(64);
\&    # => "64 bytes"
\&    human_byte_size(10005000);
\&    # => "10.01 MB"
.Ve
.IP "human_content_type($content_type)" 4
.IX Item "human_content_type($content_type)"
.PD 0
.ie n .IP "human_content_type($content_type, $default)" 4
.el .IP "human_content_type($content_type, \f(CW$default\fR)" 4
.IX Item "human_content_type($content_type, $default)"
.PD
.Vb 8
\&    human_content_type(\*(Aqapplication/x\-dos_ms_excel\*(Aq);
\&    # => "Excel"
\&    human_content_type(\*(Aqapplication/zip\*(Aq);
\&    # => "ZIP archive"
\&    human_content_type(\*(Aqfoo/x\-unknown\*(Aq);
\&    # => "foo/x\-unknown"
\&    human_content_type(\*(Aqfoo/x\-unknown\*(Aq, \*(AqUnknown\*(Aq);
\&    # => "Unknown"
.Ve
.SS "\s-1XML\s0 functions"
.IX Subsection "XML functions"
.Vb 1
\&    use Catmandu::Util qw(:xml);
.Ve
.IP "\fBxml_declaration()\fR" 4
.IX Item "xml_declaration()"
Returns \f(CW\*(C`qq(<?xml version="1.0" encoding="UTF\-8"?>\en)\*(C'\fR.
.IP "xml_escape($str)" 4
.IX Item "xml_escape($str)"
Returns an \s-1XML\s0 escaped copy of \f(CW$str\fR.
.SS "Miscellaneous functions"
.IX Subsection "Miscellaneous functions"
.IP "require_package($pkg)" 4
.IX Item "require_package($pkg)"
.PD 0
.ie n .IP "require_package($pkg, $namespace)" 4
.el .IP "require_package($pkg, \f(CW$namespace\fR)" 4
.IX Item "require_package($pkg, $namespace)"
.PD
Load package \f(CW$pkg\fR at runtime with \f(CW\*(C`require\*(C'\fR and return it's full name.
.Sp
.Vb 2
\&    my $pkg = require_package(\*(AqFile::Spec\*(Aq);
\&    my $dir = $pkg\->tmpdir();
\&
\&    require_package(\*(AqUtil\*(Aq, \*(AqCatmandu\*(Aq);
\&    # => "Catmandu::Util"
\&    require_package(\*(AqCatmandu::Util\*(Aq, \*(AqCatmandu\*(Aq);
\&    # => "Catmandu::Util"
.Ve
.Sp
Throws a Catmandu::Error on failure.
.IP "use_lib(@dirs)" 4
.IX Item "use_lib(@dirs)"
Add directories to \f(CW@INC\fR at runtime.
.Sp
Throws a Catmandu::Error on failure.
.ie n .IP "pod_section($package_or_file, $section [, @options] )" 4
.el .IP "pod_section($package_or_file, \f(CW$section\fR [, \f(CW@options\fR] )" 4
.IX Item "pod_section($package_or_file, $section [, @options] )"
Get documentation of a package for a selected section. Additional options are
passed to Pod::Usage.
.IP "now($format)" 4
.IX Item "now($format)"
Returns the current datetime as a string. \f(CW$format\fRcan be any
\&\f(CW\*(C`strftime\*(C'\fR format. There are also 2 builtin formats, \f(CW\*(C`iso_date_time\*(C'\fR
and \f(CW\*(C`iso_date_time_millis\*(C'\fR.  \f(CW\*(C`iso_date_time\*(C'\fR is equivalent to
\&\f(CW\*(C`%Y\-%m\-%dT%H:%M:%SZ\*(C'\fR. \f(CW\*(C`iso_date_time_millis\*(C'\fR is the same, but with
added milliseconds.
.Sp
.Vb 2
\&    now(\*(Aq%Y/%m/%d\*(Aq);
\&    now(\*(Aqiso_date_time_millis\*(Aq);
.Ve
.Sp
The default format is \f(CW\*(C`iso_date_time\*(C'\fR;