# DataSet JavaScript API

The DataSet data type can be configured and constructed using a JavaScript API; it is created by invoking the Constructor.

###### Data Types and Schema

The DataSet data type can contain a heterogeneous mixture of columns, but rows must be consistent. This means that a component referencing the DataSet can assume that each column contains the same data type in the cells across all rows, or the cell is empty (e.g. undefined).

The DataSet supports four types of data types: Boolean, Integer, Double (Real) and String. These are the data types that define the columns in the DataSet. The data type of the columns are defined by one of two methods:

1. Using the DataSet JavaScript Constructor, by providing the schema as arguments (shown below in the Constructor section).
2. If the schema is not defined by Constructor arguments, the first row that is inserted in the table (via the addRow function), will automatically define the schema.

The schema is defined by the following:

1. The data type for each column, which is a string value of "Boolean", "String", "Integer", "Double".
2. A name string value for each column, such as "Acquisition", "Pass", "Fail", etc.
3. The order of the columns, which is defined by the order of the data type and name strings.

Note:

- If the DataSet constructor only defines the column data types, the header names of the columns will be auto-generated ("Column0", "Column1", etc.).
- Each row in the DataSet contains the data types specified by the schema, unless a cell value is "undefined" (this is how JavaScript expresses a "null" value). When a cell in a row is "undefined", it will be an empty cell.
- The column header names can be used to reference cells of the table, using the name of the column via the getByColumnName and setByColumnName functions (described below in the Functions section).
- The column header names can be changed using the setColumnNames function.
- The maximum number of rows in a DataSet is 256 rows.

###### Constructor

Signature | Description
--- | ---
    new DataSet(colTypes : Array<string>,colNames : Array<string>) : DataSet
| This is the primary Constructor; you invoke this Constructor and pass in the schema for the DataSet being constructed. The schema is defined in two arrays: colTypes: An array of strings, from the following set: "Boolean", "String", "Integer", "Double" colNames: An array of strings, containing a name for each column. Note: If the colNames array length (n) is smaller than the number of columns in the DataSet, the names will be applied to the first n columns only. If the array length is longer than the number of columns, the extra items will be ignored. If the colNames array contains a duplicate entry, such as ["X", "Y", "X", "Z"], the first instance will be applied while the remaining instances will be replaced with "Column<i>", where i is the index, from the left. Example
    var columnTypes = ["Integer", "Double", "Boolean"];
    var headerNames = ["AcqId", "Measurement", "Pass"];
    var ds = new DataSet(columnTypes, headerNames)
    new DataSet() : DataSet
| This constructor will leave the schema of the DataSet unspecified. When the schema is not defined by arguments, the first row that is inserted in the table (via the addRow function), will automatically define the schema, and the column header names will be auto-generated (i.e. "Column0", "Column1", etc.).
    new DataSet(ColTypes : Array<string>) : DataSet
| The column data types are defined, but the column header names are auto-generated (i.e. "Column0", "Column1", etc.).

###### Functions - Data Manipulation

Signature | Description
--- | ---
    AddRow(values : Array<object>) : undefined
| This function inserts a new row to the end of the DataSet. The input is a JavaScript array, which can contain a mixture of heterogeneous values that correspond to the cells of the row. Note: If the data types of the columns are defined using the colTypes argument of the DataSet constructor, or if there are already rows in the DataSet (i.e. the column data types were auto-generated), the addRow function may throw an exception if the data type values in the row being inserted do not match the defined column data types. The argument array can contain an "undefined" value. In this case, the DataSet must be constructed with defined column data types; otherwise, if the DataSet is empty and it was not constructed with defined column data types, it will return an error.
    AddRow(val1 : value,
           val2 : value, ...) : undefined
| This is an alternative method of invoking the addRow function, which allows you to not wrap the argument into an array. This means that adding the cell values as separate arguments will also work.
    AddDataSet(dataSet : DataSet) : undefined
| This function inserts multiple rows from another DataSet. Note: An exception will be thrown if there is a mismatch between the schemas of the DataSet; i.e. if the number of columns is different or the data types are mismatched. However, the column names do not have to match.
    InsertColumn(index : number,
                 dataType : string
                 columnName : string) : undefined
| This function is used to modify the existing columns of a DataSet by inserting a new column at the specified index, with the specified data type and column name. Inserted columns will shift existing columns to the right of the indexed column. Note: If the DataSet has rows, the rows will be updated with an "undefined" value in the new column, and existing cells will be shifted to the right of the index where the new column was added.
    RemoveColumn(index : number) : undefined
| This function is used to remove the specified column (via its index) from the DataSet. Note: If the DataSet has rows, the rows will also be updated and any values in the removed column will be lost.
    Set(row : number,
        column : number,
        value : value) : undefined
| This function is used to set the specified cell to the value argument, based on an index number for the row and column. Note: Calling a set function on a nonexistent row and/or column will throw an exception.
    SetByColumnName(row : number,
                    columnName : string,
                    value : value) : undefined
| This function is used to set the specified cell to the value argument, based on the column name and row number.
    ClearRows() : undefined
| This function is used to remove all the rows, but retains the column data type and header name definitions.
    RemoveRow(index : number) : undefined
| This function is used to remove the indexed row of a DataSet.
    RemoveRows(from : number,
               to : number) : undefined
| This function is used to remove multiple rows from a DataSet. The rows to be removed are specified using the from and to index numbers, inclusively.

###### Functions - Data Access

Signature | Description
--- | ---
    GetRowCount() : number
| This function is used to return the number of rows currently in the DataSet.
    GetColumnCount() : number
| This function is used to return the number of columns currently in the DataSet.
    GetRow(index : number) : Array
| This function is used to return a specified row, via its index, as a JavaScript array. Note: Calling this function on a nonexistent row column will throw an exception.
    GetRowObject(index : number) : JsObject
| This function is used to return a specified row, via its index, as a JavaScript object, with the cell values assigned to properties, which are named according to the column names in the schema. Note: Calling this function on a nonexistent row column will throw an exception. Getting the row as an object allows iterating through the cells as JavaScript properties. Example
    var ds = new DataSet(["Integer", "Boolean"], ["AcqId", "Pass"]);
    ds.AddRow([1, false]);
    ds.AddRow([2, true]);
    // later
    if(ds.GetRowObject(1).Pass) {
      // ...
    }
    GetRows(from : number,
            to : number) : DataSet
| This function is used to return multiple rows, specified using the from and to index numbers, inclusively, as a DataSet. The DataSet that is returned inherits the schema (i.e. column data types and names) of the referenced DataSet. The returned rows are copies of the original rows. Note: If either of the arguments are outside of the referenced DataSet's row boundaries, an exception will be thrown.
    Get(row : number,
        column : number) : value
| This function is used to return a specified cell value; the column and row is referenced via an index number. Note: Calling a get function on a nonexistent row and/or column will throw an exception.
    GetByColumnName(row : number,
                    colName : string) : value
| This function is used to return a specified cell value by referencing a column name and row number. Note: Calling a get function on a nonexistent row and/or column will throw an exception.
    GetDataCsv() : string
| This function is used to return the data from a DataSet as a string, which is transformed into the CSV format. Note: For more information, see the Saving a DataSet as CSV File topic.

###### Functions - Schema

Signature | Description
--- | ---
    GetColumnNames() : Array<string>
| This function is used to return a JavaScript Array of strings, containing the names of the column headers in the specified DataSet.
    GetColumnTypes() : Array<string>
| This function is used to return a JavaScript Array of strings, containing the data types (i.e. "Boolean", "Integer", "Double", "String", "DataSet") of each column in the specified DataSet.
    SetColumnNames(Array<string> columnNames) : undefined
| This function is used to assign names to columns, using an array of strings, which allows the names to be used when referencing cells, and also to be used as a table header when the DataSet is displayed on a WebPage HMI. Note: Using this function will overwrite the current set of column names. If the array length (n) is smaller than the number of columns in the DataSet, names will only be applied to the first n columns. If the array length is longer than the number of columns in the DataSet, the names that exceed the length will be ignored. If the array contains duplicate entries, such as ["X", "Y", "X", "Z"], the first instance will be applied, but the duplicate will be replaced by "Column<i>" (where i is the index of the column, from the left).