Home of tabular programming.
Class Table( [heading] )
| heading | The heading of the table (array) |
| Methods | |
| append | Adds a row at the end of the current page in the table. |
| back | Returns the last item in the table. |
| bidding | Performs a bidding between rows. |
| choice | Performs a choice between rows. |
| columnData | Returns the column data bound with a certain column |
| columnPos | Returns the number of a given column name. |
| curPage | Gets the current table page. |
| find | Finds an element in a table. |
| first | Returns an iterator to the first element of the table. |
| front | Returns the first item in the table. |
| get | Gets a row in a table. |
| getColData | Gets the clumn wide data associated with this table. |
| getHeader | Gets the name of one header, or the list of header names. |
| getPage | Returns a copy of a given page in the table. |
| insert | Insert a row in the table. |
| insertColumn | Inserts a column in a table. |
| insertPage | Inserts a new table page. |
| last | Returns an iterator to the last element of the table. |
| len | Returns the length of the table (the number of rows). |
| order | Returns the order of the table (column count). |
| pageCount | Gets the number of pages in this table. |
| remove | Remove a row from the table. |
| removeColumn | Removes a column from a table. |
| removePage | Removes a page. |
| resetColumn | Applies a value on a column, eventually setting one or more rows to a different value. |
| set | Changes the value of a whole row. |
| setColumn | Change the title or column data of a column. |
| setHeader | Sets the header of an empty table. |
| setPage | Sets current active page. |
Adds a row at the end of the current page in the table.
Table.append( element )
| element | The row to be inserted. | ||
| Raise |
|
This method adds the element at the end of the page currently selected in this table.
Note: This method is equivalent to Table.insert with row set as nil.
Returns the last item in the table.
Table.back()
| Return | The last item in the table. | ||
| Raise |
|
If the table is not empty, it returns the last element (row) in the table.
Performs a bidding between rows.
Table.bidding( column, [offer],[rows] )
| column | Betting column (number or name). | ||
| offer | Offer column (number or name). | ||
| rows | Range of rows in which to perform the bidding. | ||
| Return | The winning row, or the corresponding value in the offer column. | ||
| Raise |
|
This method calls iteratively all the items in a determined column of the table, recording their return value, which must be numeric. It is allowed also to have numeric and nil values in the cells in the betting column. Numeric values will be considered as final values and will participate in the final auction, while row having nil values will be excluded.
After the bidding is complete, the row offering the highest value is selected and returned, or if the offer parameter is specified, the corresponding value in the given column will be returned.
Note: If the bidding element is a plain function, it will be called as a method of the array, so "self" will be available. In all the other cases, the array will be passed as the last parameter.
A rows range can be specified to limit the bidding to a part smaller part of the table.
Performs a choice between rows.
Table.choice( func, [offer],[rows] )
| func | Choice function or callable. |
| offer | Offer column (number or name). |
| rows | Range of rows in which to perform the bidding. |
| Return | The winning row, or the corresponding value in the offer column. |
This method sends all the rows in the table as the sole parameter of a function which has to return a numeric value for each row.
After all the rows have been processed, the row for which the called function had the highest value is returned. If the optional parameter offer is specified, then the item specified by that column number or name is returned instead.
If two or more rows are equally evaluated by the choice function, only the first one is returned.
The evaluation function may return a number lower than 0 to have the row effectively excluded from the evaluation. If all the rows are evaluated to have a value lower than zero, the function returns nil (as if the table was empty).
The function may force an immediate selection by returning an out of band item. An out of band nil will force this method to return nil, and an out of band number will force the selection of the current row.
If an offer parameter is specified, then the item in the corresponding column (indicated by a numeric index or by column name) is returned.
A row range can be used to iterate selectively on one part of the table.
If the table is empty, or if the given row range is empty, the function returns nil.
Note: Except for OOB nil, every return value coming from the choice function will be turned into a floating point numeric value. Non-numeric returns will be evaluated as 0.0.
Returns the column data bound with a certain column
Table.columnData( column, [data] )
| column | The column header name or numeric position. |
| data | New data to be stored as column data. |
| Return | The column data for the given column, or nil is not found. |
If the data parameter is specified, then the value of the given column data is changed. Anyhow, the previous value is returned.
Notice that the column data of an existing column may be nil; to know if a column with a given name exists, use the Table.columnPos method.
Returns the number of a given column name.
Table.columnPos( column )
| column | The column header name. |
| Return | The numeric position of the column or -1 if not found. |
Gets the current table page.
Table.curPage()
| Return | The currently active table page. |
All the tables are created with at least one page having ID = 0.
Finds an element in a table.
Table.find( column, value, [tcol],[dflt] )
| column | The column where to perform the search (either name or 0 based number). | ||
| value | The value to be found. | ||
| tcol | The name of the column to be extracted (target column; either name or 0 based number). | ||
| dflt | A default value to be returned if the row is not found. | ||
| Return | An array (if the column is not specified) or an item. | ||
| Raise |
|
The returned array is a "table component", and as such, its size cannot be changed; also, it inherits all the table columns, that can be accessed as bindings with the dot accessor and will resolve in one of the element in the array.
In case of success, through the BOM method Array.tabRow it is possible to retrieve the table row position of the returned array.
In case of failure, a TableError is raised, unless a dflt parameter is specified.
Returns an iterator to the first element of the table.
Table.first()
| Return | An iterator. |
Returns an iterator to the first element of the table. If the table is empty, an invalid iterator will be returned, but an insertion on that iterator will succeed and append an item to the table.
Returns the first item in the table.
Table.front()
| Return | The first item in the table. | ||
| Raise |
|
If the table is not empty, it returns the first element (row) in the table.
Gets a row in a table.
Table.get( row, [tcol] )
| row | a Row number. |
| tcol | The name of the column to be extracted (target column; either name or 0 based number). |
| Return | An array (if the column is not specified) or an item. |
The returned array is a "table component", and as such, its size cannot be changed; also, it inherits all the table clumns, that can be accessed as bindings with the dot accessor and will resolve in one of the element in the array.
Gets the clumn wide data associated with this table.
Table.getColData( [id] )
| id | If given, a number indicating the column of which to get the data. |
| Return | An item (if id is given) or the vector of ordered column names. |
Gets the name of one header, or the list of header names.
Table.getHeader( [id] )
| id | If given, a number indicating the column of which to get the name. |
| Return | A string (if id is given) or the vector of ordered column names. |
Returns a copy of a given page in the table.
Table.getPage( [pageId] )
| pageId | The page to be copied (defaults to the current page). |
| Return | An array containing all the rows in the page. |
While the returned item is a copy, and modifying it doesn't cause the change the be reflected on the table, each row returned with it is the actual item stored in the table. So, modifying the Nth element of one of the arrays in the returned one will affect the page.
Insert a row in the table.
Table.insert( row, element )
| row | The position where to insert the row. | ||||
| element | The row to be inserted. | ||||
| Raise |
|
The element is inserted before the given position.
If pos is greater or equal to the length of the table, the row will be inserted at end (added). If pos is negative, the row will be accessed backward, -1 being the last element (the row will be inserted before the last one).
Inserts a column in a table.
Table.insertColumn( column, name, [coldata],[dflt] )
| column | The column name or position where to insert the column. |
| name | The name of the new column. |
| coldata | The column data for the new column. |
| dflt | Default value for the newly inserted columns. |
This method creates a new column in the table, inserting or adding a new heading, a new column data and an item in the corresponding column position of each array in the table.
If dflt parameter is specified, that value is used to fill the newly created columns in the table rows, otherwise the new items will be nil.
Inserts a new table page.
Table.insertPage( [pageId],[data] )
| pageId | The position at which to insert the page. |
| data | an array of rows (arrays), each of which having length equal to table order. |
If pos is greater than the number of pages in the table, or not given, the page will be appended at the end.
Returns an iterator to the last element of the table.
Table.last()
| Return | An iterator. |
Returns an iterator to the last element of the table. If the table is empty, an invalid iterator will be returned, but an insertion on that iterator will succeed and append an item to the table.
Returns the length of the table (the number of rows).
Table.len()
| Return | The rows in the current page of the table. |
Tables may have multiple pages, each of which having the same order (column count), but different length (rows).
This method returns the length of the currently active page.
Returns the order of the table (column count).
Table.order()
| Return | The number of the columns, and of the length of every array in the table. |
Gets the number of pages in this table.
Table.pageCount()
| Return | Number of pages stored in this table. |
Remove a row from the table.
Table.remove( row )
| row | The number of the row to be removed. | ||
| Return | The removed array. | ||
| Raise |
|
This method removes one of the rows from the table.
However, the array still remember the table from which it came from, as the table may have multiple reference to the array. So, the array stays bound with the table, and cannot be modified.
Removes a column from a table.
Table.removeColumn( column )
| column | The column name or position to be removed. | ||
| Raise |
|
This method removes column in the table, removing also the item at corresponding position in all the rows of all the pages in this table.
Removes a page.
Table.removePage( pageId )
| pageId | The page to be removed. |
The table cannot exist without at least one page, and if the deleted page is the current one, the page 0 is selected.
Applies a value on a column, eventually setting one or more rows to a different value.
Table.resetColumn( column, [resetVal],[row],[value] )
| column | Column name or number where the value must be applied. |
| resetVal | The value that must be set to clear the rows (defaults to nil). |
| row | The row (or rows, if a range is given) to be set to value. |
| value | The value that must be set in the given row(s) (defaults to true). |
This method takes a column in the current page and sets all the values in all the rows to resetVal (or nil if not given).
Optionally, a single row or a range of rows where to apply a different value can be given.
In example, this allows to create a diagonal matrix like the following:
x = Table( ["a","b","c"] )
x.insert( 0, arrayBuffer( 3 ) )
x.insert( 0, arrayBuffer( 3 ) )
x.insert( 0, arrayBuffer( 3 ) )
for i in [0:3]
x.resetColumn( i, 0, i, 1 )
end
Tables are not meant for linear algebra calculus, but it is often useful to clear a whole column, and it can come useful to set just one row in a table to stand out, especially in decision support systems and program logic control, which is what Falcon tables are specifically designed.
Changes the value of a whole row.
Table.set( row, element )
| row | a Row number. |
| element | The new data to be placed at the given row. |
This method changes an existing row placing a completely new value over it.
Change the title or column data of a column.
Table.setColumn( column, name, [coldata] )
| column | The number of name of the column to be renamed. |
| name | The new name of the column, or nil to let it unchanged. |
| coldata | The new column data. |
This method changes the column heading in a table. It may be also used to change the column-wide data.
Sets the header of an empty table.
Table.setHeader( header )
| header | An array of strings or future bindings that will be used as table header | ||
| Raise |
|
This method allows to set the header of an uninitialized table after its creation.
Sets current active page.
Table.setPage( pageId )
| pageId | The number of the selected page. |
All the tables are created with at least one page having ID = 0.