Role::TinyCommons::Collection::FindItem - The find_item() interface


This document describes version 0.003 of Role::TinyCommons::Collection::FindItem (from Perl distribution Role-TinyCommons-Collection), released on 2021-04-20.


In your class:

 package YourClass;
 use Role::Tiny::With;
 with 'Role::TinyCommons::Collection::FindItem';

 sub new { ... }
 sub find_item { ... }

In the code of your class user:

 use YourClass;

 my $obj = YourClass->new(...);

 # basic finding
 my @results = $obj->find_item(item => 'x');
 die "Not found" unless @results;

 # shortcut for the above
 die "Not found" unless $obj->has_item('x');

 # return all items instead of only the first
 my @results = $obj->find_item(item => 'x', all => 1);

 # return positions instead of the items themselves
 my @pos = $obj->find_item(item => 'x', return_pos => 1);

 # numeric comparison
 my @results = $obj->find_item(item => 10, numeric=>1);


find_item() is an interface to do exact matching and/or single-item searching in a collection. Some options are provided. The implementor is given flexibility to support additional options, but the basic modes of finding must be supported.

To search for multiple items based on some criteria, there is the Role::TinyCommons::Collection::SelectItems interface.




 my @results = $obj->find_item(%args);

Find an item. Must return either 0 (if not found) or 1 (if found) item. If "all" mode is turned on, can return more than one item. The item(s) themselves must be returned, unless "return_pos" mode is enabled, in which the positions are returned.


  • item

    Type: any. The item to search for. The item should be matched exactly with items in the collection (using numerical or string-wise equality comparison, or something like Data::Cmp), unless approximate matching ("approx") is turned on.

    If implementor provides both numeric vs string-wise comparison for choosing, the string-wise comparison must be the default and the numeric searching mode must be turned on using the "numeric" option.

    This argument must be supported.

  • return_pos

    Type: bool. If set to true, must return found positions of items in the collection instead of the items themselves.

    This argument must be supported for ordered collection (where each item in the collection has a fixed position).

  • all

    Type: bool. If set to true, must enable all mode, returning all instead of the first item found.

    This argument must be supported.

  • numeric

    Type: bool. If set to true, must enable numeric searching mode. Otherwise, string-wise searching mode is the default.

    This argument must be supported as a way to choose modes if both numeric and stringwise searching modes are available.

  • ignore_case

    Type: bool. If set to true, must enable case-insensitive matching. Otherwise, matching should be case-sensitive.

    This argument is optional to implement. It should be supported if stringwise comparison is used.

  • approx

    Type: bool. If set to true, must enable approximate matching.

    This argument is optional to implement.

Implementor is free to add more options.




 my $has_item = $obj->has_item($item);

Must return a bool, true if collection has item $item, false otherwise. Equivalent to:

 my @results = $obj->find_item(item => $item);
 return @results ? 1:0;


Please visit the project's homepage at


Source repository is at


Please report any bugs or feature requests on the bugtracker website

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.




perlancar <>


This software is copyright (c) 2021 by

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