+ package Number;
+ sub minus {
+ my ($self, $other, $swap) = @_;
+ my $result = $$self - $other; # *
+ $result = -$result if $swap;
+ ref $result ? $result : bless \$result;
+ }
+ # * may recurse once - see table below
+
+Three arguments are passed to all subroutines specified in the
+C<use overload> directive (with exceptions - see below, particularly
+L</nomethod>).
+
+The first of these is the operand providing the overloaded
+operator implementation -
+in this case, the object whose C<minus()> method is being called.
+
+The second argument is the other operand, or C<undef> in the
+case of a unary operator.
+
+The third argument is set to TRUE if (and only if) the two
+operands have been swapped. Perl may do this to ensure that the
+first argument (C<$self>) is an object implementing the overloaded
+operation, in line with general object calling conventions.
+For example, if C<$x> and C<$y> are C<Number>s:
+
+ operation | generates a call to
+ ============|======================
+ $x - $y | minus($x, $y, '')
+ $x - 7 | minus($x, 7, '')
+ 7 - $x | minus($x, 7, 1)
+
+Perl may also use C<minus()> to implement other operators which
+have not been specified in the C<use overload> directive,
+according to the rules for L<Magic Autogeneration> described later.
+For example, the C<use overload> above declared no subroutine
+for any of the operators C<-->, C<neg> (the overload key for
+unary minus), or C<-=>. Thus
+
+ operation | generates a call to
+ ============|======================
+ -$x | minus($x, 0, 1)
+ $x-- | minus($x, 1, undef)
+ $x -= 3 | minus($x, 3, undef)
+
+Note the C<undef>s:
+where autogeneration results in the method for a standard
+operator which does not change either of its operands, such
+as C<->, being used to implement an operator which changes
+the operand ("mutators": here, C<--> and C<-=>),
+Perl passes undef as the third argument.
+This still evaluates as FALSE, consistent with the fact that
+the operands have not been swapped, but gives the subroutine
+a chance to alter its behaviour in these cases.
+
+In all the above examples, C<minus()> is required
+only to return the result of the subtraction:
+Perl takes care of the assignment to $x.
+In fact, such methods should I<not> modify their operands,
+even if C<undef> is passed as the third argument
+(see L<Overloadable Operations>).
+
+The same is not true of implementations of C<++> and C<-->:
+these are expected to modify their operand.
+An appropriate implementation of C<--> might look like
+
+ use overload '--' => "decr",
+ # ...
+ sub decr { --${$_[0]}; }
+
+If the experimental "bitwise" feature is enabled (see L<feature>), a fifth
+TRUE argument is passed to subroutines handling C<&>, C<|>, C<^> and C<~>.
+This indicates that the caller is expecting numeric behaviour. The fourth
+argument will be C<undef>, as that position (C<$_[3]>) is reserved for use
+by L</nomethod>.
+
+=head3 Mathemagic, Mutators, and Copy Constructors
+
+The term 'mathemagic' describes the overloaded implementation
+of mathematical operators.
+Mathemagical operations raise an issue.
+Consider the code:
+
+ $a = $b;
+ --$a;
+
+If C<$a> and C<$b> are scalars then after these statements
+
+ $a == $b - 1
+
+An object, however, is a reference to blessed data, so if
+C<$a> and C<$b> are objects then the assignment C<$a = $b>
+copies only the reference, leaving C<$a> and C<$b> referring
+to the same object data.
+One might therefore expect the operation C<--$a> to decrement
+C<$b> as well as C<$a>.
+However, this would not be consistent with how we expect the
+mathematical operators to work.
+
+Perl resolves this dilemma by transparently calling a copy
+constructor before calling a method defined to implement
+a mutator (C<-->, C<+=>, and so on.).
+In the above example, when Perl reaches the decrement
+statement, it makes a copy of the object data in C<$a> and
+assigns to C<$a> a reference to the copied data.
+Only then does it call C<decr()>, which alters the copied
+data, leaving C<$b> unchanged.
+Thus the object metaphor is preserved as far as possible,
+while mathemagical operations still work according to the
+arithmetic metaphor.
+
+Note: the preceding paragraph describes what happens when
+Perl autogenerates the copy constructor for an object based
+on a scalar.
+For other cases, see L<Copy Constructor>.