=encoding utf8

=head1 Title

Scalar API reference

=head2 Typical usage

use Scalar

=head2 Exported functions

The following functions are exported by default:

=over

=item defined

  our Bool multi Scalar::defined ( Any $thing )
  our Bool multi Scalar::defined ( Any $thing, ::role )

C<defined> returns true if the parameter has a value and that value is
not the undefined value (per C<undef>), otherwise false is returned.

Same as Perl 5, only takes extra optional argument to ask if value is defined
with respect to a particular role:

    $x.defined(SomeRole);

A value may be defined according to one role and undefined according to another.
Without the extra argument, defaults to the definition of defined supplied by
the type of the object.

=item undefine

  our multi Any::undefine( Any $thing )

Takes any variable as a parameter and attempts to "remove" its
definition. For simple scalar variables this means assigning
the undefined value to the variable. For objects, this is equivalent
to invoking their undefine method. For arrays, hashes and other
complex data, this might require emptying the structures associated
with the object.

In all cases, calling C<undefine> on a variable
should place the object in the same state as if it was just
declared.

=item undef

  constant Scalar Scalar::undef

Returns the undefined scalar object. C<undef> has no value at
all, but for historical compatibility, it will numify to C<0>
and stringify to the empty string, potentially generating a
warning in doing so. There are two ways to determine if a
value equal to undef: the C<defined> function (or method) can
be called or the C<//> (or C<orelse>) operator can be used.

C<undef> is also considered to be false in a boolean context.
Such a conversion does not generate a warning.

Perl 5's unary C<undef> function is renamed C<undefine> to avoid
confusion with the value C<undef> (which is always 0-ary now).

=back

=head2 Methods

These functions are also provided as methods, which can be called an
any scalar type:

=over

=item defined

  our Bool multi method Scalar::defined ( Scalar $thing: )
  our Bool multi method Scalar::defined ( Scalar $thing: ::role )

Returns a true value if C<$thing> is defined. See above for the meaning
of the C<::role> argument.

=item undefine

  our multi method Any::undefine ( Any $thing: )

Sets the invocant (C<$thing>) to an undefined value.

=cut