1 /**
  2  * @class dataTable
  3  * @extends component
  4  * @description
  5  * A component that can store and import arbitrary data. Instantiates with {@link sandboxe.dataTable.create()} </br></br>
  6  *
  7  * Provides a convenient interface for placing and retrieving named properties.</br></br>
  8  * Often with programs, there is a need to preserve data beyond the execution of the 
  9  * program. Sometimes, it is enough to simply write to a text file, but this isn't 
 10  * always flexible, and has little resistance against device errors, forms 
 11  * of corruption, and user tampering. dataTable provides a non-sequential, corruption-resistant 
 12  * way to store data. Using the Write functions, you can store named variables 
 13  * , data, and even other dataTables in a safe manner. Then getState() can be 
 14  * used to retrieve a data buffer that represents the dataTable's exact state,
 15  * which can then be used later in another instance.</br></br>
 16  *
 17  * Known {@link component} events:</br>
 18  * <pre>
 19  * - on-read: after reading a piece of data. 
 20  * - on-write: before writing a piece of data. The default handler actually performs the write, so stopping propogation will prevent writing.
 21  * - on-remove: before removing a piece of data. The default handler actually performs the removal, so stopping propogation will prevent removal. 
 22  * - on-read-state: after successfully reading a state
 23  * </pre>
 24  *
 25  * 
 26  */ 
 27 function dataTable() {
 28 
 29     /**
 30      * Associates a datum with a name.
 31      *
 32      * @param {String} name The name that the data will be associated with 
 33      * @param {String} i    The data to store 
 34      */
 35     this.writeString = function(name, i){};
 36 
 37     /**
 38      * Associates a datum with a name. 
 39      *
 40      * @param {String} name The name that the data will be associated with 
 41      * @param {Array} byteData    The data to store as an array of numbers, each being a byte value 
 42      */
 43     this.writeByteArray = function(name, yteData){};
 44 
 45     /**
 46      * Retrieves a datum associated with a name. If there is no such association,
 47      * an empty string is returned.
 48      * 
 49      * @param {String} name The name associated with the data.
 50      * @returns {String} The data for that name.
 51      */
 52     this.readString = function(name){};
 53 
 54     /**
 55     * Retrieves a datum associated with a name. If there is no such association,
 56     * an empty Array is returned.
 57     * 
 58     * @param {String} name The name associated with the data.
 59     * @returns {Array} The data for that name.
 60      */
 61     this.readByteArray = function(name){};
 62 
 63 
 64 
 65     /**
 66      * Returns whether there is a datum-name association 
 67      * with the given name.
 68      * @param {String} name The name to look up.
 69      * @returns {boolean}
 70      */
 71     this.query = function(name){};
 72 
 73 
 74     /**
 75      * Removes the datum-name association.
 76      * @param {String} name The name to remove.
 77      */
 78     this.remove = function(){};
 79 
 80 
 81 
 82     /**
 83      * Removes all stored associations and data entries, restoring 
 84      * the container back to a default state.
 85      */
 86     this.clear = function(){};
 87 
 88 
 89 
 90     /**
 91      * Writes a pure data-form of the table's contents. This can then be 
 92      * passed into setState() turn the calling object into an exact copy 
 93      * of this one.
 94      *
 95      * getState() / setState() were intended to be used in tandem to preserve data contents of 
 96      * the dataTable across program invocations. Along with writing the exact state of 
 97      * the dataTable, the data includes header and checksum data to improve parity across 
 98      * execution states.
 99      * @returns {Array} An array of byte values to later be re-read with setState()
100      */
101     this.getState = function(){};
102 
103 
104     /**
105      * Sets the dataTable state to reflect the state
106      * defined by the input buffer.
107      *
108      * The buffer is implied to have been produced from a getState call.
109      * If not, or corruption on some device has occurred, 
110      * there is a good chance that this function will detect it before applying the data. 
111      * In the case that an error does occur, false will be returned and no action taken.
112      * @param {Array} byteArray An array of byte values assumed to be from getState().
113      */
114     this.setState = function(){};
115     
116 
117 
118 
119 
120 
121     return this;
122 }