Binary/F

STATUS: PROPOSAL

Implementations

[[Implementations/TeaJS|]]

• Draft 3
• Draft 1* Draft 2

This proposal, based on Binary/E and Binary/F/Wes, defines a single, mutable, fixed-length, numeric byte storage type.

Specification

The "common/buffer" module exports a "Buffer" type that meets the following criteria.

A Buffer is a mutable, fixed-length, representation of a C unsigned char (byte) array.

Constructor

1. A Buffer function must exist.
2. Calling and constructing a Buffer both return a new Buffer instance.
3. Buffers are instances of Buffer and Object.
4. The type of a Buffer is "object".
5. Any call or construction of Buffer that does not have a Number, Buffer, Array, or String as its first argument throws a TypeError.

Buffer(length Number, Number(fill_opt))

1. New Buffer of the given length, with the given fill number at all offsets.
2. The default filler is 0.

Buffer(source Buffer, Number(start_opt), Number(stop_opt), Boolean(copy_opt))

1. New Buffer that is either a copy or a view of the allocation as the given buffer, from "start" to "stop".
2. "start" is 0 if undefined or omitted.
3. "stop" is the other buffer's length if undefined or omitted.
4. "start" and "stop" may both be negative numbers, in which case they correspond to offsets counting from the length of the buffer.
5. "copy" is true if undefined or omitted
6. When true, "copy" indicates that the buffer must have its own copy of the allocation.
7. When false, "copy" indicates that the buffer must share its allocation with the given buffer.

Buffer(source Array, Number(start_opt), Number(stop_opt))

1. New Buffer that contains the respective values from the given array, from "start" to "stop".
2. "start" is 0 if undefined or omitted.
3. "stop" is the array's "length" if undefined or omitted.
4. The "length" of the new buffer is exactly the length from "start" to "stop".
5. "start" and "stop" may both be negative numbers, in which case they correspond to offsets counting from the length of the array.

Buffer(string String, String(charset))

1. Create a buffer from a string, the result being encoded with "charset".

Prototype Properties

toString() String

1. Returns a debug representation like "[Buffer 10]", where 10 is the length this Buffer.
2. This signature of "toString" applies if the "arguments.length" is 0.

toString(String(charset), Number(start_opt), Number(stop_opt)) String

1. Decodes this between "start" and "stop" according to the given character set and returns the String from the corresponding unicode points.
2. "start" is 0 if undefined or omitted.
3. "stop" is the length of this buffer if undefined or omitted.
4. "start" and "stop" may be negative numbers, in which case they correspond to an offset counting from this buffer's length.
5. Must throw a RangeError if the buffer is malformed, undefined, out of range, or incomplete for the given character set.
6. "charset" must be one of "UTF-8", "UTF-16", "ISO-8859-1", "ASCII", "BINARY". Any other "charset" throws a RangeError.
   1. "ASCII" must properly transcode all 7-bit ASCII code points..
   2. Note: "ASCII" is not required to properly transcode any code points outside its seven bit domain. "ASCII" may be an alias of "UTF-8" or "ISO-8859-1". For highest performance, "ASCII" may opt to ignore bits outside its domain.
   3. "BINARY" must properly transcode all 8-bit ISO-8859-1 code points.
   4. Note: "BINARY" is not required to properly transcode any code points outside its eight bit domain. "BINARY" may be an alias of "ISO-8859-1". For highest performance, "BINARY" may opt to ignore bits outside its domain.
7. This signature of "toString" applies if the "arguments.length" is not 0.

toSource() String

1. Returns "require("binary").Buffer([])" for a null buffer or "require("binary").Buffer([0, 1, 2])" for a buffer of length 3 with bytes 0, 1, and 2.

range(Number(start_opt), Number(stop_opt)) Buffer

1. Returns a Buffer that views the given range of the same allocated byte buffer.
2. "start" is 0 if undefined or omitted.
3. "stop" is the length of this buffer if undefined or omitted.
4. "start" and "stop" may be negative numbers, in which case they correspond to an offset counting from this buffer's length.
5. The length of "range" is 2.

slice(Number(start_opt), Number(stop_opt)) Buffer

1. Returns a Buffer with a new internal allocation, containing a copy of this buffer from "start" to "stop" offsets.
2. "start" is 0 if undefined or omitted.
3. "stop" is this buffer's length if undefined or omitted.
4. "start" and "stop" may be negative numbers, in which case they correspond to an offset counting from this buffer's length.

copy(target, Number(targetStart_opt), Number(start_opt)), Number(stop_opt)) Buffer

1. Copies the Number values of each byte from this between "start" and "stop" to a "target" Buffer or Array at the "targetStart" offset.
2. "stop" is the length of this if undefined or omitted.
3. "targetStart", "start", and "stop" are internally coerced to Numbers with the Number constructor.
4. "targetStart" may be negative, in which case it corresponds to an offset counting from the length of the target.
5. "start" and "stop" may be negative, in which case they correspond to an offset counting from this buffer's length.
6. Throws a TypeError if the target is not a Buffer or Array.
7. Returns this.

copyFrom(source, Number(sourceStart_opt), Number(start_opt), Number(stop_opt)) Buffer

1. Copies the Number values of each byte from a given Buffer or Array into this from "start" to "stop" from the given "sourceStart" offset.
2. "start" is 0 if undefined or omitted.
3. "stop" is the length of this buffer if undefined or omitted.
4. "sourceStart" may be negative, in which case it corresponds to an offset counting from this buffer's length.
5. "start" and "stop" may be negative, in which case they correspond to offsets counting from the length of the source.
6. "sourceStart", "start", and "stop" are internally coerced to Numbers with the Number constructor.
7. If the source is an Array, all values of that array are coerced to Numbers and masked with 0xFF.
8. Throws a TypeError if the target is not a Buffer or Array.
9. Returns this.

read(String(charset), state Object, Number(start_opt), Number(stop_opt)) String

1. Decodes as many complete and well formed character codes as possible between "start" and "stop" to a String from the given character set.
2. "charset" must be one of "UTF-8", "UTF-16", "ISO-8859-1", "ASCII", "BINARY". Any other "charset" throws a RangeError.
3. Assumes that the given byte range begins at the beginning of a code point.
4. Stops decoding after the last complete code point byte sequence.
5. Returns the decoded String.
6. Sets the "bytes" property of the "state" object to the number of bytes transcoded.
7. Sets the "characters" property of the "state" object to the number of characters transcoded.
8. Sets the "error" property of the "state" object to "malformed" if reading stops at the beginning of a malformed byte sequence.
9. The actual stop offset must be either equal to "stop" or at the beginning of the first incomplete code point byte sequence.

write(source String, String(charset), state Object, Number(start_opt), Number(stop_opt)) Number

1. Encodes as much as possible of a String in a given character set into this buffer from "source" to "stop", using the source string, and returns the actual stop index of the source string.
2. "charset" must be one of "UTF-8", "UTF-16", "ISO-8859-1", "ASCII", "BINARY". Any other "charset" throws a RangeError.
3. "start" is 0 if undefined or omitted and measures bytes.
4. "stop" is this buffer's length if undefined or omitted, measured in bytes.
5. "start" and "stop" may be negative, in which case they correspond to offsets counting from the length of the source.
6. Sets the "characters" property of the "state" object to the number of characters encoded.
7. Sets the "bytes" property of the "state" object to the number of bytes written.
8. Returns the number of bytes written.

fill(Number(value), Number(start_opt), Number(stop_opt)) Buffer

1. Fills all of this buffer's bytes with the given value as a Number from the "start" offset to the "stop" offset.
2. "start" is 0 if undefined or omitted.
3. "stop" is the length of this buffer if undefined or omitted.
4. "start" and "stop" may be negative, in which case they correspond to offsets counting from the length of this buffer.
5. "value" is 0 if undefined or omitted.
6. "value" is coerced to Number and masked with 0xFF.
7. Returns this.

Content

1. an alias of Number, indicating that Number is the type of what [[Get]] returns.

Internal Properties

[[Get]] Number

1. Returns the Number value of a the byte at the given offset.

[[Put]] Number

1. Sets the byte value at the given offset.
2. Throws a RangeError if the index is beyond the current bounds of the buffer.
3. Implicitly coerces the value to a Number and masks it with 0xFF.

Instance Properties

length

1. The length in bytes.
2. Not [[Configurable]], not [[Enumerable]]. [[ReadOnly]].

Notation

1. The notation functionName(argument Type) indicates that the given behavior only occurs when the argument pattern matches the given "Type".
2. If the functionName(argument Type) is mentioned for an argument and none of the given forms match the types of the argument, the function must throw a TypeError.
3. The notation functionName(argument_opt) indicates that the argument may be undefined or omitted.
4. The distinction between an omitted or undefined argument is only detectable by checking the arguments.length
5. The notation function(Type(argument)) implies that any type matches the argument and that it must be internally coerced to the "Type".
6. Extra arguments are ignored.

General Requirements

1. All of the properties specified on prototypes are not [[Enumerable]] on instances.
2. All operations that copy values to a byte in the byte buffer implicitly coerce the value to a Number and bit mask such values with 0xFF.

Relevant Discussions

• ByteArray and ByteString proposal
• ByteArray: byteAt method
• Binary/B Extension Proposals and Implementation Notes
• Binary D ready for review
• Binary/D Draft 2