NAME
    List::Util::Uniq - List utilities related to finding unique items

VERSION
    This document describes version 0.008 of List::Util::Uniq (from Perl
    distribution List-Util-Uniq), released on 2024-01-19.

SYNOPSIS
     use List::Util::Uniq qw(
         uniq
         uniqint
         uniqnum
         uniqstr

         is_monovalued
         is_monovalued_ci
         is_uniq
         is_uniq_ci
         uniq_adj
         uniq_adj_ci
         uniq_ci

         dupe
         dupeint
         dupenum
         dupestr
         dupe_ci

         pushuniq
         pushuniqint
         pushuniqnum
         pushuniqstr
     );

     $res = is_monovalued(qw/a a a/); # => 1
     $res = is_monovalued(qw/a b a/); # => 0

     $res = is_monovalued_ci(qw/a a A/); # => 1
     $res = is_monovalued_ci(qw/a b A/); # => 0

     $res = is_uniq(qw/a b a/); # => 0
     $res = is_uniq(qw/a b c/); # => 1

     $res = is_uniq_ci(qw/a b A/); # => 0
     $res = is_uniq_ci(qw/a b c/); # => 1

     @res = uniq_adj(1, 4, 4, 3, 1, 1, 2); # => (1, 4, 3, 1, 2)

     @res = uniq_adj_ci("a", "b", "B", "c", "a"); # => ("a", "b", "c", "a")

     @res = uniq_ci("a", "b", "B", "c", "a"); #  => ("a", "b", "c")

     @res = dupe("a","b","a","a","b","c"); #  => ("a","a","b")
     @res = dupeint(1,1.2,1.3,2); #  => (1.2,1.3)
     @res = dupenum(1,2,1,1,2,3); #  => (1,1,2)
     @res = dupenum("a",0,0.0,1); #  => (0,0.0), because "a" becomes 0 numerically
     @res = dupestr("a","b","a","a","b","c"); # => ("a","a","b")

     @res = dupe_ci("a", "b", "B", "c", "a"); #  => ("B", "a")

     my @ary = (1,"a",2,1,"a","b"); pushuniqstr @ary, 1,"a","c","c";   # @ary is now (1,"a",2,1,"a","b","c")
     my @ary = (1,"1.0",1.1,2); pushuniqnum @ary, 2,"1.00",1.2,"1.000",3,3;   # @ary is now (1,"1.0",1.1,2,1.2,3)
     my @ary = (1,"1.0",1.1,2); pushuniqint @ary, 2,"1.00",1.2,"1.000",3,3;   # @ary is now (1,"1.0",1.1,2,3)

DESCRIPTION
    This module supplements List::Util with functions related to list item's
    uniqueness.

FUNCTIONS
    None exported by default but exportable.

  uniq
    See "uniqstr".

  uniqnum
    Usage:

     my @uniq = uniqnum(@list);

    Like List::Util's "uniqnum". This module provides a pure-Perl
    implementation for convenience and so we do not need to depend on
    List::Util.

  uniqint
    Usage:

     my @uniq = uniqint(@list);

    Like List::Util's "uniqint". This module provides a pure-Perl
    implementation for convenience and so we do not need to depend on
    List::Util.

  uniqstr
    Usage:

     my @uniq = uniqstr(@list);

    Like List::Util's "uniqstr". This module provides a pure-Perl
    implementation for convenience and so we do not need to depend on
    List::Util.

  uniq_adj
    Usage:

     my @uniq = uniq_adj(@list);

    Remove *adjacent* duplicates from list, i.e. behave more like Unix
    utility's uniq instead of List::Util's "uniq" function. Uses string
    equality test (the "eq" operator).

  uniq_adj_ci
    Like "uniq_adj" except case-insensitive.

  uniq_ci
    Like "List::Util"' "uniq" ("uniqstr") except case-insensitive.

  is_uniq
    Usage:

     my $is_uniq = is_uniq(@list);

    Return true when the values in @list is unique (compared string-wise).
    In theory, knowing whether a list has unique values is faster using this
    function compared to doing:

     my @uniq = uniq(@list);
     @uniq == @list;

    because of short-circuiting.

  is_uniq_ci
    Like "is_uniq" except case-insensitive.

  is_monovalued
    Usage:

     my $is_monovalued = is_monovalued(@list);

    Examples:

     is_monovalued(qw/a b c/); # => 0
     is_monovalued(qw/a a a/); # => 1

    Return true if @list contains only a single value. Returns true for
    empty list. Undef is coerced to empty string, so is_monovalued(undef)
    and "is_monovalued(undef, undef)" return true.

  is_monovalued_ci
    Like "is_monovalued" except case-insensitive.

  dupe
    See "dupestr".

  dupeint
    Like "dupestr" but the values are compared as integers. If you only want
    to list each duplicate elements once, you can do:

     @uniq_dupes = uniqint(dupeint(@list));

    where "uniqint" can be found in List::Util, but the pure-perl version is
    also provided by this module, for convenience.

  dupenum
    Like "dupestr" but the values are compared numerically. If you only want
    to list each duplicate elements once, you can do:

     @uniq_dupes = uniqnum(dupenum(@list));

    where "uniqnum" can be found in List::Util, but the pure-perl version is
    also provided by this module, for convenience.

  dupestr
    Usage:

     @dupes = dupestr(@list);

    Return duplicate elements (the second and subsequence occurrences of
    each element) in @list. If you only want to list each duplicate elements
    once, you can do:

     @uniq_dupes = uniqstr(dupestr(@list));

    where "uniqstr" can be found in List::Util, but the pure-perl version is
    also provided by this module, for convenience.

  dupe_ci
    Like "dupe" except case-insensitive.

  pushuniq
    See "pushuniqstr".

  pushuniqstr
    Usage:

     pushuniqstr @ary, LIST;

    Push items of *LIST* to *@ary* only if items are not already in @ary
    (using string-wise equal comparison operator, "eq"). Shortcut for
    something like:

     for my $item (LIST) { push @ary, $_ unless grep { $item eq $_ } @ary }

  pushuniqnum
    Usage:

     pushuniqnum @ary, LIST;

    Push items of *LIST* to *@ary* only if items are not already in @ary
    (using numeric equal comparison operator, "=="). Shortcut for something
    like:

     for my $item (LIST) { push @ary, $_ unless grep { $item == $_ } @ary }

  pushuniqint
    Usage:

     pushuniqnum @ary, LIST;

    Push items of *LIST* to *@ary* only if items are not already in @ary
    (using integer equal comparison). Shortcut for something like:

     for my $item (LIST) { push @ary, $_ unless grep { int($item) == int($_) } @ary }

HOMEPAGE
    Please visit the project's homepage at
    <https://metacpan.org/release/List-Util-Uniq>.

SOURCE
    Source repository is at
    <https://github.com/perlancar/perl-List-Util-Uniq>.

SEE ALSO
    List::Util

    Other "List::Util::*" modules.

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,
    Pod::Weaver::PluginBundle::Author::PERLANCAR, and sometimes one or two
    other Dist::Zilla- and/or Pod::Weaver plugins. Any additional steps
    required beyond that are considered a bug and can be reported to me.

COPYRIGHT AND LICENSE
    This software is copyright (c) 2024, 2023, 2018 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=List-Util-Uniq>

    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.