=begin pod

=TITLE Operators

=head1 Operator Precedence

In an expression like C<1 + 2 * 3>, the C<2 * 3> is evaluated first
because the infix C<*> has tighter B<precedence> than the C<+>.

The following table summarizes the precedence levels in Perl 6, from
tightest to loosest:

=begin table

    A  Level             Examples
    =  =====             ========
    N  Terms             42 3.14 "eek" qq["foo"] $x :!verbose @$array
    L  Method postfix    .meth .+ .? .* .() .[] .{} .<> .«» .:: .= .^ .:
    N  Autoincrement     ++ --
    R  Exponentiation    **
    L  Symbolic unary    ! + - ~ ? | || +^ ~^ ?^ ^
    L  Multiplicative    * / % %% +& +< +> ~& ~< ~> ?& div mod gcd lcm
    L  Additive          + - +| +^ ~| ~^ ?| ?^
    L  Replication       x xx
    X  Concatenation     ~
    X  Junctive and      &
    X  Junctive or       | ^
    L  Named unary       temp let
    N  Structural infix  but does <=> leg cmp .. ..^ ^.. ^..^
    C  Chaining infix    != == < <= > >= eq ne lt le gt ge ~~ === eqv !eqv
    X  Tight and         &&
    X  Tight or          || ^^ // min max
    R  Conditional       ?? !! ff fff
    R  Item assignment   = => += -= **= xx= .=
    L  Loose unary       so not
    X  Comma operator    , :
    X  List infix        Z minmax X X~ X* Xeqv ...
    R  List prefix       print push say die map substr ... [+] [*] any Z=
    X  Loose and         and andthen
    X  Loose or          or xor orelse
    X  Sequencer         <==, ==>, <<==, ==>>
    N  Terminator        ; {...}, unless, extra ), ], }

=end table

Using two C<!> symbols below generically to represent any pair of operators
that have the same precedence, the associativities specified above
for binary operators are interpreted as follows:

=begin table

    A   Assoc     Meaning of $a ! $b ! $c
    =   =====     =======================
    L   left      ($a ! $b) ! $c
    R   right     $a ! ($b ! $c)
    N   non       ILLEGAL
    C   chain     ($a ! $b) and ($b ! $c)
    X   list      infix:<!>($a; $b; $c)

=end table

For unary operators this is interpreted as:

=begin table

    A   Assoc     Meaning of !$a!
    =   =====     =========================
    L   left      (!$a)!
    R   right     !($a!)
    N   non       ILLEGAL

=end table

In the operator descriptions below, a default associativity of I<left>
is assumed.

=head1 Operator classification

Operators can occur in several positions relative to a term:

=begin table

    +term           prefix
    term1 + term2   infix
    term++          postfix
    (term)          circumfix
    term1[term2]    postcircumfix

=end table

Each operator is also available as a routine; postcircumfix operators as
methods, all others as subroutines. The name of the routine is formed of
the operator category, then a colon, and a list quote construct with the
symbol(s) that make up the operator:

    infix:<+>(1, 2)                 # same as 1 + 2
    circumfix:«( )»('a', 'b', 'c')  # same as ('a', 'b', 'c')

As a special case the I<listop> (list operator) can stand either as a
term or as a prefix. Subroutine calls are the most common listops. Other
cases include meta-reduced infix operators (C<[+]| 1, 2, 3>) and the
L<#prefix ...> etc. stub operators.

(Niecza currently turns postcircumfix operators in a subroutine call,
while Rakudo interprets them as methods).

=head1 Term Precedence

=head2 circumfix < >

The quote-words construct. Breaks up the contents on whitespace, and returns
a C<Parcel> of the words. If a word
looks like a number literal or a C<Pair> literal, it is converted the
appropriate number.

    say <a b c>[1];     # b

(Rakudo currently always returns a parcel of strings).

=head2 circumfix ( )

The grouping operator.

An empty group C<()> creates an empty L<Parcel>.
Parens around non-empty expressions simply structure the expression, but
not have additional semantics.

In an argument list, putting parenthesis around an argument prevents it from
being interpreted as a named argument.

    multi sub p(:$a!) { say 'named'      }
    multi sub p($a)   { say 'positional' }
    p a => 1;       # named
    p (a => 1);     # positional

=head2 circumfix { }

Block or L<Hash> constructor.

If the contents looks like a list of pairs and does not use L<$_> or other
placeholder parameters, returns an itemized L<Hash>.

Otherwise it constructs a L<Block>.

Note that this construct does not re-parse the contents; rather the
contents are always parsed as a statement list (i.e. like a block),
and if the later analysis shows that it needs to be interpreted as a hash,
the block is executed and coerced to L<Hash>.

=head2 circumfix [ ]

The L<Array> constructor. Returns an itemized L<Array> which does not flatten
in list context.

=head1 Method Postfix Precedence

=head2 postcircumfix { }

The hash indexing postcircumfix. Fail on type L<Any>, and on L<EnumMap>,
L<Hash> and related types it allows lookup of hash elements by key.

    my %h = a => 1, b => 2;
    say %h{'a'};        # 1
    say %h{'a', 'b'};   # 1, 2

=head2 postcircumfix < >

The hash indexing quote-words operator. Interprets the argument list
as a list of words, just like C<< circumfix < > >>, and then calls
C<< postcircumfix:<{ }> >>, i.e. the hash indexing operator.

Thus you can write

    my %h = a => 1, b => 2;
    say %h<a>;          # 1
    say %h<b a>;        # 2, 1

=head2 postcircumfix ( )

The call operator. Treats the invocant as a L<Callable> and invokes it,
using the expression between the parens as arguments.

Note that an identifier followed by a pair of parens is always parsed as a
subroutine call.

If you want your objects to respond to the call operator, you need to
implement a C<< method postcircumfix:<( )> >>.

=head2 postcircumfix [ ]

The array indexing operator. Treats the invocant as a L<Positional> and
indexes it by position.

    my @a = 'a' .. 'z';
    say @a[0];                      # a

Lists of indexes produce list of results as if they were all indexed
separately.

    my @a = 'a' .. 'z';
    say @a[15, 4, 17, 11].join;     # perl

L<Callable> indexes are invoked with the number of elements as arguments.

This lets you write

    my @a[*-1];                     # z

to index lists and arrays from the end.

Non-L<Positional> invocants are interpreted as a one-list element of the object.

=head2 postfix .

The operator for calling one method, C<$invocant.method>.

Technically this is not an operator, but syntax special-cased in the compiler.

=head2 postfix .?

Potential method calls. C<$invocant.?method> calls method C<method> on
C<$invocant> if it has a method of such name. Otherwise it returns L<Nil>.

Technically this is not an operator, but syntax special-cased in the compiler.

=head2 postfix .+

C<$invocant.+method> calls all methods called C<method> from C<$invocant>,
and returns a L<Parcel> of the results. Dies if no such method was found.

Technically this is not an operator, but syntax special-cased in the compiler.

=head2 postfix .*

C<$invocant.*method> calls all methods called C<method> from C<$invocant>,
and returns a L<Parcel> of the results. If no such method was found, an empty
L<Parcel> is returned.

Technically this is not an operator, but syntax special-cased in the compiler.

# TODO: .= .^ .:: .() .[] .{} .<>

=head1 Autoincrement Precedence

=head2 prefix ++

    multi sub prefix:<++>($x is rw) is assoc<none>

Increments its argument by one, and returns the incremented value.

    my $x = 3;
    say ++$x;       # 4
    say $x;         # 4

It works by calling the L<succ> method (for I<successor>) on its argument,
which gives custom types the freedom to implement their own incrementation
semantics.

=head2 prefix --

    multi sub prefix:<-->($x is rw) is assoc<none>

Decrements its argument by one, and returns the decremented value.

    my $x = 3;
    say --$x;       # 2
    say $x;         # 2

It works by calling the L<pred> method (for I<predecessor>) on its argument,
which gives custom types the freedom to implement their own decrementation
semantics.


=head2 postfix ++

    multi sub postfix:<++>($x is rw) is assoc<none>

Increments its argument by one, and returns the unincremented value.

    my $x = 3;
    say $++x;       # 3
    say $x;         # 4

It works by calling the L<succ> method (for I<successor>) on its argument,
which gives custom types the freedom to implement their own incrementation
semantics.

Note that this does not necessarily return its argument. For example for
undefined values, it returns 0:

    my $x;
    say $x++;       # 0
    say $x;         # 1

=head2 postfix --

    multi sub postfix:<-->($x is rw) is assoc<none>

Decrements its argument by one, and returns the undecremented value.

    my $x = 3;
    say $x--;       # 3
    say $x;         # 2

It works by calling the L<pred> method (for I<predecessor>) on its argument,
which gives custom types the freedom to implement their own decrementation
semantics.

Note that this does not necessarily return its argument. For example for
undefined values, it returns 0:

    my $x;
    say $x--;       # 0
    say $x;         # -1

=head1 Exponentiation Precedence

=head2 infix **

    multi sub infix:<**>(Any, Any) returns Numeric:D is assoc<right>

The exponentiation operator coerces both arguments to L<Numeric>
and calculates the left-hand-side raised to the power of the right-hand side.

If the right-hand side is a non-negative integer and the left-hand side
is an arbitrary precision type (L<Int>, L<FatRat>), then the calculation
is carried out without loss of precision.

=head1 Symbolic Unary Precedence

=head2 prefix ?

    multi sub prefix:<?>(Mu) returns Bool:D

Boolean context operator.

Coerces the argument to L<Bool> by calling the C<Bool> method on it.
Note that this collapses L<Junction>s.

=head2 prefix !

    multi sub prefix:<!>(Mu) returns Bool:D

Negated boolean context operator.

Coerces the argument to L<Bool> by calling the C<Bool> method on it,
and returns the negation of the result.
Note that this collapses L<Junction>s.

=head2 prefix +

    multi sub prefix:<+>(Any) returns Numeric:D

Numeric context operator.

Coerces the argument to L<Numeric> by calling the C<Numeric> method on it.

=head2 prefix -

    multi sub prefix:<->(Any) returns Numeric:D

Negative numeric context operator.

Coerces the argument to L<Numeric> by calling the C<Numeric> method on it,
and then negates the result.

=head2 prefix ~

    multi sub prefix:<->(Any) returns Str:D

String context operator.

Coerces the argument to L<Str> by calling the C<Str> method on it.

=head2 prefix |

Flattens objects of type L<Capture>, L<Enum>, L<Pair>, L<List>, L<Parcel>,
L<EnumMap> and L<Hash> into an argument list.

(In Rakudo, this is implemented not as a proper operator but as a special
case in the compiler, which means it only works in argument lists, not in
arbitrary code).

=head2 prefix +^

    multi sub prefix:<+^>(Any) returns Int:D

Integer bitwise negation.

Coerces the argument to L<Int> and does a bitwise negation on the result,
assuming L<two's complement|https://en.wikipedia.org/wiki/Two%27s_complement>.

=head2 prefix ?^

    multi sub prefix:<?^>(Mu) returns Bool:D

Boolean bitwise negation.

Coerces the argument to L<Bool> and then does a bit flip, which makes it the
same as C<< prefix:<!> >>.

=head2 prefix ^

    multi sub prefix:<^>(Any) returns Range:D

I<upto> operator.

Coerces the argument to L<Numeric>, and generates a range from 0 up to (but
excluding) the argument.

    say ^5;         # 0..^5
    for ^5 { }      # 5 iterations

=head1 Multiplicative Precedence

=head2 infix *

    multi sub infix:<*>(Any, Any) returns Numeric:D

Coerces both arguments to L<Numeric> and multiplies them. The result
is of the wider type. See L<Numeric> for details.

=head2 infix /

    multi sub infix:</>(Any, Any) returns Numeric:D

Coerces both argument to L<Numeric> and divides the left through the right
number. Division of L<Int> values returns L<Rat>, otherwise the "wider type"
rule described in L<Numeric> holds.

=head2 infix div

    multi sub infix:<div>(Int:D, Int:D) returns Int:D

Integer division. Rounds down.

=head2 infix %

    multi sub infix:<%>($x, $y) return Numeric:D

Modulo operator. Coerces to L<Numeric> first.

Generally the following identity holds:

    $x % $y == $x - floor($x / $y) * $y

=head2 infix %%

    multi sub infix:<%%>($a, $b) returns Bool:D

Divisibility operator. Returns C<True> if C<$a %  $b == 0>.

=head2 infix mod

    multi sub infix:<mod>(Int:D $a, Int:D $b) returns Int:D

Integer modulo operator. Returns the remainder of an integer modulo operation.

=head2 infix +&

    multi sub infix:<+&>($a, $b) returns Int:D

Numeric bitwise I<AND>. Coerces both arguments to L<Int> and does a bitwise
I<AND> operation assuming two's complement.

=head2 infix +<

    multi sub infix:<< +< >>($a, $b) returns Int:D

Integer bit shift to the left.

=head2 infix +>

    multi sub infix:<< +> >>($a, $b) returns Int:D

Integer bit shift to the right.

=head2 infix gcd

    multi sub infix:<gcd>($a, $b) returns Int:D

Coerces both arguments to L<Int> and returns the greatest common denominator.

=head2 infix lcm

    multi sub infix:<lcm>($a, $b) returns Int:D

Coerces both arguments to L<Int> and returns the least common multiple,
that is the smallest integer that is smallest integer that is evenly
divisible by both arguments.

=head1 Additive Precedence

=head2 infix +

    multi sub infix:<+>($a, $b) returns Numeric:D

Coerces both arguments to L<Numeric> and adds them.

=head2 infix -

    multi sub infix:<->($a, $b) returns Numeric:D

Coerces both arguments to L<Numeric> and subtracts the second from the
first.

=head2 infix +|

    multi sub infix:<+|>($a, $b) returns Int:D

Coerces both arguments to L<Int> and does a bitwise I<OR> (inclusive OR)
operation.

=head2 infix +^

    multi sub infix:<+^>($a, $b) returns Int:D

Coerces both arguments to L<Int> and does a bitwise I<XOR> (exclusive OR)
operation.

=head2 infix ?|

    multi sub infix:<?|>($a, $b) returns Bool:D

Coerces both arguments to L<Bool> and does a logical I<OR> (inclusive OR)
operation.

=head1 Replication Precedence

=head2 infix x

    proto sub infix:<x>(Any, Any) returns Str:D
    multi sub infix:<x>(Any, Any)
    multi sub infix:<x>(Str:D, Int:D)

Coerces C<$a> to L<Str> and C<$b> to L<Int> and repeats the string C<$b>
times. Return the empty string if C<< $b <= 0 >>.

    say 'ab' x 3;       # ababab
    say 42 x 3;         # 424242

=head2 infix xx

    multi sub infix:<xx>($a, $b) returns List:D

Returns a list of C<$a> repeated and evaluated C<$b> times (C<$b> is coerced
to L<Int>). If C<< $b <= 0 >>, the empty list is returned.

The left-hand side is evaluated for each repetition, so

    [1, 2] xx 5

returns five distinct arrays (but with the same content each time), and

    rand xx 3

returns three pseudo random numbers that are determined independently.

The right-hand side can be C<*>, in which case a lazy, infinite list
is returned.

=head1 Concatenation

=head2 infix ~

    proto sub infix:<~>(Any, Any) returns Str:D
    multi sub infix:<~>(Any,   Any)
    multi sub infix:<~>(Str:D, Str:D)

Coerces both arguments to L<Str> and concatenates them.

    say 'ab' ~ 'c';     # abc

=head1 Junctive AND (all) Precedence

=head2 infix &

    multi sub infix:<&>($a, $b) returns Junction:D is assoc<list>

Creates an I<all> L<Junction> from its arguments. See L<Junction> for more
details.

=head1 Junctive OR (any) Precedence

=head2 infix |

    multi sub infix:<|>($a, $b) returns Junction:D is assoc<list>

Creates an I<any> L<Junction> from its arguments. See L<Junction> for more
details.

=head2 infix ^

    multi sub infix:<^>($a, $b) returns Junction:D is assoc<list>

Creates a I<one> L<Junction> from its arguments. See L<Junction> for more
details.

=head1 Named Unary Precedence

=head2 prefix temp

    sub prefix:<temp>(Mu $a is rw)

"temporizes" the variable passed as the argument, which means it is reset
to its old value on scope exit. (This is similar to the
L<local|http://perldoc.perl.org/functions/local.html> operator in Perl 5,
except that C<temp> does not reset the value).

=head2 prefix let

    sub prefix:<let>(Mu $a is rw)

Hypothetical reset: if the current scope is exited either through an exception
or C<fail()>, the old value is restored.

=head1 Nonchaining Binary Precedence

=head2 infix does

    sub infix:<does>(Mu $obj, Mu $role) is assoc<none>

Mixes C<$role> into C<$obj> at run time. Requires C<$obj> to be mutable.

C<$role> doesn't need to a be a role, it can be something that knows how
to act like a role, for example enum values.

=head2 infix but

    sub infix:<but>(Mu $obj, Mu $role) is assoc<none>

Creates a copy of C<$obj> with C<$role> mixed in. Since C<$obj> is not
modified, C<but> can be used to created immutable values with mixins.

C<$role> doesn't need to a be a role, it can be something that knows how
to act like a role, for example enum values.

=head2 infix cmp

    proto sub infix:<cmp>(Any, Any) returns Order:D is assoc<none>
    multi sub infix:<cmp>(Any,       Any)
    multi sub infix:<cmp>(Real:D,    Real:D)
    multi sub infix:<cmp>(Str:D,     Str:D)
    multi sub infix:<cmp>(Enum:D,    Enum:D)
    multi sub infix:<cmp>(Version:D, Version:D)

Generic, "smart" three-way comparator.

Compares strings with string semantics, numbers
with number semantics, L<Pair> objects first by key and then by value etc.

if C<$a eqv $b>, then C<$a cmp $b> always returns C<Order::Same>.

    say (a => 3) cmp (a => 4);      # Increase
    say 4        cmp 4.0;           # Same
    say 'b'      cmp 'a';           # Decrease

=head2 infix leg

    proto sub infix:<leg>($a, $b) returns Order:D is assoc<none>
    multi sub infix:<leg>(Any,   Any)
    multi sub infix:<leg>(Str:D, Str:D)

String three-way comparator.

Coerces both arguments to L<Str>, and then does a lexicographic comparison.

=head2 infix <=>

    multi sub infix:«<=>»($a, $b) returns Order:D is assoc<none>

Numeric three-way comparator.

Coerces both arguments to L<Real>, and then does a numeric comparison.

=head2 infix ..

    multi sub infix:<..>($a, $b) returns Range:D is assoc<none>

Constructs a L<Range> from the arguments.

=head2 infix ..^

    multi sub infix:<..^>($a, $b) returns Range:D is assoc<none>

Constructs a L<Range> from the arguments, excluding the end point.

=head2 infix ^..

    multi sub infix:<^..>($a, $b) returns Range:D is assoc<none>

Constructs a L<Range> from the arguments, excluding the start point.


=head2 infix ^..^

    multi sub infix:<^..^>($a, $b) returns Range:D is assoc<none>

Constructs a L<Range> from the arguments, excluding both start and end point.

=head1 Chaining Binary Precedence

=head2 infix ==

    proto sub infix:<==>($, $) returns Bool:D is assoc:<chain>
    multi sub infix:<==>(Any, Any)
    multi sub infix:<==>(Int:D, Int:D)
    multi sub infix:<==>(Num:D, Num:D)
    multi sub infix:<==>(Rational:D, Rational:D)
    multi sub infix:<==>(Real:D, Real:D)
    multi sub infix:<==>(Complex:D, Complex:D)
    multi sub infix:<==>(Numeric:D, Numeric:D)

Coerces both arguments to L<Numeric> if necessary, and returns C<True>
if they are equal.

=head2 infix !=

    proto sub infix:<!=>(Mu, Mu) returns Bool:D is assoc<chain>

Coerces both arguments to L<Numeric> (if necessary), and returns C<True> if they are
distinct.

=head2 infix <

    proto sub infix:«<»(Any, Any) returns Bool:D is assoc<chain>
    multi sub infix:«<»(Int:D, Int:D)
    multi sub infix:«<»(Num:D, Num:D)
    multi sub infix:«<»(Real:D, Real:D)

Coerces both arguments to L<Real> (if necessary), and returns C<True> if the first argument
is smaller than the second.

=head2 infix <=

    proto sub infix:«<=»(Any, Any) returns Bool:D is assoc<chain>
    multi sub infix:«<=»(Int:D, Int:D)
    multi sub infix:«<=»(Num:D, Num:D)
    multi sub infix:«<=»(Real:D, Real:D)

Coerces both arguments to L<Real> (if necessary), and returns C<True> if the first argument
is smaller than or equal to the second.


=head2 infix >

    proto sub infix:«>»(Any, Any) returns Bool:D is assoc<chain>
    multi sub infix:«>»(Int:D, Int:D)
    multi sub infix:«>»(Num:D, Num:D)
    multi sub infix:«>»(Real:D, Real:D)

Coerces both arguments to L<Real> (if necessary), and returns C<True> if the first argument
is larger than the second.

=head2 infix >=

    proto sub infix:«>=»(Any, Any) returns Bool:D is assoc<chain>
    multi sub infix:«>=»(Int:D, Int:D)
    multi sub infix:«>=»(Num:D, Num:D)
    multi sub infix:«>=»(Real:D, Real:D)

Coerces both arguments to L<Real> (if necessary), and returns C<True> if
the first argument is larger than or equal to the second.

=head2 infix eq

    proto sub infix:<eq>(Any, Any) returns Bool:D is assoc<chain>
    multi sub infix:<eq>(Any,   Any)
    multi sub infix:<eq>(Str:D, Str:D)

Coerces both arguments to L<Str> (if necessary), and returns C<True> if both
are equal.

Mnemonic: I<equal>

=head2 infix ne

    proto sub infix:<ne>(Mu, Mu) returns Bool:D is assoc<chain>
    multi sub infix:<ne>(Mu,    Mu)
    multi sub infix:<ne>(Str:D, Str:D)

Coerces both arguments to L<Str> (if necessary), and returns C<False> if both
are equal.

Mnemonic: I<not equal>

=head2 infix gt

    proto sub infix:<gt>(Mu, Mu) returns Bool:D is assoc<chain>
    multi sub infix:<gt>(Mu,    Mu)
    multi sub infix:<gt>(Str:D, Str:D)

Coerces both arguments to L<Str> (if necessary), and returns C<True> if
the first is larger than the second, as determined by lexicographic
comparison.

Mnemonic: I<greater than>

=head2 infix ge

    proto sub infix:<ge>(Mu, Mu) returns Bool:D is assoc<chain>
    multi sub infix:<ge>(Mu,    Mu)
    multi sub infix:<ge>(Str:D, Str:D)

Coerces both arguments to L<Str> (if necessary), and returns C<True> if
the first is equal to or larger than the second, as determined by lexicographic
comparison.

Mnemonic: I<greater or equal>

=head2 infix lt

    proto sub infix:<lt>(Mu, Mu) returns Bool:D is assoc<chain>
    multi sub infix:<lt>(Mu,    Mu)
    multi sub infix:<lt>(Str:D, Str:D)

Coerces both arguments to L<Str> (if necessary), and returns C<True> if
the first is smaller than the second, as determined by lexicographic
comparison.

Mnemonic: I<less than>

=head2 infix le

    proto sub infix:<le>(Mu, Mu) returns Bool:D is assoc<chain>
    multi sub infix:<le>(Mu,    Mu)
    multi sub infix:<le>(Str:D, Str:D)

Coerces both arguments to L<Str> (if necessary), and returns C<True> if
the first is equal to or smaller than the second, as determined by lexicographic
comparison.

Mnemonic: I<less or equal>

=head2 infix before

    proto sub infix:<before>(Any, Any) returns Bool:D is assoc<chain>
    multi sub infix:<before>(Any,       Any)
    multi sub infix:<before>(Real:D,    Real:D)
    multi sub infix:<before>(Str:D,     Str:D)
    multi sub infix:<before>(Enum:D,    Enum:D)
    multi sub infix:<before>(Version:D, Version:D)

Generic ordering, uses the same semantics as L<cmp|#infix cmp>.
Returns C<True> if the first argument is smaller than the second.

=head2 infix after

    proto sub infix:<after>(Any, Any) returns Bool:D is assoc<chain>
    multi sub infix:<after>(Any,       Any)
    multi sub infix:<after>(Real:D,    Real:D)
    multi sub infix:<after>(Str:D,     Str:D)
    multi sub infix:<after>(Enum:D,    Enum:D)
    multi sub infix:<after>(Version:D, Version:D)

Generic ordering, uses the same semantics as L<cmp|#infix cmp>.
Returns C<True> if the first argument is larger than the second.

=head2 infix eqv

    proto sub infix:<eqv>(Any, Any) returns Bool:D is assoc<chain>
    proto sub infix:<eqv>(Any, Any)

Equivalence operator. Returns C<True> if the two arguments are structurally
the same, i.e. from the same type and (recursively) contain the same values.

=head2 infix ===

    proto sub infix:<===>(Any, Any) returns Bool:D is assoc<chain>
    proto sub infix:<===>(Any, Any)

Value identity. Returns C<True> if both arguments are the same object.

    class A { };
    my $a = A.new;
    say $a === $a;              # True
    say A.new === A.new;        # False
    say A === A;                # True

For value types, C<===> behaves like C<eqv>:

    say 'a' === 'a';            # True
    say 'a' === 'b';            # False

    # different types
    say 1 === 1.0;              # False

C<===> uses the L<WHICH> method to obtain the object identity, so all value
types must override method C<WHICH>.

=head2 infix =:=

    proto sub infix:<=:=>(Mu $a is rw, Mu $b is rw) returns Bool:D is assoc<chain>
    multi sub infix:<=:=>(Mu $a is rw, Mu $b is rw)

Container identity. Returns L<True> if both arguments are bound to the same
container.

=head2 infix ~~

The smart-match operator. Aliases the left-hand side to C<$_>, then evaluates
the right-hand side, and calls C<.ACCEPTS($_)> on it. The semantics are left
to the type of the right-hand side operand.

Here is an excerpt of built-in smart-matching functionality:

=begin table

    Right-hand side     Comparison semantics
    ===============     ====================
    Mu:U                type check
    Str                 string equality
    Numeric             numeric equality
    Regex               regex match
    Callable            boolean result of invocation
    Any:D               object identity

=end table

=head1 Tight AND Precedence

=head2 infix &&

Returns the first argument that evaluates to C<False> in boolean context,
or otherwise the last argument.

Note that this short-circuits, i.e. if one of the arguments evaluates to a
false value, the arguments to the right of are never evaluated.

    sub a { 1 }
    sub b { 0 }
    sub c { die "never called" };
    say a() && b() && c();      # 0

=head1 Tight OR Precedence

=head2 infix ||

Returns the first argument that evaluates to C<True> in boolean context,
or otherwise the last argument.

Note that this short-circuits, i.e. if one of the arguments evaluates to a
true value, the arguments to the right of are never evaluated.

    sub a { 0 }
    sub b { 1 }
    sub c { die "never called" };
    say a() || b() || c();      # 1

=head2 infix ^^

Returns the first true argument if there is only one, and L<Nil> otherwise.
Short-circuits as soon as two true arguments are found.

    say 0 ^^ 42;                # 42
    say 0 ^^ 42 ^^ 1 ^^ die 8;  # (empty line)

=head2 infix //

Defined-or operator. Returns the first defined operand. Short-circuits.

    say Any // 0 // 42;         # 0

=head2 infix min

Returns the smallest of the arguments, as determined by L<cmp> semantics.

    $foo min= 0  # read as: $foo decreases to 0

=head2 infix max

Returns the largest of the arguments, as determined by L<cmp> semantics.

    $foo max= 0  # read as: $foo increases to 0

=head1 Conditional Operator Precedence

=head2 infix ?? !!

Ternary operator, conditional operator.

C<$condition ?? $true !! $false> evaluates and returns the expression from the
C<$true> branch if C<$condition> is a true value. Otherwise it evaluates and
returns the C<$false> branch.

# TODO: ff, ^ff, ff^, ^ff^, fff, ^fff, fff^, ^fff^

=head1 Item Assignment Precedence

=head2 infix =

    sub infix:<=>(Mu $a is rw, Mu $b)

Item assignment.

Places the value of the left-hand side into the container on the right-hand
side.

(Note that item assignment and list assignment have different precedence
levels, and the syntax of the left-hand side decides whether an equal sign
C<=> is parsed as item assignment or list assignment operator).

=head2 infix =>

    sub infix:«=>»($key, Mu $value) returns Pair:D

L<Pair> constructor.

Constructs a L<Pair> object with the left-hand side as the key and the
right-hand side as the value.

Note that the C<< => >> operator is syntactically special-cased, in that
it allows unquoted identifier on the left-hand side.

    my $p = a => 1;
    say $p.key;         # a
    say $p.value;       # 1

A L<Pair> within an argument list with an unquoted identifier on the left
is interpreted as a named argument.

=head1 Loose Unary Precedence

=head2 prefix not

    multi sub prefix:<not>(Mu $x) returns Bool:D

Evaluates its argument in boolean context (and thus collapses L<Junction>s),
and negates the result.

=head2 prefix so

    multi sub prefix:<so>(Mu $x) returns Bool:D

Evaluates its argument in boolean context (and thus collapses L<Junction>s),
and returns the result.

=head1 Comma Operator Precedence

=head2 infix ,

    sub infix:<,>(*@a) is assoc<list> returns Parcel:D

Constructs a L<Parcel> from its arguments. Also used syntactically as the
separator of arguments in calls.

=head2 infix :

Used as an argument separator just like infix C<,> and marks the argument to
its left as the invocant. That turns what would otherwise be a function call
into a method call.

    substr('abc': 1);       # same as 'abc'.substr(1)

Infix C<:> is only allowed after the first argument of a non-method call. In
other positions it is a syntax error.

=head1 List Infix Precedence

=head2 infix Z

    sub infix:<Z>(**@lists) returns List:D is assoc<chain>

Zip operator.

Interleaves the lists passed to C<Z> like a zipper, stopping as soon as
the first input list is exhausted:

    say (1, 2 Z <a b c> Z <+ ->).perl;  # ((1, "a", "+"), (2, "b", "-")).list

The C<Z> operator also exists as a meta operator, in which case the inner
parcels are replaced by the value from applying the meta'ed operator to the
list:

    say 100, 200 Z+ 42, 23;             # 142, 223
    say 1..3 Z~ <a b c> Z~ 'x' xx 3;    # 1ax 2bx 3cx

=head2 infix X

    sub infix:<X>(**@lists) returns List:D is assoc<chain>

Creates a cross product from all the lists, order so that the rightmost
elements vary most rapidly

    1..3 X <a b> X 9
    # produces   (1, 'a', 9), (1, 'b', 9), (1, 'c', 9),
                 (2, 'a', 9), (2, 'b', 9), (2, 'c', 9),
                 (3, 'a', 9), (3, 'b', 9), (3, 'c', 9)

The C<X> operator also exists as a meta operator, in which case the inner
parcels are replaced by the value from applying the meta'ed operator to the
list:

    1..3 X~ <a b> X~ 9
    # produces   '1a9', '1b9', '1c9',
                 '2a9', '2b9', '2c9',
                 '3a9', '3b9', '3c9'

=head2 infix ...

    multi sub infix:<...>(**@) is assoc<list>
    multi sub infix:<...^>(**@) is assoc<list>

The sequence operator is a generic operator to produce lazy lists.

It can have initial elements and a generator on left-hand side, and an
endpoint on the right-hand side.

The sequence operator invokes the generator with as many arguments as
necessary. The arguments are taken from the initial elements and the already
generated elements.

The default generator is C<*.>L<succ> or C<*.>L<pred>, depending on how
the end points compare:

    say 1 ... 4;        # 1 2 3 4
    say 4 ... 1;        # 4 3 2 1
    say 'a' ... 'e';    # a b c d e
    say 'e' ... 'a';    # e d c b a

An endpoint of C<*> (L<Whatever>) generates an infinite sequence,
with a default generator of *.succ

    say (1 ... *)[^5];  # 1 2 3 4 5


Custom generators are the last argument before the '...' operator.
This one takes two arguments, and generates the Fibonacci numbers

    say (1, 1, -> $a, $b { $a + $b } ... *)[^8];    # 1 1 2 3 5 8 13 21
    # same but shorter
    say (1, 1, *+* ... *)[^8];                      # 1 1 2 3 5 8 13 21

Of course the generator can also take only one argument.

    say 5, { $_ * 2 } ... 40;                       # 5 10 20 40

There must be at least as many initial elements as arguments to the generator.

Without a generator, and more than one initial element, and all initial
elements numeric, the sequence operator tries to deduce the generator. It
knows about arithmetic and geometric sequences.

    say 2, 4, 6 ... 12;     # 2 4 6 8 10 12
    say 1, 2, 4 ... 32;     # 1 2 4 8 16 32

If the endpoint is not C<*>, it is smart-matched against each generated
element, and the sequence is terminated when the smart-match succeeded.
For the C<...> operator, the final element is included, for the C<...^>
operator it is excluded.

This allows you to write

    say 1, 1, *+* ...^ *>= 100;

To generate all Fibonacci numbers up to but excluding 100.

=head1 List Prefix Precedence

=head2 item = (list assignment)

List assignment. Its exact semantics are left to the container type on the
left-hand side. See L<Array> and L<Hash> for common cases.

The distinction between item assignment and list assignment is determined by
the parser depending on the syntax of the left-hand side.

=head2 listop ...

The I<yada, yada, yada> operator or I<stub> operator. If it is the only
statement in a routine or type, it marks that routine or type as a stub
(which is significant in the context of pre-declaring types and composing
roles).

If the C<...> statement is executed, it calls L<&fail>, with the default
message C<stub code executed>.

=head2 listop !!!

If it is the only
statement in a routine or type, it marks that routine or type as a stub
(which is significant in the context of pre-declaring types and composing
roles).

If the C<!!!> statement is executed, it calls L<&die>, with the default
message C<stub code executed>.

=head2 listop ???

If it is the only
statement in a routine or type, it marks that routine or type as a stub
(which is significant in the context of pre-declaring types and composing
roles).

If the C<???> statement is executed, it calls L<&warn>, with the default
message C<stub code executed>.

=head1 Loose AND precedence

=head2 infix and

Same as L<#infix &&>, except with looser precedence.

Returns the first operand that evaluates to C<False> in boolean context, or
otherwise the last operand. Short-circuits.

=head2 infix andthen

Returns the first undefined argument, otherwise the last argument.
Short-circuits.

=head1 Loose OR Precedence

=head2 infix or

Same as C<infix ||>, except with looser precedence.

Returns the first argument that evaluates to C<True> in boolean context,
or otherwise the last argument. Short-circuits.

=head2 infix orelse

Same as C<infix //>, except with looser precedence.

Returns the first defined argument, or else the last argument.
Short-circuits.

=end pod
