=begin pod

=TITLE class Any

=SUBTITLE Thing/object

    class Any is Mu {}

While L<Mu|/type/Mu> is the root of the Perl 6 class hierarchy, C<Any> is the class
that serves as a default base class for new classes, and as the base class for
most built-in classes.

Since Perl 6 intentionally confuses items and single-element lists, most
methods in C<Any> are also present on class L<List|/type/List>, and coerce to
List or a list-like type.

=head1 Methods

=head2 method ACCEPTS

Defined as:

    multi method ACCEPTS(Any:D: Mu $other)

Usage:

=begin code :skip-test
EXPR.ACCEPTS(EXPR);
=end code

Returns C<True> if C<$other === self> (i.e. it checks object identity).

Many built-in types override this for more specific comparisons

=head2 method any

Defined as:

    method any(--> Junction:D)

Interprets the invocant as a list and creates an
C<any>-L<Junction|/type/Junction> from it.

    say so 2 == <1 2 3>.any;        # OUTPUT: «True␤»
    say so 5 == <1 2 3>.any;        # OUTPUT: «False␤»

=head2 method all

Defined as:

    method all(--> Junction:D)

Interprets the invocant as a list and creates an
C<all>-L<Junction|/type/Junction> from it.

    say so 1 < <2 3 4>.all;         # OUTPUT: «True␤»
    say so 3 < <2 3 4>.all;         # OUTPUT: «False␤»

=head2 method one

Defined as:

    method one(--> Junction:D)

Interprets the invocant as a list and creates a
C<one>-L<Junction|/type/Junction> from it.

    say so 1 == (1, 2, 3).one;      # OUTPUT: «True␤»
    say so 1 == (1, 2, 1).one;      # OUTPUT: «False␤»

=head2 method none

Defined as:

    method none(--> Junction:D)

Interprets the invocant as a list and creates a
C<none>-L<Junction|/type/Junction> from it.

    say so 1 == (1, 2, 3).none;     # OUTPUT: «False␤»
    say so 4 == (1, 2, 3).none;     # OUTPUT: «True␤»

=head2 method list

Defined as:

    method list(--> List:D)

Interprets the invocant as a list, and returns that L<List|/type/List>.

    say 42.list.^name;           # OUTPUT: «List␤»
    say 42.list.elems;           # OUTPUT: «1␤»

=head2 method push

Defined as:

    method push(|values --> Positional:D)

The method push is defined for undefined invocants and allows for
autovivifying undefined to an empty C<Array>, unless the undefined value
implements C<Positional> already.  The argument provided will then be pushed
into the newly created Array.

    my %h;
    dd %h<a>;      # Any (and therefore undefined)
    %h<a>.push(1); # .push on Any
    dd %h;         # «Hash %h = {:a($[1])}␤» # please note the Array

=head2 routine reverse

Defined as:

    multi sub    reverse(*@list  --> Seq:D)
    multi method reverse(List:D: --> Seq:D)

Returns a L«C<Seq>|/type/Seq> with the same elements in reverse order.

Note that C<reverse> always refers to reversing elements of a list;
to reverse the characters in a string, use L<flip>.

Examples:

    say <hello world!>.reverse;     # OUTPUT: «(world! hello)␤»
    say reverse ^10;                # OUTPUT: «(9 8 7 6 5 4 3 2 1 0)␤»

=head2 method sort

Sorts iterables with C<infix:<cmp>> or given code object and returns a new C<List>.

Examples:

    say <b c a>.sort;                           # OUTPUT: «(a b c)␤»
    say 'bca'.comb.sort.join;                   # OUTPUT: «abc␤»
    say 'bca'.comb.sort({$^b cmp $^a}).join;    # OUTPUT: «cba␤»
    say '231'.comb.sort(&infix:«<=>»).join;     # OUTPUT: «123␤»

=head2 method map

Defined as:

    multi method map(\SELF: &block;; :$label, :$item)
    multi method map(HyperIterable:D: &block;; :$label)

C<map> will iterate over the invocant and apply the number of positional
parameters of the code object from the invocant per call.  The returned values
of the code object will become elements of the returned C<Seq>.

The C<:$label> and C<:$item> are useful only internally, since C<for> loops
get converted to C<map>s. The C<:$label> takes an existing C<Label> to label
the C<.map>'s loop with and C<:$item> controls whether the iteration will
occur over C<(SELF,)> (if C<:$item> is set) or C<SELF>.

=head2 method deepmap

Defined as:

    method deepmap(&block --> List) is nodal

C<deepmap> will apply C<&block> to each element and return a new C<List> with
the return values of C<&block>, unless the element does the C<Iterable> role.
For those elements C<deepmap> will descend recursively into the sublist.

    dd [[1,2,3],[[4,5],6,7]].deepmap(*+1);
    # OUTPUT: «[[2, 3, 4], [[5, 6], 7, 8]]␤»

=head2 method duckmap

Defined as:

    method duckmap(&block) is rw is nodal

C<duckmap> will apply C<&block> on each element and return a new list with
defined return values of the block. For undefined return values, C<duckmap>
will try to descend into the element if that element implements C<Iterable>.

    my @a = [1,[2,3],4];
    dd @a.duckmap({ $_ ~~ Int ?? $_++ !! Any });
    # OUTPUT: «(1, (2, 3), 4)␤»

=head2 method flat

Defined as:

    method flat(--> Seq:D) is nodal

Interprets the invocant as a list, flattens it, and returns that list.
Please note that C<.flat> will not solve the
L<halting problem|https://en.wikipedia.org/wiki/Halting_problem> for you.
If you flat an infinite list C<.flat> may return that infinite list, eating
all your RAM in the process.

    say ((1, 2), (3)).elems;        # OUTPUT: «2␤»
    say ((1, 2), (3)).flat.elems;   # OUTPUT: «3␤»

Please note that C<flat> does not recurse into sub lists. You have to recurse by
hand or reconsider your data structures. A single level of nesting can often be
handled with L<destructuring|/type/Signature#Destructuring_Parameters> in
signatures. For deeper structures you may consider
L<gather/take|/syntax/gather take> to create a lazy list.

    my @a = [[1,2,3],[[4,5],6,7]];
    say gather deepmap *.take, @a; # OUTPUT: «(1 2 3 4 5 6 7)␤»

=head2 method eager

Defined as:

    method eager(--> Seq:D) is nodal

Interprets the invocant as a list, evaluates it eagerly, and returns that
list.

    say (1..10).eager;              # OUTPUT: «(1 2 3 4 5 6 7 8 9 10)␤»

=head2 method elems

Defined as:

    method elems(--> Int:D) is nodal

Interprets the invocant as a list, and returns the number of elements in the
list.

    say 42.elems;                   # OUTPUT: «1␤»
    say <a b c>.elems;              # OUTPUT: «3␤»

=head2 method end

    method end(--> Any:D) is nodal

Interprets the invocant as a list, and returns the last index of that list.

    say 6.end;                      # OUTPUT: «0␤»
    say <a b c>.end;                # OUTPUT: «2␤»

=head2 method pairup

Defined as:

    method pairup(--> Seq:D) is nodal

Interprets the invocant as a list, and constructs a list of
L<pairs|/type/Pair> from it, in the same way that assignment to a
L<Hash|/type/Hash> does.  That is, it takes two consecutive elements and
constructs a pair from them, unless the item in the key position already is a
pair (in which case the pair is passed is passed through, and the next
list item, if any, is considered to be a key again).

    say (a => 1, 'b', 'c').pairup.perl;     # OUTPUT: «(:a(1), :b("c")).Seq␤»

=head2 sub exit

Defined as:

    sub exit(Int() $status = 0)

Exits the current process with return code C<$status>.

=comment TODO maybe find a better place to document &exit

=head2 sub item

X<|$ (item contextualizer)>

Defined as:

    proto sub item(|) is pure
    multi sub item(\x)
    multi sub item(|c)
    multi sub item(Mu $a)

Forces given object to be evaluated in item context and returns the value of it.

    say item([1,2,3]).perl;              # OUTPUT: «$[1, 2, 3]␤»
    say item({ apple => 10 }).perl;      # OUTPUT: «${:apple(10)}␤»
    say item("abc").perl;                # OUTPUT: «"abc"␤»

You can also use C<$> as item contextualizer.

    say $[1,2,3].perl;                   # OUTPUT: «$[1, 2, 3]␤»
    say $("abc").perl;                   # OUTPUT: «"abc"␤»

=head2 method Array

Defined as:

    method Array(--> Array:D) is nodal

Coerce the invocant to L<Array|/type/Array>.

=head2 method List

Defined as:

    method List(--> List:D) is nodal

Coerce the invocant to L<List|/type/List>.

=head2 method Hash

Defined as:

    method Hash(--> Hash:D) is nodal

Coerce the invocant to L<Hash|/type/Hash>.

=head2 method hash

Defined as:

    method hash(--> Hash:D) is nodal

Coerce the invocant to L<Hash|/type/Hash>.

=head2 method Slip

Defined as:

    method Slip(--> Slip:D) is nodal

Coerce the invocant to L<Slip|/type/Slip>.

=head2 method Map

Defined as:

    method Map(--> Map:D) is nodal

Coerce the invocant to L<Map|/type/Map>.

=head2 method Bag

Defined as:

    method Bag(--> Bag:D) is nodal

Coerce the invocant to L<Bag|/type/Bag>, whereby C<Positionals> are treated as
lists of values.

=head2 method BagHash

Defined as:

    method BagHash(--> BagHash:D) is nodal

Coerce the invocant to L<BagHash|/type/BagHash>, whereby C<Positionals> are
treated as lists of values.

=head2 method Set

Defined as:

    method Set(--> Set:D) is nodal

Coerce the invocant to L<Set|/type/Set>, whereby C<Positionals> are treated as
lists of values.

=head2 method SetHash

Defined as:

    method SetHash(--> SetHash:D) is nodal

Coerce the invocant to L<SetHash|/type/BSetash>, whereby C<Positionals> are
treated as lists of values.

=head2 method Mix

Defined as:

    method Mix(--> Mix:D) is nodal

Coerce the invocant to L<Mix|/type/Mix>, whereby C<Positionals> are treated as
lists of values.

=head2 method MixHash

Defined as:

    method MixHash(--> MixHash:D) is nodal

Coerce the invocant to L<MixHash|/type/MixHash>, whereby C<Positionals> are
treated as lists of values.

=head2 method Supply

Defined as:

    method Supply(--> Supply:D) is nodal

Coerce the invocant first to a C<List> and then to a L<Supply|/type/Supply>.

=head2 method min

Defined As:

    multi method min(--> Any:D)
    multi method min(&by --> Any:D)

Coerces to Iterable and returns the numerically smallest element. If a
C<Callable> is provided it is called with each element and its smallest return
values is returned.

=head2 method max

Defined As:

    multi method max(--> Any:D)
    multi method min(&by --> Any:D)

Coerces to Iterable and returns the numerically biggest element. If a
C<Callable> is provided it is called with each element and its biggest return
values is returned.

=head2 method minmax

Defined As:

    multi method minmax(--> List:D)
    multi method minmax(&by --> List:D)

Returns a list containing the smallest and the biggest element. If a
C<Callable> is provided each element is filtered and then numerically compared.

TODO

=head2 method minpairs

Defined As:

    multi method minpairs(Any:D: --> Seq:D)

Calls L«C<.pairs>|/routine/pairs» and returns a L«C<Seq>|/type/Seq» with
all of the Pairs with minimum values, as judged by the
L«C<cmp> operator|/routine/cmp»:

    <a b c a b c>.minpairs.perl.put; # OUTPUT: «(0 => "a", 3 => "a").Seq␤»
    %(:42a, :75b).minpairs.perl.put; # OUTPUT: «(:a(42),).Seq␤»

=head2 method maxpairs

Defined As:

    multi method maxpairs(Any:D: --> Seq:D)

Calls L«C<.pairs>|/routine/pairs» and returns a L«C<Seq>|/type/Seq» with
all of the Pairs with maximum values, as judged by the
L«C<cmp> operator|/routine/cmp»:

    <a b c a b c>.maxpairs.perl.put; # OUTPUT: «(2 => "c", 5 => "c").Seq␤»
    %(:42a, :75b).maxpairs.perl.put; # OUTPUT: «(:b(75),).Seq␤»

=head2 method sum

Defined As:

=for code :skip-test
    method sum(--> TODO)

TODO

=head2 method keys

Defined As:

=for code :skip-test
    method keys(--> TODO)

TODO

=head2 method flatmap

Defined As:

=for code :skip-test
    method flatmap(--> TODO)

TODO

=head2 method roll

Defined As:

=for code :skip-test
    method roll(--> TODO)

TODO

=head2 method pick

Defined As:

=for code :skip-test
    method pick(--> TODO)

TODO

=head2 method head

Defined As:

=for code :skip-test
    method head(--> TODO)

TODO

=head2 method tail

Defined As:

=for code :skip-test
    method tail(--> TODO)

TODO

=head2 method skip

Defined As:

=for code :skip-test
    method skip(--> TODO)

TODO

=head2 method prepend

Defined As:

=for code :skip-test
    method prepend(--> TODO)

TODO

=head2 method unshift

Defined As:

=for code :skip-test
    method unshift(--> TODO)

TODO

=head2 method first

Defined As:

=for code :skip-test
    method first(--> TODO)

TODO

=head2 method unique

Defined As:

=for code :skip-test
    method unique(--> TODO)

TODO

=head2 method repeated

Defined As:

=for code :skip-test
    method repeated(--> TODO)

TODO

=head2 method squish

Defined As:

=for code :skip-test
    method squish(--> TODO)

TODO

=head2 method reduce

Defined As:

=for code :skip-test
    method reduce(--> TODO)

TODO

=head2 method permutations

Defined As:

=for code :skip-test
    method permutations(--> TODO)

TODO

=head2 method categorize

Defined As:

=for code :skip-test
    method categorize(--> TODO)

TODO

=head2 method classify

Defined As:

=for code :skip-test
    method classify(--> TODO)

TODO

=head2 method produce

Defined As:

=for code :skip-test
    method produce(--> TODO)

TODO

=head2 method rotor

Defined As:

=for code :skip-test
    method rotor(--> TODO)

TODO

=head2 method pairs

Defined As:

=for code :skip-test
    method pairs(--> TODO)

TODO

=head2 method antipairs

Defined As:

=for code :skip-test
    method antipairs(--> TODO)

TODO

=head2 method kv

Defined As:

=for code :skip-test
    method kv(--> TODO)

TODO

=head2 method tree

Defined As:

=for code :skip-test
    method tree(--> TODO)

TODO

=head2 method nl-out

Defined As:

=for code :skip-test
    method nl-out(--> TODO)

TODO

=head2 method invert

Defined As:

=for code :skip-test
    method invert(--> TODO)

TODO

=head2 method combinations

Defined As:

=for code :skip-test
    method combinations(--> TODO)

TODO

=head2 method print-nl

Defined As:

=for code :skip-test
    method print-nl(--> TODO)

TODO

=head2 method nodemap

Defined As:

=for code :skip-test
    method nodemap(--> TODO)

TODO

=head2 method iterator

Defined As:

=for code :skip-test
    method iterator(--> TODO)

TODO

=head2 method grep

Defined As:

=for code :skip-test
    method grep(--> TODO)

TODO

=head2 method match

Defined As:

=for code :skip-test
    method match(--> TODO)

TODO

=head2 method append

Defined As:

=for code :skip-test
    method append(--> TODO)

TODO

=head2 method join

Defined As:

=for code :skip-test
    method join(--> TODO)

TODO

=head2 method values

Defined As:

=for code :skip-test
    method values(--> TODO)

TODO

=head2 method collate

Defined As:

=for code :skip-test
    method collate(--> TODO)

TODO

=head2 method batch

Defined As:

=for code :skip-test
    method batch(--> TODO)

TODO

=head2 method cache

Defined As:

=for code :skip-test
    method cache(--> TODO)

TODO

=end pod

# vim: expandtab shiftwidth=4 ft=perl6
