/ 
Array-Find-0.08
River stage one • 1 direct dependent • 1 total dependent
/ Array::Find

NAME

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

VERSION

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

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']

DESCRIPTION

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

FUNCTIONS

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):

  • array => 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.

  • arrays => 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"].

  • ci => bool (default: 0)

    Set case insensitive.

  • item => str

    Item to find.

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

  • items => 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"].

  • max_compare => 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.

  • max_result => int

    Set maximum number of results.

    0 means unlimited (find in all elements of all arrays).

    +N means find until results have N items. Example: find_in_array(item=>'a', array=>['a', 'b', 'a', 'a'], max_result=>2) will return result ['a', 'a'].

    -N is useful when looking for multiple items (see 'items' argument). It means find until N items to look for have been found. Example: find_in_array(items=>['a','b'], array=>['a', 'a', 'b', 'b'], max_results=>-2) will return result ['a', 'a', 'b']. As soon as 2 items to look for have been found it will stop.

  • mode => str (default: "exact")

    Comparison mode.

    Exact match is the default, will only match 'ap' with 'ap'. Prefix matching will also match 'ap' with 'ap', 'apple', and 'apricot'. Suffix matching will match 'le' with 'le' and 'apple'. Infix will only match 'ap' with 'claps' and not with 'ap', 'clap', or 'apple'. Regex will regard item as a regex and perform a regex match on each element of array.

    See also 'word_sep' which affects prefix/suffix/infix matching.

  • shuffle => bool

    Shuffle result.

  • unique => bool

    Whether to return only unique results.

    If set to true, results will not contain duplicate items.

  • word_sep => str

    Define word separator.

    If set, item and array element will be regarded as a separated words. This will affect prefix/suffix/infix matching. Example, with '.' as the word separator and 'a.b' as the item, prefix matching will 'a.b', 'a.b.', and 'a.b.c' (but not 'a.bc'). Suffix matching will match 'a.b', '.a.b', 'c.a.b' (but not 'ca.b'). Infix matching will match 'c.a.b.c' and won't match 'a.b', 'a.b.c', or 'c.a.b'.

Return value: (any)

SEE ALSO

List::Util, List::MoreUtils

HOMEPAGE

Please visit the project's homepage at https://metacpan.org/release/Array-Find.

SOURCE

Source repository is at https://github.com/perlancar/perl-Array-Find.

BUGS

Please report any bugs or feature requests on the bugtracker website https://rt.cpan.org/Public/Dist/Display.html?Name=Array-Find

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.

AUTHOR

perlancar <perlancar@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2015 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.