Bool.pod6

=begin pod

=TITLE enum Bool

=SUBTITLE Logical boolean

    enum Bool <False True>

X<|True>
X<|False>
X<|Boolean>
An enum for boolean true/false decisions.

=head1 Methods

=head2 method ACCEPTS

   method ACCEPTS(Bool:D: --> Bool:D)

Used for smartmatch comparison. When the right side is C<True> returns always
C<True>, when the right side of the match is C<False> returns always C<False>.
In particular, C<ACCEPTS> returns always the instance on which it is invoked,
that is the right side of a smartmatch. As an example:

=begin code

my $b = Bool.new( True );
# when True on the right side returns
# always True
True  ~~ $b;     # True
False ~~ $b;     # True

$b = Bool.new( False );
# when False on the right side
# returns always False
False ~~ $b;     # False
True ~~ $b;      # False
=end code


=head2 routine succ

    method succ(--> Bool:D)

Returns C<True>.

    say True.succ;                                    # OUTPUT: «True␤»
    say False.succ;                                   # OUTPUT: «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(--> Bool:D)

Returns C<False>.

    say True.pred;                                    # OUTPUT: «False␤»
    say False.pred;                                   # OUTPUT: «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 "lowest" Bool enum value, its own predecessor is also C<False>.

=head2 routine enums

    method enums(--> Hash:D)

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

    say Bool.enums;                                   # OUTPUT: «{False => 0, True => 1}␤»
    say False.enums;                                  # OUTPUT: «{False => 0, True => 1}␤»

=head2 routine pick

    multi method pick(Bool:U --> Bool:D)
    multi method pick(Bool:U $count --> 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;                                    # OUTPUT: «True␤»
    say Bool.pick(1);                                 # OUTPUT: «(False)␤»
    say Bool.pick(*);                                 # OUTPUT: «(False True)␤»

=head2 routine roll

    multi method roll(Bool:U --> Bool:D)
    multi method roll(Bool:U $count --> 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;                                    # OUTPUT: «True␤»
    say Bool.roll(3);                                 # OUTPUT: «(True False False)␤»
    say Bool.roll(*);                                 # OUTPUT: «(...)␤»

=head2 routine Int

    multi method Int(Bool:D --> Int:D)

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

    say False.Int;                                # OUTPUT: «0␤»
    say True.Int;                                 # OUTPUT: «1␤»

=head2 routine Numeric

    multi method Numeric(Bool:D --> Int:D)

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

    say False.Numeric;                                # OUTPUT: «0␤»
    say True.Numeric;                                 # OUTPUT: «1␤»

=head1 Operators

=head2 prefix ?

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

Coerces its argument to C<Bool>.

=head2 prefix so

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

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

=end pod

# vim: expandtab softtabstop=4 shiftwidth=4 ft=perl6