Issue 151 - [Typed objects] Implement dynamically-sized array types

lib/typedObjects.js

 /*
  * This file is part of Adblock Plus <http://adblockplus.org/>,
  * Copyright (C) 2006-2014 Eyeo GmbH
  *
  * Adblock Plus is free software: you can redistribute it and/or modify
  * it under the terms of the GNU General Public License version 3 as
  * published by the Free Software Foundation.
  *
  * Adblock Plus is distributed in the hope that it will be useful,
  * but WITHOUT ANY WARRANTY; without even the implied warranty of
@@ skipping 33 matching lines @@
  *
  * The optional second parameter sets type metadata:
  *
  *    constructor: function that will be called whenever an object of the type
  *        is created. Parameters supplied during object creation will be passed
  *        to the constructor.
  *    destructor: function that will be called when an object of the type is
  *        freed.
  *    bufferSize: number of objects that should be placed into a single typed
  *        buffer (by default 128).
+ *    watch: a map assigning watcher functions to properties. These functions
+ *        are called with the new property value before the property is set.
+ *        They have to return the value that should actually be set for the
+ *        property, it doesn't necessarily have to be the original value.
  *
  * Creating and releasing an object instance
  * -----------------------------------------
  *
  *    var point = Point2D(5, 10);
  *    point.rotate(10);
  *    console.log(point.x + ", " + point.y);
  *
  * The parameters 5 and 10 will be passed to the constructor function defined
  * for this type.
@@ skipping 38 matching lines @@
  * All objects inherit from ObjectBase type implicitly and share its methods.
  * In particular, object.equals() can be used to compare objects:
  *
  *    var point1 = Point2D(5, 10);
  *    var point2 = Point2D(6, 12);
  *    console.log(point1.equals(point2)); // false
  *    console.log(point1.equals(point1)); // true
  *
  * Note that JavaScript comparison operators == and != won't always produce
  * correct results for typed objects.
+ *
+ * Array types
+ * -----------
+ *
+ * An array type can be created with any other type as element type:
+ *
+ *    var uint8Array = uint8.Array();
+ *    var array = uint8Array();
+ *    array.length = 2;
+ *    array.set(0, 5);
+ *    array.set(1, 8);
+ *
+ *    var Blob = ObjectType({
+ *      name: uint8Array,
+ *      data: uint8Array
+ *    });
+ *    var blob = Blob();
+ *    blob.data = array;
+ *    array.release();
+ *
+ * Array() function takes the same parameters as ObjectType(), meaning that an
+ * array can have a constructor, destructor and custom properties or methods.
+ * This also means that there can be multiple array types for each element type,
+ * each Array() call will generate a new type that won't be compatible with
+ * the other types. The metadata parameter for arrays can have the additional
+ * arrayBufferSize property determining the number of array elements stored in
+ * a single buffer (not the same as bufferSize property which applies to buffers
+ * containing array metadata and custom array properties and determines the
+ * number of arrays stored in these buffers).
+ *
+ * An array is an object meaning that it has the properties common for all
+ * objects, in particular retain() and release() determining when the array is
+ * garbage collected. In addition, it has the following properties and methods:
+ *
+ *    get(index): retrieves the array element at specified index.
+ *    set(index, value): sets the array element at specified index.
+ *    length: number of elements in the array, by default 0. Increase the length
+ *        to match your data size.
+ *    size: size of the allocated buffer in array elements, will be at least
+ *        equal to length. Normally you won't need to set the size explicitly.
+ *        However, the size won't decrease automatically if the array gets
+ *        smaller so you might want to set it in order to shrink the array.
  */
 
 function forwardExports(module)
 {
   let moduleExports = require(module);
   for (let key in moduleExports)
     exports[key] = moduleExports[key];
 }
 
 forwardExports("typedObjects/primitiveTypes");
 forwardExports("typedObjects/objectTypes");