-----------------------------------------------------------
David Abrahams * Boost Consulting
dave@boost-consulting.com * http://www.boost-consulting.com
----- Original Message -----
From: "Beman Dawes"
At 04:46 PM 7/25/2002, David Abrahams wrote:
However, enough people have had problems approaching this library that I thought it would be useful to ask about what would make a gentle introductory example. Beman recently sent me the enclosed, but it seems to define such an oddball toy iterator that I'm not sure it would be a very good motivating example.
ia_experiment.cpp is definitely oddball and definitely a toy. It was written to help me understand why I was getting compile errors from a real adaptor.
Someone else can probably come up with an introductory example which is less oddball.
But I'd like to defend the general principle of "toy" introductory examples.
When someone knows nothing about a topic, a toy example is the best introduction. It is "known good", and can be used to verify that compilations using the library work as expected. It can be modified to see the effect of changes. Because it is a toy, it is totally non-threatening. It makes the reader feel superior, rather than like a dunce.
The "C Programming Language" and "C++ Programming Language" books both started with a little "hello, world" program, very much a toy. Although simple, it starts the ball rolling with something that works and is understandable almost every reader.
In the case of ia_experiment.cpp, it illustrates the relationship between the finished iterator, the Base class, and the Policies class with greater clarity IMO than documentation in any form other than C++ code.
Sure, I'm all for toys, as in "this doesn't really do everything I'd want from a real example, but it shows me how the system works". The problem I have with ia_experiment.cpp is that my first reaction was "why would anyone want an "iterator" which does *that*?" The fact that it iterates over only two elements and stores its value internally is pretty weird. I think most people who have only seen the standard iterators would have a hard time imagining that this is also an iterator. Though technically, it is an iterator, it's so different in nature from most iterators that it seems like it would be completely foreign. What about a singly-linked-list iterator example? Wouldn't that show everything you're illustrating, but more transparently? -Dave