mXrap - Xadapter

Xadapter

require.mx('mxjs/base/algorithms/xadapter.js');

This library provides adapters for use with different data inputs and outputs.

Adapters are objects that behave like data tables, while reading from or writing to a different underlying data structure, such as an array or a set of arrays.

Tabular data can be stored in different ways within mXrap, e.g. in a data table, or in a set of arrays, or in an interleaved array. As a result, it can be difficult to standardise what each library function should accept as input. After much consideration, the mXrap team have settled on the data table method - libraries in mXrap will in general take in a Table and its read or write functions as the standard way of reading/writing tabular data.

If your tabular data is in a set of column arrays, or in an interleaved array, you will instead want to use an adapter. You can create an adapter over the arrays/array, which provides you with an object that pretends to be a data table, when its actually reading from/writing to the underlying arrays. You can then use this adapter to provide input/output to library functions which take in data tables.

Adapters can be read-only, or write-enabled. You can use standard data table methods like size() and if write-enabled, grow(), resize(), reserve().

You can also create adapters that are in "subset" mode, that is, they operate over a specified range of the arrays or data table. When in "subset" mode, you can write to the records (if write-enabled), but you cannot resize or add/remove records.

One caveat with using adapters is that they are relatively expensive to create. Hence you should always free() your adapters once you are done using them. Freed adapters are re-used where possible, which greatly reduces the overhead of using adapters.

QuickRef

createArrayAdapter
createDataTableAdapter
createInterleavedArrayAdapter
createSubsetArrayAdapter
createSubsetDataTableAdapter
createSubsetInterleavedArrayAdapter
free
table
table.mapTable
util
util.copy
util.transform
Adapter
Adapter.changeSubset
Adapter.grow
Adapter.reserve
Adapter.resize
Adapter.size

Status	Name
	`Adapter` createArrayAdapter ( `boolean` writeAllowed, `Number` numRecords, `Array` col_arrays... ) Creates an adapter based on the specified (up to 10) column arrays
	`Adapter` createDataTableAdapter ( `boolean` writeAllowed, `Table` Table, `Number` numColumns, `Array` readFunctionsArray, `Array` writeFunctionsArray ) Creates an adapter based on the specified data tables and columns (in the order provided).
	`Adapter` createInterleavedArrayAdapter ( `boolean` writeAllowed, `Number` numRecords, `Number` numColumns, `Array` interleaved_array ) Creates an adapter based on the specified interleaved array.
	`Adapter` createSubsetArrayAdapter ( `boolean` writeAllowed, `Number` offset, `Number` range, `Array` col_arrays... ) Creates an adapter based on the specified (up to 10) column arrays, over the subset range of indices. grow, resize and reserve are not allowed for a subset adapter, even if it is writeAllowed.
	`Adapter` createSubsetDataTableAdapter ( `boolean` writeAllowed, `Number` offset, `Number` range, `Table` Table, `Number` numColumns, `Array` readFunctionsArray, `Array` writeFunctionsArray ) Creates an adapter based on the specified data tables and columns (in the order provided), over the subset range of indices. grow, resize and reserve are not allowed for a subset adapter, even if it is writeAllowed.
	`Adapter` createSubsetInterleavedArrayAdapter ( `boolean` writeAllowed, `Number` offset, `Number` range, `Number` numColumns, `Array` interleaved_array ) Creates an adapter based on the specified interleaved array, over the subset range of indices. grow, resize and reserve are not allowed for a subset adapter, even if it is writeAllowed.
	free ( `Adapter` adapter ) Frees up an adapter that is no longer required, allowing it to be reused elsewhere.
	`Object` table.mapTable ( `Object` table_object, `Object` mapping ) This function creates a data table object with different column javascript names based on another data table object. Suppose Table1 is a mXrap defined table such that you have data API: Table1.read_ID, Table1.read_sigma1, Table1.read_sigma3 `const Table2 = XAdapter.mapTable(Table1, { "ID" : "ID", "x" : "sigma1", "y" : "sigma3"});` Table2 now behaves like a mXrap defined table that reads/writes back to Table1, but with data API: Table2.read_ID, Table2.read_x, Table2.read_y
	util.copy ( `Adapter` input_adapter, `Adapter` output_adapter ) This function copies all values from the input_adapter to the output_adapter.
	util.transform ( `Adapter` input_adapter, `Number` input_index, `Adapter` output_adapter, `Number` output_index, `Function` func ) For each value in the input adapter (at specified input index), it executes the function with the value as the single input and writes the output to the output adapter (at specified output index).

Library Functions

adapter = Lib.createArrayAdapter ( writeAllowed, numRecords, col_arrays... ) Beta

Creates an adapter based on the specified (up to 10) column arrays

Parameters:

boolean writeAllowed
Number numRecords
Array col_arrays... - up to 10 column arrays

Returns: Adapter adapter

adapter = Lib.createDataTableAdapter ( writeAllowed, Table, numColumns, readFunctionsArray, writeFunctionsArray ) Beta

Creates an adapter based on the specified data tables and columns (in the order provided).

Parameters:

boolean writeAllowed
Table Table - data table to create the adapter over
Number numColumns - number of columns to put in the adapter
Array readFunctionsArray - array of read functions (in order of columns). [Table.read_Field1, Table.read_Field2, ... Table.readFieldN], where N is numColumns
Array writeFunctionsArray - array of write functions (in order of columns). [Table.write_Field1, Table.write_Field2, ... Table.writeFieldN], where N is numColumns. Optional - Can be omitted if write is not allowed.

Returns: Adapter adapter

adapter = Lib.createInterleavedArrayAdapter ( writeAllowed, numRecords, numColumns, interleaved_array ) Beta

Creates an adapter based on the specified interleaved array.

Parameters:

boolean writeAllowed
Number numRecords - number of rows in the interleaved array provided
Number numColumns - number of columns in the interleaved array provided
Array interleaved_array - an interleaved array is a array with multiple columns in it, e.g. [x1, y1, z1, x2, y2, z2, ...]

Returns: Adapter adapter

adapter = Lib.createSubsetArrayAdapter ( writeAllowed, offset, range, col_arrays... ) Beta

Creates an adapter based on the specified (up to 10) column arrays, over the subset range of indices. grow, resize and reserve are not allowed for a subset adapter, even if it is writeAllowed.

Parameters:

boolean writeAllowed
Number offset - for the subset. e.g. writing to row n of the adapter will write to row n + offset of the underlying column arrays
Number range - for the subset. e.g. the adapter will operate over rows starting from offset (inclusive) and ending with offset + range (exclusive) of the underlying column arrays
Array col_arrays... - up to 10 column arrays

Returns: Adapter adapter

adapter = Lib.createSubsetDataTableAdapter ( writeAllowed, offset, range, Table, numColumns, readFunctionsArray, writeFunctionsArray ) Beta

Creates an adapter based on the specified data tables and columns (in the order provided), over the subset range of indices. grow, resize and reserve are not allowed for a subset adapter, even if it is writeAllowed.

Parameters:

boolean writeAllowed
Number offset - for the subset. e.g. writing to row n of the adapter will write to row n + offset of the underlying data table
Number range - for the subset. e.g. the adapter will operate over rows starting from offset (inclusive) and ending with offset + range (exclusive) of the underlying data table
Table Table - data table to create the adapter over
Number numColumns - number of columns to put in the adapter
Array readFunctionsArray - array of read functions (in order of columns). [Table.read_Field1, Table.read_Field2, ... Table.readFieldN], where N is numColumns
Array writeFunctionsArray - array of write functions (in order of columns). [Table.write_Field1, Table.write_Field2, ... Table.writeFieldN], where N is numColumns. Optional - Can be omitted if write is not allowed.

Returns: Adapter adapter

adapter = Lib.createSubsetInterleavedArrayAdapter ( writeAllowed, offset, range, numColumns, interleaved_array ) Beta

Creates an adapter based on the specified interleaved array, over the subset range of indices. grow, resize and reserve are not allowed for a subset adapter, even if it is writeAllowed.

Parameters:

boolean writeAllowed
Number offset - for the subset. e.g. writing to row n of the adapter will write to row n + offset of the underlying interleaved array
Number range - for the subset. e.g. the adapter will operate over rows starting from offset (inclusive) and ending with offset + range (exclusive) of the underlying interleaved array
Number numColumns - number of columns in the interleaved array provided
Array interleaved_array - an interleaved array is a array with multiple columns in it, e.g. [x1, y1, z1, x2, y2, z2, ...]

Returns: Adapter adapter

Lib.free ( adapter ) Beta

Frees up an adapter that is no longer required, allowing it to be reused elsewhere.

Parameters:

Adapter adapter

Category: table

This category contains functions for reading/writing via the data table interface

mappedDataTable = Lib.table.mapTable ( table_object, mapping ) Beta

This function creates a data table object with different column javascript names based on another data table object.

Suppose Table1 is a mXrap defined table such that you have data API:
Table1.read_ID, Table1.read_sigma1, Table1.read_sigma3
const Table2 = XAdapter.mapTable(Table1, { "ID" : "ID", "x" : "sigma1", "y" : "sigma3"});
Table2 now behaves like a mXrap defined table that reads/writes back to Table1, but with data API:
Table2.read_ID, Table2.read_x, Table2.read_y

Parameters:

Object table_object
Object mapping

Returns: Object mappedDataTable

Category: util

This category contains utility functions.

Lib.util.copy ( input_adapter, output_adapter ) Beta

This function copies all values from the input_adapter to the output_adapter.

Parameters:

Adapter input_adapter
Adapter output_adapter

Lib.util.transform ( input_adapter, input_index, output_adapter, output_index, func ) Beta

For each value in the input adapter (at specified input index), it executes the function with the value as the single input and writes the output to the output adapter (at specified output index).

Parameters:

Adapter input_adapter
Number input_index
Adapter output_adapter
Number output_index
Function func

Class: Adapter

Adapters mimic data tables

Status	Name
Member	`Array` read an array of functions, such that the function to read from the ith row of the second column is adapter.read[1](i)
Member	`Array` write an array of functions, such that the function to write to the ith row of the second column is adapter.write[1](i)
	changeSubset ( `Number` subsetOffset, `Number` subsetRange ) If this adapter is a subset adapter, changes the subset range that this adapter operates over.
	grow ( `Number` numRecords ) Increases the number of available records within the Adapter by specified size
	reserve ( `Number` numRecords ) Preps the adapter about your intention to increase the number of available records within the Adapter by specified size.
	resize ( `Number` numRecords ) Changes the number of available records within the Adapter to specified size
	`Number` size ( ) Returns the number of records within the Adapter

Adapter.changeSubset ( subsetOffset, subsetRange ) Beta

If this adapter is a subset adapter, changes the subset range that this adapter operates over.

Parameters:

Number subsetOffset - - index of item to start from.
Number subsetRange - - number of items from offset to include

Adapter.grow ( numRecords ) Beta

Increases the number of available records within the Adapter by specified size

Parameters:

Number numRecords

Adapter.reserve ( numRecords ) Beta

Preps the adapter about your intention to increase the number of available records within the Adapter by specified size.

Parameters:

Number numRecords

Adapter.resize ( numRecords ) Beta

Changes the number of available records within the Adapter to specified size

Parameters:

Number numRecords

Adapter.size ( ) Beta

Returns the number of records within the Adapter

Parameters:

Returns: Number numRecords

Libraries

Categories

Classes

Xadapter

Library Functions

Category: table

Category: util

Class: Adapter