Pike Manual

14.9 ADT.Table

ADT.Table is a generic module for manipulating tables. Each table contains one or several columns. Each column is associated with a name, the column name. Optionally, one can provide a column type. The Table module can do a number of operations on a given table, like computing the sum of a column, grouping, sorting etc.

All column references are case insensitive. A column can be referred to by its position (starting from zero). All operations are non-destructive. That means that a new table object will be returned after, for example, a sort.

An example is available at the end of this section.

METHOD

ADT.Table.table.create - create a table object

SYNTAX

void create(array(array) table, array(string) column_names, array(mapping)|void column_types);

DESCRIPTION

The table class takes two or three arguments:

table is a two-dimensional array consisting of one array of columns per row. All rows must have the same number of columns as specified in column_names.

column_names is an array of column names associated with each column in the table. References by column name are case insensitive. The case used in column_names will be used when the table is displayed. A column can also be referred to by its position, starting from zero.

column_types is an optional array of mappings. The column type information is only used when displaying the table. Currently, only the keyword "type" is recognized. The type can be specified as "text" or "num" (numerical). Text columns are left adjusted, whereas numerical columns are right adjusted. If a mapping in the array is 0 (zero), it will be assumed to be a text column. If column_types is omitted, all columns will displayed as text. See ADT.Table.ASCII.encode on how to display a table.

EXAMPLE

object t = ADT.Table.table( ({ ({ "Blixt", "Gordon" }), ({ "Buck", "Rogers" }) }), ({ "First name", "Last name" }) );

SEE ALSO

ADT.Table.ASCII.encode

METHOD: ADT.Table.table._indices - gives the column names
SYNTAX: array(string) _indices();
DESCRIPTION: This method returns the column names for the table. The case used when the table was created will be returned.

METHOD: ADT.Table.table._values - gives the table contents
SYNTAX: array(array) _values();
DESCRIPTION: This method returns the contents of a table as a two dimensional array. The format is an array of rows. Each row is an array of columns.

METHOD: ADT.Table.table._sizeof - gives the number of table rows
SYNTAX: int _sizeof();
DESCRIPTION: This method returns the number of rows in the table.

METHOD: ADT.Table.table.reverse - reverses the table rows
SYNTAX: object reverse();
DESCRIPTION: This method reverses the rows of the table and returns a new table object.

METHOD: ADT.Table.table.rename - rename a column
SYNTAX: object rename(string|int from, string to);
DESCRIPTION: This method renames the column named from to to and returns a new table object. Note that from can be the column position.

METHOD: ADT.Table.table.type - fetch or set the type for a column
SYNTAX: mapping type(string|int column, mapping|void type);
DESCRIPTION

METHOD: ADT.Table.table.limit - truncate the table
SYNTAX: object limit(int n);
DESCRIPTION: This method truncates the table to the first n rows and returns a new object.

METHOD: ADT.Table.table.sort - sort the table on one or several columns
SYNTAX: object sort(string|int column1, string|int column2, ...);
DESCRIPTION: This method sorts the table in ascendent order on one or several columns and returns a new table object. The left most column is sorted last. Note that the sort is stable.

METHOD: ADT.Table.table.rsort - sort the table in reversed order on one or several columns
SYNTAX: object rsort(string|int column1, string|int column2, ...);
DESCRIPTION

METHOD: ADT.Table.table.distinct - keep unique rows only
SYNTAX: object distinct(string|int column1, string|int column2, ...);
DESCRIPTION: This method groups by the given columns and returns a table with only unique rows. When no columns are given, all rows will be unique. A new table object will be returned.

METHOD: ADT.Table.Table.table.sum - computes the sum of equal rows
SYNTAX: object sum(string|int column1, string|int column2, ...);
DESCRIPTION: This method sums all equal rows. The table will be grouped by the columns not listed. The result will be returned as a new table object.

METHOD: ADT.Table.table.group - group the table using functions
SYNTAX: object group(mapping(string|int:funcion) fus, mixed ... arg); object group(funcion f, array(string|int)|string|int columns, mixed ... arg);
DESCRIPTION: This method calls the function for each column each time a non uniqe row will be joined. The table will be grouped by the columns not listed. The result will be returned as a new table object.

METHOD: ADT.Table.table.map - map columns over a function
SYNTAX: object map(funcion fu, string|int|array(int|string) columns, mixed ... arg);
DESCRIPTION: This method calls the function for all rows in the table. The value returned will replace the values in the columns given as argument to map. If the function returns an array, several columns will be replaced. Otherwise the first column will be replaced. The result will be returned as a new table object.

METHOD: ADT.Table.table.where - filter the table through a function
SYNTAX: object where(array(string|int)|string|int column1, funcion fu, mixed ... arg);
DESCRIPTION: This method calls the function for each row. If the function returns zero, the row will be thrown away. If the function returns something non-zero, the row will be kept. The result will be returned as a new table object.

METHOD: ADT.Table.table.select - keep only the given columns
SYNTAX: object select(string|int column1, string|int column2, ...);
DESCRIPTION: This method returns a new table object with the selected columns only.

METHOD: ADT.Table.table.remove - remove columns
SYNTAX: object remove(string|int column1, string|int column2, ...);
DESCRIPTION

METHOD: ADT.Table.table.encode - represent the table as a binary string
SYNTAX: string encode();
DESCRIPTION: This method returns a binary string representation of the table. It is useful when one wants to store a table, for example in a file.

METHOD: ADT.Table.table.decode - decode an encoded table
SYNTAX: string decode(string table_string);
DESCRIPTION: This method returns a table object from a binary string representation of a table.

METHOD: ADT.Table.table.col - fetch a column
SYNTAX: array col(string|int column);
DESCRIPTION: This method returns the contents of a given column as an array.

METHOD: ADT.Table.table.`[] - fetch a column
SYNTAX: array `[](string|int column);
DESCRIPTION

METHOD: ADT.Table.table.row - fetch a row
SYNTAX: array row(int row_number);
DESCRIPTION: This method returns the contents of a given row as an array.

METHOD: ADT.Table.table.`== - compare two tables
SYNTAX: int `==(object table);
DESCRIPTION: This method compares two tables. They are equal if the contents of the tables and the column names are equal. The column name comparison is case insensitive.

METHOD: ADT.Table.table.append_bottom - concatenate two tables
SYNTAX: object append_bottom(object table);
DESCRIPTION: This method appends two tables. The table given as an argument will be added at the bottom of the current table. Note, the column names must be equal. The column name comparison is case insensitive.

METHOD: ADT.Table.table.append_right - concatenate two tables
SYNTAX: object append_right(object table);
DESCRIPTION: This method appends two tables. The table given as an argument will be added on the right side of the current table. Note that the number of rows in both tables must be equal.

METHOD: ADT.Table.ASCII.encode - produces an ASCII formated table
SYNTAX: string encode(object table, mapping|void options);
DESCRIPTION: This method returns a table represented in ASCII suitable for human eyes. options is an optional mapping. If the keyword "indent" is used with a number, the table will be indented with that number of space characters.

EXAMPLE

array(string) cols = ({ "Fruit", "Provider", "Quantity" }); array(mapping) types = ({ 0, 0, ([ "type":"num" ]) }); array(array) table = ({ ({ "Avocado", "Frukt AB", 314 }), ({ "Banana", "Banankompaniet", 4276 }), ({ "Orange", "Frukt AB", 81 }), ({ "Banana", "Frukt AB", 1174 }), ({ "Orange", "General Food", 523 }) }); object t = ADT.Table.table(table, cols, types); write("FRUITS\n\n"); write(ADT.Table.ASCII.encode(t, ([ "indent":4 ]))); write("\nPROVIDERS\n\n"); write(ADT.Table.ASCII.encode(t->select("provider", "quantity")-> sum("quantity")->rsort("quantity"))); write("\nBIG PROVIDERS\n\n"+ ADT.Table.ASCII.encode(t->select("provider", "quantity")-> sum("quantity")-> where("quantity", `>, 1000)-> rsort("quantity"))); write("\nASSORTMENT\n\n"); write(ADT.Table.ASCII.encode(t->select("fruit")->distinct("fruit")-> sort("fruit"), ([ "indent":4 ])));

Previous section

To contents

Next section