Zig: Proposal: Rename `InStream` and `OutStream`

[jayschwa]

Spun off from https://github.com/ziglang/zig/pull/4908#issuecomment-608181422

"In" and "out" are relative to a mental "reference point" in the programmer's head. In scenarios where the reference point is the application relative to some external thing, InStream and OutStream seem intuitive (e.g. standard I/O, files, etc.). However, I think the names are not intuitive for situations where the reference point might be different, like a data structure. For example, when using the LinearFifo (first in, first out) data structure, you write into the FIFO by using outStream, and read out of the FIFO by using inStream. In this case, I think the names will be confusing for the majority of programmers and the opposite of what they expect.

I propose renaming the streaming types to something like Reader and Writer. It decouples the names from any reference point in the programmer's head and should be intuitive in a wider variety of scenarios. They'll do exactly what they say on the tin (similar to the existing Allocator).

[marler8997]

Doesn't Reader and Writer have the same reference point issue as In and Out?

For example, when using the LinearFifo (first in, first out) data structure, you write into the FIFO by using outStream, and read out of the FIFO by using inStream.

From the FIFO's perspective

the FIFO is reading data into it with a "reader" and writing data out of it with a "writer"

From Outside the FIFO's perspective:

write data into a FIFO with a "writer" and read data out of it with a "reader"

I don't see how reader/writer helps disambiguate the reference point.

[pixelherodev]

Because it's about the usage pattern; you're entirely working outside the FIFO in most situations.

[marler8997]

Because it's about the usage pattern; you're entirely working outside the FIFO in most situations.

I don't understand. If you're saying that you always look at it from outside the FIFO's perspective, then how is reader/writer less ambiguous than in/out?

[SpexGuy]

IMO it's less ambiguous because there's a long-term target location and a short-term buffer parameter. Read and write are always defined relative to this relationship - Readers read data into the temporary buffer from the target and Writers write data from the passed buffer into something more permanent. This terminology is not ambiguous, in the same way that the terms "read into a register" and "write out from a register" are not ambiguous. You could argue that readers are writing to the temporary, but nobody really cares about the reference point of the temporary because it's temporary. In/Out can theoretically be defined in the same way but IMO it's harder to intuit those properties from the name.

[MasterQ32]

I fully agree with @SpexGuy.

[marler8997]

After thinking on this more and reading your replies, I think I see why reader and writer is less ambiguous than in and out. Both sets of terms have the same issue that you need to define whose perspective you're speaking from, however, in/out has an extra level of ambiguity, namely, which one is "sending data" and which is "receiving data".

For example, is data coming in from the FIFO, or is data coming out of the FIFO? Even though we've established that our perspective is outside the FIFO, we still don't know whether in or out is the operation that "receives data".

Thanks for people's perspective. I agree that reader and writer (or sender/receiver) removes ambiguity from the current in/out convention.

[SuperAuguste]

I definitely agree with this proposal! For example, when writing to an ArrayList, you write to an OutStream, which may confuses many people because when thinking of out, you think of data coming out, while in this case, data is going in.

[andrewrk]

I believe this is now implemented thanks to @marler8997. There is already an issue to track removing deprecated API here: #3811

@marler8997 let me know if there are any tasks left and I'll re-open.

[marler8997]

The API should be usable by applications now (already using it here: https://github.com/marler8997/ziget/commit/a47321b2629113c0b2e37e23847770c410c31566)

All that's left is to remove the old API along with any components in the zig repo that are still using the old API.