NAME

Data::Object::Hash

ABSTRACT

Hash Class for Perl 5

SYNOPSIS

  package main;

  use Data::Object::Hash;

  my $hash = Data::Object::Hash->new({1..4});

DESCRIPTION

This package provides methods for manipulating hash data.

INHERITS

This package inherits behaviors from:

Data::Object::Kind

INTEGRATES

This package integrates behaviors from:

Data::Object::Role::Dumpable

Data::Object::Role::Proxyable

Data::Object::Role::Throwable

LIBRARIES

This package uses type constraints from:

Data::Object::Types

METHODS

This package implements the following methods:

clear

  clear() : HashLike

The clear method is an alias to the empty method.

clear example #1

  my $hash = Data::Object::Hash->new({1..8});

  $hash->clear; # {}

count

  count() : Num

The count method returns the total number of keys defined.

count example #1

  my $hash = Data::Object::Hash->new({1..4});

  $hash->count; # 2

defined

  defined() : Num

The defined method returns true if the value matching the key specified in the argument if defined, otherwise returns false.

defined example #1

  my $hash = Data::Object::Hash->new;

  $hash->defined;

delete

  delete(Num $arg1) : Any

The delete method returns the value matching the key specified in the argument and returns the value.

delete example #1

  my $hash = Data::Object::Hash->new({1..8});

  $hash->delete(1); # 2

each

  each(CodeRef $arg1, Any @args) : Any

The each method executes callback for each element in the hash passing the routine the key and value at the current position in the loop.

each example #1

  my $hash = Data::Object::Hash->new({1..8});

  $hash->each(sub {
    my ($key, $value) = @_;

    [$key, $value]
  });

each_key

  each_key(CodeRef $arg1, Any @args) : Any

The each_key method executes callback for each element in the hash passing the routine the key at the current position in the loop.

each_key example #1

  my $hash = Data::Object::Hash->new({1..8});

  $hash->each_key(sub {
    my ($key) = @_;

    [$key]
  });

each_n_values

  each_n_values(Num $arg1, CodeRef $arg2, Any @args) : Any

The each_n_values method executes callback for each element in the hash passing the routine the next n values until all values have been seen.

each_n_values example #1

  my $hash = Data::Object::Hash->new({1..8});

  $hash->each_n_values(4, sub {
    my (@values) = @_;

    # $values[1] # 2
    # $values[2] # 4
    # $values[3] # 6
    # $values[4] # 8

    [@values]
  });

each_value

  each_value(CodeRef $arg1, Any @args) : Any

The each_value method executes callback for each element in the hash passing the routine the value at the current position in the loop.

each_value example #1

  my $hash = Data::Object::Hash->new({1..8});

  $hash->each_value(sub {
    my ($value) = @_;

    [$value]
  });

empty

  empty() : HashLike

The empty method drops all elements from the hash.

empty example #1

  my $hash = Data::Object::Hash->new({1..8});

  $hash->empty; # {}

eq

  eq(Any $arg1) : Num

The eq method will throw an exception if called.

eq example #1

  my $hash = Data::Object::Hash->new;

  $hash->eq({});

exists

  exists(Num $arg1) : Num

The exists method returns true if the value matching the key specified in the argument exists, otherwise returns false.

exists example #1

  my $hash = Data::Object::Hash->new({1..8,9,undef});

  $hash->exists(1); # 1; true

exists example #2

  my $hash = Data::Object::Hash->new({1..8,9,undef});

  $hash->exists(0); # 0; false

filter_exclude

  filter_exclude(Str @args) : HashRef

The filter_exclude method returns a hash reference consisting of all key/value pairs in the hash except for the pairs whose keys are specified in the arguments.

filter_exclude example #1

  my $hash = Data::Object::Hash->new({1..8});

  $hash->filter_exclude(1,3); # {5=>6,7=>8}

filter_include

  filter_include(Str @args) : HashRef

The filter_include method returns a hash reference consisting of only key/value pairs whose keys are specified in the arguments.

filter_include example #1

  my $hash = Data::Object::Hash->new({1..8});

  $hash->filter_include(1,3); # {1=>2,3=>4}

fold

  fold(Str $arg1, HashRef $arg2, HashRef $arg3) : HashRef

The fold method returns a single-level hash reference consisting of key/value pairs whose keys are paths (using dot-notation where the segments correspond to nested hash keys and array indices) mapped to the nested values.

fold example #1

  my $hash = Data::Object::Hash->new({3,[4,5,6],7,{8,8,9,9}});

  $hash->fold; # {'3:0'=>4,'3:1'=>5,'3:2'=>6,'7.8'=>8,'7.9'=>9}

ge

  ge(Any $arg1) : Num

The ge method will throw an exception if called.

ge example #1

  my $hash = Data::Object::Hash->new;

  $hash->ge({});

get

  get(Str $arg1) : Any

The get method returns the value of the element in the hash whose key corresponds to the key specified in the argument.

get example #1

  my $hash = Data::Object::Hash->new({1..8});

  $hash->get(5); # 6

grep

  grep(CodeRef $arg1, Any $arg2) : HashRef

The grep method executes callback for each key/value pair in the hash passing the routine the key and value at the current position in the loop and returning a new hash reference containing the elements for which the argument evaluated true.

grep example #1

  my $hash = Data::Object::Hash->new({1..4});

  $hash->grep(sub {
    my ($value) = @_;

    $value >= 3
  });

  # {3=>4}

gt

  gt(Any $arg1) : Num

The gt method will throw an exception if called.

gt example #1

  my $hash = Data::Object::Hash->new;

  $hash->gt({});

head

  head() : Any

The head method will throw an exception if called.

head example #1

  my $hash = Data::Object::Hash->new;

  $hash->head;

invert

  invert() : Any

The invert method returns the hash after inverting the keys and values respectively. Note, keys with undefined values will be dropped, also, this method modifies the hash.

invert example #1

  my $hash = Data::Object::Hash->new({1..8,9,undef,10,''});

  $hash->invert; # {''=>10,2=>1,4=>3,6=>5,8=>7}

iterator

  iterator() : CodeRef

The iterator method returns a code reference which can be used to iterate over the hash. Each time the iterator is executed it will return the values of the next element in the hash until all elements have been seen, at which point the iterator will return an undefined value.

iterator example #1

  my $hash = Data::Object::Hash->new({1..8});

  my $iterator = $hash->iterator;

  # while (my $value = $iterator->next) {
  #     say $value; # 2
  # }

join

  join() : Any

The join method will throw an exception if called.

join example #1

  my $hash = Data::Object::Hash->new;

  $hash->join;

keys

  keys() : ArrayRef

The keys method returns an array reference consisting of all the keys in the hash.

keys example #1

  my $hash = Data::Object::Hash->new({1..8});

  $hash->keys; # [1,3,5,7]

kvslice

  kvslice(Str @args) : HashRef

The kvslice method returns a hash reference containing the elements in the hash at the key(s) specified in the arguments.

kvslice example #1

  my $hash = Data::Object::Hash->new({1..8});

  $hash->kvslice(1,5); # {1=>2,5=>6}

le

  le(Any $arg1) : Num

The le method will throw an exception if called.

le example #1

  my $hash = Data::Object::Hash->new;

  $hash->le;

length

  length() : Num

The length method returns the number of keys in the hash.

length example #1

  my $hash = Data::Object::Hash->new({1..8});

  $hash->length; # 4

list

  list() : (Any)

The list method returns a shallow copy of the underlying hash reference as an array reference.

list example #1

  my $hash = Data::Object::Hash->new({1..8});

  [$hash->list];

lookup

  lookup(Str $arg1) : Any

The lookup method returns the value of the element in the hash whose key corresponds to the key specified in the argument. The key can be a string which references (using dot-notation) nested keys within the hash. This method will return undefined if the value is undef or the location expressed in the argument can not be resolved. Please note, keys containing dots (periods) are not handled.

lookup example #1

  my $hash = Data::Object::Hash->new({1..3,{4,{5,6,7,{8,9,10,11}}}});

  $hash->lookup('3.4.7'); # {8=>9,10=>11}

lookup example #2

  my $hash = Data::Object::Hash->new({1..3,{4,{5,6,7,{8,9,10,11}}}});

  $hash->lookup('3.4'); # {5=>6,7=>{8=>9,10=>11}}

lookup example #3

  my $hash = Data::Object::Hash->new({1..3,{4,{5,6,7,{8,9,10,11}}}});

  $hash->lookup(1); # 2

lt

  lt(Any $arg1) : Num

The lt method will throw an exception if called.

lt example #1

  my $hash = Data::Object::Hash->new;

  $hash->lt({});

map

  map(CodeRef $arg1, Any $arg2) : ArrayRef

The map method executes callback for each key/value in the hash passing the routine the value at the current position in the loop and returning a new hash reference containing the elements for which the argument returns a value or non-empty list.

map example #1

  my $hash = Data::Object::Hash->new({1..4});

  $hash->map(sub {
    $_[0] + 1
  });

merge

  merge() : HashRef

The merge method returns a hash reference where the elements in the hash and the elements in the argument(s) are merged. This operation performs a deep merge and clones the datasets to ensure no side-effects. The merge behavior merges hash references only, all other data types are assigned with precendence given to the value being merged.

merge example #1

  my $hash = Data::Object::Hash->new({1..8});

  $hash->merge({7,7,9,9}); # {1=>2,3=>4,5=>6,7=>7,9=>9}

ne

  ne(Any $arg1) : Num

The ne method will throw an exception if called.

ne example #1

  my $hash = Data::Object::Hash->new;

  $hash->ne({});

pairs

  pairs() : ArrayRef

The pairs method is an alias to the pairs_array method.

pairs example #1

  my $hash = Data::Object::Hash->new({1..8});

  $hash->pairs; # [[1,2],[3,4],[5,6],[7,8]]

reset

  reset() : HashLike

The reset method returns nullifies the value of each element in the hash.

reset example #1

  my $hash = Data::Object::Hash->new({1..8});

  $hash->reset; # {1=>undef,3=>undef,5=>undef,7=>undef}

reverse

  reverse() : HashRef

The reverse method returns a hash reference consisting of the hash's keys and values inverted. Note, keys with undefined values will be dropped.

reverse example #1

  my $hash = Data::Object::Hash->new({1..8,9,undef});

  $hash->reverse; # {8=>7,6=>5,4=>3,2=>1}

set

  set(Str $arg1, Any $arg2) : Any

The set method returns the value of the element in the hash corresponding to the key specified by the argument after updating it to the value of the second argument.

set example #1

  my $hash = Data::Object::Hash->new({1..8});

  $hash->set(1,10); # 10

set example #2

  my $hash = Data::Object::Hash->new({1..8});

  $hash->set(1,12); # 12

set example #3

  my $hash = Data::Object::Hash->new({1..8});

  $hash->set(1,0); # 0

slice

  slice(Str @args) : ArrayRef

The slice method returns an array reference of the values that correspond to the key(s) specified in the arguments.

slice example #1

  my $hash = Data::Object::Hash->new({1..8});

  $hash->slice(1,3); # [2,4]

sort

  sort() : Any

The sort method will throw an exception if called.

sort example #1

  my $hash = Data::Object::Hash->new({1..8});

  $hash->sort;

tail

  tail() : Any

The tail method will throw an exception if called.

tail example #1

  my $hash = Data::Object::Hash->new({1..8});

  $hash->tail;

unfold

  unfold() : HashRef

The unfold method processes previously folded hash references and returns an unfolded hash reference where the keys, which are paths (using dot-notation where the segments correspond to nested hash keys and array indices), are used to created nested hash and/or array references.

unfold example #1

  my $hash = Data::Object::Hash->new(
    {'3:0'=>4,'3:1'=>5,'3:2'=>6,'7.8'=>8,'7.9'=>9}
  );

  $hash->unfold; # {3=>[4,5,6],7,{8,8,9,9}}

values

  values() : ArrayRef

The values method returns an array reference consisting of the values of the elements in the hash.

values example #1

  my $hash = Data::Object::Hash->new({1..8});

  $hash->values; # [2,4,6,8]

AUTHOR

Al Newkirk, "awncorp@cpan.org"

LICENSE

This is free software; you can redistribute it and/or modify it under the terms of the The Apache License, Version 2.0, as elucidated in the "license file" <https://github.com/iamalnewkirk/data-object/blob/master/LICENSE>.

PROJECT

Wiki <https://github.com/iamalnewkirk/data-object/wiki>

Project <https://github.com/iamalnewkirk/data-object>

Initiatives <https://github.com/iamalnewkirk/data-object/projects>

Milestones <https://github.com/iamalnewkirk/data-object/milestones>

Contributing <https://github.com/iamalnewkirk/data-object/blob/master/CONTRIBUTE.md>

Issues <https://github.com/iamalnewkirk/data-object/issues>