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

Issue Type:
Bug
Created:
2010-05-12T12:39:45.000+0000
Last Updated:
2010-05-13T12:15:30.000+0000
Status:
Resolved
Fix version(s):
  • 1.10.5 (26/May/10)
Reporter:
Bishop Bettini (bishop)
Assignee:
Thomas Weidner (thomas)
Tags:
  • Zend_Measure
Related issues:
Attachments:

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

Posted by Thomas Weidner (thomas) on 2010-05-13T11:43:27.000+0000

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

Posted by Bishop Bettini (bishop) on 2010-05-13T12:04:13.000+0000

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?

Posted by Thomas Weidner (thomas) on 2010-05-13T12:12:20.000+0000

Docu clearified with r22160

Posted by Thomas Weidner (thomas) on 2010-05-13T12:15:30.000+0000

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.