## DESCRIPTION

This module provides the functions used by PDL to overload the basic mathematical operators (`"+ - / *"`etc.) and functions (

`"sin sqrt"`etc.)

It also includes the function `"log10"`, which should
be a perl function so that we can overload it!

Matrix multiplication (the operator `"x"`) is handled
by the module PDL::Primitive.

## SYNOPSIS

none## FUNCTIONS

## plus

Signature: (a(); b(); [o]c(); int swap)

add two piddles

$c = plus $a, $b, 0; # explicit call with trailing 0 $c = $a + $b; # overloaded call $a->inplace->plus($b,0); # modify $a inplace

It can be made to work inplace with the `"$a->inplace"` syntax.
This function is used to overload the binary `"+"` operator.
Note that when calling this function explicitly you need to supply
a third argument that should generally be zero (see first example).
This restriction is expected to go away in future releases.

plus processes bad values. The state of the bad-value flag of the output piddles is unknown.

## mult

Signature: (a(); b(); [o]c(); int swap)

multiply two piddles

$c = mult $a, $b, 0; # explicit call with trailing 0 $c = $a * $b; # overloaded call $a->inplace->mult($b,0); # modify $a inplace

It can be made to work inplace with the `"$a->inplace"` syntax.
This function is used to overload the binary `"*"` operator.
Note that when calling this function explicitly you need to supply
a third argument that should generally be zero (see first example).
This restriction is expected to go away in future releases.

mult processes bad values. The state of the bad-value flag of the output piddles is unknown.

## minus

Signature: (a(); b(); [o]c(); int swap)

subtract two piddles

$c = minus $a, $b, 0; # explicit call with trailing 0 $c = $a - $b; # overloaded call $a->inplace->minus($b,0); # modify $a inplace

It can be made to work inplace with the `"$a->inplace"` syntax.
This function is used to overload the binary `"-"` operator.
Note that when calling this function explicitly you need to supply
a third argument that should generally be zero (see first example).
This restriction is expected to go away in future releases.

minus processes bad values. The state of the bad-value flag of the output piddles is unknown.

## divide

Signature: (a(); b(); [o]c(); int swap)

divide two piddles

$c = divide $a, $b, 0; # explicit call with trailing 0 $c = $a / $b; # overloaded call $a->inplace->divide($b,0); # modify $a inplace

It can be made to work inplace with the `"$a->inplace"` syntax.
This function is used to overload the binary `"/"` operator.
Note that when calling this function explicitly you need to supply
a third argument that should generally be zero (see first example).
This restriction is expected to go away in future releases.

divide processes bad values. The state of the bad-value flag of the output piddles is unknown.

## gt

Signature: (a(); b(); [o]c(); int swap)

the binary > (greater than) operation

$c = gt $a, $b, 0; # explicit call with trailing 0 $c = $a > $b; # overloaded call $a->inplace->gt($b,0); # modify $a inplace

It can be made to work inplace with the `"$a->inplace"` syntax.
This function is used to overload the binary `">"` operator.
Note that when calling this function explicitly you need to supply
a third argument that should generally be zero (see first example).
This restriction is expected to go away in future releases.

gt processes bad values. The state of the bad-value flag of the output piddles is unknown.

## lt

Signature: (a(); b(); [o]c(); int swap)

the binary < (less than) operation

$c = lt $a, $b, 0; # explicit call with trailing 0 $c = $a < $b; # overloaded call $a->inplace->lt($b,0); # modify $a inplace

It can be made to work inplace with the `"$a->inplace"` syntax.
This function is used to overload the binary `"<"` operator.
Note that when calling this function explicitly you need to supply
a third argument that should generally be zero (see first example).
This restriction is expected to go away in future releases.

lt processes bad values. The state of the bad-value flag of the output piddles is unknown.

## le

Signature: (a(); b(); [o]c(); int swap)

the binary <= (less equal) operation

$c = le $a, $b, 0; # explicit call with trailing 0 $c = $a <= $b; # overloaded call $a->inplace->le($b,0); # modify $a inplace

It can be made to work inplace with the `"$a->inplace"` syntax.
This function is used to overload the binary `"<="` operator.
Note that when calling this function explicitly you need to supply
a third argument that should generally be zero (see first example).
This restriction is expected to go away in future releases.

le processes bad values. The state of the bad-value flag of the output piddles is unknown.

## ge

Signature: (a(); b(); [o]c(); int swap)

the binary >= (greater equal) operation

$c = ge $a, $b, 0; # explicit call with trailing 0 $c = $a >= $b; # overloaded call $a->inplace->ge($b,0); # modify $a inplace

It can be made to work inplace with the `"$a->inplace"` syntax.
This function is used to overload the binary `">="` operator.
Note that when calling this function explicitly you need to supply
a third argument that should generally be zero (see first example).
This restriction is expected to go away in future releases.

ge processes bad values. The state of the bad-value flag of the output piddles is unknown.

## eq

Signature: (a(); b(); [o]c(); int swap)

binary *equal to* operation (`"=="`)

$c = eq $a, $b, 0; # explicit call with trailing 0 $c = $a == $b; # overloaded call $a->inplace->eq($b,0); # modify $a inplace

It can be made to work inplace with the `"$a->inplace"` syntax.
This function is used to overload the binary `"=="` operator.
Note that when calling this function explicitly you need to supply
a third argument that should generally be zero (see first example).
This restriction is expected to go away in future releases.

eq processes bad values. The state of the bad-value flag of the output piddles is unknown.

## ne

Signature: (a(); b(); [o]c(); int swap)

binary *not equal to* operation (`"!="`)

$c = ne $a, $b, 0; # explicit call with trailing 0 $c = $a != $b; # overloaded call $a->inplace->ne($b,0); # modify $a inplace

It can be made to work inplace with the `"$a->inplace"` syntax.
This function is used to overload the binary `"!="` operator.
Note that when calling this function explicitly you need to supply
a third argument that should generally be zero (see first example).
This restriction is expected to go away in future releases.

ne processes bad values. The state of the bad-value flag of the output piddles is unknown.

## shiftleft

Signature: (a(); b(); [o]c(); int swap)

leftshift `$a` by `$b`

$c = shiftleft $a, $b, 0; # explicit call with trailing 0 $c = $a << $b; # overloaded call $a->inplace->shiftleft($b,0); # modify $a inplace

It can be made to work inplace with the `"$a->inplace"` syntax.
This function is used to overload the binary `"<<"` operator.
Note that when calling this function explicitly you need to supply
a third argument that should generally be zero (see first example).
This restriction is expected to go away in future releases.

shiftleft processes bad values. The state of the bad-value flag of the output piddles is unknown.

## shiftright

Signature: (a(); b(); [o]c(); int swap)

rightshift `$a` by `$b`

$c = shiftright $a, $b, 0; # explicit call with trailing 0 $c = $a >> $b; # overloaded call $a->inplace->shiftright($b,0); # modify $a inplace

It can be made to work inplace with the `"$a->inplace"` syntax.
This function is used to overload the binary `">>"` operator.
Note that when calling this function explicitly you need to supply
a third argument that should generally be zero (see first example).
This restriction is expected to go away in future releases.

shiftright processes bad values. The state of the bad-value flag of the output piddles is unknown.

## or2

Signature: (a(); b(); [o]c(); int swap)

binary *or* of two piddles

$c = or2 $a, $b, 0; # explicit call with trailing 0 $c = $a | $b; # overloaded call $a->inplace->or2($b,0); # modify $a inplace

It can be made to work inplace with the `"$a->inplace"` syntax.
This function is used to overload the binary `"|"` operator.
Note that when calling this function explicitly you need to supply
a third argument that should generally be zero (see first example).
This restriction is expected to go away in future releases.

or2 processes bad values. The state of the bad-value flag of the output piddles is unknown.

## and2

Signature: (a(); b(); [o]c(); int swap)

binary *and* of two piddles

$c = and2 $a, $b, 0; # explicit call with trailing 0 $c = $a & $b; # overloaded call $a->inplace->and2($b,0); # modify $a inplace

It can be made to work inplace with the `"$a->inplace"` syntax.
This function is used to overload the binary `"&"` operator.
Note that when calling this function explicitly you need to supply
a third argument that should generally be zero (see first example).
This restriction is expected to go away in future releases.

and2 processes bad values. The state of the bad-value flag of the output piddles is unknown.

## xor

Signature: (a(); b(); [o]c(); int swap)

binary *exclusive or* of two piddles

$c = xor $a, $b, 0; # explicit call with trailing 0 $c = $a ^ $b; # overloaded call $a->inplace->xor($b,0); # modify $a inplace

It can be made to work inplace with the `"$a->inplace"` syntax.
This function is used to overload the binary `"^"` operator.
Note that when calling this function explicitly you need to supply
a third argument that should generally be zero (see first example).
This restriction is expected to go away in future releases.

xor processes bad values. The state of the bad-value flag of the output piddles is unknown.

## bitnot

Signature: (a(); [o]b())

unary bit negation

$b = ~ $a; $a->inplace->bitnot; # modify $a inplace

It can be made to work inplace with the `"$a->inplace"` syntax.
This function is used to overload the unary `"~"` operator/function.

bitnot processes bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.

## power

Signature: (a(); b(); [o]c(); int swap)

raise piddle `$a` to the power `$b`

$c = $a->power($b,0); # explicit function call $c = $a ** $b; # overloaded use $a->inplace->power($b,0); # modify $a inplace

It can be made to work inplace with the `"$a->inplace"` syntax.
This function is used to overload the binary `"**"` function.
Note that when calling this function explicitly you need to supply
a third argument that should generally be zero (see first example).
This restriction is expected to go away in future releases.

power processes bad values. The state of the bad-value flag of the output piddles is unknown.

## atan2

Signature: (a(); b(); [o]c(); int swap)

elementwise `"atan2"` of two piddles

$c = $a->atan2($b,0); # explicit function call $c = atan2 $a, $b; # overloaded use $a->inplace->atan2($b,0); # modify $a inplace

It can be made to work inplace with the `"$a->inplace"` syntax.
This function is used to overload the binary `"atan2"` function.
Note that when calling this function explicitly you need to supply
a third argument that should generally be zero (see first example).
This restriction is expected to go away in future releases.

atan2 processes bad values. The state of the bad-value flag of the output piddles is unknown.

## modulo

Signature: (a(); b(); [o]c(); int swap)

elementwise `"modulo"` operation

$c = $a->modulo($b,0); # explicit function call $c = $a % $b; # overloaded use $a->inplace->modulo($b,0); # modify $a inplace

It can be made to work inplace with the `"$a->inplace"` syntax.
This function is used to overload the binary `"%"` function.
Note that when calling this function explicitly you need to supply
a third argument that should generally be zero (see first example).
This restriction is expected to go away in future releases.

modulo processes bad values. The state of the bad-value flag of the output piddles is unknown.

## spaceship

Signature: (a(); b(); [o]c(); int swap)

elementwise ``<=>'' operation

$c = $a->spaceship($b,0); # explicit function call $c = $a <=> $b; # overloaded use $a->inplace->spaceship($b,0); # modify $a inplace

It can be made to work inplace with the `"$a->inplace"` syntax.
This function is used to overload the binary `"<=>"` function.
Note that when calling this function explicitly you need to supply
a third argument that should generally be zero (see first example).
This restriction is expected to go away in future releases.

spaceship processes bad values. The state of the bad-value flag of the output piddles is unknown.

## sqrt

Signature: (a(); [o]b())

elementwise square root

$b = sqrt $a; $a->inplace->sqrt; # modify $a inplace

It can be made to work inplace with the `"$a->inplace"` syntax.
This function is used to overload the unary `"sqrt"` operator/function.

sqrt processes bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.

## abs

Signature: (a(); [o]b())

elementwise absolute value

$b = abs $a; $a->inplace->abs; # modify $a inplace

It can be made to work inplace with the `"$a->inplace"` syntax.
This function is used to overload the unary `"abs"` operator/function.

abs processes bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.

## sin

Signature: (a(); [o]b())

the sin function

$b = sin $a; $a->inplace->sin; # modify $a inplace

It can be made to work inplace with the `"$a->inplace"` syntax.
This function is used to overload the unary `"sin"` operator/function.

sin processes bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.

## cos

Signature: (a(); [o]b())

the cos function

$b = cos $a; $a->inplace->cos; # modify $a inplace

It can be made to work inplace with the `"$a->inplace"` syntax.
This function is used to overload the unary `"cos"` operator/function.

cos processes bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.

## not

Signature: (a(); [o]b())

the elementwise *not* operation

$b = ! $a; $a->inplace->not; # modify $a inplace

It can be made to work inplace with the `"$a->inplace"` syntax.
This function is used to overload the unary `"!"` operator/function.

not processes bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.

## exp

Signature: (a(); [o]b())

the exponential function

$b = exp $a; $a->inplace->exp; # modify $a inplace

It can be made to work inplace with the `"$a->inplace"` syntax.
This function is used to overload the unary `"exp"` operator/function.

exp processes bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.

## log

Signature: (a(); [o]b())

the natural logarithm

$b = log $a; $a->inplace->log; # modify $a inplace

It can be made to work inplace with the `"$a->inplace"` syntax.
This function is used to overload the unary `"log"` operator/function.

log processes bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.

## log10

Signature: (a(); [o]b())

the base 10 logarithm

$b = log10 $a; $a->inplace->log10; # modify $a inplace

It can be made to work inplace with the `"$a->inplace"` syntax.
This function is used to overload the unary `"log10"` operator/function.

log10 processes bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.

## assgn

Signature: (a(); [o]b())

Plain numerical assignment. This is used to implement the ``.='' operator

assgn does not process bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.

## ipow

Signature: (a(); b(); [o] ans())

raise piddle `$a` to integer power `$b`

$c = $a->ipow($b,0); # explicit function call $c = ipow $a, $b; $a->inplace->ipow($b,0); # modify $a inplace

It can be made to work inplace with the `"$a->inplace"` syntax.
Note that when calling this function explicitly you need to supply
a third argument that should generally be zero (see first example).
This restriction is expected to go away in future releases.

Algorithm from Wikipedia <http://en.wikipedia.org/wiki/Exponentiation_by_squaring>

ipow does not process bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.

## AUTHOR

Tuomas J. Lukka ([email protected]), Karl Glazebrook ([email protected]), Doug Hunt ([email protected]), Christian Soeller ([email protected]), Doug Burke ([email protected]), and Craig DeForest ([email protected]).