NAME
Role::TinyCommons::Collection::PickItems::RandomSeekLines - Provide pick_items() that picks items by random seeking lines in a (file)handle
VERSION
This document describes version 0.008 of Role::TinyCommons::Collection::PickItems::RandomSeekLines (from Perl distribution Role-TinyCommons-Collection), released on 2021-05-20.
DESCRIPTION
This role provides pick_items() that picks random items by seeking lines in a seekable filehandle. Your class must support these methods to expose the seekable handle: fh
(and optionally fh_min_offset
and fh_max_offset
) (if your collection does not meet this requirement, there are other choices in Role::TinyCommons::Collection::PickItems::*
).
The algorithm is as follow:
If
fh_min_offset
andfh_max_offset
is not available, then do astat()
on the handle to find the size ($size
).Seek to a random position in the handle (if
fh_min_offset
andfh_max_offset
is available, then seek between these limits; otherwise seek between 0 and$size
.If we seek to the minimum position (0 or
fh_min_offset
), we find the next newiine and get the line as the random item to pick. Otherwise, since we might seek to the middle of a line, we find the next newline and discard the partial line first, then get the next line as the random item to pick.Remove duplicates as needed (unless
pick_items()
'sallow_resampling
option is set to true). Repeat step 2 and 3 until we get the required number of random items to pick.
Caveats:
Each of your item must be a line in the handle (excluding the newline) because this method bypasses the
get_next_item()
abstraction.Not all lines are picked uniformly. Due to the nature of the algorithm, the algorithm favors longer lines; longer lines have a greater probability of being picked.
ROLES MIXED IN
Role::TinyCommons::Collection::PickItems
REQUIRED METHODS
get_item_at_pos
get_item_count
HOMEPAGE
Please visit the project's homepage at https://metacpan.org/release/Role-TinyCommons-Collection.
SOURCE
Source repository is at https://github.com/perlancar/perl-Role-TinyCommons-Collection.
BUGS
Please report any bugs or feature requests on the bugtracker website https://github.com/perlancar/perl-Role-TinyCommons-Collection/issues
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.
SEE ALSO
Role::TinyCommons::Collection::PickItems and other Role::TinyCommons::Collection::PickItems::*
.
AUTHOR
perlancar <perlancar@cpan.org>
COPYRIGHT AND LICENSE
This software is copyright (c) 2021 by 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.