*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->IRIX man pages -> perl5/overload (3)              


overload(3)							   overload(3)

NAME    [Toc]    [Back]

     overload -	Package	for overloading	perl operations

SYNOPSIS    [Toc]    [Back]

	 package SomeThing;

	 use overload
	     '+' => \&myadd,
	     '-' => \&mysub;
	     # etc

	 package main;
	 $a = new SomeThing 57;
	 if (overload::Overloaded $b) {...}
	 $strval = overload::StrVal $b;

CAVEAT SCRIPTOR    [Toc]    [Back]

     Overloading of operators is a subject not to be taken lightly.  Neither
     its precise implementation, syntax, nor semantics are 100%	endorsed by
     Larry Wall.  So any of these may be changed at some point in the future.

DESCRIPTION    [Toc]    [Back]

     Declaration of overloaded functions

     The compilation directive

	 package Number;
	 use overload
	     "+" => \&add,
	     "*=" => "muas";

     declares function Number::add() for addition, and method muas() in	the
     "class" Number (or	one of its base	classes) for the assignment form *= of

     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.
     Note that values specified	as strings are interpreted as methods, not
     subroutines.  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	the section on MAGIC AUTOGENERATION.  (Mathemagical methods
     refer to methods triggered	by an overloaded mathematical operator.)

									Page 1

overload(3)							   overload(3)

     Since overloading respects	inheritance via	the @ISA hierarchy, the	above
     declaration would also trigger overloading	of + and *= in all the
     packages which inherit from Number.

     Calling Conventions for Binary Operations    [Toc]    [Back]

     The functions specified in	the use	overload ... directive are called with
     three (in one particular case with	four, see the section on 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:

     FALSE  the	order of arguments is as in the	current	operation.

     TRUE   the	arguments are reversed.

     undef  the	current	operation is an	assignment variant (as in $a+=7), but
	    the	usual function is called instead.  This	additional information
	    can	be used	to generate some optimizations.

     Calling Conventions for Unary Operations    [Toc]    [Back]

     Unary operation are considered binary operations with the second argument
     being undef.  Thus	the functions that overloads {"++"} is called with
     arguments ($a,undef,'') when $a++ is executed.

     Overloadable Operations    [Toc]    [Back]

     The following symbols can be specified in use overload:

     o Arithmetic operations

	      "+", "+=", "-", "-=", "*", "*=", "/", "/=", "%", "%=",
	      "**", "**=", "<<", "<<=",	">>", ">>=", "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.

     o Comparison operations

	      "<",  "<=", ">",	">=", "==", "!=", "<=>",
	      "lt", "le", "gt",	"ge", "eq", "ne", "cmp",

	  If the corresponding "spaceship" variant is available, it can	be

									Page 2

overload(3)							   overload(3)

	  used to substitute for the missing operation.	 During	sorting
	  arrays, cmp is used to compare values	subject	to use overload.

     o Bit operations

	      "&", "^",	"|", "neg", "!", "~",

	  "neg"	stands for unary minus.	 If the	method for neg is not
	  specified, it	can be autogenerated using the method for subtraction.
	  If the method	for "!"	is not specified, it can be autogenerated
	  using	the methods for	"bool",	or "\"\"", or "0+".

     o Increment and decrement

	      "++", "--",

	  If undefined,	addition and subtraction methods can be	used instead.
	  These	operations are called both in prefix and postfix form.

     o Transcendental functions

	      "atan2", "cos", "sin", "exp", "abs", "log", "sqrt",

	  If abs is unavailable, it can	be autogenerated using methods for "<"
	  or "<=>" combined with either	unary minus or subtraction.

     o Boolean,	string and numeric conversion

	      "bool", "\"\"", "0+",

	  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.

     o Special

	      "nomethod", "fallback", "=",

	  see the section on SPECIAL SYMBOLS FOR use overload.

     See the section on	Fallback for an	explanation of when a missing method
     can be autogenerated.

     Inheritance and overloading    [Toc]    [Back]

     Inheritance interacts with	overloading in two ways.

									Page 3

overload(3)							   overload(3)

     Strings as	values of use overload directive
	  If value in

	    use	overload key =>	value;

	  is a string, it is interpreted as a method name.

     Overloading of an operation is inherited by derived classes
	  Any class derived from an overloaded class is	also overloaded.  The
	  set of overloaded methods is the union of overloaded methods of all
	  the ancestors. If some method	is overloaded in several ancestor,
	  then which description will be used is decided by the	usual
	  inheritance rules:

	  If A inherits	from B and C (in this order), B	overloads + with
	  \&D::plus_sub, and C overloads + by "plus_meth", then	the subroutine
	  D::plus_sub will be called to	implement operation + for an object in
	  package A.

     Note that since the value of the fallback key is not a subroutine,	its
     inheritance is not	governed by the	above rules.  In the current
     implementation, the value of fallback in the first	overloaded ancestor is
     used, but this is accidental and subject to change.

     Three keys	are recognized by Perl that are	not covered by the above

     Last Resort    [Toc]    [Back]

     "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    [Toc]    [Back]

     The key "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":

									Page 4

overload(3)							   overload(3)

     o undef	     Perl tries	to use a substituted method (see the section
		     on	MAGIC AUTOGENERATION).	If this	fails, it then tries
		     to	calls "nomethod" value;	if missing, an exception will
		     be	raised.

     o TRUE	     The same as for the undef value, but no exception is
		     raised.  Instead, it silently reverts to what it would
		     have done were there no use overload present.

     o defined,	but FALSE
		     No	autogeneration is tried.  Perl tries to	call
		     "nomethod"	value, and if this is missing, raises an

     Note. "fallback" inheritance via @ISA is not carved in stone yet, see the
     section on	Inheritance and	overloading.

     Copy Constructor    [Toc]    [Back]

     The value for "=" is a reference to a function with three arguments,
     i.e., it looks like the other values in use overload. However, it does
     not overload the Perl assignment operator.	This would go against Camel

     This operation is called in the situations	when a mutator is applied to a
     reference that shares its object with some	other reference, such as


     To	make this change $a and	not change $b, a copy of $$a is	made, and $a
     is	assigned a reference to	this new object.  This operation is done
     during execution of the $a++, and not during the assignment, (so before
     the increment $$a coincides with $$b).  This is only done if ++ is
     expressed via a method for	'++' or	'+='.  Note that if this operation is
     expressed via '+' a nonmutator, i.e., as in


     then $a does not reference	a new copy of $$a, since $$a does not appear
     as	lvalue when the	above code is executed.

     If	the copy constructor is	required during	the execution of some mutator,
     but a method for '=' was not specified, it	can be autogenerated as	a
     string copy if the	object is a plain scalar.

     Example    [Toc]    [Back]
	  The actually executed	code for

									Page 5

overload(3)							   overload(3)

		  Something else which does not	modify $a or $b....

	  may be

		  Something else which does not	modify $a or $b....
		  $a = $a->clone(undef,"");

	  if $b	was mathemagical, and '++' was overloaded with \&incr, '=' was
	  overloaded with \&clone.


     If	a method for an	operation is not found,	and the	value for  "fallback"
     is	TRUE or	undefined, Perl	tries to autogenerate a	substitute method for
     the missing operation based on the	defined	operations.  Autogenerated
     method substitutions are possible for the following operations:

     Assignment	forms of arithmetic operations
		     $a+=$b can	use the	method for "+" if the method for "+="
		     is	not defined.

     Conversion	operations
		     String, numeric, and boolean conversion are calculated in
		     terms of one another if not all of	them are defined.

     Increment and decrement
		     The ++$a operation	can be expressed in terms of $a+=1 or
		     $a+1, and $a-- in terms of	$a-=1 and $a-1.

     abs($a)	     can be expressed in terms of $a<0 and -$a (or 0-$a).

     Unary minus     can be expressed in terms of subtraction.

     Negation	     ! and not can be expressed	in terms of boolean
		     conversion, or string or numerical	conversion.

     Concatenation   can be expressed in terms of string conversion.

     Comparison	operations
		     can be expressed in terms of its "spaceship" counterpart:
		     either <=>	or cmp:

			 <, >, <=, >=, ==, !=	     in	terms of <=>
			 lt, gt, le, ge, eq, ne	     in	terms of cmp

     Copy operator   can be expressed in terms of an assignment	to the
		     dereferenced value, if this value is a scalar and not a

									Page 6

overload(3)							   overload(3)

WARNING    [Toc]    [Back]

     The restriction for the comparison	operation is that even if, for
     example, `cmp' should return a blessed reference, the autogenerated `lt'
     function will produce only	a standard logical value based on the
     numerical value of	the result of `cmp'.  In particular, a working numeric
     conversion	is needed in this case (possibly expressed in terms of other

     Similarly,	.=  and	x= operators lose their	mathemagical properties	if the
     string conversion substitution is applied.

     When you chop() a mathemagical object it is promoted to a string and its
     mathemagical properties are lost.	The same can happen with other
     operations	as well.

Run-time Overloading    [Toc]    [Back]

     Since all use directives are executed at compile-time, the	only way to
     change overloading	during run-time	is to

	 eval 'use overload "+"	=> \&addmethod';

     You can also use

	 eval 'no overload "+",	"--", "<="';

     though the	use of these constructs	during run-time	is questionable.

Public functions    [Toc]    [Back]

     Package overload.pm provides the following	public functions:

	  Gives	string value of	arg as in absence of stringify overloading.

	  Returns true if arg is subject to overloading	of some	operations.

	  Returns undef	or a reference to the method that implements op.

IMPLEMENTATION    [Toc]    [Back]

     What follows is subject to	change RSN.

     The table of methods for all operations is	cached in magic	for the	symbol
     table hash	for the	package.  The cache is invalidated during processing
     of	use overload, no overload, new function	definitions, and changes in
     @ISA. However, this invalidation remains unprocessed until	the next
     blessing into the package.	Hence if you want to change overloading
     structure dynamically, you'll need	an additional (fake) blessing to
     update the	table.

									Page 7

overload(3)							   overload(3)

     (Every SVish thing	has a magic queue, and magic is	an entry in that
     queue.  This is how a single variable may participate in multiple forms
     of	magic simultaneously.  For instance, environment variables regularly
     have two forms at once: their %ENV	magic and their	taint magic. However,
     the magic which implements	overloading is applied to the stashes, which
     are rarely	used directly, thus should not slow down Perl.)

     If	an object belongs to a package using overload, it carries a special
     flag.  Thus the only speed	penalty	during arithmetic operations without
     overloading is the	checking of this flag.

     In	fact, if use overload is not present, there is almost no overhead for
     overloadable operations, so most programs should not suffer measurable
     performance penalties.  A considerable effort was made to minimize	the
     overhead when overload is used in some package, but the arguments in
     question do not belong to packages	using overload.	 When in doubt,	test
     your speed	with use overload and without it.  So far there	have been no
     reports of	substantial speed degradation if Perl is compiled with
     optimization turned on.

     There is no size penalty for data if overload is not used.	The only size
     penalty if	overload is used in some package is that all the packages
     acquire a magic during the	next blessing into the package.	This magic is
     three-words-long for packages without overloading,	and carries the	cache
     tabel if the package is overloaded.

     Copying ($a=$b) is	shallow; however, a one-level-deep copying is carried
     out before	any operation that can imply an	assignment to the object $a
     (or $b) refers to,	like $a++.  You	can override this behavior by defining
     your own copy constructor (see the	section	on Copy	Constructor).

     It	is expected that arguments to methods that are not explicitly supposed
     to	be changed are constant	(but this is not enforced).

AUTHOR    [Toc]    [Back]

     Ilya Zakharevich <ilya@math.mps.ohio-state.edu>.

DIAGNOSTICS    [Toc]    [Back]

     When Perl is run with the -Do switch or its equivalent, overloading
     induces diagnostic	messages.

     Using the m command of Perl debugger (see the perldebug manpage) one can
     deduce which operations are overloaded (and which ancestor	triggers this
     overloading). Say,	if eq is overloaded, then the method (eq is shown by
     debugger. The method () corresponds to the	fallback key (in fact a
     presence of this method shows that	this package has overloading enabled,
     and it is what is used by the Overloaded function).

BUGS    [Toc]    [Back]

     Because it	is used	for overloading, the per-package hash %OVERLOAD	now
     has a special meaning in Perl. The	symbol table is	filled with names
     looking like line-noise.

									Page 8

overload(3)							   overload(3)

     For the purpose of	inheritance every overloaded package behaves as	if
     fallback is present (possibly undefined). This may	create interesting
     effects if	some package is	not overloaded,	but inherits from two
     overloaded	packages.

     This document is confusing.

									Page 9

overload(3)							   overload(3)

								       PPPPaaaaggggeeee 11110000
[ Back ]
 Similar pages
Name OS Title
Term::ReadLine IRIX Perl interface to various readline packages. If no real package is found, substitutes stubs instead of basic f
perljp OpenBSD AEuEU,i Perl Y~YxYE `A^a`I`A Perl xIAx3|xOxex|x3x1/2! Perl 5.8.0 xexeicUni- _ codeYuYYi1/4YEx~AcEyxE...
perlnumber OpenBSD semantics of numbers and numeric operations in Perl
ops IRIX Perl pragma to restrict unsafe operations when compiling
locale IRIX Perl pragma to use and avoid POSIX locales for built-in operations
pkg_sign FreeBSD handle package signatures
AutoSplit IRIX split a package for autoloading
pkg_check FreeBSD handle package signatures
dh_installemacsen Linux register an emacs add on package
pthread_once OpenBSD dynamic package initialization
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service