view release on metacpan or  search on metacpan

lib/Array/Find.pm  view on Meta::CPAN

package Array::Find;

our $DATE = '2015-09-03'; # DATE
our $VERSION = '0.08'; # VERSION

use 5.010001;
use strict;
use warnings;

use List::Util qw(shuffle);

require Exporter;
our @ISA       = qw(Exporter);
our @EXPORT_OK = qw(find_in_array);

our %SPEC;

$SPEC{find_in_array} = {
    v => 1.1,
    summary       => 'Find items in array, with several options',
    description   => <<'_',

find_in_array looks for one or more items in one or more arrays and return an
array containing all or some results (empty arrayref if no results found). You
can specify several options, like maximum number of results, maximum number of
comparisons, searching by suffix/prefix, case sensitivity, etc. Consult the list
of arguments for more details.

Currently, items are compared using the Perl's eq operator, meaning they only
work with scalars and compare things asciibetically.

_
    args          => {
        item             => {
            summary      => 'Item to find',
            description  => <<'_',

Currently can only be scalar. See also 'items' if you want to find several items
at once.

_
            schema       => ['str*'],
            pos          => 0,
        },
        array            => {
            summary      => 'Array to find items in',
            description  => <<'_',

See also 'arrays' if you want to find in several arrays. Array elements can be
undef and will only match undef.

_
            schema       => ['array*' => of=>'str*'],
            pos          => 1,
        },
        items            => {
            summary      => "Just like 'item', except several",
            description  => <<'_',

Use this to find several items at once. Elements can be undef if you want to
search for undef.

Example: find_in_array(items => ["a", "b"], array => ["b", "a", "c", "a"]) will
return result ["b", "a", "a"].

_
            schema       => ['array*' => of => 'str*'],
        },
        arrays            => {
            summary      => "Just like 'array', except several",
            description  => <<'_',

Use this to find several items at once.

Example: find_in_array(item => "a", arrays => [["b", "a"], ["c", "a"]]) will
return result ["a", "a"].

_
            schema       => ['array*' => of=>['array*', of=>'str*']],
        },
        max_result       => {
            summary      => "Set maximum number of results",
            description  => <<'_',

lib/Array/Find.pm  view on Meta::CPAN

}

1;
# ABSTRACT: Find items in array, with several options

__END__

=pod

=encoding UTF-8

=head1 NAME

Array::Find - Find items in array, with several options

=head1 VERSION

This document describes version 0.08 of Array::Find (from Perl distribution Array-Find), released on 2015-09-03.

=head1 SYNOPSIS

 use Array::Find qw(find_in_array);
 use Data::Dump;

 dd find_in_array(
     items      => [qw/a x/],
     array      => [qw/a b d a y x/],
     max_result => 2,
 ); # ['a', 'a']

 # return unique results
 dd find_in_array(
     items      => [qw/a x/],
     array      => [qw/a b d a y x/],
     max_result => 2,
     unique     => 1,
 ); # ['a', 'x']

 # find by prefix (or suffix, with/without word separator), in multiple arrays
 dd find_in_array(
     item       => 'a.b',
     mode       => 'prefix',
     word_sep   => '.',
     arrays     => [
         [qw/a a.b. a.b a.bb/],
         [qw/a.b.c b.c.d/],
     ],
 ); # ['a.b.', 'a.b', 'a.b.c']

=head1 DESCRIPTION

This module provides one subroutine: C<find_in_array> to find items in array.

=head1 FUNCTIONS


=head2 find_in_array(%args) -> any

Find items in array, with several options.

find_in_array looks for one or more items in one or more arrays and return an
array containing all or some results (empty arrayref if no results found). You
can specify several options, like maximum number of results, maximum number of
comparisons, searching by suffix/prefix, case sensitivity, etc. Consult the list
of arguments for more details.

Currently, items are compared using the Perl's eq operator, meaning they only
work with scalars and compare things asciibetically.

Arguments ('*' denotes required arguments):

=over 4

=item * B<array> => I<array[str]>

Array to find items in.

See also 'arrays' if you want to find in several arrays. Array elements can be
undef and will only match undef.

=item * B<arrays> => I<array[array[str]]>

Just like 'array', except several.

Use this to find several items at once.

Example: find_in_array(item => "a", arrays => [["b", "a"], ["c", "a"]]) will
return result ["a", "a"].

=item * B<ci> => I<bool> (default: 0)

Set case insensitive.

=item * B<item> => I<str>

Item to find.

Currently can only be scalar. See also 'items' if you want to find several items
at once.

=item * B<items> => I<array[str]>

Just like 'item', except several.

Use this to find several items at once. Elements can be undef if you want to
search for undef.

Example: find_in_array(items => ["a", "b"], array => ["b", "a", "c", "a"]) will
return result ["b", "a", "a"].

=item * B<max_compare> => I<int>

Set maximum number of comparison.

Maximum number of elements in array(s) to look for, 0 means unlimited. Finding
will stop as soon as this limit is reached, regardless of max_result. Example:
find(item=>'a', array=>['q', 'w', 'e', 'a'], max_compare=>3) will not return
result.

=item * B<max_result> => I<int>