NAME

Data::Bucketeer - sort data into buckets based on thresholds

VERSION

version 0.006

OVERVIEW

Data::Bucketeer lets you easily map values in ranges to results. It's for doing table lookups where you're looking for the key in a range, not a list of fixed values.

For example, you sell widgets with prices based on quantity:

  YOU ORDER    | YOU PAY, EACH
  -------------+---------------
    1 -  100   |  10 USD
  101 -  200   |   5 USD
  201 -  500   |   4 USD
  501 - 1000   |   3 USD
  1001+        |   2 USD

This can be easily turned into a bucketeer:

  use Data::Bucketeer;

  my $buck = Data::Bucketeer->new({
       0 => 10,
     100 => 5,
     200 => 4,
     500 => 3,
    1000 => 2,
  });

  my $cost = $buck->result_for( 701 ); # cost is 3

By default, the values exclusive minima. For example, above, you end up with a result of 3 by having an input strictly greater than 500, and less than or equal to 500. If you want to use a different operator, you can specify it like this:

  my $buck = Data::Bucketeer->new( '>=', {
       1 => 10,
     101 => 5,
     201 => 4,
     501 => 3,
    1001 => 2,
  });

  my $cost = $buck->result_for( 701 ); # cost is 3

This distinction can be useful when dealing with non-integers. The understood operators are:

• >

• >=

• <=

• <

If the result value is a code reference, it will be invoked with $_ set to the input. This can be used for dynamically generating results, or to throw exceptions. Here is a contrived example of exception-throwing:

  my $greeting = Data::Bucketeer->new( '>=', {
    '-Inf' => sub { die "secs-into-day must be between 0 and 86399; got $_" },

         0 => "Good evening.",
    28_800 => "Good morning.",
    43_200 => "Good afternoon.",
    61_200 => "Good evening.",

    86_400 => sub { die "secs-into-day must be between 0 and 86399; got $_" },
  });

PERL VERSION

This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years.

Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl.

METHODS

result_for

  my $result = $buck->result_for( $input );

This returns the result for the given input, as described above.

bound_and_result_for

  my ($bound, $result) = $buck->bound_and_result_for( $input );

This returns two values: the boundary key whose result was used, and the result itself.

Using the item quantity price above, for example:

  my $buck = Data::Bucketeer->new({
       0 => 10,
     100 => 5,
     200 => 4,
     500 => 3,
    1000 => 2,
  });

  my ($bound, $cost) = $buck->bound_and_result_for( 701 );

  # $bound is 500
  # $cost  is 3

AUTHOR

Ricardo Signes <cpan@semiotic.systems>

CONTRIBUTORS

• Graham Knop <haarg@haarg.org>

• Ricardo Signes <rjbs@semiotic.systems>

• Ricardo Signes <rjbs@users.noreply.github.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2011 by Ricardo Signes.

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

cpanm Data::Bucketeer

perl -MCPAN -e shell
install Data::Bucketeer