40
edits
ServerJS/Binary/C: Difference between revisions
no edit summary
No edit summary |
No edit summary |
||
| Line 10: | Line 10: | ||
This proposal is based off of API's drafted for MonkeyScript ([http://draft.monkeyscript.org/api/_std/Blob.html Blob] [http://draft.monkeyscript.org/api/_std/Buffer.html Buffer]). | This proposal is based off of API's drafted for MonkeyScript ([http://draft.monkeyscript.org/api/_std/Blob.html Blob] [http://draft.monkeyscript.org/api/_std/Buffer.html Buffer]). | ||
== Terms == | == Terms and reading notes == | ||
To avoid confusion and ambiguity these are the basic definitions of terms used | To avoid confusion and ambiguity these are the basic definitions of terms used | ||
within this document. | within this document. | ||
| Line 21: | Line 21: | ||
:A type of list which manages a list of items. These items are not related to one another in any way other than their inclusion in the list and do not need to be of the same type. | :A type of list which manages a list of items. These items are not related to one another in any way other than their inclusion in the list and do not need to be of the same type. | ||
:A key importance is an Array is a loose collection of items, these items do not have any sort of fixed unit to them. | :A key importance is an Array is a loose collection of items, these items do not have any sort of fixed unit to them. | ||
Where "as if by" is used in the spec the result is meant, the algorithm should not be affected by changes to the class' prototype. | |||
== Differences between a Sequence and an Array == | == Differences between a Sequence and an Array == | ||
| Line 86: | Line 88: | ||
;blob.valueAt(index); | ;blob.valueAt(index); | ||
::@showofhands (ashb suggests .byteAt could return Number (byte) instead of a single unit blob; .valueAt would still return blob so that abstract code still works) | ::@showofhands (ashb suggests .byteAt could return Number (byte) instead of a single unit blob; .valueAt would still return blob so that abstract code still works) | ||
:Extracts a single byte from the blob and returns a new blob object containing only it. Note that the blob[i] form is optional, implementations may chose to exclude support for it. This should be ideally be relevant to support for string[i], thus if the interpreter being used supports string[i] it is expected that an implementation should attempt to support it as well. | :Extracts a single byte from the blob and returns a new blob object containing only it. <del>Note that the blob[i] form is optional, implementations may chose to exclude support for it. This should be ideally be relevant to support for string[i], thus if the interpreter being used supports string[i] it is expected that an implementation should attempt to support it as well.</del> (Waiting on show of hands) | ||
;blob.byteCodeAt(index); | |||
;blob.codeAt(index); | |||
:Extracts a single byte from the blob and returns it as a unsigned integer (Number) such that the number will be in the range 0..255. | |||
;blob.indexOf(blob, offset=0); | ;blob.indexOf(blob, offset=0); | ||
| Line 105: | Line 111: | ||
;blob.toBlob([fromCharset, toCharset]); | ;blob.toBlob([fromCharset, toCharset]); | ||
:If passed with no argument returns the same blob. | :If passed with no argument returns the same blob. | ||
:If passed with two | :If passed with two charset arguments transcodes the data from one charset to the other and returns the data as a new blob. | ||
:Note that if a single argument is passed to this method it should throw a TypeError to prevent gotchas where someone runs .toBlob(charset) on a blob instead of a string where it is relevant. | :Note that if a single argument is passed to this method it should throw a TypeError to prevent gotchas where someone runs .toBlob(charset) on a blob instead of a string where it is relevant. | ||
| Line 115: | Line 121: | ||
;blob.toArray(); | ;blob.toArray(); | ||
:Returns an array containing the bytes as numbers. | :Returns an array containing the bytes as numbers as if by <code>[ blob.byteCodeAt(i) for ( i in blob ) ]</code>. | ||
;blob.toArray( | |||
:Returns an array containing the decoded Unicode code points. | ;blob.toArray(fromCharset); | ||
:Returns an array containing the decoded Unicode code points as if by <code>var str = blob.toString(fromCharset); [ str.charCodeAt(i) for ( i in str ) ]</code>. | |||
;blob.toSource(); | ;blob.toSource(); | ||
| Line 173: | Line 180: | ||
;buf.clear(start, length); | ;buf.clear(start, length); | ||
:Zero out a section of the buffer. Binary buffers have bytes replaced with 0 bytes and text buffers have characters replaced with '\0' (null characters). | |||
;buf.fill(start, length, seq); | |||
:Zero out a section of the buffer. Binary buffers have bytes replaced with 0 bytes and text buffers have characters replaced with '\0' (null characters). | :Zero out a section of the buffer. Binary buffers have bytes replaced with 0 bytes and text buffers have characters replaced with '\0' (null characters). | ||
| Line 212: | Line 222: | ||
:An alias for string.charAt(index); | :An alias for string.charAt(index); | ||
:The point of this prototype is so that (string or blob).valueAt(index); may be used independently of whether the sequence is a string or a blob. This will allow strings to maintain .charAt and blobs to maintain .byteAt without returning unintuitive results while still allowing a method of working abstractly without relying on things like (str or blob)[index] which may not be implemented in some engines. | :The point of this prototype is so that (string or blob).valueAt(index); may be used independently of whether the sequence is a string or a blob. This will allow strings to maintain .charAt and blobs to maintain .byteAt without returning unintuitive results while still allowing a method of working abstractly without relying on things like (str or blob)[index] which may not be implemented in some engines. | ||
;string.codeAt(index); | |||
:An alias for string.charCodeAt(index); | |||
:The point of this prototype is so that (string or blob).codeAt(index); may be used independently of whether the sequence is a string or a blob. This will allow strings to maintain .charCodeAt and blobs to maintain .byteCodeAt without returning unintuitive results. | |||
== General requirements == | == General requirements == | ||