| 1 | |
|---|
| 2 | =encoding utf8 |
|---|
| 3 | |
|---|
| 4 | =head1 Title |
|---|
| 5 | |
|---|
| 6 | Scalar API reference |
|---|
| 7 | |
|---|
| 8 | =head2 Typical usage |
|---|
| 9 | |
|---|
| 10 | use Scalar |
|---|
| 11 | |
|---|
| 12 | =head2 Exported functions |
|---|
| 13 | |
|---|
| 14 | The following functions are exported by default: |
|---|
| 15 | |
|---|
| 16 | =over |
|---|
| 17 | |
|---|
| 18 | =item defined |
|---|
| 19 | |
|---|
| 20 | our Bool multi Scalar::defined ( Any $thing ) |
|---|
| 21 | our Bool multi Scalar::defined ( Any $thing, ::role ) |
|---|
| 22 | |
|---|
| 23 | C<defined> returns true if the parameter has a value and that value is |
|---|
| 24 | not the undefined value (per C<undef>), otherwise false is returned. |
|---|
| 25 | |
|---|
| 26 | Same as Perl 5, only takes extra optional argument to ask if value is defined |
|---|
| 27 | with respect to a particular role: |
|---|
| 28 | |
|---|
| 29 | $x.defined(SomeRole); |
|---|
| 30 | |
|---|
| 31 | A value may be defined according to one role and undefined according to another. |
|---|
| 32 | Without the extra argument, defaults to the definition of defined supplied by |
|---|
| 33 | the type of the object. |
|---|
| 34 | |
|---|
| 35 | =item undefine |
|---|
| 36 | |
|---|
| 37 | our multi Any::undefine( Any $thing ) |
|---|
| 38 | |
|---|
| 39 | Takes any variable as a parameter and attempts to "remove" its |
|---|
| 40 | definition. For simple scalar variables this means assigning |
|---|
| 41 | the undefined value to the variable. For objects, this is equivalent |
|---|
| 42 | to invoking their undefine method. For arrays, hashes and other |
|---|
| 43 | complex data, this might require emptying the structures associated |
|---|
| 44 | with the object. |
|---|
| 45 | |
|---|
| 46 | In all cases, calling C<undefine> on a variable |
|---|
| 47 | should place the object in the same state as if it was just |
|---|
| 48 | declared. |
|---|
| 49 | |
|---|
| 50 | =item undef |
|---|
| 51 | |
|---|
| 52 | constant Scalar Scalar::undef |
|---|
| 53 | |
|---|
| 54 | Returns the undefined scalar object. C<undef> has no value at |
|---|
| 55 | all, but for historical compatibility, it will numify to C<0> |
|---|
| 56 | and stringify to the empty string, potentially generating a |
|---|
| 57 | warning in doing so. There are two ways to determine if a |
|---|
| 58 | value equal to undef: the C<defined> function (or method) can |
|---|
| 59 | be called or the C<//> (or C<orelse>) operator can be used. |
|---|
| 60 | |
|---|
| 61 | C<undef> is also considered to be false in a boolean context. |
|---|
| 62 | Such a conversion does not generate a warning. |
|---|
| 63 | |
|---|
| 64 | Perl 5's unary C<undef> function is renamed C<undefine> to avoid |
|---|
| 65 | confusion with the value C<undef> (which is always 0-ary now). |
|---|
| 66 | |
|---|
| 67 | =back |
|---|
| 68 | |
|---|
| 69 | =head2 Methods |
|---|
| 70 | |
|---|
| 71 | These functions are also provided as methods, which can be called an |
|---|
| 72 | any scalar type: |
|---|
| 73 | |
|---|
| 74 | =over |
|---|
| 75 | |
|---|
| 76 | =item defined |
|---|
| 77 | |
|---|
| 78 | our Bool multi method Scalar::defined ( Scalar $thing: ) |
|---|
| 79 | our Bool multi method Scalar::defined ( Scalar $thing: ::role ) |
|---|
| 80 | |
|---|
| 81 | Returns a true value if C<$thing> is defined. See above for the meaning |
|---|
| 82 | of the C<::role> argument. |
|---|
| 83 | |
|---|
| 84 | =item undefine |
|---|
| 85 | |
|---|
| 86 | our multi method Any::undefine ( Any $thing: ) |
|---|
| 87 | |
|---|
| 88 | Sets the invocant (C<$thing>) to an undefined value. |
|---|
| 89 | |
|---|
| 90 | =cut |
|---|
