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:


The 1.10 documentation reads:…

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:

<pre class="highlight">

$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:

<pre class="literal">
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.


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):

<pre class="highlight">
$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.

Have you found an issue?

See the Overview section for more details.


© 2006-2016 by Zend, a Rogue Wave Company. Made with by awesome contributors.

This website is built using zend-expressive and it runs on PHP 7.