Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Rename Encoding's "streams" to "I/O queues" #215

Merged
merged 27 commits into from Sep 8, 2020
Merged

Rename Encoding's "streams" to "I/O queues" #215

Changes from 1 commit
Commits
Show all changes
27 commits
Select commit Hold shift + click to select a range
cbeb639
Rename Encoding's "streams" to "token queues"
May 28, 2020
bb9b17b
Export token queue and its algorithms.
May 28, 2020
a53fcbd
Don't export prepend.
Jun 4, 2020
660bd8e
Adds implicit conversions between token queues and strings/byte seque…
Jun 4, 2020
f93f483
Merge remote-tracking branch 'upstream/master' into token-queues
Jun 21, 2020
5367e9b
Fixing typos in the conversion algorithms before refactoring
Jul 15, 2020
1114d02
Renaming token queues to I/O queues and making them a subtype of list
Jul 15, 2020
0314d3e
Add the blocking behavior and the special handling of EOF
Jul 16, 2020
04c5e8f
Clarify that streaming I/O queues should be used in parallel
Jul 16, 2020
c62d26c
Remove link defaults for list and ReadableStream.
Jul 16, 2020
68f4d9d
Rename EOF to end-of-queue.
Jul 16, 2020
2bff546
Use create, convert and so on on the API section.
Jul 16, 2020
2d5354d
Fix trailing whitespace.
Jul 16, 2020
f55ce2c
Remove link defaults for item
Jul 16, 2020
5fba611
Add a peek operation.
Jul 16, 2020
189f580
Reduce the conversions to a short paragraph.
Jul 20, 2020
9dab74d
Incorporate a suggestion from code review
Jul 22, 2020
d23557c
Using the list shorthand rather than a "create" operation.
Jul 22, 2020
eca3dbe
Incorporate suggestions from code review.
Aug 26, 2020
a65d680
Don't change the id of the insertion example
Aug 26, 2020
f4dff40
formatting nits
annevk Aug 31, 2020
a4916e6
Change push and prepend to avoid end-of-queue items on the wrong places.
Sep 2, 2020
88ac022
Refactor BOM sniff in terms of the peek operation.
Sep 2, 2020
852adcb
Update the language for reading multiple bytes in UTF-8 decode
Sep 3, 2020
4096269
Add an output optional parameter to the decode/encode hooks.
Sep 3, 2020
faae433
Push end-of-queue on the process operation
Sep 7, 2020
fa4a2cf
minor nits
annevk Sep 8, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
108 changes: 21 additions & 87 deletions encoding.bs
View file
Open in desktop
Expand Up @@ -96,8 +96,10 @@ values</a>). <dfn id="end-of-stream" export>End-of-queue</dfn> is a special
<a for=list>item</a> that can be present in <a for=/>I/O queues</a> of any type, and that
signifies no more <a for=list>items</a> are in the queue.

<p>To <dfn for="I/O queue" export>create</dfn> an <a for=/>I/O queue</a>, return a new
<a for=/>I/O queue</a> containing an <a>end-of-queue</a> item.
<p>To <dfn for="I/O queue" export>create</dfn> an <a for=/>I/O queue</a>, optionally initialized
with a list <var>contents</var>, return a new <a for=/>I/O queue</a> containing the
<a for=list>items</a> of <var>contents</var> in order, if it is given, followed by an
<a>end-of-queue</a> item.
andreubotella marked this conversation as resolved.
Show resolved Hide resolved

<div class=note>
<p>There are two ways to use an <a for=/>I/O queue</a>: in immediate mode, to
Expand Down Expand Up @@ -199,92 +201,24 @@ items, in the given order, before the first item in the queue.
results in an I/O queue "<code>&amp;#128169; hello world</code>". The next item
to be read would be <code>&amp;</code>. <!-- 💩 -->

<p>To <dfn for="from I/O queue">convert</dfn> an <a for=/>I/O queue</a> <var>ioQueue</var> into a
<a for=/>list</a>, <a>string</a> or <a>byte sequence</a>, return the result of
<a for="I/O queue">reading</a> an indefinite number of <a for=list>items</a> from
<var>ioQueue</var>. To <dfn for="to I/O queue">convert</dfn> a <a for=/>list</a>, <a>string</a> or
<a>byte sequence</a> <var>input</var> into an <a for=/>I/O queue</a>, return the result of
<a for="I/O queue">creating</a> an <a for=/>I/O queue</a> initialized with <var>input</var>.

<p class=XXX>The Infra standard is expected to define some infrastructure around type conversions.
See <a href="https://github.com/whatwg/infra/issues/319">whatwg/infra issue #319</a>. [[INFRA]]

<p class=note><a for=/>I/O queues</a> are defined as <a for=/>lists</a>, not
<a spec=infra>queues</a>, because they feature a <a for="I/O queue">prepend</a>
operation. However, this prepend operation is an internal detail of the
algorithms in this specification, and is not to be used by other standards.
Implementations are free to find alternative ways to implement such algorithms,
as detailed in [[#implementation-considerations]].

<hr>

<p><a for=/>I/O queues</a> can be implicitly converted into and from
<a>strings</a> and <a>byte sequences</a> using the following operations.

<p>To <dfn for="byte sequence to I/O queue" export>convert</dfn> a <a>byte
sequence</a> <var>byteSeq</var> into an <a for=/>I/O queue</a> of bytes, run
these steps:

<ol>
<li><p>Let <var>output</var> be the result of <a for="I/O queue">creating</a> an
<a for=/>I/O queue</a> of bytes.

<li><p>For each byte <var>byte</var> in <var>byteSeq</var>,
<a for="I/O queue">push</a> <var>byte</var> into <var>output</var>.

<li><p>Return <var>output</var>.
</ol>

<p>To <dfn for="string to I/O queue" export>convert</dfn> a <a>string</a>
<var>string</var> into an <a for=/>I/O queue</a> of scalar values, run these
steps:

<ol>
<li><p><a for="string">Convert</a> <var>string</var> into a <a>scalar value
string</a>.

<li><p>Let <var>output</var> be the result of <a for="I/O queue">creating</a> an
<a for=/>I/O queue</a> of scalar values.

<li><p>For each scalar value <var>scalarValue</var> in <var>string</var>,
<a for="I/O queue">push</a> <var>scalarValue</var> into <var>output</var>.

<li><p>Return <var>output</var>.
</ol>

<p>To <dfn for="I/O queue to byte sequence" export>convert</dfn> an
<a for=/>I/O queue</a> of bytes <var>ioQueue</var> into a <a>byte sequence</a>,
run these steps:

<ol>
<li><p>Let <var>output</var> be an empty <a>byte sequence</a>.

<li>
<p>While true:

<ol>
<li><p>Let <var>item</var> be the result of <a for="I/O queue">reading</a>
from <var>ioQueue</var>.

<li><p>If <var>item</var> is <a>end-of-queue</a>, return <var>output</var>.

<li><p>Append <var>item</var> to <var>output</var>.
</ol>
</ol>

<p>To <dfn for="I/O queue to string" export>convert</dfn> an <a for=/>I/O
queue</a> of scalar values <var>ioQueue</var> into a <a>string</a>, run these
steps:

<ol>
<li><p>Let <var>output</var> be an empty <a>string</a>.

<li>
<p>While true:

<ol>
<li><p>Let <var>item</var> be the result of <a for="I/O queue">reading</a>
from <var>ioQueue</var>.

<li><p>If <var>item</var> is <a>end-of-queue</a>, return <var>output</var>.

<li><p>Append <var>item</var> to <var>output</var>.
</ol>
</ol>

<p class=note>The conversion from <a for=/>I/O queues</a> into <a>strings</a>
and <a>byte sequences</a> empties the <a for=/>I/O queue</a>. Therefore, it is
to be used only when there are no other references to the queue.

<h2 id=encodings>Encodings</h2>

Expand Down Expand Up @@ -1560,8 +1494,8 @@ constructor steps are to do nothing.
<p>The <dfn method for=TextEncoder><code>encode(<var>input</var>)</code></dfn> method steps are:

<ol>
<li><p><a for="string to I/O queue">Convert</a> <var>input</var> to an <a for=/>I/O queue</a> of
scalar values.
<li><p><a for="to I/O queue">Convert</a> <var>input</var> to an <a for=/>I/O queue</a> of scalar
values.

<li><p>Let <var>output</var> be the result of <a for="I/O queue">creating</a> an
<a for=/>I/O queue</a> of bytes.
Expand All @@ -1581,7 +1515,7 @@ constructor steps are to do nothing.

<p class=note>The <a>UTF-8 encoder</a> cannot return <a>error</a>.

<li><p>If <var>result</var> is <a>finished</a>, <a for="I/O queue to byte sequence">convert</a>
<li><p>If <var>result</var> is <a>finished</a>, <a for="from I/O queue">convert</a>
<var>output</var> into a byte sequence, and then return a {{Uint8Array}} object wrapping an
{{ArrayBuffer}} containing <var>output</var>.
<!-- XXX https://www.w3.org/Bugs/Public/show_bug.cgi?id=26966 -->
Expand All @@ -1608,8 +1542,8 @@ method steps are:
<p class=note>The <a>handler</a> algorithm invoked below requires this argument, but it is not
used by the <a>UTF-8 encoder</a>.

<li><p><a for="string to I/O queue">Convert</a> <var>source</var> to an <a for=/>I/O queue</a> of
scalar values.
<li><p><a for="to I/O queue">Convert</a> <var>source</var> to an <a for=/>I/O queue</a> of scalar
values.

<li>
<p>While true:
Expand Down Expand Up @@ -1969,7 +1903,7 @@ constructor steps are:
<var>chunk</var> to a {{DOMString}}. If this throws an exception, then return a promise rejected
with that exception.

<li><p><a for="string to I/O queue">Convert</a> <var>input</var> to an <a for=/>I/O queue</a> of
<li><p><a for="to I/O queue">Convert</a> <var>input</var> to an <a for=/>I/O queue</a> of
<a>code units</a>.

<p class=note>{{DOMString}}, as well as an <a for=/>I/O queue</a> of code units rather than scalar
Expand All @@ -1993,7 +1927,7 @@ constructor steps are:
<p>If <var>item</var> is <a>end-of-queue</a>, run these steps:

<ol>
<li><p><a for="I/O queue to byte sequence">Convert</a> <var>output</var> into a byte sequence.
<li><p><a for="from I/O queue">Convert</a> <var>output</var> into a byte sequence.

<li>
<p>If <var>output</var> is non-empty, run these steps:
Expand Down