view-buffer v0.0.7

ViewBuffer

Using the magic of Proxies a ViewBuffer is a polymorphous buffer interface that allows each instance to encompass all the features of DataView, Buffer, and the Typed Arrays.

npm install view-buffer

API

Functions from Array.prototype: forEach, map, reduce, reduceRight, join, reverse

• get(index, view), set(index, value, view): functional version of indexed accessors also allowing a specific view. If the view has a different size index is in terms of that view.
• setView(view): functional way to set view property
• subarray(start, end): new ViewBuffer using the same underlying buffer where start and end are indexes based on the current view
• slice(start, end): like subarray but it's always based on bytes
• write(value, start, length, view): write a value with indexes and a length like a string, array, or buffer. Writes based on indexes relative to current view or the optionally provided one
• clone(): create's a new buffer and copies the current ones' data to it using the current view
• fill(v, start, end): fill with a value or zero, from start to end of 0 to length if none given. Relative to current view's indexes
• toString(encoding): convert to encoding or current string format or hex if current is numeric and joins to a string
• copy(target, targetOffset, start, end): copy data from current buffer to target. Target can be anything with indices and a length. Iterates based on current view.

views

• numeric - Int8, Uint8, Int16, Uint16, Int32, Uint32, Float32, Float64
• string - Ascii, Ucs2, Hex
• other - Binary (individual bits)

Usage

buffer creation

A ViewBuffer can be used to wrap an existing Buffer or TypedArray or it can be used to create new buffers instead of using ArrayBuffer or Buffer. The constructor can handle the same options as other buffers as well as a few others. The simplest usage is simply passing a size in bytes.

var ViewBuffer = require('view-buffer');

var b = ViewBuffer(10);
b[3] = 100;
{ view: 'Uint8',
  bytes: 10,
  length: 10,
  '0': 0,
  '1': 0,
  '2': 0,
  '3': 100,
  '4': 0,
  '5': 0,
  '6': 0,
  '7': 0,
  '8': 0,
  '9': 0 }

Changings Views

Views are important because most of the functions ViewBuffer has iterate based on the current view's length and indices, and values are formatted based on the current view.

b.view = 'uint32';
{ view: 'Uint32',
  bytes: 10,
  length: 2,
  '0': 1677721600,
  '1': 0 }

b.view = 'uint16';
{ view: 'Uint16',
  bytes: 10,
  length: 5,
  '0': 0,
  '1': 25600,
  '2': 0,
  '3': 0,
  '4': 0 }

Strings

When writing a string the default will be to use ascii and one byte per character. The view will automatically be changed internally to do the write and then changed back. Changing the view to a text format will cause the returned values to actually be strings.

b.write('viewbuffer')
//oops
{ view: 'Uint16',
  bytes: 10,
  length: 5,
  '0': 26998,
  '1': 30565,
  '2': 30050,
  '3': 26214,
  '4': 29285 }

b.view = 'ascii';
{ view: 'Ascii',
  bytes: 10,
  length: 10,
  '0': 'v',
  '1': 'i',
  '2': 'e',
  '3': 'w',
  '4': 'b',
  '5': 'u',
  '6': 'f',
  '7': 'f',
  '8': 'e',
  '9': 'r' }

The magic of the ViewBuffer is that it allows for seamlessly abstracting away the underlying data sizes and offsets and types. Writing from a ascii view to a ucs2 view is simple.

var ucs2 = ViewBuffer('ucs2', 20);
b.copy(ucs2);
{ view: 'Ucs2',
  bytes: 20,
  length: 10,
  '0': 'v',
  '1': 'i',
  '2': 'e',
  '3': 'w',
  '4': 'b',
  '5': 'u',
  '6': 'f',
  '7': 'f',
  '8': 'e',
  '9': 'r' }

ucs2.view = 'ascii';
{ view: 'Ascii',
  bytes: 20,
  length: 20,
  '0': 'v',
  '1': '\u0000',
  '2': 'i',
  '3': '\u0000',
  '4': 'e',
  '5': '\u0000',
  '6': 'w',
  '7': '\u0000',
  '8': 'b',
  '9': '\u0000',
  '10': 'u',
  '11': '\u0000',
  '12': 'f',
  '13': '\u0000',
  '14': 'f',
  '15': '\u0000',
  '16': 'e',
  '17': '\u0000',
  '18': 'r',
  '19': '\u0000' }