NAME
    Array::Sample::WeightedRandom - Sample elements randomly, with weights
    (with or without replacement)

VERSION
    This document describes version 0.005 of Array::Sample::WeightedRandom
    (from Perl distribution Array-Sample-WeightedRandom), released on
    2022-05-22.

SYNOPSIS
     use Array::Sample::WeightedRandom qw(sample_weighted_random_with_replacement sample_weighted_random_no_replacement);

     # "b" will be picked more often because it has a greater weight. it's also more
     # likely to be picked at the beginning.
     sample_weighted_random_with_replacement([ ["a",1], ["b",2.5] ], 1); => ("b")
     sample_weighted_random_with_replacement([ ["a",1], ["b",2.5] ], 1); => ("a")
     sample_weighted_random_with_replacement([ ["a",1], ["b",2.5] ], 1); => ("b")
     sample_weighted_random_with_replacement([ ["a",1], ["b",2.5] ], 5); => ("b", "b", "a", "b", "b")

     sample_weighted_random_no_replacement([ ["a",1], ["b",2.5] ], 5); => ("b", "a")

DESCRIPTION
    Keywords: weight, weighting, pick

FUNCTIONS
    All functions are not exported by default, but exportable.

  sample_weighted_random_with_replacement
    Syntax: sample_simple_random_with_replacement(\@ary, $n [ , \%opts ]) =>
    list

    Options:

    *   pos => bool

        If set to true, will return positions instead of the elements.

    *   shuffle => bool

        By default, a heavier-weighted item will be more likely to be at the
        front of the resulting sample. If this option is set to true, the
        function will shuffle the random samples before returning it,
        resulting in random order regardless of weight.

    *   algo => str

        Default is 'copy'. Another choice is 'nocopy', which avoids creating
        a shallow (1-level) copy of the input array. The 'nocopy' algorithm
        is generally a bit slower but could save memory usage *if* your
        array is very very large (e.g. tens of millions of elements).

    *   with_weight => bool

        If set to true, will return the original elements (values with
        weights) instead of just the values.

    The function takes an array reference ("\@ary") and number of samples to
    take ($n). The array must be structured as follow: each element is a
    2-element arrayref containing a value followed by weight (a non-negative
    real number). The function will take samples at random position but
    taking weight into consideration. The larger the weight of an element,
    the greater the possibility of the element's value being chosen *and*
    the greater the possibility of the element's value being in the front of
    the samples. An element can be picked more than once.

    The function will return a list of sample items (values only, without
    the weights).

    If you want random order regardless of weight, you can shuffle the
    resulting list e.g. using List::Util's "shuffle"; or you can use the
    "shuffle" option which does the same.

  sample_weighted_random_no_replacement
    Syntax: sample_simple_random_no_replacement(\@ary, $n [ , \%opts ]) =>
    list

    Like "sample_weighted_random_with_replacement" but an element can only
    be picked once.

HOMEPAGE
    Please visit the project's homepage at
    <https://metacpan.org/release/Array-Sample-WeightedRandom>.

SOURCE
    Source repository is at
    <https://github.com/perlancar/perl-Array-Sample-WeightedRandom>.

SEE ALSO
    Data::Random::Weighted returns only a single item, uses hash internally
    so you can't have duplicate elements, and only allows integer as
    weights.

    Other sampling methods: Array::Sample::SysRand,
    Array::Sample::Partition, Array::Sample::SimpleRandom.

AUTHOR
    perlancar <perlancar@cpan.org>

CONTRIBUTING
    To contribute, you can send patches by email/via RT, or send pull
    requests on GitHub.

    Most of the time, you don't need to build the distribution yourself. You
    can simply modify the code, then test via:

     % prove -l

    If you want to build the distribution (e.g. to try to install it locally
    on your system), you can install Dist::Zilla,
    Dist::Zilla::PluginBundle::Author::PERLANCAR, and sometimes one or two
    other Dist::Zilla plugin and/or Pod::Weaver::Plugin. Any additional
    steps required beyond that are considered a bug and can be reported to
    me.

COPYRIGHT AND LICENSE
    This software is copyright (c) 2022 by perlancar <perlancar@cpan.org>.

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

BUGS
    Please report any bugs or feature requests on the bugtracker website
    <https://rt.cpan.org/Public/Dist/Display.html?Name=Array-Sample-Weighted
    Random>

    When submitting a bug or request, please include a test-file or a patch
    to an existing test-file that illustrates the bug or desired feature.