List::Objects::WithUtils::Role::Hash - Hash manipulation methods
## Via List::Objects::WithUtils::Hash -> use List::Objects::WithUtils 'hash'; my $hash = hash(foo => 'bar'); $hash->set( foo => 'baz', pie => 'tasty', ); my @matches = $hash->keys->grep(sub { $_[0] =~ /foo/ })->all; my $pie = $hash->get('pie') if $hash->exists('pie'); for my $pair ( $hash->kv->all ) { my ($key, $val) = @$pair; ... } my $obj = $hash->inflate; my $foo = $obj->foo; ## As a Role -> use Role::Tiny::With; with 'List::Objects::WithUtils::Role::Hash';
A Role::Tiny role defining methods for creating and manipulating HASH-type objects.
In addition to the methods documented below, these objects provide a TO_JSON method exporting a plain HASH-type reference for convenience when feeding JSON::Tiny or similar.
TO_JSON
Constructs a new HASH-type object.
my %hash = $hash->export;
Returns a raw key/value list.
Clears the current hash entirely.
Returns the hash object (as of version 1.013).
Creates a shallow clone of the current object.
Returns a plain /HASH reference (shallow clone).
/HASH
if ( $hash->defined($key) ) { ... }
Returns boolean true if the key has a defined value.
$hash->delete( @keys );
Deletes keys from the hash.
Returns an "array_type" object containing the deleted values.
if ( $hash->exists($key) ) { ... }
Returns boolean true if the key exists.
my $val = $hash->get($key); my @vals = $hash->get(@keys)->all;
Retrieves a key or list of keys from the hash.
If we're taking a slice (multiple keys were specified), values are returned as an "array_type" object. (See "sliced" if you'd rather generate a new hash.)
# Expect to find an array() obj at $key in $hash, # or create an empty one if $key doesn't exist: my @all = $hash->get_or_else($key => array)->all; # Or pass a coderef # First arg is the object being operated on # Second arg is the requested key my $item = $hash->get_or_else($key => sub { shift->get($defaultkey) });
Retrieves a key from the hash; optionally takes a second argument that is used as a default value if the given key does not exist in the hash.
If the second argument is a coderef, it is invoked on the object (with the requested key as an argument) and its return value is taken as the default value.
my $obj = hash(foo => 'bar', baz => 'quux')->inflate; my $baz = $obj->baz;
Inflates a simple object providing accessors for a hash.
By default, accessors are read-only; specifying rw = 1> allows setting new values:
rw =
my $obj = hash(foo => 'bar', baz => 'quux')->inflate(rw => 1); $obj->foo('frobulate');
Returns an "inflated_type" (or "inflated_rw_type") object.
The default objects provide a DEFLATE method returning a plain hash; this makes it easy to turn inflated objects back into a hash() for modification:
DEFLATE
hash()
my $first = hash( foo => 'bar', baz => 'quux' )->inflate; my $second = hash( $first->DEFLATE, frobulate => 1 )->inflate;
my $first = hash(a => 1, b => 2, c => 3); my $second = hash(b => 2, c => 3, d => 4); my $intersection = $first->intersection($second); my @common = $intersection->sort->all;
Returns the list of keys common between all given hash-type objects (including the invocant) as an "array_type" object.
The opposite of "intersection"; returns the list of keys that are not common to all given hash-type objects (including the invocant) as an "array_type" object.
Returns boolean true if the hash has no keys.
Returns boolean true if the hash is mutable; immutable subclasses can override to provide a negative value.
The opposite of "is_mutable".
my @keys = $hash->keys->all;
Returns the list of keys in the hash as an "array_type" object.
my @vals = $hash->values->all;
Returns the list of values in the hash as an "array_type" object.
my $iter = $hash->iter; while (my ($key, $val) = $iter->()) { # ... }
Returns an iterator that, when called, returns ($key, $value) pairs.
The iterator operates on a shallow clone of the current hash, making it (relatively) safe to operate on the original hash while using the iterator.
for my $pair ($hash->kv->all) { my ($key, $val) = @$pair; }
Returns an "array_type" object containing the key/value pairs in the hash, each of which is a two-element ARRAY.
# Add 1 to each value, get back an array-type object: my $kvs = hash(a => 2, b => 2, c => 3) ->kv_map(sub { ($_[0], $_[1] + 1) });
Like map, but operates on pairs. See "pairmap" in List::Util.
map
Returns an "array_type" object containing the results of the map.
my $kvs = hash(a => 1, b => 2, c => 3)->kv_sort; # $kvs = array( # [ a => 1 ], # [ b => 2 ], # [ c => 3 ] # ) my $reversed = hash(a => 1, b => 2, c => 3) ->kv_sort(sub { $_[1] cmp $_[0] }); # Reverse result as above
Like "kv", but sorted by key. A sort routine can be provided; $_[0] and $_[1] are equivalent to the usual sort variables $a and $b.
$_[0]
$_[1]
$a
$b
$hash->set( key1 => $val, key2 => $other, )
Sets keys in the hash.
As of version 1.007, returns the current hash object. The return value of prior versions is unreliable.
my $hash = hash(foo => 1, bar => 2, baz => 3); $hash->maybe_set(foo => 2, bar => 3, quux => 4); # $hash = +{ foo => 1, bar => 2, baz => 3, quux => 4 }
Like "set", but only sets values that do not already exist in the hash.
Returns the hash object.
my $newhash = $hash->sliced(@keys);
Returns a new hash object built from the specified set of keys.
(See "get" if you only need the values.)
The class name of array-type objects that will be used to contain the results of methods returning a list.
Defaults to List::Objects::WithUtils::Array.
Subclasses can override array_type to produce different types of array objects; the method can also be queried to find out what kind of array object will be returned:
array_type
my $type = $hash->array_type;
The class name that objects are blessed into when calling "inflate".
Defaults to List::Objects::WithUtils::Hash::Inflated.
The class name that objects are blessed into when calling "inflate" with rw = 1>.
Defaults to List::Objects::WithUtils::Hash::Inflated::RW, a subclass of List::Objects::WithUtils::Hash::Inflated.
List::Objects::WithUtils
List::Objects::WithUtils::Hash
List::Objects::WithUtils::Hash::Immutable
List::Objects::WithUtils::Hash::Typed
Data::Perl
Jon Portnoy <avenj@cobaltirc.org>
Portions of this code are derived from Data::Perl by Matthew Phillips (CPAN: MATTP), haarg et al
Licensed under the same terms as Perl.
To install List::Objects::WithUtils, copy and paste the appropriate command in to your terminal.
cpanm
cpanm List::Objects::WithUtils
CPAN shell
perl -MCPAN -e shell install List::Objects::WithUtils
For more information on module installation, please visit the detailed CPAN module installation guide.