=head1 NAME

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

=head1 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',
      },
    );
  }

=head1 DESCRIPTION

This is a library of methods for L<Sub::HandlesVia>.

=head1 DELEGATABLE METHODS

=head2 C<< accessor( $key, $value? ) >>

Arguments: B<< Str >>, B<< Optional[Any] >>.

Acts like C<get> if given just a key, or C<set> if given a key and a value.

=head2 C<< all() >>

Returns the hash in list context.

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

=head2 C<< 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

=head2 C<< count() >>

Returns the number of keys in the hash.

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

=head2 C<< defined( $key ) >>

Arguments: B<< 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

=head2 C<< 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

=head2 C<< delete_where( $match ) >>

Arguments: B<< 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 }

=head2 C<< elements() >>

Returns the hash in list context.

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

=head2 C<< exists( $key ) >>

Arguments: B<< 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

=head2 C<< for_each_key( $coderef ) >>

Arguments: B<< CodeRef >>.

Chainable method which calls the coderef for each key in the hash, passing just the key to the coderef. The key will also be available as C<< $_ >>.

=head2 C<< for_each_pair( $coderef ) >>

Arguments: B<< CodeRef >>.

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

=head2 C<< for_each_value( $coderef ) >>

Arguments: B<< CodeRef >>.

Chainable method which calls the coderef for each value in the hash, passing just the value to the coderef. The value will also be available as C<< $_ >>.

=head2 C<< 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

=head2 C<< 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

=head2 C<< 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;

=head2 C<< kv() >>

Returns a list of arrayrefs, where each arrayref is a key-value pair.

=head2 C<< reset() >>

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

=head2 C<< 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

=head2 C<< shallow_clone() >>

Creates a new hashref with the same keys and values as the original.

=head2 C<< 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;

=head2 C<< 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;

=head1 BUGS

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

=head1 SEE ALSO

L<Sub::HandlesVia>.

=head1 AUTHOR

Toby Inkster E<lt>tobyink@cpan.orgE<gt>.

=head1 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.

=head1 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.

