Comment #0 by landergriffith+dlangbz — 2015-11-02T18:38:31Z
As a newcomer to D, I wanted to write a library with an output stream that std.stream.OutputStream would have been a good candidate for but in the docs saw that the stream module is deprecated. I went in to IRC to ask what the replacement is and was told to use ranges -- specifically an OutputRange.
On the documentation page for std.range (http://dlang.org/phobos/std_range.html) I searched for OutputRange and the *only* results are in the context of NullSink and tee. The tee part of the documentation actually hyperlinks OutputRange, so clicking that I'd expect it to take me somewhere that I can read more info about the OutputRange but it goes nowhere (link in question: http://dlang.org/phobos/std_range.html#OutputRange).
From the top of the page:
> Ranges generalize the concept of arrays, lists, or anything that involves sequential access. This abstraction enables the same set of algorithms (see std.algorithm) to be used with a vast variety of different concrete types. For example, a linear search algorithm such as std.algorithm.find works not just for arrays, but for linked-lists, input files, incoming network data, etc.
The last part of that mainly involves *input* data, not output data. Some of the methods described involve mutating or combining the arrays but I'm somewhat surprised the "put" method is not mentioned at least once on the page. Even referring to the source was more helpful than the docs (https://github.com/D-Programming-Language/phobos/blob/master/std/range/interfaces.d#L235 -- I was told in IRC that this isn't entirely accurate as I want the template method but it helped some).
I think that the documentation page for std.range is seriously lacking info about using an OutputRange and in general that streams are two-directional. Perhaps a documentation improvement could also be made to the std.stream module to describe the move to ranges instead as well.