when($_ ~~ $foo)
-In fact C<when(EXPR)> is treated as an implicit smart match most of the
-time. The exceptions are that when EXPR is:
+Most of the time, C<when(EXPR)> is treated as an implicit smart match of
+C<$_>, i.e. C<$_ ~~ EXPR>. (See L</"Smart matching in detail"> for more
+information on smart matching.) But when EXPR is one of the below
+exceptional cases, it is used directly as a boolean:
=over 4
when (/^\d+$/ && $_ < 75) { ... }
Another useful shortcut is that, if you use a literal array
-or hash as the argument to C<when>, it is turned into a
+or hash as the argument to C<given>, it is turned into a
reference. So C<given(@foo)> is the same as C<given(\@foo)>,
for example.
C<default> behaves exactly like C<when(1 == 1)>, which is
to say that it always matches.
-See L</"Smart matching in detail"> for more information
-on smart matching.
-
=head3 Breaking out
You can use the C<break> keyword to break out of the enclosing
determined by the type of the right operand). Note that the smart match
implicitly dereferences any non-blessed hash or array ref, so the "Hash"
and "Array" entries apply in those cases. (For blessed references, the
-"Any" entry apply.)
+"Object" entries apply.)
+
+Note that the "Matching Code" column is not always an exact rendition. For
+example, the smart match operator short-circuits whenever possible, but
+C<grep> does not.
$a $b Type of Match Implied Matching Code
====== ===== ===================== =============
Any undef undefined !defined $a
- Any Object invokes ~~ overloading on $object, or dies
+ Any Object invokes ~~ overloading on $object, or dies
Hash CodeRef sub truth for each key[1] !grep { !$b->($_) } keys %$a
Array CodeRef sub truth for each elt[1] !grep { !$b->($_) } @$a
Object Any invokes ~~ overloading on $object, or falls back:
Any Num numeric equality $a == $b
Num numish[4] numeric equality $a == $b
+ undef Any undefined !defined($b)
Any Any string equality $a eq $b
-
1 - empty hashes or arrays will match.
2 - that is, each element smart-matches the element of same index in the
other array. [3]
3 - If a circular reference is found, we fall back to referential equality.
4 - either a real number, or a string that looks like a number
-The "matching code" doesn't represent the I<real> matching code,
-of course: it's just there to explain the intended meaning. Unlike
-C<grep>, the smart match operator will short-circuit whenever it can.
-
=head3 Custom matching via overloading
You can change the way that an object is matched by overloading
-the C<~~> operator. This trumps the usual smart match semantics.
-See L<overload>.
+the C<~~> operator. This may alter the usual smart match semantics.
It should be noted that C<~~> will refuse to work on objects that
don't overload it (in order to avoid relying on the object's
underlying structure).
+Note also that smart match's matching rules take precedence over
+overloading, so if C<$obj> has smart match overloading, then
+
+ $obj ~~ X
+
+will not automatically invoke the overload method with X as an argument;
+instead the table above is consulted as normal, and based in the type of X,
+overloading may or may not be invoked.
+
+See L<overload>.
+
=head3 Differences from Perl 6
The Perl 5 smart match and C<given>/C<when> constructs are not