declares function Number::add() for addition, and method muas() in
the ``class'' Number
(or one of its base classes)
for the assignment form *=
of multiplication.
Arguments of this directive come in (key, value) pairs. Legal values
are values legal inside a &{ ... }
call, so the name of a subroutine,
a reference to a subroutine, or an anonymous subroutine will all work.
Legal keys are listed below.
The subroutine add
will be called to execute $a+$b
if $a
is a reference to an object blessed into the package Number
, or if $a is
not an object from a package with defined mathemagic addition, but $b is a
reference to a Number
. It can also be called in other situations, like
$a+=7
, or $a++
. See
MAGIC AUTOGENERATION
. (Mathemagical
methods refer to methods triggered by an overloaded mathematical
operator.)
use overload ...
directive are called
with three (in one particular case with four, see
Last Resort
)
arguments. If the corresponding operation is binary, then the first
two arguments are the two arguments of the operation. However, due to
general object calling conventions, the first argument should always be
an object in the package, so in the situation of 7+$a
, the
order of the arguments is interchanged. It probably does not matter
when implementing the addition method, but whether the arguments
are reversed is vital to the subtraction method. The method can
query this information by examining the third argument, which can take
three different values:
$a+=7
), but the usual function is called instead. This additional
information can be used to generate some optimizations.
{``++''}
is called with arguments ($a,undef,'')
when $a++ is executed.
use overload
:
``+'', ``+='', ``-'', ``-='', ``*'', ``*='', ``/'', ``/='', ``%'', ``%='', ``**'', ``**='', ``<<'', ``<<='', ``>>'', ``>>='', ``x'', ``x='', ``.'', ``.='',
For these operations a substituted non-assignment variant can be called if
the assignment variant is not available. Methods for operations ``+
'',
``-
'', ``+=
'', and ``-=
'' can be called to automatically generate
increment and decrement methods. The operation ``-
'' can be used to
autogenerate missing methods for unary minus or abs
.
If the corresponding ``spaceship'' variant is available, it can be
used to substitute for the missing operation. During sort
ing
arrays, cmp
is used to compare values subject to use overload
.
``neg
'' stands for unary minus. If the method for neg
is not
specified, it can be autogenerated using the method for subtraction.
If undefined, addition and subtraction methods can be used instead. These operations are called both in prefix and postfix form.
If abs
is unavailable, it can be autogenerated using methods
for ``<'' or ``<=>'' combined with either unary minus or subtraction.
If one or two of these operations are unavailable, the remaining ones can
be used instead. bool
is used in the flow control operators
(like while
) and for the ternary ``?:
'' operation. These functions can
return any arbitrary Perl value. If the corresponding operation for this value
is overloaded too, that operation will be called again with this value.
see SPECIAL SYMBOLS FOR use overload
use overload
``nomethod''
should be followed by a reference to a function of four
parameters. If defined, it is called when the overloading mechanism
cannot find a method for some operation. The first three arguments of
this function coincide with the arguments for the corresponding method if
it were found, the fourth argument is the symbol
corresponding to the missing method. If several methods are tried,
the last one is used. Say, 1-$a
can be equivalent to
if the pair ``nomethod'' => ``nomethodMethod''
was specified in the
use overload
directive.
If some operation cannot be resolved, and there is no function
assigned to ``nomethod''
, then an exception will be raised via die()--
unless ``fallback''
was specified as a key in use overload
directive.
``fallback''
governs what to do if a method for a particular
operation is not found. Three different cases are possible depending on
the value of ``fallback''
:
``nomethod''
value; if missing, an exception
will be raised.
use overload
present.
``nomethod''
value, and if this is missing, raises an exception.
``=''
is a reference to a function with three
arguments, i.e., it looks like the other values in C