This page details the arithmetic operations available for classes which implement SimpleNumberInterface and that use ArithmeticSimpleTrait.

Available Modes

The ArithmeticSimpleTrait supports the modes:

  • Selectable::CALC_MODE_PRECISION
  • Selectable::CALC_MODE_NATIVE

See Also

For more detail on calculation modes, see the Getting Started > Calculation Modes page.

Available Methods

The following methods are available for classes that implement SimpleNumberInterface and that use ArithmeticSimpleTrait.

Return Value Depends On Context

While all return values will implement NumberInterface, the exact class returned depends on both what type is provided as the $num, and on the type of calling class. In general, the class that best fits the data of the result is returned, with preference given to the type of the calling class. See the examples below.

Mixed Argument Limitations

The arguments are listed in this documentation as mixed. In fact, the valid input types are:

  • An integer
  • A float
  • A string that contains only a single number in base-10
  • A string that contains only a single number in base-10 with the i character at the end, denoting an imaginary value
  • A string that contains two base-10 numbers separated by a division bar /
  • A string that contains two base-10 numbers separated by a + or -, with the number on the right having the i character after the value
  • An object that implements NumberInterface

If the provided $value matches none of these, an exception of type Samsara\Exceptions\UsageError\IntegrityConstraint is thrown.

add(mixed $num): NumberInterface

$num
Accepts a mixed value that is limited to the formats detailed in the Available Methods section.
returns
Returns an object of the same class as the calling class if the resulting value can be represented with a SimpleNumberInterface. Returns an object of the ImmutableComplexNumber class if the resulting value has both a real and imaginary component.

This function adds the current value with $num and returns the result.

Examples: Add

 1<?php
 2
 3use Samsara\Fermat\Values\ImmutableDecimal;
 4
 5$balance = new ImmutableDecimal('100');
 6$deposit = new ImmutableDecimal('50');
 7
 8$balance = $balance->add($deposit);
 9
10echo "Balance: ".$balance;
11// Prints: 'Balance: 150'

 1<?php
 2
 3use Samsara\Fermat\Values\ImmutableDecimal;
 4use Samsara\Fermat\Values\ImmutableFraction;
 5
 6$pizzas = new ImmutableDecimal('3');
 7$extraSlices = new ImmutableFraction('3', '8');
 8
 9$pizzas = $pizzas->add($extraSlices);
10
11echo "I have ".$pizzas." pizzas";
12// Prints: 'I have 3.375 pizzas'

 1<?php
 2
 3use Samsara\Fermat\Values\ImmutableDecimal;
 4use Samsara\Fermat\Values\ImmutableFraction;
 5
 6$leftOvers = new ImmutableFraction('3', '8');
 7$newOrder = new ImmutableDecimal('3');
 8
 9$pizzas = $leftOvers->add($newOrder);
10
11echo "I have ".$pizzas->getNumerator()." slices (".$pizzas." pizzas)";
12// Prints: 'I have 27 slices (27/8 pizzas)'

 1<?php
 2
 3use Samsara\Fermat\Values\ImmutableDecimal;
 4use Samsara\Fermat\Values\ImmutableComplexNumber;
 5
 6// Four volts being added to the circuit
 7$newVoltage = new ImmutableDecimal('4');
 8// Six volts in the circuit originally
 9$oldVoltage = new ImmutableDecimal('6');
10// Twenty amps in the circuit originally
11$oldCurrent = new ImmutableDecimal('20i');
12$circuitState = new ImmutableComplexNumber($oldVoltage, $oldCurrent);
13
14$newCircuitState = $newVoltage->add($circuitState);
15
16echo 'Circuit State: '.$newCircuitState;
17// Prints: 'Circuit State: 10+20i'
18
19// Addition is commutative even for complex numbers
20$newCircuitState = $circuitState->add($newVoltage);
21
22echo 'Circuit State: '.$newCircuitState;
23// Prints: 'Circuit State: 10+20i'

subtract(mixed $num): NumberInterface

$num
Accepts a mixed value that is limited to the formats detailed in the Available Methods section.
returns
Returns an object of the same class as the calling class if the resulting value can be represented with a SimpleNumberInterface. Returns an object of the ImmutableComplexNumber class if the resulting value has both a real and imaginary component.

This function subtracts $num from the current value and returns the result.

Examples: Subtract

 1<?php
 2
 3use Samsara\Fermat\Values\ImmutableDecimal;
 4
 5$balance = new ImmutableDecimal('100');
 6$debit = new ImmutableDecimal('50');
 7
 8$balance = $balance->subtract($debit);
 9
10echo "Balance: ".$balance;
11// Prints: 'Balance: 50'

 1<?php
 2
 3use Samsara\Fermat\Values\ImmutableDecimal;
 4use Samsara\Fermat\Values\ImmutableFraction;
 5
 6$pizzas = new ImmutableDecimal('3');
 7$eatenByFriends = new ImmutableFraction('3', '8');
 8
 9$pizzas = $pizzas->subtract($eatenByFriends);
10
11echo "I have ".$pizzas." pizzas";
12// Prints: 'I have 2.625 pizzas'

 1<?php
 2
 3use Samsara\Fermat\Values\ImmutableDecimal;
 4use Samsara\Fermat\Values\ImmutableFraction;
 5
 6$leftOvers = new ImmutableFraction('25', '8');
 7$eatenByFriends = new ImmutableDecimal('2');
 8
 9$pizzas = $leftOvers->subtract($eatenByFriends);
10
11echo "I have ".$pizzas->getNumerator()." slices (".$pizzas." pizzas)";
12// Prints: 'I have 9 slices (9/8 pizzas)'

 1<?php
 2
 3use Samsara\Fermat\Values\ImmutableDecimal;
 4use Samsara\Fermat\Values\ImmutableComplexNumber;
 5
 6// Four volts being removed from the circuit
 7$newVoltage = new ImmutableDecimal('4');
 8// Six volts in the circuit originally
 9$oldVoltage = new ImmutableDecimal('6');
10// Twenty amps in the circuit originally
11$oldCurrent = new ImmutableDecimal('20i');
12$circuitState = new ImmutableComplexNumber($oldVoltage, $oldCurrent);
13
14$newCircuitState = $newVoltage->subtract($circuitState);
15
16echo 'Circuit State: '.$newCircuitState;
17// Prints: 'Circuit State: -2-20i'
18
19// Subtraction is not commutative
20$newCircuitState = $circuitState->subtract($newVoltage);
21
22echo 'Circuit State: '.$newCircuitState;
23// Prints: 'Circuit State: 2+20i'

multiply(mixed $num): NumberInterface

$num
Accepts a mixed value that is limited to the formats detailed in the Available Methods section.
returns
Returns an object of the same class as the calling class if the resulting value can be represented with a SimpleNumberInterface. Returns an object of the ImmutableComplexNumber class if the resulting value has both a real and imaginary component.

This function multiplies $num with the current value and returns the result.

Examples: Multiply

 1<?php
 2
 3use Samsara\Fermat\Values\ImmutableDecimal;
 4
 5$balance = new ImmutableDecimal('100');
 6$returnRate = new ImmutableDecimal('1.05');
 7
 8$balance = $balance->multiply($returnRate);
 9
10echo "Balance: ".$balance;
11// Prints: 'Balance: 105'

 1<?php
 2
 3use Samsara\Fermat\Values\ImmutableDecimal;
 4use Samsara\Fermat\Values\ImmutableFraction;
 5
 6$friends = new ImmutableDecimal('3');
 7$slicesPerPerson = new ImmutableFraction('3', '8');
 8
 9$pizzas = $friends->multiply($slicesPerPerson);
10
11echo "I need ".$pizzas." pizzas";
12// Prints: 'I have 3.125 pizzas'

 1<?php
 2
 3use Samsara\Fermat\Values\ImmutableDecimal;
 4use Samsara\Fermat\Values\ImmutableFraction;
 5
 6$friends = new ImmutableDecimal('3');
 7$slicesPerPerson = new ImmutableFraction('3', '8');
 8
 9$pizzas = $friends->multiply($slicesPerPerson);
10
11echo "I need ".$pizzas->getNumerator()." slices (".$pizzas." pizzas)";
12// Prints: 'I need 9 slices (9/8 pizzas)'

 1<?php
 2
 3use Samsara\Fermat\Values\ImmutableDecimal;
 4use Samsara\Fermat\Values\ImmutableComplexNumber;
 5
 6// Four circuits
 7$totalCircuits = new ImmutableDecimal('4');
 8// Six volts in each circuit
 9$oldVoltage = new ImmutableDecimal('6');
10// Twenty amps in each circuit originally
11$oldCurrent = new ImmutableDecimal('20i');
12$circuitState = new ImmutableComplexNumber($oldVoltage, $oldCurrent);
13
14$newCircuitState = $totalCircuits->multiply($circuitState);
15
16echo 'Circuit State: '.$newCircuitState;
17// Prints: 'Circuit State: 24+80i'
18
19// Multiplication is commutative
20$newCircuitState = $circuitState->multiply($totalCircuits);
21
22echo 'Circuit State: '.$newCircuitState;
23// Prints: 'Circuit State: 24+80i'

divide(mixed $num, ?int $scale = null): NumberInterface

$num
Accepts a mixed value that is limited to the formats detailed in the Available Methods section.
returns
Returns an object of the same class as the calling class if the resulting value can be represented with a SimpleNumberInterface. Returns an object of the ImmutableComplexNumber class if the resulting value has both a real and imaginary component.

This function divides $num with the current value and returns the result.

Automatic Scale

If no scale setting is provided for this operation, the scale of both numbers is compared and the larger scale is used. The returned value has this programmatically determined scale, which can be greater than, but not less than, the scale of the calling object.

Examples: Divide

 1<?php
 2
 3use Samsara\Fermat\Values\ImmutableDecimal;
 4
 5$assets = new ImmutableDecimal('100');
 6$shares = new ImmutableDecimal('50');
 7
 8$price = $assets->divide($shares);
 9
10echo "Price: ".$price;
11// Prints: 'Price: 2'

 1<?php
 2
 3use Samsara\Fermat\Values\ImmutableDecimal;
 4use Samsara\Fermat\Values\ImmutableFraction;
 5
 6$pizzas = new ImmutableDecimal('4');
 7$slicesPerPerson = new ImmutableFraction('3', '8');
 8
 9$friends = $pizzas->divide($slicesPerPerson);
10
11echo "I have enough pizzas for ".$friends." friends";
12// Prints: 'I have enough pizzas for 10.6666666666 friends'

 1<?php
 2
 3use Samsara\Fermat\Values\ImmutableDecimal;
 4use Samsara\Fermat\Values\ImmutableFraction;
 5
 6$pizzaSlices = new ImmutableDecimal('3');
 7$slicesPerPerson = new ImmutableDecimal('3');
 8$friends = new ImmutableDecimal('6');
 9$pizzaGoal = new ImmutableFraction($slicesPerPerson, $friends);
10
11$pizzaGoal = $pizzaGoal->divide($pizzaSlices);
12
13echo "I have ".$pizzaGoal." of the pizza needed to feed everyone";
14// Prints: 'I have 1/6 of the pizza needed to feed everyone'

 1<?php
 2
 3use Samsara\Fermat\Values\ImmutableDecimal;
 4use Samsara\Fermat\Values\ImmutableComplexNumber;
 5
 6// Four circuits
 7$totalCircuits = new ImmutableDecimal('4');
 8// Six volts in each circuit
 9$oldVoltage = new ImmutableDecimal('6');
10// Twenty amps in each circuit originally
11$oldCurrent = new ImmutableDecimal('20i');
12$circuitState = new ImmutableComplexNumber($oldVoltage, $oldCurrent);
13
14$newCircuitState = $totalCircuits->divide($circuitState);
15
16echo 'Circuit State: '.$newCircuitState;
17// Prints: 'Circuit State: 0.0550458715-0.1834862385i'
18
19// Multiplication is commutative
20$newCircuitState = $circuitState->divide($totalCircuits);
21
22echo 'Circuit State: '.$newCircuitState;
23// Prints: 'Circuit State: 1.5+5i'

pow(mixed $num): NumberInterface

$num
Accepts a mixed value that is limited to the formats detailed in the Available Methods section.
returns
Returns an object of the same class as the calling class if the resulting value can be represented with a SimpleNumberInterface. Returns an object of the ImmutableComplexNumber class if the resulting value has both a real and imaginary component.

This function raises the current value to the power of $num and returns the result.

Examples: Divide

 1<?php
 2
 3use Samsara\Fermat\Values\ImmutableDecimal;
 4
 5$assets = new ImmutableDecimal('100');
 6$growthRate = new ImmutableDecimal('1.05');
 7
 8$value = $assets->pow($growthRate);
 9
10echo "Value: ".$value;
11// Prints: 'Value: 125.8925411794'

 1<?php
 2
 3use Samsara\Fermat\Values\ImmutableDecimal;
 4use Samsara\Fermat\Values\ImmutableFraction;
 5
 6$pizzas = new ImmutableDecimal('4');
 7$slicesPerPerson = new ImmutableFraction('3', '8');
 8
 9$friends = $pizzas->divide($slicesPerPerson);
10
11echo "I have enough pizzas for ".$friends." friends";
12// Prints: 'I have enough pizzas for 10.6666666666 friends'

 1<?php
 2
 3use Samsara\Fermat\Values\ImmutableDecimal;
 4use Samsara\Fermat\Values\ImmutableFraction;
 5
 6$pizzaSlices = new ImmutableDecimal('3');
 7$slicesPerPerson = new ImmutableDecimal('3');
 8$friends = new ImmutableDecimal('6');
 9$pizzaGoal = new ImmutableFraction($slicesPerPerson, $friends);
10
11$pizzaGoal = $pizzaGoal->divide($pizzaSlices);
12
13echo "I have ".$pizzaGoal." of the pizza needed to feed everyone";
14// Prints: 'I have 1/6 of the pizza needed to feed everyone'

 1<?php
 2
 3use Samsara\Fermat\Values\ImmutableDecimal;
 4use Samsara\Fermat\Values\ImmutableComplexNumber;
 5
 6// Four circuits
 7$totalCircuits = new ImmutableDecimal('4');
 8// Six volts in each circuit
 9$oldVoltage = new ImmutableDecimal('6');
10// Twenty amps in each circuit originally
11$oldCurrent = new ImmutableDecimal('20i');
12$circuitState = new ImmutableComplexNumber($oldVoltage, $oldCurrent);
13
14$newCircuitState = $totalCircuits->divide($circuitState);
15
16echo 'Circuit State: '.$newCircuitState;
17// Prints: 'Circuit State: 0.0550458715-0.1834862385i'
18
19// Multiplication is commutative
20$newCircuitState = $circuitState->divide($totalCircuits);
21
22echo 'Circuit State: '.$newCircuitState;
23// Prints: 'Circuit State: 1.5+5i'