Re: [whatwg/encoding] Rename Encoding's "streams" to "I/O queues" (#215)

@annevk commented on this pull request.

Apologies for the slow follow-up here.

>  
-<p>When one or more <a>tokens</a> are
-<dfn id=concept-stream-push for=stream>pushed</dfn> to a <a for=/>stream</a>,
-those tokens must be inserted, in given order, after the last token in the stream.
+ <li><p>Let <var>prefix</var> be an empty list.
+
+ <li>
+  <p><a for=list>For each</a> <var>n</var> in <a>the range</a> 1 to <var>number</var>, inclusive:
+
+  <ol>
+   <li><p>If <var>ioQueue</var>[<var>n</var>] is <a>end-of-queue</a>, <a>break</a>. Otherwise,

Let's make this two steps?

> -those tokens must be inserted, in given order, after the last token in the stream.
+ <li><p>Let <var>prefix</var> be an empty list.
+
+ <li>
+  <p><a for=list>For each</a> <var>n</var> in <a>the range</a> 1 to <var>number</var>, inclusive:
+
+  <ol>
+   <li><p>If <var>ioQueue</var>[<var>n</var>] is <a>end-of-queue</a>, <a>break</a>. Otherwise,
+   <a for=list>append</a> <var>ioQueue</var>[<var>n</var>] to <var>prefix</var>.
+  </ol>
+ </li>
+
+ <li><p>Return <var>prefix</var>.
+</ol>
+
+<p>To <dfn id=concept-stream-push for="I/O queue" export>push</dfn> one

s/one/an/

> +   <li><p>If <var>ioQueue</var>[<var>n</var>] is <a>end-of-queue</a>, <a>break</a>. Otherwise,
+   <a for=list>append</a> <var>ioQueue</var>[<var>n</var>] to <var>prefix</var>.
+  </ol>
+ </li>
+
+ <li><p>Return <var>prefix</var>.
+</ol>
+
+<p>To <dfn id=concept-stream-push for="I/O queue" export>push</dfn> one
+<a for=list>item</a> <var>item</var> to an <a for=/>I/O queue</a> <var>ioQueue</var>, run
+these steps:
+
+<ol>
+ <li><p>If the last <a for=list>item</a> in <var>ioQueue</var> is <a>end-of-queue</a>,
+ then <a for=list>insert</a> <var>item</var> before the last <a for=list>item</a> in the
+ queue.

s/the queue/_ioQueue_/

> + <li><p>Return <var>prefix</var>.
+</ol>
+
+<p>To <dfn id=concept-stream-push for="I/O queue" export>push</dfn> one
+<a for=list>item</a> <var>item</var> to an <a for=/>I/O queue</a> <var>ioQueue</var>, run
+these steps:
+
+<ol>
+ <li><p>If the last <a for=list>item</a> in <var>ioQueue</var> is <a>end-of-queue</a>,
+ then <a for=list>insert</a> <var>item</var> before the last <a for=list>item</a> in the
+ queue.
+
+ <li><p>Otherwise, <a for=list>append</a> <var>item</var> to <var>ioQueue</var>.
+</ol>
+
+<p>To push a sequence of items is to push each item in the sequence, in the

We should probably use equivalent wording to reading here.

> + <li><p>If the last <a for=list>item</a> in <var>ioQueue</var> is <a>end-of-queue</a>,
+ then <a for=list>insert</a> <var>item</var> before the last <a for=list>item</a> in the
+ queue.
+
+ <li><p>Otherwise, <a for=list>append</a> <var>item</var> to <var>ioQueue</var>.
+</ol>
+
+<p>To push a sequence of items is to push each item in the sequence, in the
+given order.
+
+<p>To <dfn id=concept-stream-prepend for="I/O queue">prepend</dfn> one
+<a for=list>item</a> to an <a for=/>I/O queue</a>, perform the normal <a for=/>list</a>
+<a for=list>prepend</a> operation. To prepend a sequence of items, insert those
+items, in the given order, before the first item in the queue.
+
+<p class=example id=example-items>Inserting the sequence of scalar value items

Let's not change the ID here.

>  
 <ol>
- <li><p>Wait until <var>stream</var> has three bytes available or the <a>end-of-stream</a> has been
- reached, whichever comes first.
+ <li><p>Let <var>BOM</var> be the result of <a for="I/O queue">reading</a> 3 bytes from
+ <var>ioQueue</var>, converted to a byte sequence.

xref convert?

> +
+<p>To <dfn id=concept-stream-read for="I/O queue" export>read</dfn> an
+<a for=list>item</a> from an <a for=/>I/O queue</a> <var>ioQueue</var>, run these steps:
+
+<ol>
+ <li><p>If <var>ioQueue</var> is <a for=list>empty</a>, then wait until its
+ <a for=list>size</a> is at least 1.
+
+ <li><p>If the first item in <var>ioQueue</var> is <a>end-of-queue</a>, then
+ return <a>end-of-queue</a>.
+
+ <li><p>Otherwise, <a for=list>remove</a> the first item in <var>ioQueue</var>
+ and return it.
+</ol>
+
+<p>To read a number <var>number</var> of <a for=list>items</a> from <var>ioQueue</var>,

Thinking about this some more maybe overloading is the way to go. In that case we should xref "read" here and leave it at that I think. (I tried thinking of some alternative ways of doing this including "read"/"read multiple" (looks awkward) or "read one or more" (but then return type is annoying), and I can't really figure it out.

Perhaps @domenic has thoughts on this.

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/whatwg/encoding/pull/215#pullrequestreview-473226071