ServerJS/Binary/C: Difference between revisions

ServerJS/Binary/C (view source)

Revision as of 17:31, 4 August 2009

599 bytes removed , 4 August 2009

→‎Buffer

Dantman

40

edits

@@ Line 142: / Line 142: @@
 === Buffer ===
-Buffer is a '''''generic''''' buffer which may act on either binary or textual data using the same api (Two purposes in one class is derived from the [http://draft.monkeyscript.org/api/_std/Buffer.html MonkeyScript Buffer]; the .text = bool; idiom came from the .text property in MonkeyScript's Stream class, the idea is to make it as easy as possible to create a buffer of the same type without needing to use a ternary, this point is up for discussion on the list).
+Buffer is accompanied by three classes; Buffer, StringBuffer, and BlobBuffer. Buffer itself is the generic class, making calls to it will normally create either a StringBuffer or a BlobBuffer. Both StringBuffer and BlobBuffer should inherit from Buffer and return true in a <code>buf instanceof Buffer</code>.
-(Note: Whether to allow type conversion of a buffer with no content or not could be discussed) A Buffer may initially be created as untyped without any length, or may be given a type and/or length when created. A Buffer which has a type assigned to it (binary or text) and has content within it (length > 0) may not be converted to another type and should throw an error if attempted.
+Buffers may implement smart resizing in the background (ie: padding arrays or whatnot to sizes to avoid reallocating on each insert) but information on this is not available to the JavaScript API.
-A buffer gains a type when .text is assigned a true or false value, or it inherits the data type of the first piece of data added to the buffer. After it is typed a buffer should throw an error if someone attempts to insert a different type of data into the buffer (If you want to insert a string into a binary buffer, you should convert it to a blob first yourself; automatic type conversion in these cases would cause gotchas).
+Buffers will only take their own data type as arguments. If you try to insert a String into a BlobBuffer or a Blob into a StringBuffer a TypeError will be thrown.
-Buffers may implement smart resizing in the background (ie: padding arrays or whatnot to sizes to avoid reallocating on each insert) but information on this is not available to the JavaScript API.
 ;new Buffer();
-:Construct an empty buffer with no set type
+:No-op... This simply creates an instanceof of Buffer. On it's own the Buffer class does nothing so this simply exists so that prototypes may be made that inherit from Buffer.
-;new Buffer([String or Blob], [len]);
+;new StringBuffer();
-:Construct a new buffer.
+:Creates a new empty text buffer.
-:The constructor may accept the <code>String</code> function or the <code>Blob</code> function as a hint of what type to set on the buffer.
+;new BlobBuffer();
-:The constructor also may accept a length argument to set the default length of the buffer.
+:Creates a new empty binary buffer.
-;new Buffer(sequence);
+;new StringBuffer(len);
-:Construct a buffer based on a string or a blob. The Buffer will be the same length as the sequence, inherit the same type, and start off with the same content as the sequence.
+:Creates a new text buffer of <code>len</code> size.
+;new BlobBuffer(len);
+:Creates a new binary buffer of <code>len</code> size.
+;new Buffer('''String''');
+:Creates a new empty StringBuffer.
+;new Buffer('''Blob''');
+:Creates a new empty BlobBuffer.
+;new Buffer('''String''', len);
+:Creates a new StringBuffer of <code>len</code> size.
+;new Buffer('''Blob''', len);
+:Creates a new BlobBuffer of <code>len</code> size.
+;new Buffer(string);
+:Creates a new StringBuffer with the same size and contents as the string.
+;new Buffer(blob);
+:Creates a new BlobBuffer with the same size and contents as the blob.
 ;buf.length;
@@ Line 165: / Line 177: @@
 ;buf.text;
-;buf.text = bool;
+:(May be removed in favor of a better idiom)
-:Get or set the type of the buffer. Binary buffers return false, text buffers return true, buffers which have not been assigned a type yet return undefined.
+:Get the type of the buffer. Binary buffers return false, text buffers return true.
-:This will throw a TypeError if you try to set a type on a buffer that already has a type and has a length greater than 0.
 ;buf[index];
@@ Line 210: / Line 221: @@
 ;buf.valueOf();
 :Return the non-mutable sequence for the buffer.
-:* In binary mode this returns a Blob which matches the contents of the buffer.
+:* In a BlobBuffer this returns a Blob which matches the contents of the buffer.
-:* In text mode this returns a String which matches the contents of the buffer.
+:* In a StringBuffer this returns a String which matches the contents of the buffer.
 === String extensions ===