+=head2 Experimental Details on given and when
+
+As previously mentioned, the "switch" feature is considered highly
+experimental; it is subject to change with little notice. In particular,
+C<when> has tricky behaviours that are expected to change to become less
+tricky in the future. Do not rely upon its current (mis)implementation.
+Before Perl 5.18, C<given> also had tricky behaviours that you should still
+beware of if your code must run on older versions of Perl.
+
+Here is a longer example of C<given>:
+
+ use feature ":5.10";
+ given ($foo) {
+ when (undef) {
+ say '$foo is undefined';
+ }
+ when ("foo") {
+ say '$foo is the string "foo"';
+ }
+ when ([1,3,5,7,9]) {
+ say '$foo is an odd digit';
+ continue; # Fall through
+ }
+ when ($_ < 100) {
+ say '$foo is numerically less than 100';
+ }
+ when (\&complicated_check) {
+ say 'a complicated check for $foo is true';
+ }
+ default {
+ die q(I don't know what to do with $foo);
+ }
+ }
+
+Before Perl 5.18, C<given(EXPR)> assigned the value of I<EXPR> to
+merely a lexically scoped I<B<copy>> (!) of C<$_>, not a dynamically
+scoped alias the way C<foreach> does. That made it similar to
+
+ do { my $_ = EXPR; ... }
+
+except that the block was automatically broken out of by a successful
+C<when> or an explicit C<break>. Because it was only a copy, and because
+it was only lexically scoped, not dynamically scoped, you could not do the
+things with it that you are used to in a C<foreach> loop. In particular,
+it did not work for arbitrary function calls if those functions might try
+to access $_. Best stick to C<foreach> for that.
+
+Most of the power comes from the implicit smartmatching that can
+sometimes apply. Most of the time, C<when(EXPR)> is treated as an
+implicit smartmatch of C<$_>, that is, C<$_ ~~ EXPR>. (See
+L<perlop/"Smartmatch Operator"> for more information on smartmatching.)
+But when I<EXPR> is one of the 10 exceptional cases (or things like them)
+listed below, it is used directly as a boolean.
+
+=over 4
+
+=item 1.
+
+A user-defined subroutine call or a method invocation.
+
+=item 2.
+
+A regular expression match in the form of C</REGEX/>, C<$foo =~ /REGEX/>,
+or C<$foo =~ EXPR>. Also, a negated regular expression match in
+the form C<!/REGEX/>, C<$foo !~ /REGEX/>, or C<$foo !~ EXPR>.
+
+=item 3.
+
+A smart match that uses an explicit C<~~> operator, such as C<EXPR ~~ EXPR>.
+
+=item 4.
+
+A boolean comparison operator such as C<$_ E<lt> 10> or C<$x eq "abc"> The
+relational operators that this applies to are the six numeric comparisons
+(C<< < >>, C<< > >>, C<< <= >>, C<< >= >>, C<< == >>, and C<< != >>), and
+the six string comparisons (C<lt>, C<gt>, C<le>, C<ge>, C<eq>, and C<ne>).
+
+B<NOTE:> You will often have to use C<$c ~~ $_> because
+the default case uses C<$_ ~~ $c> , which is frequently
+the opposite of what you want.
+
+=item 5.
+
+At least the three builtin functions C<defined(...)>, C<exists(...)>, and
+C<eof(...)>. We might someday add more of these later if we think of them.
+
+=item 6.
+
+A negated expression, whether C<!(EXPR)> or C<not(EXPR)>, or a logical
+exclusive-or, C<(EXPR1) xor (EXPR2)>. The bitwise versions (C<~> and C<^>)
+are not included.
+
+=item 7.
+
+A filetest operator, with exactly 4 exceptions: C<-s>, C<-M>, C<-A>, and
+C<-C>, as these return numerical values, not boolean ones. The C<-z>
+filetest operator is not included in the exception list.
+
+=item 8.
+
+The C<..> and C<...> flip-flop operators. Note that the C<...> flip-flop
+operator is completely different from the C<...> elliptical statement
+just described.
+
+=back
+
+In those 8 cases above, the value of EXPR is used directly as a boolean, so
+no smartmatching is done. You may think of C<when> as a smartsmartmatch.
+
+Furthermore, Perl inspects the operands of logical operators to
+decide whether to use smartmatching for each one by applying the
+above test to the operands:
+
+=over 4
+
+=item 9.
+
+If EXPR is C<EXPR1 && EXPR2> or C<EXPR1 and EXPR2>, the test is applied
+I<recursively> to both EXPR1 and EXPR2.
+Only if I<both> operands also pass the
+test, I<recursively>, will the expression be treated as boolean. Otherwise,
+smartmatching is used.
+
+=item 10.
+
+If EXPR is C<EXPR1 || EXPR2>, C<EXPR1 // EXPR2>, or C<EXPR1 or EXPR2>, the
+test is applied I<recursively> to EXPR1 only (which might itself be a
+higher-precedence AND operator, for example, and thus subject to the
+previous rule), not to EXPR2. If EXPR1 is to use smartmatching, then EXPR2
+also does so, no matter what EXPR2 contains. But if EXPR2 does not get to
+use smartmatching, then the second argument will not be either. This is
+quite different from the C<&&> case just described, so be careful.
+
+=back
+
+These rules are complicated, but the goal is for them to do what you want
+(even if you don't quite understand why they are doing it). For example:
+
+ when (/^\d+$/ && $_ < 75) { ... }
+
+will be treated as a boolean match because the rules say both
+a regex match and an explicit test on C<$_> will be treated
+as boolean.
+
+Also:
+
+ when ([qw(foo bar)] && /baz/) { ... }
+
+will use smartmatching because only I<one> of the operands is a boolean:
+the other uses smartmatching, and that wins.
+
+Further:
+
+ when ([qw(foo bar)] || /^baz/) { ... }
+
+will use smart matching (only the first operand is considered), whereas
+
+ when (/^baz/ || [qw(foo bar)]) { ... }
+
+will test only the regex, which causes both operands to be
+treated as boolean. Watch out for this one, then, because an
+arrayref is always a true value, which makes it effectively
+redundant. Not a good idea.
+
+Tautologous boolean operators are still going to be optimized
+away. Don't be tempted to write
+
+ when ("foo" or "bar") { ... }
+
+This will optimize down to C<"foo">, so C<"bar"> will never be considered (even
+though the rules say to use a smartmatch
+on C<"foo">). For an alternation like
+this, an array ref will work, because this will instigate smartmatching:
+
+ when ([qw(foo bar)] { ... }
+
+This is somewhat equivalent to the C-style switch statement's fallthrough
+functionality (not to be confused with I<Perl's> fallthrough
+functionality--see below), wherein the same block is used for several
+C<case> statements.
+
+Another useful shortcut is that, if you use a literal array 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.
+
+=head3 Breaking out
+
+You can use the C<break> keyword to break out of the enclosing
+C<given> block. Every C<when> block is implicitly ended with
+a C<break>.
+
+=head3 Fall-through
+
+You can use the C<continue> keyword to fall through from one
+case to the next:
+
+ given($foo) {
+ when (/x/) { say '$foo contains an x'; continue }
+ when (/y/) { say '$foo contains a y' }
+ default { say '$foo does not contain a y' }
+ }
+
+=head3 Return value
+
+When a C<given> statement is also a valid expression (for example,
+when it's the last statement of a block), it evaluates to:
+
+=over 4
+
+=item *
+
+An empty list as soon as an explicit C<break> is encountered.
+
+=item *
+
+The value of the last evaluated expression of the successful
+C<when>/C<default> clause, if there happens to be one.
+
+=item *
+
+The value of the last evaluated expression of the C<given> block if no
+condition is true.
+
+=back
+
+In both last cases, the last expression is evaluated in the context that
+was applied to the C<given> block.
+
+Note that, unlike C<if> and C<unless>, failed C<when> statements always
+evaluate to an empty list.
+
+ my $price = do {
+ given ($item) {
+ when (["pear", "apple"]) { 1 }
+ break when "vote"; # My vote cannot be bought
+ 1e10 when /Mona Lisa/;
+ "unknown";
+ }
+ };
+
+Currently, C<given> blocks can't always
+be used as proper expressions. This
+may be addressed in a future version of Perl.
+
+=head3 Switching in a loop
+
+Instead of using C<given()>, you can use a C<foreach()> loop.
+For example, here's one way to count how many times a particular
+string occurs in an array:
+
+ use v5.10.1;
+ my $count = 0;
+ for (@array) {
+ when ("foo") { ++$count }
+ }
+ print "\@array contains $count copies of 'foo'\n";
+
+Or in a more recent version:
+
+ use v5.14;
+ my $count = 0;
+ for (@array) {
+ ++$count when "foo";
+ }
+ print "\@array contains $count copies of 'foo'\n";
+
+At the end of all C<when> blocks, there is an implicit C<next>.
+You can override that with an explicit C<last> if you're
+interested in only the first match alone.
+
+This doesn't work if you explicitly specify a loop variable, as
+in C<for $item (@array)>. You have to use the default variable C<$_>.
+
+=head3 Differences from Perl 6
+
+The Perl 5 smartmatch and C<given>/C<when> constructs are not compatible
+with their Perl 6 analogues. The most visible difference and least
+important difference is that, in Perl 5, parentheses are required around
+the argument to C<given()> and C<when()> (except when this last one is used
+as a statement modifier). Parentheses in Perl 6 are always optional in a
+control construct such as C<if()>, C<while()>, or C<when()>; they can't be
+made optional in Perl 5 without a great deal of potential confusion,
+because Perl 5 would parse the expression
+
+ given $foo {
+ ...
+ }
+
+as though the argument to C<given> were an element of the hash
+C<%foo>, interpreting the braces as hash-element syntax.
+
+However, their are many, many other differences. For example,
+this works in Perl 5:
+
+ use v5.12;
+ my @primary = ("red", "blue", "green");
+
+ if (@primary ~~ "red") {
+ say "primary smartmatches red";
+ }
+
+ if ("red" ~~ @primary) {
+ say "red smartmatches primary";
+ }
+
+ say "that's all, folks!";
+
+But it doesn't work at all in Perl 6. Instead, you should
+use the (parallelizable) C<any> operator instead:
+
+ if any(@primary) eq "red" {
+ say "primary smartmatches red";
+ }
+
+ if "red" eq any(@primary) {
+ say "red smartmatches primary";
+ }
+
+The table of smartmatches in L<perlop/"Smartmatch Operator"> is not
+identical to that proposed by the Perl 6 specification, mainly due to
+differences between Perl 6's and Perl 5's data models, but also because
+the Perl 6 spec has changed since Perl 5 rushed into early adoption.
+
+In Perl 6, C<when()> will always do an implicit smartmatch with its
+argument, while in Perl 5 it is convenient (albeit potentially confusing) to
+suppress this implicit smartmatch in various rather loosely-defined
+situations, as roughly outlined above. (The difference is largely because
+Perl 5 does not have, even internally, a boolean type.)
+