ZF-9831: Apparent difference b/w documentation for add() and sub() and actual behavior

Description

The 1.10 documentation reads: http://zendframework.com/manual/en/…

bq. ... Each addition will create a new object for the result. The actual object will never be changed by the class.

Considering a simple example, slightly modified from the documentation:


require_once('Zend/Measure/Length.php');

$unit = new Zend_Measure_Length(200, Zend_Measure_Length::CENTIMETER);
$unit2 = new Zend_Measure_Length(1, Zend_Measure_Length::METER);

echo "$unit + $unit2 = ?\n";
$sum = $unit->add($unit2);
echo "$unit + $unit2 = $sum\n";

Has an actual result of:

200 cm + 1 m = ?
300 cm + 100 cm = 300 cm

By my reading of the documentation, I expect that the $unit variable will not be modified. Note that, however, $unit IS modified.

I do not know if this is a change from previous versions, a documentation issue, an issue in my version/build (5.2.12-pl0-gentoo) or a misunderstanding on my part.

Comments

The API shows that the fluid interface is used. So behaviour of code is correct.

Thanks Thomas for the quick response!

My concern here is not the accuracy of the code, but the precision of the documentation. I fail to see where the documentation mentions or alludes to the fact that the left-hand side of -> will be modified.

By my notion of "fluent interface", this would be allowed (and good):


$unit1 = new Zend_Measure_Length(1);
$unit2 = new Zend_Measure_Length(2);
$unit3 = new Zend_Measure_Length(3);

$unit6 = $unit1->add($unit2)->add($unit3);

And there would be no side effects -- the only variable that would change in that equation is $unit6. The documentation as it exists seems to support that intention.

At a minimum, if the LHS of the operation is modified, I think the docs should note that. Thoughts?

Docu clearified with r22160

The manual stated already {quote} Dynamic objects support a fluid style of programming, where complex sequences of operations can be nested without risk of side-effects altering the input objects {quote}

Only the beginning was changed as it irritated.