NAME

       Sub::HandlesVia::HandlerLibrary::Hash - library of hash-related methods

SYNOPSIS

         package My::Class {
           use Moo;
           use Sub::HandlesVia;
           use Types::Standard 'HashRef';
           has attr => (
             is => 'rwp',
             isa => HashRef,
             handles_via => 'Hash',
             handles => {
               'my_accessor' => 'accessor',
               'my_all' => 'all',
               'my_clear' => 'clear',
               'my_count' => 'count',
               'my_defined' => 'defined',
               'my_delete' => 'delete',
               'my_delete_where' => 'delete_where',
               'my_elements' => 'elements',
               'my_exists' => 'exists',
               'my_for_each_key' => 'for_each_key',
               'my_for_each_pair' => 'for_each_pair',
               'my_for_each_value' => 'for_each_value',
               'my_get' => 'get',
               'my_is_empty' => 'is_empty',
               'my_keys' => 'keys',
               'my_kv' => 'kv',
               'my_reset' => 'reset',
               'my_set' => 'set',
               'my_shallow_clone' => 'shallow_clone',
               'my_sorted_keys' => 'sorted_keys',
               'my_values' => 'values',
             },
           );
         }

DESCRIPTION

       This is a library of methods for Sub::HandlesVia.

DELEGATABLE METHODS

   "accessor( $key, $value? )"
       Arguments: Str, Optional[Any].

       Acts like "get" if given just a key, or "set" if given a key and a value.

   "all()"
       Returns the hash in list context.

         my $object = My::Class->new( attr => { foo => 0, bar => 1 } );
         my %hash = $object->my_all;

   "clear()"
       Empties the hash.

         my $object = My::Class->new( attr => { foo => 0, bar => 1 } );
         $object->my_clear;
         say exists $object->attr->{foo}; ## ==> false
         say exists $object->attr->{bar}; ## ==> false

   "count()"
       Returns the number of keys in the hash.

         my $object = My::Class->new( attr => { foo => 0, bar => 1 } );
         say $object->my_count; ## ==> 2

   "defined( $key )"
       Arguments: Str.

       Indicates whether a value exists and is defined in the hashref by its key.

         my $object = My::Class->new( attr => { foo => 0, bar => 1 } );
         say $object->my_defined( 'foo' ); ## ==> 1

   "delete( $key )"
       Removes a value from the hashref by its key.

         my $object = My::Class->new( attr => { foo => 0, bar => 1 } );
         $object->my_delete( 'foo' );
         say exists $object->attr->{foo}; ## ==> false

   "delete_where( $match )"
       Arguments: CodeRef|RegexpRef.

       Removes values from the hashref by matching keys against a coderef or regexp.

         my $object = My::Class->new( attr => { foo => 0, bar => 1, baz => 2 } );
         $object->my_delete_where( sub { $_ eq 'foo' or $_ eq 'bar' } );
         say Dumper( $object->attr ); ## ==> { baz => 2 }

         my $object2 = My::Class->new( attr => { foo => 0, bar => 1, baz => 2 } );
         $object2->my_delete_where( qr/^b/ );
         say Dumper( $object2->attr ); ## ==> { foo => 0 }

   "elements()"
       Returns the hash in list context.

         my $object = My::Class->new( attr => { foo => 0, bar => 1 } );
         my %hash = $object->my_elements;

   "exists( $key )"
       Arguments: Str.

       Indicates whether a value exists in the hashref by its key.

         my $object = My::Class->new( attr => { foo => 0, bar => 1 } );
         say $object->my_exists( 'foo' ); ## ==> true
         say $object->my_exists( 'baz' ); ## ==> false

   "for_each_key( $coderef )"
       Arguments: CodeRef.

       Chainable method which calls the coderef for each key in the hash, passing just the key to
       the coderef.

   "for_each_pair( $coderef )"
       Arguments: CodeRef.

       Chainable method which calls the coderef for each key in the hash, passing the key and
       value to the coderef.

   "for_each_value( $coderef )"
       Arguments: CodeRef.

       Chainable method which calls the coderef for each value in the hash, passing just the
       value to the coderef.

   "get( $key )"
       Returns a value from the hashref by its key.

         my $object = My::Class->new( attr => { foo => 0, bar => 1 } );
         say $object->my_get( 'bar' ); ## ==> 1

   "is_empty()"
       Returns true iff there are no keys in the hash.

         my $object = My::Class->new( attr => { foo => 0, bar => 1 } );
         say $object->my_is_empty; ## ==> false
         $object->_set_attr( {} );
         say $object->my_is_empty; ## ==> true

   "keys()"
       Returns the list of keys in the hash.

         my $object = My::Class->new( attr => { foo => 0, bar => 1 } );
         # says 'foo' and 'bar' in an unpredictable order
         say for $object->my_keys;

   "kv()"
       Returns a list of arrayrefs, where each arrayref is a key-value pair.

   "reset()"
       Resets the attribute to its default value, or an empty hashref if it has no default.

   "set( $key, $value, ... )"
       Given a key and value, adds the key to the hashref with the given value.

         my $object = My::Class->new( attr => { foo => 0, bar => 1 } );
         $object->my_set( bar => 2, baz => 1 );
         say $object->attr->{foo}; ## ==> 0
         say $object->attr->{baz}; ## ==> 1
         say $object->attr->{bar}; ## ==> 2

   "shallow_clone()"
       Creates a new hashref with the same keys and values as the original.

   "sorted_keys()"
       Returns an alphabetically sorted list of keys in the hash.

         my $object = My::Class->new( attr => { foo => 0, bar => 1 } );
         # says 'bar' then 'foo'
         say for $object->my_sorted_keys;

   "values()"
       Returns the list of values in the hash.

         my $object = My::Class->new( attr => { foo => 0, bar => 1 } );
         # says '0' and '1' in an unpredictable order
         say for $object->my_values;

BUGS

       Please report any bugs to <https://github.com/tobyink/p5-sub-handlesvia/issues>.

SEE ALSO

       Sub::HandlesVia.

AUTHOR

       Toby Inkster <tobyink@cpan.org>.

COPYRIGHT AND LICENCE

       This software is copyright (c) 2020, 2022 by Toby Inkster.

       This is free software; you can redistribute it and/or modify it under the same terms as
       the Perl 5 programming language system itself.

DISCLAIMER OF WARRANTIES

       THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING,
       WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR
       PURPOSE.