=begin pod

=TITLE enum Bool

=SUBTITLE Logical boolean

    enum Bool <False True>

An enum for boolean true/false decisions.

=head1 Methods

=head2 routine succ

    method succ() returns Bool:D

Returns C<True>.

    say True.succ;                                    # True
    say False.succ;                                   # True

C<succ> is short for "successor"; it returns the next enum value. Bool is a special enum with only two values, C<False> and C<True>. When sorted, C<False> comes first, so C<True> is its successor. And since C<True> is the "highest" Bool enum value, its own successor is also C<True>.

=head2 routine pred

    method pred() returns Bool:D

Returns C<False>.

    say True.pred;                                    # False
    say False.pred;                                   # False

C<pred> is short for "predecessor"; it returns the previous enum value. Bool is a special enum with only two values, C<False> and C<True>. When sorted, C<False> comes first, so C<False> is the predecessor to C<True>. And since C<False> is the "loweset" Bool enum value, its own predecessor is also C<False>.

=head2 routine enums

    method enums() returns Hash:D

Returns a L<Hash|/type/Hash> of enum-pairs. Works on both the C<Bool> type
and any key.

    say Bool.enums;                                   # {False => 0, True => 1}
    say False.enums;                                  # {False => 0, True => 1}

=head2 routine pick

    multi method pick(Bool:U) returns Bool:D
    multi method pick(Bool:U $count) returns Seq:D

Returns C<True> or C<False> if called without any argument. Otherwise returns
C<$count> elements chosen at random (without repetition) from the C<enum>. If
C<*> is passed as C<$count>, or C<$count> is greater than or equal to two, then
both elements are returned in random order.

    say Bool.pick;                                    # True
    say Bool.pick(1);                                 # (False)
    say Bool.pick(*);                                 # (False True)

=head2 routine roll

    multi method roll(Bool:U) returns Bool:D
    multi method roll(Bool:U $count) returns Seq:D

Returns C<True> or C<False> if called without any argument. Otherwise returns
C<$count> elements chosen at random. Note that each random choice from the
C<enum> is made independently, like a separate coin toss where each side of the
coin represents one of the two values of the C<enum>. If C<*> is passed as
C<$count> an infinite L<Seq|/type/Seq> of C<Bool>s is returned.

    say Bool.roll;                                    # True
    say Bool.roll(3);                                 # (True False False)
    say Bool.roll(*);                                 # (...)

=head2 routine Numeric

    multi method Numeric(Bool:D) returns Int:D

Returns the value part of the C<enum> pair.

    say False.Numeric;                                # 0
    say True.Numeric;                                 # 1

=head1 Operators

=head2 prefix ?

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

Coerces its argument to C<Bool>.

=head2 prefix so

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

Coerces its argument to C<Bool>, has looser precedence than C<< prefix:<?> >>.

=end pod
