Example code and descriptive text are misleading

[jerrywrice]

• I have searched open and closed issues and pull requests for duplicates, using these search terms:
  -Object-Oriented
  -Encapsulation

• I have checked the latest main branch to see if this has already been fixed, in this file:
  -src/ch17-01-what-is-oo.md

URL to the section(s) of the book with this problem:
https://doc.rust-lang.org/book/ch17-01-what-is-oo.html
Description of the problem:
In Section 17.1 + sub-section 'Encapsulation that Hides Implementation Details', the example with struct 'AveragedCollection' provides the three (3) public trait methods =>

'pub fn add(&mut self, value: i32)'
'pub fn remove(&mut self) -> Option'
'pub fn average(&self) -> f64'

Regarding the supporting text shown next, and specifically the high-lighted sentence =>

Because we’ve encapsulated the implementation details of the struct AveragedCollection, we can easily change aspects, such as the data structure, in the future. For instance, we could use a HashSet instead of a Vec for the list field. As long as the signatures of the add, remove, and average public methods stay the same, code using AveragedCollection wouldn’t need to change. If we made list public instead, this wouldn’t necessarily be the case: HashSet and Vec have different methods for adding and removing items, so the external code would likely have to change if it were modifying list directly.

The (above) descriptive text fails to mention that the specific return value of these trait methods must be identical to the original when invoked in the same order and with the same input argument values. This is essential for the internal (encapsulated) private implementation to be changed and have no measurable impact on existing client code, with the exception of total memory usage, CPU usage, and elapsed run time duration.

Suggested fix:
Replace the existing high-lighted/bold text above with =>

Because we’ve encapsulated the implementation details of the struct AveragedCollection, we can easily change aspects, such as the data structure, in the future. For instance, we could use a HashMap<i32,isize> instead of a Vec for the list field. The signatures of the add, remove, and average public methods must stay the same, and new implementations of the public method functions must be such that client code invoking these public trait methods in a given order and with the same input arguments must return the identical value as did the original. If we had made list public instead, existing client code which directly accessed this field would almost certainly require changes.

[carols10cents]

The (above) descriptive text fails to mention that the specific return value of these trait methods must be identical to the original when invoked in the same order and with the same input argument values. This is essential for the internal (encapsulated) private implementation to be changed and have no measurable impact on existing client code, with the exception of total memory usage, CPU usage, and elapsed run time duration.

The intent in this section is to say that the code using these methods would not need to change in order to compile, which is all "breaking changes" in the semantic versioning sense means. If there's any change to be made here, I would consider adding the "in order to compile" caveat. Would that solve your issue?

[jerrywrice]

Carol, Thanks for the prompt and thoughtful response. Yes, I agree that would be a concise way of handling this. Best regards, Jerry W. Rice, Chief Technology Officer <http://www.FABNexus.com> www.FABNexus.com 660 Arboleda Drive Los Altos, CA 94024 Email: ***@***.***> ***@***.*** Cell: 650-207-8235 From: Carol (Nichols || Goulding) ***@***.***> Sent: Monday, April 15, 2024 7:12 AM To: rust-lang/book ***@***.***> Cc: JWR_FABNexus ***@***.***>; Author ***@***.***> Subject: Re: [rust-lang/book] Example code and descriptive text are misleading (Issue #3886) The (above) descriptive text fails to mention that the specific return value of these trait methods must be identical to the original when invoked in the same order and with the same input argument values. This is essential for the internal (encapsulated) private implementation to be changed and have no measurable impact on existing client code, with the exception of total memory usage, CPU usage, and elapsed run time duration. The intent in this section is to say that the code using these methods would not need to change in order to compile, which is all "breaking changes" in the semantic versioning sense means. If there's any change to be made here, I would consider adding the "in order to compile" caveat. Would that solve your issue? — Reply to this email directly, view it on GitHub <#3886 (comment)> , or unsubscribe <https://github.com/notifications/unsubscribe-auth/AEHOLCXAVNAXXGTSHEQON5DY5PNZRAVCNFSM6AAAAABGGKBW22VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDANJWHE2TSOBSGI> . You are receiving this because you authored the thread. <https://github.com/notifications/beacon/AEHOLCVWJS3K4V6Z4RN5PH3Y5PNZRA5CNFSM6AAAAABGGKBW22WGG33NNVSW45C7OR4XAZNMJFZXG5LFINXW23LFNZ2KUY3PNVWWK3TUL5UWJTT2TK3U4.gif> Message ID: ***@***.*** ***@***.***> >