<?xml version="1.0" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>Hub::Perl::Language</title>
<link rel="stylesheet" href="../../styles.css" type="text/css" />
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
<link rev="made" href="mailto:Gentoo@livesitemail.(none)" />
</head>
<body>
<p><a name="__index__"></a></p>
<!-- INDEX BEGIN -->
<ul>
<li><a href="#name">NAME</a></li>
<li><a href="#synopsis">SYNOPSIS</a></li>
<li><a href="#description">DESCRIPTION</a></li>
<li><a href="#public_methods">PUBLIC METHODS</a></li>
<ul>
<li><a href="#sizeof">sizeof</a></li>
<li><a href="#check">check</a></li>
<li><a href="#opts">opts</a></li>
<li><a href="#objopts">objopts</a></li>
<li><a href="#cmdopts">cmdopts</a></li>
<li><a href="#hashopts">hashopts</a></li>
<li><a href="#subst">subst</a></li>
<li><a href="#getuid">getuid</a></li>
<li><a href="#getgid">getgid</a></li>
<li><a href="#touch">touch</a></li>
<li><a href="#expect">expect</a></li>
<li><a href="#fear">fear</a></li>
<li><a href="#abort">abort</a></li>
<li><a href="#bestof">bestof</a></li>
<li><a href="#min">min</a></li>
<li><a href="#max">max</a></li>
<li><a href="#intdiv">intdiv</a></li>
<li><a href="#flip">flip</a></li>
<li><a href="#rmval">rmval</a></li>
<li><a href="#cpref">cpref</a></li>
<li><a href="#random_id">random_id</a></li>
<li><a href="#checksum">checksum</a></li>
<li><a href="#merge">merge</a></li>
<li><a href="#flatten">flatten</a></li>
<li><a href="#replace">replace</a></li>
<li><a href="#digout">digout</a></li>
<li><a href="#diff">diff</a></li>
<li><a href="#dice">dice</a></li>
<li><a href="#indexmatch">indexmatch</a></li>
</ul>
<li><a href="#internal_methods">INTERNAL METHODS</a></li>
<ul>
<li><a href="#_assignopt">_assignopt</a></li>
<li><a href="#_merge_hash">_merge_hash</a></li>
<li><a href="#_merge_array">_merge_array</a></li>
<li><a href="#_merge_element">_merge_element</a></li>
<li><a href="#_diff_hashes">_diff_hashes</a></li>
<li><a href="#_diff_arrays">_diff_arrays</a></li>
</ul>
<li><a href="#author">AUTHOR</a></li>
<li><a href="#copyright">COPYRIGHT</a></li>
<li><a href="#updated">UPDATED</a></li>
</ul>
<!-- INDEX END -->
<hr />
<p>
</p>
<h1><a name="name">NAME</a></h1>
<p>Hub::Perl::Language -</p>
<p>
<a href="#__index__"><small>Top</small></a>
</p>
<hr />
<h1><a name="synopsis">SYNOPSIS</a></h1>
<p>
<a href="#__index__"><small>Top</small></a>
</p>
<hr />
<h1><a name="description">DESCRIPTION</a></h1>
<p>
<a href="#__index__"><small>Top</small></a>
</p>
<hr />
<h1><a name="public_methods">PUBLIC METHODS</a></h1>
<p>
</p>
<h2><a name="sizeof">sizeof</a></h2>
<dl>
<dt><strong><a name="item_integer_size_of_hashes_2c_arrays_2c_and_scalars">Integer size of hashes, arrays, and scalars</a></strong>
<dd>
<pre>
Usage: sizeof \%hash
Usage: sizeof \@array
Usage: sizeof \$scalar_ref
Usage: sizeof $scalar
Usage: sizeof \%more, \@than, $one</pre>
</dd>
<dd>
<p>Sizes are computed as follows:</p>
</dd>
<dd>
<pre>
HASH - Number of keys in the hash
ARRAY - Number of elements
SCALAR - Length as returned by C<length()></pre>
</dd>
<dd>
<p>The total size of all arguments is returned.</p>
</dd>
<dd>
<p><strong>Example: Hash</strong>: (matches)</p>
</dd>
<dd>
<pre>
sizeof( { a=>1, b=>2, c=>3 } );</pre>
</dd>
<dd>
<pre>
3</pre>
</dd>
<dd>
<p><strong>Example: Array</strong>: (matches)</p>
</dd>
<dd>
<pre>
sizeof( [ 'a1', 'b2', 'c3' ] );</pre>
</dd>
<dd>
<pre>
3</pre>
</dd>
<dd>
<p><strong>Example: Scalar</strong>: (matches)</p>
</dd>
<dd>
<pre>
sizeof( "abc" );</pre>
</dd>
<dd>
<pre>
3</pre>
</dd>
<dd>
<p><strong>Example: Scalar (ref)</strong>: (matches)</p>
</dd>
<dd>
<pre>
sizeof( \"abc" );</pre>
</dd>
<dd>
<pre>
3</pre>
</dd>
<dd>
<p><strong>Example: Nothing</strong>: (matches)</p>
</dd>
<dd>
<pre>
sizeof( undef );</pre>
</dd>
<dd>
<pre>
0</pre>
</dd>
<dd>
<p><strong>Example: Multiple values</strong>: (matches)</p>
</dd>
<dd>
<pre>
sizeof( "a", "b", "c" );</pre>
</dd>
<dd>
<pre>
3</pre>
</dd>
</dl>
<p>
</p>
<h2><a name="check">check</a></h2>
<dl>
<dt><strong><a name="item_true_if_all_items_in_list_pass_the_test_2e">True if all items in list pass the test.</a></strong>
<dd>
<pre>
Usage: check [OPTIONS], [TEST], LIST</pre>
</dd>
<dd>
<p>OPTIONS:</p>
</dd>
<dd>
<pre>
-opr (or|and|xor) Operator (default: 'and')</pre>
</dd>
<dd>
<p>TEST:</p>
</dd>
<dd>
<pre>
-test (def|num|str|match|blessed|eval) Test type (default: 'def')
-isa EXPR
-ref EXPR</pre>
</dd>
<dd>
<p>OPERATORS:</p>
</dd>
<dd>
<pre>
and True when all items pass the test.</pre>
</dd>
<dd>
<pre>
or True when any single item passes the test.</pre>
</dd>
<dd>
<pre>
xor Alternation pattern. True unless two consecutive values
both pass or fail the test.</pre>
</dd>
<dd>
<p>BASIC TEST:</p>
</dd>
<dd>
<pre>
def Items are defined
num Items are numeric
str Items are *not* numeric</pre>
</dd>
<dd>
<p>OTHER TESTS:</p>
</dd>
<dd>
<pre>
match=EXPR Items match EXPR
eval Items are eval'd and truth is based on $@. Note that the
eval *actually* happens, so don't do anything that will
break your code. The intention of this check is for:</pre>
</dd>
<dd>
<p><strong>Example</strong> returns: <strong>abort</strong>:</p>
</dd>
<dd>
<pre>
my $compression = check( '-test=eval', 'use IO::Zlib' ) ? 1 : 0;</pre>
</dd>
<dd>
<p>STRUCTURE TESTS:</p>
</dd>
<dd>
<pre>
blessed Items are blessed
ref=EXPR Item's ref matches EXPR (does *not* include @ISA)
isa=EXPR Item's ref or @ISA match EXPR. Much like UNIVERSAL::isa
except allows regular expressions.</pre>
</dd>
<dd>
<p><strong>Example: none are defined</strong> returns: <strong>false</strong>:</p>
</dd>
<dd>
<pre>
check( undef, undef, undef );</pre>
</dd>
<dd>
<p><strong>Example: only one is defined</strong> returns: <strong>false</strong>:</p>
</dd>
<dd>
<pre>
check( 1, undef );</pre>
</dd>
<dd>
<p><strong>Example: both are defined</strong> returns: <strong>true</strong>:</p>
</dd>
<dd>
<pre>
check( 1, 1 );</pre>
</dd>
<dd>
<p><strong>Example: one is defined</strong> returns: <strong>true</strong>:</p>
</dd>
<dd>
<pre>
check( 1, undef, -opr => 'or' );</pre>
</dd>
<dd>
<p><strong>Example</strong> returns: <strong>false</strong>:</p>
</dd>
<dd>
<pre>
check( -opr => 'xor', 1, 1 );</pre>
</dd>
<dd>
<p><strong>Example</strong> returns: <strong>false</strong>:</p>
</dd>
<dd>
<pre>
check( -opr => 'xor', undef, undef );</pre>
</dd>
<dd>
<p><strong>Example</strong> returns: <strong>true</strong>:</p>
</dd>
<dd>
<pre>
check( -opr => 'xor', undef, 1 );</pre>
</dd>
<dd>
<p><strong>Example</strong> returns: <strong>true</strong>:</p>
</dd>
<dd>
<pre>
check( -opr => 'xor', 1, undef );</pre>
</dd>
<dd>
<p><strong>Example</strong> returns: <strong>true</strong>:</p>
</dd>
<dd>
<pre>
check( -opr => 'xor', 1, undef, 1, undef );</pre>
</dd>
<dd>
<p><strong>Example</strong> returns: <strong>false</strong>:</p>
</dd>
<dd>
<pre>
check( -opr => 'xor', 1, undef, 1, 1, undef );</pre>
</dd>
<dd>
<p><strong>Example</strong> returns: <strong>true</strong>:</p>
</dd>
<dd>
<pre>
check( -opr => 'xor', undef, 1, undef, 1 );</pre>
</dd>
</dl>
<p>
</p>
<h2><a name="opts">opts</a></h2>
<dl>
<dt>
<dd>
<pre>
Usage: opts [OPTIONS], \ARRAY, [\HASH]</pre>
</dd>
<dd>
<p>Split parameter arrays into options and arguments.</p>
</dd>
<dd>
<p>OPTIONS:</p>
</dd>
<dd>
<pre>
-prefix=EXPR # specify option prefix, default is single dash (-).</pre>
</dd>
<dd>
<pre>
-assign=EXPR # specify assignment character, default is the
equal sign (=).</pre>
</dd>
<dd>
<pre>
-append=EXPR # specify append character, default is the
plus sign (+).</pre>
</dd>
<dd>
<p>In array context, we return two references. Which may cause confusion:</p>
</dd>
<dd>
<pre>
my %opts = Hub::opts( \@_ ); # Wrong!
my $opts = Hub::opts( \@_ ); # Correct!
my ($opts,$args) = Hub::opts( \@_ ); # Correct!</pre>
</dd>
<dd>
<p>Options are extracted (via splice) from the referenced array. The advantage
is both for performance (don't make a copy of the array), and so you may
use @_ (or @ARGV, etc) normally, as data:</p>
</dd>
<dd>
<p><strong>Example: at-underscore contains everyting but the '-with' option</strong>: (matches)</p>
</dd>
<dd>
<pre>
sub myjoin {
my $opts = Hub::opts( @_ );
return join( $$opts{'with'}, @_ );
}</pre>
</dd>
<dd>
<pre>
myjoin( 'a', 'b', '-with=;', 'c', 'd' );</pre>
</dd>
<dd>
<pre>
a;b;c;d</pre>
</dd>
<dd>
<p>1. Arguments are elements which do *not* begin with a dash (-).</p>
</dd>
<dd>
<p>2. Options are elements which begin with a <strong>single</strong> dash (-) and are not
negative numbers.</p>
</dd>
<dd>
<p>3. An option of '-opts' is reserved for passing in already parsed option
hashes.</p>
</dd>
<dd>
<p>4. Options will have their leading dash (-) removed.</p>
</dd>
<dd>
<p>5. Options values are formed as:</p>
</dd>
<dd>
<pre>
Given: opt1 will be: because:</pre>
</dd>
<dd>
<pre>
-opt1=value 'value' contains an equal sign
-opt1 nextelem 'nextelem' next element is *not* an option
-opt1 -option2 1 next element is also an option
-opt1 1 it is the last element
-opt1 1 it is the last element
-opt1=a -opt1=b b last one wins
-opt1=a +opt1=b [ 'a', 'b' ] it was specified using '+'
+opt1=a +opt1=b [ 'a', 'b' ] they can both be '+'</pre>
</dd>
<dd>
<p>For example:</p>
</dd>
<dd>
<pre>
my($opts,$args) = Hub::opts( [ 'a', 'b', '-c' => 'c', '-x', '-o=out' ] );</pre>
</dd>
<dd>
<pre>
print "Opts:\n", Hub::hprint( $opts );
print "Args:\n", Hub::hprint( $args );</pre>
</dd>
<dd>
<p>Will print:</p>
</dd>
<dd>
<pre>
Opts:
c => c
o => out
x => 1
Args:
a
b</pre>
</dd>
</dl>
<p>
</p>
<h2><a name="objopts">objopts</a></h2>
<dl>
<dt><strong><a name="item_into">Split @_ into ($self,$opts), leaving @_ with remaining items.</a></strong>
<dd>
<pre>
Usage: objopts \@params, [\%defaults]</pre>
</dd>
<dd>
<p>Convienence method for splitting instance method parameters.</p>
</dd>
<dd>
<p>Returns an array.</p>
</dd>
<dd>
<p><strong>Example: Test return value</strong>: (matches)</p>
</dd>
<dd>
<pre>
my $obj = mkinst( 'Object' );
my @result = objopts( [ $obj ] );
join( ',', map { ref($_) } @result );</pre>
</dd>
<dd>
<pre>
Hub::Base::Object,</pre>
</dd>
</dl>
<p>
</p>
<h2><a name="cmdopts">cmdopts</a></h2>
<dl>
<dt><strong><a name="item_extract_short_and_long_options_from__40argv">Extract short and long options from @ARGV</a></strong>
<dd>
<pre>
Usage: cmdopts \@arguments
Usage: cmdopts \@arguments, \%default_options</pre>
</dd>
<dd>
<p>Single-dash paramaters are always boolean flags. Flags are broken apart such
that:</p>
</dd>
<dd>
<pre>
-lal</pre>
</dd>
<dd>
<p>becomes</p>
</dd>
<dd>
<pre>
-l -a -l</pre>
</dd>
<dd>
<p>To create a list (ARRAY) of items, use '++' where you would normally use '--'.</p>
</dd>
<dd>
<p><strong>Example</strong>: (matches)</p>
</dd>
<dd>
<pre>
my $opts = cmdopts(['--letters=a', '++letters=b', '++letters=c']);
join('-', @{$$opts{'letters'}});</pre>
</dd>
<dd>
<pre>
a-b-c</pre>
</dd>
</dl>
<p>
</p>
<h2><a name="hashopts">hashopts</a></h2>
<dl>
<dt><strong><a name="item_get_options_and_parameters_as_a_hash">Get options and parameters as a hash</a></strong>
<dd>
<pre>
Usage: hashopts \@parameters</pre>
</dd>
<dd>
<p>The purpose of this method is to even out the returned parameter list by
adding an undefined value if there are an odd number of elements in the list.</p>
</dd>
<dd>
<p>This avoids the Perl warning:</p>
</dd>
<dd>
<pre>
Odd number of elements in hash assignment</pre>
</dd>
<dd>
<p>When parsing options as:</p>
</dd>
<dd>
<pre>
my ($opts, %fields) = Hub::opts(...)</pre>
</dd>
<dd>
<p><strong>Example</strong> returns: <strong>defined</strong>:</p>
</dd>
<dd>
<pre>
my ($opts, %hash) = Hub::hashopts(['key1', -foo]);
$hash{'key1'}</pre>
</dd>
</dl>
<p>
</p>
<h2><a name="subst">subst</a></h2>
<dl>
<dt>
<dd>
<pre>
Usage: subst</pre>
</dd>
<dd>
<p>Call to perl's substitution operator. Represented here as a function to
facilitate transformation by reducing the need for temporaries. In essence,
the goal is to reduce:</p>
</dd>
<dd>
<pre>
my $bakname = getfilename();
$bakname =~ s/\.db$/\.bak/;</pre>
</dd>
<dd>
<p>to:</p>
</dd>
<dd>
<pre>
my $bakname = Hub::subst( getfilename(), '\.db$', '.bak' );</pre>
</dd>
<dd>
<p>without modifying the original string returned by getfilename().</p>
</dd>
</dl>
<p>
</p>
<h2><a name="getuid">getuid</a></h2>
<dl>
<dt><strong><a name="item_return_the_uid_of_the_provided_user">Return the UID of the provided user</a></strong>
<dd>
<pre>
Usage: getuid $user_name
If perl has not been compiled with 'getpwnam', $user_name is returned.</pre>
</dd>
<dd>
<p>-1 is returned when no user is found</p>
</dd>
</dl>
<p>
</p>
<h2><a name="getgid">getgid</a></h2>
<dl>
<dt><strong><a name="item_return_the_gid_of_the_provided_group">Return the GID of the provided group</a></strong>
<dd>
<pre>
Usage: getgid - $group_name
If perl has not been compiled with 'getgrnam', $group_name is returned.</pre>
</dd>
<dd>
<p>-1 is returned when no group is found</p>
</dd>
</dl>
<p>
</p>
<h2><a name="touch">touch</a></h2>
<dl>
<dt>
<dd>
<pre>
Usage: touch LIST</pre>
</dd>
<dd>
<p>Changes the access and modification times on each file of a list of files.</p>
</dd>
</dl>
<p>
</p>
<h2><a name="expect">expect</a></h2>
<dl>
<dt><strong><a name="item_croak_if_arguments_do_not_match_their_expected_typ">Croak if arguments do not match their expected type</a></strong>
<dd>
<pre>
Usage: expect [OPTIONS], [TEST], LIST</pre>
</dd>
<dd>
<p>OPTIONS:</p>
</dd>
<dd>
<pre>
-back \d # Carp level (for reporting further up the callstack)
-not 0|1 # Invert the result</pre>
</dd>
<dd>
<p>TESTS:</p>
</dd>
<dd>
<pre>
-blessed # All LIST items are blessed
-match=EXPR # All LIST items match /EXPR/
-ref=EXPR # All LIST items' ref match /EXPR/</pre>
</dd>
<dd>
<p>By default, LIST is made up of key/value pairs, where the key is the type
(what <code>ref()</code> will return) and the value is what will be tested. LIST may
contain one or more key/value pairs such as:</p>
</dd>
<dd>
<pre>
HASH => arg
REF => arg
My::Package => arg</pre>
</dd>
<dd>
<p><strong>Example</strong> returns: <strong>true</strong>:</p>
</dd>
<dd>
<pre>
Hub::expect( -match => 'and|or|xor', 'and' );</pre>
</dd>
<dd>
<p><strong>Example</strong> returns: <strong>true</strong>:</p>
</dd>
<dd>
<pre>
Hub::expect( HASH => {}, HASH => {} );</pre>
</dd>
<dd>
<p><strong>Example</strong> returns: <strong>abort</strong>:</p>
</dd>
<dd>
<pre>
Hub::expect( -blessed => {} );</pre>
</dd>
<dd>
<p><strong>Example</strong> returns: <strong>true</strong>:</p>
</dd>
<dd>
<pre>
Hub::expect( -blessed => mkinst( 'Object' ) );</pre>
</dd>
<dd>
<p><strong>Example</strong> returns: <strong>abort</strong>:</p>
</dd>
<dd>
<pre>
Hub::expect( -match => 'and|or|xor', 'if', 'or', 'and' );</pre>
</dd>
<dd>
<p><strong>Example</strong> returns: <strong>abort</strong>:</p>
</dd>
<dd>
<pre>
Hub::expect( ARRAY => {} );</pre>
</dd>
<dd>
<p><strong>Example</strong> returns: <strong>abort</strong>:</p>
</dd>
<dd>
<pre>
Hub::expect( -blessed => 'abc' );</pre>
</dd>
<dd>
<p><strong>Example</strong> returns: <strong>true</strong>:</p>
</dd>
<dd>
<pre>
Hub::expect( -ref => 'HASH', {} );</pre>
</dd>
<dd>
<p><strong>Example</strong> returns: <strong>true</strong>:</p>
</dd>
<dd>
<pre>
Hub::expect( -ref => 'HASH', mkinst('Object') );</pre>
</dd>
</dl>
<p>
</p>
<h2><a name="fear">fear</a></h2>
<dl>
<dt>
<dd>
<p>Croak if arguments match their feared type.</p>
</dd>
<dd>
<p>This is a shortcut to <a href="#expect">the expect manpage</a> with a '-not=1' option.</p>
</dd>
<dd>
<p><strong>Example</strong> returns: <strong>abort</strong>:</p>
</dd>
<dd>
<pre>
Hub::fear( HASH => {} );</pre>
</dd>
<dd>
<p><strong>Example</strong> returns: <strong>true</strong>:</p>
</dd>
<dd>
<pre>
Hub::fear( HASH => [] );</pre>
</dd>
</li>
</dl>
<p>
</p>
<h2><a name="abort">abort</a></h2>
<dl>
<dt><strong><a name="item_croak_nicely_2e">Croak nicely.</a></strong>
<dd>
<pre>
Usage: abort -msg => 'Croak message'
Usage: abort -back => LEVEL</pre>
</dd>
<dd>
<p><strong>Example</strong> returns: <strong>abort</strong>:</p>
</dd>
<dd>
<pre>
abort( -msg => 'Goddamn hippies' );</pre>
</dd>
</dl>
<p>
</p>
<h2><a name="bestof">bestof</a></h2>
<dl>
<dt>
<dd>
<pre>
Usage: bestof @list
Usage: bestof @list, -by=max|min|def|len|gt|lt|true</pre>
</dd>
<dd>
<p>Best value by criteria (default 'def').</p>
</dd>
</dl>
<p>
</p>
<h2><a name="min">min</a></h2>
<dl>
<dt><strong><a name="item_minimum_value">Minimum value</a></strong>
<dd>
<pre>
Usage: min @LIST</pre>
</dd>
<dd>
<p>Returns the least element in a set.</p>
</dd>
<dd>
<p><strong>Example: Two integers</strong>: (matches)</p>
</dd>
<dd>
<pre>
Hub::min(1,2);</pre>
</dd>
<dd>
<pre>
1</pre>
</dd>
<dd>
<p><strong>Example: Three integers</strong>: (matches)</p>
</dd>
<dd>
<pre>
Hub::min(2,1,3);</pre>
</dd>
<dd>
<pre>
1</pre>
</dd>
<dd>
<p><strong>Example: Three integers</strong>: (matches)</p>
</dd>
<dd>
<pre>
Hub::min(2,-1,3);</pre>
</dd>
<dd>
<pre>
-1</pre>
</dd>
<dd>
<p><strong>Example: One integer</strong>: (matches)</p>
</dd>
<dd>
<pre>
Hub::min(1);</pre>
</dd>
<dd>
<pre>
1</pre>
</dd>
<dd>
<p><strong>Example: Undefined value</strong>: (matches)</p>
</dd>
<dd>
<pre>
Hub::min(1,undef);</pre>
</dd>
<dd>
<pre>
1</pre>
</dd>
<dd>
<p><strong>Example: Zero</strong>: (matches)</p>
</dd>
<dd>
<pre>
Hub::min(undef,1,0);</pre>
</dd>
<dd>
<pre>
0</pre>
</dd>
<dd>
<p><strong>Example: Three decimal values</strong>: (matches)</p>
</dd>
<dd>
<pre>
Hub::min(.009,1.001);</pre>
</dd>
<dd>
<pre>
0.009</pre>
</dd>
</dl>
<p>
</p>
<h2><a name="max">max</a></h2>
<dl>
<dt><strong><a name="item_maximum_value">Maximum value</a></strong>
<dd>
<pre>
Usage: max @LIST</pre>
</dd>
<dd>
<p>Returns the greatest element in a set.</p>
</dd>
<dd>
<p><strong>Example: Three decimal values</strong>: (matches)</p>
</dd>
<dd>
<pre>
Hub::max(.009,-1.01,2,undef,0);</pre>
</dd>
<dd>
<pre>
2</pre>
</dd>
</dl>
<p>
</p>
<h2><a name="intdiv">intdiv</a></h2>
<dl>
<dt><strong><a name="item_integer_division">Integer division</a></strong>
<dd>
<pre>
Usage: intdiv $DIVIDEND, $DIVISOR</pre>
</dd>
<dd>
<p>Returns an array with the number of times the divisor is contained in the
dividend, and the remainder.</p>
</dd>
<dd>
<p><strong>Example: 3 divided by 2 is 1R1</strong>: (matches)</p>
</dd>
<dd>
<pre>
join(',',Hub::intdiv(3,2));</pre>
</dd>
<dd>
<pre>
1,1</pre>
</dd>
</dl>
<p>
</p>
<h2><a name="flip">flip</a></h2>
<dl>
<dt>
<dd>
<p>given a hash reference, swap keys with values and return a new hash reference.</p>
</dd>
</li>
</dl>
<p>
</p>
<h2><a name="rmval">rmval</a></h2>
<dl>
<dt><strong><a name="item_remove_matching_elements_from_a_hash_or_an_array_2">Remove matching elements from a hash or an array.</a></strong>
<dd>
<pre>
Usage: rmval \@array, $value
Usage: rmval \%hash, $value</pre>
</dd>
<dd>
<p><strong>Example</strong>: (matches)</p>
</dd>
<dd>
<pre>
join('',@{rmval([1,2,3,4],3)});</pre>
</dd>
<dd>
<pre>
124</pre>
</dd>
</dl>
<p>
</p>
<h2><a name="cpref">cpref</a></h2>
<dl>
<dt><strong><a name="item_recursively_clone_the_reference_2c_returning_a_new">Recursively clone the reference, returning a new reference.</a></strong>
<dd>
<pre>
Usage: cpref ?ref
Implemented because the Clone module found on CPAN crashes under my mod_perl
and FastCGI test servers...</pre>
</dd>
</dl>
<p>
</p>
<h2><a name="random_id">random_id</a></h2>
<dl>
<dt><strong><a name="item_get_a_random_numeric_value_for_use_as_an_id">Get a random numeric value for use as an id</a></strong>
<dd>
<pre>
Usage: random_id</pre>
</dd>
<dd>
<p>Creates a checksum of the current <code>time()</code> plus 4 digit <code>rand()</code> number.</p>
</dd>
</dl>
<p>
</p>
<h2><a name="checksum">checksum</a></h2>
<dl>
<dt><strong><a name="item_create_a_unique_identifier_for_the_provided_data">Create a unique identifier for the provided data</a></strong>
<dd>
<pre>
Usage: checksum [params..]
Params can be scalars, hash references, array references and the like.</pre>
</dd>
<dd>
<p><strong>Example</strong>: (matches)</p>
</dd>
<dd>
<pre>
my $x = 'like catfood';
Hub::checksum( 'my', { cats => 'breath' }, ( 'smells', $x ) );</pre>
</dd>
<dd>
<pre>
2023611966</pre>
</dd>
</dl>
<p>
</p>
<h2><a name="merge">merge</a></h2>
<dl>
<dt><strong><a name="item_merge_several_hashes">Merge several hashes</a></strong>
<dd>
<pre>
Usage: merge \%target, \%source, [\%source..], [options]
returns \%hash</pre>
</dd>
<dd>
<p>Merges the provided hashes. The first argument (destination hash) has
precedence (as in values are NOT overwritten) unless -overwrite is given.</p>
</dd>
<dd>
<p>By default this routine modifies \%target. Specifiy -copy circumvent.</p>
</dd>
<dd>
<p>OPTIONS:</p>
</dd>
<dd>
<pre>
-copy Do not modify \%target.</pre>
</dd>
<dd>
<pre>
-overwrite=1 Overwrite values as they are encounterred.</pre>
</dd>
<dd>
<pre>
-prune=1 Gives the destination hash the same structure as
the source hash (or the composite of all which is
in common when multiple source hashes are provided).</pre>
</dd>
<dd>
<pre>
If the destination is missing a value, it is
initialized from the source hash.</pre>
</dd>
<dd>
<pre>
If the destination has a value which is not in all
of the source hashes, it is deleted.</pre>
</dd>
</dl>
<p>
</p>
<h2><a name="flatten">flatten</a></h2>
<dl>
<dt><strong><a name="item_get_a_consistent_unique_2dby_2ddata_string_for_som">Get a consistent unique-by-data string for some data structure.</a></strong>
<dd>
<pre>
Usage: flatten \%hash
Usage: flatten \%array</pre>
</dd>
</dl>
<p>
</p>
<h2><a name="replace">replace</a></h2>
<dl>
<dt>
<dd>
<pre>
Usage: replace MATCHING_REGEX, SUBSTITUTION_REGEX, TEXT</pre>
</dd>
<dd>
<p>Do a s/// operation on a given segment of the string.</p>
</dd>
<dd>
<p>For example, say we want to remove the ': ;' pattern from the style portion,
but not from the data portion:</p>
</dd>
<dd>
<pre>
<div style="font-family: ;">keep this: ;stuff</div></pre>
</dd>
<dd>
<p>Use this method as:</p>
</dd>
<dd>
<pre>
$text = Hub::replace( "style=\".*?\"", "s/[\\w\\-]+\\s*:\\s*;//g", $text );</pre>
</dd>
</dl>
<p>
</p>
<h2><a name="digout">digout</a></h2>
<dl>
<dt>
<dd>
<pre>
Usage: digout REF, ID</pre>
</dd>
<dd>
<p>Return an array of all nested values in an order that can be processed.</p>
</dd>
<dd>
<p>NOTE! Scalar values are returned as references.</p>
</dd>
<dd>
<p>See how 'packdata' uses this method to dereference.</p>
</dd>
<dd>
<p>Arrays are ignored unless their members are hashes with an _id member.</p>
</dd>
<dd>
<p>Reverse the results of this array to process data in a way that the children
are affected before their parents.</p>
</dd>
</dl>
<p>
</p>
<h2><a name="diff">diff</a></h2>
<dl>
<dt><strong><a name="item_creates_a_nest_of_the_differences_between_the_prov">Creates a nest of the differences between the provided structures.</a></strong>
<dd>
<pre>
Usage: diff \%hash1, \%hash2
Usage: diff \@array1, \@array2</pre>
</dd>
<dd>
<p>If a conflict of types (with the same key) is encounterred, the right-hand
sturcture is used.</p>
</dd>
<dd>
<p>NOTE: Although this routine compares contents, it returns references to the
original hashes (use <a href="../cpref.html">the Hub::cpref manpage</a> on the result to detatch.)</p>
</dd>
</dl>
<p>
</p>
<h2><a name="dice">dice</a></h2>
<dl>
<dt><strong><a name="item_break_apart_the_string_into_the_least_number_of_se">Break apart the string into the least number of segments</a></strong>
<dd>
<pre>
Usage: dice [options] $string
options:
beg=$literal Begin of balanced pair, Default is '{'
end=$literal End of balanced pair, Default is '}'</pre>
</dd>
<dd>
<p><strong>Example</strong>: (matches)</p>
</dd>
<dd>
<pre>
join( ';', dice( "a{b{c}}c{d}" ) );</pre>
</dd>
<dd>
<pre>
a;{b{c}};c;{d}</pre>
</dd>
</dl>
<p>
</p>
<h2><a name="indexmatch">indexmatch</a></h2>
<dl>
<dt><strong><a name="item_search_for_an_expression_within_a_string_and_retur">Search for an expression within a string and return the offset</a></strong>
<dd>
<pre>
Usage: indexmatch [options] $string, $expression, $position
Usage: indexmatch [options] $string, $expression</pre>
</dd>
<dd>
<p>Returns -1 if $expression is not found.</p>
</dd>
<dd>
<p>options:</p>
</dd>
<dd>
<pre>
-after=1 Return the position *after* the expression.</pre>
</dd>
<dd>
<p><strong>Example</strong>: (matches)</p>
</dd>
<dd>
<pre>
indexmatch("abracadabra", "[cd]")</pre>
</dd>
<dd>
<pre>
4</pre>
</dd>
<dd>
<p><strong>Example</strong>: (matches)</p>
</dd>
<dd>
<pre>
indexmatch("abracadabra", "a", 3)</pre>
</dd>
<dd>
<pre>
3</pre>
</dd>
<dd>
<p><strong>Example</strong>: (matches)</p>
</dd>
<dd>
<pre>
indexmatch("abracadabra", "d{2,2}")</pre>
</dd>
<dd>
<pre>
-1</pre>
</dd>
<dd>
<p><strong>Example</strong>: (matches)</p>
</dd>
<dd>
<pre>
indexmatch("scant", "can", "-after=1")
- indexmatch("scant", "can")</pre>
</dd>
<dd>
<pre>
3</pre>
</dd>
</dl>
<p>
<a href="#__index__"><small>Top</small></a>
</p>
<hr />
<h1><a name="internal_methods">INTERNAL METHODS</a></h1>
<p>
</p>
<h2><a name="_assignopt">_assignopt</a></h2>
<dl>
<dt>
<dd>
<pre>
Usage: _assignopt Assign an option value.</pre>
</dd>
<dd>
<pre>
Usage: _assignopt \%options, \%dest, $key, $val</pre>
</dd>
</dl>
<p>
</p>
<h2><a name="_merge_hash">_merge_hash</a></h2>
<dl>
<dt>
</dl>
<p>
</p>
<h2><a name="_merge_array">_merge_array</a></h2>
<dl>
<dt>
</dl>
<p>
</p>
<h2><a name="_merge_element">_merge_element</a></h2>
<dl>
<dt>
</dl>
<p>
</p>
<h2><a name="_diff_hashes">_diff_hashes</a></h2>
<dl>
<dt>
<dd>
<pre>
Usage: _diff_hashes &HASH, &HASH</pre>
</dd>
<dd>
<p>Difference between two hashes.</p>
</dd>
</dl>
<p>
</p>
<h2><a name="_diff_arrays">_diff_arrays</a></h2>
<dl>
<dt>
<dd>
<pre>
Usage: _diff_arrays &ARRAY, &ARRAY</pre>
</dd>
<dd>
<p>Difference between two arrays.</p>
</dd>
</dl>
<p>
<a href="#__index__"><small>Top</small></a>
</p>
<hr />
<h1><a name="author">AUTHOR</a></h1>
<p>Ryan Gies (<a href="mailto:ryangies@livesite.net">ryangies@livesite.net</a>)</p>
<p>
<a href="#__index__"><small>Top</small></a>
</p>
<hr />
<h1><a name="copyright">COPYRIGHT</a></h1>
<p>Copyright (C) 2006-2007 by Livesite Networks, LLC. All rights reserved.</p>
<p>Copyright (C) 2000-2005 by Ryan Gies. All rights reserved.</p>
<p>Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:</p>
<p>* Redistributions of source code must retain the above copyright notice,
this list of conditions and the following disclaimer.</p>
<p>* The origin of this software must not be misrepresented; you must not
claim that you wrote the original software. If you use this software in a
product, an acknowledgment in the product documentation would be
appreciated but is not required.</p>
<p>* Altered source versions must be plainly marked as such, and must not be
misrepresented as being the original software.</p>
<p>* The name of the author may not be used to endorse or promote products
derived from this software without specific prior written permission.</p>
<p>THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED
WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO
EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY
OF SUCH DAMAGE.</p>
<p>To the best of our knowledge, no patented algorithms have been used. However, we
do not have the resources to carry out a patent search, and therefore cannot
give any guarantee of the above statement.</p>
<p>
<a href="#__index__"><small>Top</small></a>
</p>
<hr />
<h1><a name="updated">UPDATED</a></h1>
<p>08/02/2007</p>
<p><a href="#__index__"><small>Top</small></a></p>
</body>
</html>