ServerJS/Binary/B

From MozillaWiki
< ServerJS‎ | Binary
Revision as of 06:14, 11 April 2009 by KrisKowal (talk | contribs) (Updated according to feedback from the list.)
Jump to navigation Jump to search

All platforms must support two types for interacting with binary data: ByteArray and ByteString. The ByteArray type resembles the interface of Array in that it is mutable, extensible, and indexing will return number values for the byte in the given position, zero by default, or undefined if the index is out of bounds. The ByteString type resembles the interface of String in that it is immutable and indexing returns a ByteString of length 1. These types are exported by the 'binary' top-level module and both types are subtypes of Binary, which is not instantiable but exists only for the convenience of referring to both ByteArray and ByteString. (The idea of using these particular two types and their respective names originated with Jason Orendorff in the Binary API Brouhaha discussion.)

Philosophy

This proposal is not an object oriented variation on pack and unpack with notions of inherent endianness, read/write head position, or intrinsic codec information. The objects described in this proposal are merely for the storage and direct manipulation of strings and arrays of byte data. Some object oriented conveniences are made, but the exercise of implementing pack, unpack, or an object-oriented analog thereof are left as an exercise for a future proposal of a more abstract type or a 'struct' module (as mentioned by Ionut Gabriel Stan on the list). This goes against most mentioned prior art.

This proposal also does not provide named member functions for any particular subset of the possible codecs or digests that might operate on a byte string or array. Instead, convenience member functions are provided for interfacing with any named codec or digest module, assuming that the given module exports the specified interface. (As supported originally by Robert Schultz, Davey Waterson, Ross Boucher, and tacitly myself, Kris Kowal, on the First proposition thread on the mailing list). This proposal does not address the need for stream objects to support pipelined codecs and hash digests (mentioned by Tom Robinson and Robert Schultz in the same conversation).

This proposal also reflects both group sentiment and a pragmatic point about properties. This isn't a decree that properties like "length" should be consistently used throughout the ServerJS APIs. However, given that all platforms support properties at the native level (to host String and Array objects) and that byte strings and arrays will require support at the native level, pursuing client-side interoperability is beyond the scope of this proposal and therefore properties have been specified. (See comments by Kris Zyp about the implementability of properties in all platforms, comments by Davey Waterson from Aptana about the counter-productivity of attempting to support this API in browsers, and support properties over accessor and mutator functions by Ionut Gabriel Stand and Cameron McCormack on the mailing list).

The byte types provide functions for encoding, decoding, and transcoding, but they are all shallow interfaces that defer to a codec manager module, and may in turn use a system level codec or use a pair of pure JavaScript modules to transcode through an array or stream of canonical Unicode code points.

ByteString

A ByteString is an immutable, fixed-width representation of a C unsigned char (byte) array. ByteString supports the String API, and indexing returns a byte substring of length 1.

The ByteString constructor accepts:

  • ByteString()
  • ByteString(byteString)
  • ByteString(byteArray)
  • ByteString(array)
  • ByteString(string, codec)

ByteString instances support the following:

  • immutable length property
  • toByteArray() -> byte for byte
  • toByteArray(sourceCodec, targetCodec) -> transcoded
  • toByteString() -> copy
  • toByteString(sourceCodec, targetCodec) -> transcoded
  • toArray() -> byte value array
  • toArray(codec) -> decoded code point array
  • toString() -> a representation like "[ByteString 10]"
  • toString(codec) -> decoded
  • indexOf(byte:Number|ByteString|ByteArray)
  • indexOf(byte:Number|ByteString|ByteArray, start:Number)
  • indexOf(byte:Number|ByteString|ByteArray, start:Number, stop:Number)
  • lastIndexOf(byte:Number|ByteString|ByteArray)
  • lastIndexOf(byte:Number|ByteString|ByteArray, start:Number)
  • lastIndexOf(byte:Number|ByteString|ByteArray, start:Number, stop:Number)
  • byteAt(offset) -> Number (same as charCodeAt)
  • charCodeAt(offset:Number) -> Number
  • charAt(offset:Number) -> byte:ByteString
  • split(delimiter:Number|ByteString) -> Array of ByteStrings
  • split(delimiter:Number|ByteString, count:Number) -> Array of ByteStrings
  • slice()
  • slice(begin)
  • slice(begin, end)
  • substr(start)
  • substr(start, length)
  • substring(first)
  • substring(first, last)
  • The + operator returning new ByteStrings
  • The immutable [] operator returning ByteStrings
  • toSource() which would return "ByteString([])" for a null byte string
  • valueOf()

ByteString does not implement toUpperCase() or toLowerCase() since they are not meaningful without the context of a codec.


ByteArray

A ByteArray is a mutable, flexible representation of a C unsigned char (byte) array.

The ByteArray constructor has the following forms:

  • ByteArray()
  • ByteArray(length)
  • ByteArray(byteArray)
  • ByteArray(byteString)
  • ByteArray(array)
  • ByteString(string, codec)

Unlike the Array, the ByteArray is not variadic so that its initial length constructor is not ambiguous with its copy constructor.

All values within the length of the array are numbers stored as bytes that default to 0 if they have not been explicitly set. Assigning beyond the bounds of a ByteArray implicitly grows the array, just like an Array. Retrieving a value from an index that is out of the bounds of the Array, lower than 0 or at or beyond the length, the returned value is "undefined". Assigning an index with a value that is larger than fits in a byte will be implicitly and silently masked against 0xFF. Negative numbers will be bit extended to a byte in two's complement form and likewise masked.

ByteArray instances support the following:

  • mutable length property
    • extending a byte array fills the new entries with 0.
  • toArray() -> an array of the byte values
  • toArray(codec) -> an array of the code points, decoded
  • toString() -> a string representation like "[ByteArray 10]"
  • toString(codec) - decoded
  • toByteArray() -> just a copy
  • toByteArray(sourceCodec, targetCodec) -> transcoded
  • toByteString() -> byte for byte
  • toByteString(sourceCodec, targetCodec) -> transcoded
  • concat(other:ByteArray|ByteString|Array)
  • join(delimiter:ByteArray|ByteString|Array)
  • pop() -> byte:Number
  • push(...variadic Numbers...)-> count:Number
  • shift() -> byte:Number
  • unshift(...variadic Numbers...) -> count:Number
  • reverse() in place reversal
  • slice()
  • sort()
  • splice()
  • toSource() returns a string like "ByteArray([])" for a null byte-array.
  • valueOf()
  • The + operator returning new ByteArrays
  • The mutable [] operator for numbers

String

The String prototype will be extended with the following members:

  • toByteArray(codec)
  • toByteString(codec)
  • charCodes() -> Array of charcode:Number

Array

The Array prototype will be extended with the following members:

  • toByteArray(codec)
  • toByteString(codec)

General Requirements

None of the specified prototypes or augmentations to existing prototypes are enumerable.

Codec strings are as defined by IANA http://www.iana.org/assignments/character-sets.

Retrieved from "https://wiki.mozilla.org/index.php?title=ServerJS/Binary/B&oldid=139557"