NAME

    Data::Dict - Hash-based dictionary object

SYNOPSIS

      use Data::Dict;
    
      # Manipulate dictionary
      my $dictionary = Data::Dict->new(a => 1, b => 2, c => 3);
      delete $dictionary->{b};
      print join "\n", $dictionary->keys;
    
      # Chain methods
      $dictionary->slice(qw(a b))->grep(sub { defined $_[1] })->each(sub {
        my ($key, $value) = @_;
        print "$key: $value\n";
      });
    
      # Use the alternative constructor
      use Data::Dict 'd';
      use experimental 'signatures';
      my $num_highest = d(%counts)->transform(sub ($k, $v) { ($k, $v+1) })->grep(sub ($k, $v) { $v > 5 })->size;
    
      # Use Mojo::Collection for more chaining
      d(%hash)->map_c(sub { join ':', @_ })->shuffle->join("\n")->say;

DESCRIPTION

    Data::Dict is a hash-based container for dictionaries, with heavy
    inspiration from Mojo::Collection.

      # Access hash directly to manipulate dictionary
      my $dict = Data::Dict->new(a => 1, b => 2, c => 3);
      $dict->{b} += 100;
      print "$_\n" for values %$dict;

FUNCTIONS

 d

      my $dict = d(a => 1, b => 2);

    Construct a new hash-based Data::Dict object. Exported on demand.

METHODS

 new

      my $dict = Data::Dict->new(a => 1, b => 2);

    Construct a new hash-based Data::Dict object.

 TO_JSON

    Alias for "to_hash".

 delete

      my $deleted = $dict->delete(@keys);

    Delete selected keys from the dictionary and return a new dictionary
    containing the deleted keys and values.

 each

      my @pairs = $dict->each;
      $dict     = $dict->each(sub {...});

    Evaluate callback for each pair in the dictionary in sorted-key order,
    or return pairs as list of key/value arrayrefs in sorted-key order if
    none has been provided. The callback will receive the key and value as
    arguments.

      $dict->each(sub {
        my ($key, $value) = @_;
        print "$key: $value\n";
      });
    
      # values can be modified in place
      $dict->each(sub { $_[1] = $_[0]x2 });

 each_c

      my $collection = $dict->each_c;

    Create a new collection of key/value pairs as collections in sorted-key
    order. Requires Mojo::Collection.

      # print all keys and values
      print $dict->each_c->flatten->join(' ');

 extract

      my $extracted = $dict->extract(qr/foo/);
      my $extracted = $dict->extract(sub {...});

    Evaluate regular expression on each key, or call callback on each
    key/value pair in the dictionary in sorted-key order, and remove all
    pairs that matched the regular expression, or for which the callback
    returned true. Return a new dictionary with the removed keys and
    values. The callback will receive the key and value as arguments.

      my $high_numbers = $dict->extract(sub { $_[1] > 100 });

 grep

      my $new = $dict->grep(qr/foo/);
      my $new = $dict->grep(sub {...});

    Evaluate regular expression on each key, or call callback on each
    key/value pair in the dictionary in sorted-key order, and return a new
    dictionary with all pairs that matched the regular expression, or for
    which the callback returned true. The callback will receive the key and
    value as arguments.

      my $banana_dict = $dict->grep(qr/banana/);
    
      my $fruits_dict = $dict->grep(sub { $_[1]->isa('Fruit') });

 keys

      my @keys = $dict->keys;
      $dict    = $dict->keys(sub {...});

    Evaluate callback for each key in the dictionary in sorted-key order,
    or return all keys as a sorted list if none has been provided. The key
    will be the first argument passed to the callback, and is also
    available as $_.

 keys_c

      my $collection = $dict->keys_c;

    Create a new collection from sorted keys. Requires Mojo::Collection.

      my $first_key = $dict->keys_c->first;

 map

      my @results = $dict->map(sub {...});

    Evaluate callback for each key/value pair in the dictionary in
    sorted-key order and return the results as a list. The callback will
    receive the key and value as arguments.

      my @pairs = $dict->map(sub { [@_] });
    
      my @values = $dict->map(sub { $_[1] });

 map_c

      my $collection = $dict->map_c(sub {...});

    Evaluate callback for each key/value pair in the dictionary in
    sorted-key order and create a new collection from the results. The
    callback will receive the key and value as arguments. Requires
    Mojo::Collection.

      my $output = $dict->map_c(sub { "$_[0]: $_[1]" })->join("\n");

 size

      my $size = $dict->size;

    Number of keys in dictionary.

 slice

      my $new = $dict->slice(@keys);

    Create a new dictionary with all selected keys.

      print join ' ', d(a => 1, b => 2, c => 3)->slice('a', 'c')->map(sub { join ':', @_ });
      # a:1 c:3

 tap

      $dict = $dict->tap(sub {...});

    Perform callback and return the dictionary object for further chaining,
    as in "tap" in Mojo::Base. The dictionary object will be the first
    argument passed to the callback, and is also available as $_.

 to_array

      my $array = $dict->to_array;

    Turn dictionary into even-sized array reference in sorted-key order.

 to_hash

      my $hash = $dict->to_hash;

    Turn dictionary into hash reference.

 transform

      my $new = $dict->transform(sub {...});

    Evaluate callback for each key/value pair in the dictionary in
    sorted-key order and create a new dictionary from the returned keys and
    values (assumed to be an even-sized key/value list). The callback will
    receive the key and value as arguments.

      my $reversed = $dict->transform(sub { ($_[1], $_[0]) });
    
      my $doubled = $dict->transform(sub {
        my ($k, $v) = @_;
        return ($k => $v, ${k}x2 => $v);
      });

 values

      my @values = $dict->values;
      $dict      = $dict->values(sub {...});

    Evaluate callback for each value in the dictionary in sorted-key order,
    or return all values as a list in sorted-key order if none has been
    provided. The value will be the first argument passed to the callback,
    and is also available as $_.

      # values can be modified in place
      $dict->values(sub { $_++ });

 values_c

      my $collection = $dict->values_c;

    Create a new collection from all values in sorted-key order. Requires
    Mojo::Collection.

      my @shuffled_values = $dict->values_c->shuffle->each;

BUGS

    Report any issues on the public bugtracker.

AUTHOR

    Dan Book <dbook@cpan.org>

COPYRIGHT AND LICENSE

    This software is Copyright (c) 2018 by Dan Book.

    This is free software, licensed under:

      The Artistic License 2.0 (GPL Compatible)

SEE ALSO

    Mojo::Collection

