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

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

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

    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 being chosen. An element can
    be picked more than once.

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

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

    Options:

    *   pos => bool

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

    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
    Other sampling methods: Array::Sample::SysRand,
    Array::Sample::Partition.

    Array::Sample::SimpleRandom::Scan

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.