Copyright © 2016 Ashok P. Nadkarni. All rights reserved.

1. Introduction

The tarray extension implements typed arrays and associated commands column and table. This page provides reference documentation for commands related to typed tables. See Introduction for an overview and Programmer’s guide for a programming guide.

1.1. Installation and loading

Binary packages for some platforms are available from the Sourceforge download area. See the build instructions for other platforms.

To install the extension, extract the files from the distribution to any directory that is included in your Tcl installation’s auto_path variable.

Once installed, the extension can be loaded with the standard Tcl package require command.

% package require tarray
→ 0.8
% namespace import tarray::table

1.2. Tables

A typed table is an ordered sequence of typed columns of equal size. It can be viewed as an array of records where the record fields happen to use column-wise storage. The corresponding table command operates on typed tables.

The columns in a table are defined with a name, type and order when the table is created. Commands that operate on tables allow columns to be specified using either the column name or its position.

1.3. Types

All elements in a typed column must be of the type specified when the column is created. The following element types are available:

Table 1. Table Column types
Keyword Type

any

Any Tcl value

string

A string value

boolean

A boolean value

byte

Unsigned 8-bit integer

double

Floating point value

int

Signed 32-bit integer

uint

Unsigned 32-bit integer

wide

Signed 64-bit integer

The primary purpose of the type is to specify what values can be stored in that column. This impacts the compactness of the internal storage (really the primary purpose of the extension) as well certain operations (like sort or search) invoked on the column.

The types any and string are similar in that they can hold any Tcl value. Both are treated as string values for purposes of comparisons and operators. The difference is that the former stores the value using the Tcl internal representation while the latter stores it as a string. The advantage of the former is that internal structure, like a dictionary, is preserved. The advantage of the latter is significantly more compact representation, particularly for smaller strings.

Attempts to store values in a column that are not valid for that column will result in an error being generated.

1.4. Indices

An index into a typed column or table can be specified as either an integer or the keyword end. As in Tcl’s list commands, end specifies the index of the last element in the tarray or the index after it, depending on the command. Simple arithmetic adding of offsets to end is supported, for example end-2 or end+5.

Many commands also allow multiple indices to be specified. These may take one of two forms - a range which includes all indices between a lower and an upper bound (inclusive), and an index list which may be a list of integers, or a column of type int. This latter allows the indices returned by commands such as column search to be efficiently passed to other commands. When indices are specified as a list cause an array to be extended, the index list must include all indices beyond the current array size in any order but without any gaps. For example, if an array contains a thousand elements (the highest index thereby being 999), the index list 1001 1000 1002 is legal but 1001 1002 is not.

Note that keyword end can be used to specify a single index or as a range bound, but cannot be used in an index list.

2. Command reference

All commands are located in the tarray namespace.

2.1. Standard Options

Many commands take one or more of the standard options shown in Standard options below. The -list, -dict and -table options control the format of the returned values. The -columns option allows selection and ordering of specific columns from the table.

Table 2. Standard options

-columns COLUMNS

Selects a subset of columns from the table and their order. If this option is not specified, all columns in the table are selected as the target of the command and in the same order as in the table definition. If this option is specified, COLUMNS is a list of column indexes and names. For commands that retrieve data, like table get, only data from the specified columns is retrieved and in the column order specified in COLUMNS. For commands that modify data, only data in the specified columns is modified. The input data values are taken in the same order as specified in COLUMNS. Note that when a command invocation that causes a table to grow specifies the -columns option, all columns must be included in COLUMNS although they may be specified in any order depending on the order of the source data.

-dict

Specifies that the return values must be in the form of a dictionary keyed by the corresponding indices. The value of each key is a row which is a list each element of which is the value at that index in the corresponding column.

-list

Specifies that the return value must be in the form of a list of rows, one per index. Each row is itself a list, each element of which is the value at that index in the corresponding column.

-table

Specifies that the values are to be returned as a table. This is the default if neither -list nor -dict is specified.

2.2. Commands

table cnames TABLE

Returns the list of column names for the table.

table column TABLE COLSPEC ?NEWCOL?

If argument NEWCOL is not present, the command returns the table column specified by COLSPEC which may be either the column name or its position. If NEWCOL is specified, it must be a column of the same type and length as the table column specified by COLSPEC. The command then returns TABLE with that table column replaced by NEWCOL.

table columns TABLE ?COLSPECS?

If argument COLSPECS is not present, the command returns a list containing all the columns in the specified table. If COLSPECS is specified, it must be a list of column names or positions. In this case the returned list only contains the corresponding columns.

table create DEFINITION ROWVALUES

Returns a typed table containing a sequence of columns. DEFINITION is a list of alternating column names and column types. A column name is an identifier for a column that can be used in lieu of a column index. The type for a column must be one of the valid types described in Types.

ROWVALUES is the initial content of the table array specified as a nested list with each sublist being a row whose element types are compatible with the corresponding column types in DEFINITION.

table definition TABLE

Returns the definition of the specified table in a form that can be passed to table create.

table delete TABLE LOW HIGH

Returns a typed table with all specified rows deleted. The row indices are specified in any of the forms described in Indices.

table fill ?-columns COLUMNS? TABLE ROWVALUE LOW HIGH

Returns a typed table with specified rows set to ROWVALUE. Each element from the list ROWVALUE is assigned to the corresponding column of the table at the specified indices. Any additional elements in ROWVALUE are ignored. An error is generated if any element of ROWVALUE does not match the type of the corresponding column or if the ROWVALUE width differs from the table width. Indices are specified in any of the forms described in Indices. The size of the array will be extended if necessary.

The standard option -columns may be specified to target specific columns of the table or to match the order of columns to the supplied data.

table get ?OPTIONS? TABLE INDEXLIST

Returns the values from a table at the indices specified as a index list. Any of the standard options may be specified with this command.

table index TABLE INDEX

Returns the value of the row at the position specified by INDEX.

table inject ?-columns COLUMNS? TABLE ROWVALUES FIRST

Inserts ROWVALUES, a list of rows or a compatible table as TABLE, at the position FIRST and returns the resulting table. If FIRST is end, the values are appended to the column. In all cases, the command may extend the table if necessary.

The standard option -columns may be specified to match the order of columns to the supplied data. Note that COLUMNS must include all columns in the table as the command would not know what values to use for the unspecified columns.

table insert ?-columns COLUMNS? TABLE ROWVALUE FIRST COUNT

Inserts COUNT rows with value ROWVALUE at position FIRST and returns the new table. The rows are inserted at the specified position. In all cases, the command may extend the array if necessary.

The standard option -columns may be specified to match the order of columns to the supplied data. Note that COLUMNS must include all columns in the table as the command would not know what values to use for the unspecified columns.

table place ?-columns COLUMNS? TABLE ROWVALUES INDICES

Returns a table with the specified values at the corresponding indices. ROWVALUES may be a list of row values or a compatible table. The number of rows in ROWVALUES must not be less than the number of indices specified in INDICES and the width of each row must be the same as the width of the table. INDICES must be a index list in the one of the forms described in Indices and may extend the column if the condition listed there are satisfied.

The standard option -columns may be specified to target specific columns of the table or to match the order of columns to the supplied data.

table put ?-columns COLUMNS? TABLE ROWVALUES ?FIRST?

Returns a table with the elements starting at index FIRST replaced by the corresponding elements of ROWVALUES. ROWVALUES may be a list of values or a table of the same type. The command may extend the array if necessary. If FIRST is not specified the elements are appended.

The standard option -columns may be specified to target specific columns of the table or to match the order of columns to the supplied data.

table range ?OPTIONS? TABLE LOW ?HIGH?

Returns all values from a table in the specified index range LOW to HIGH. Any of the standard options may be specified with this command.

table reverse TABLE

Returns the table with order of elements reversed.

table size TABLE

Returns the number of rows in the table.

table slice TABLE COLUMNLIST

Returns a table containing only the specified columns from TABLE. The columns are specified by their positions or names as a list. A column must not be included more than once. The returned table contains columns in the same order as COLUMNLIST.

table vcolumn TABLEVAR COLSPEC ?NEWCOL?

Returns or sets a specified column in the table contained in the variable TABLEVAR. If argument NEWCOL is not present, the command returns the table column specified by COLSPEC which may be either the column name or its position. TABLEVAR is not modified.

If NEWCOL is specified, it must be a column of the same type and length as the table column specified by COLSPEC. The command then replaces that column in TABLEVAR with NEWCOL and returns the variable’s new value.

table vdelete TABLEVAR LOW HIGH

Deletes rows from the table in variable TABLEVAR. The new value is assigned back to the variable. The resulting value of the variable (which may differ because of traces) is returned as the result of the command. Indices are specified in any of the forms described in Indices.

table vfill ?-columns COLUMNS? TABLEVAR ROWVALUE LOW HIGH

Set the elements of the table in variable TABLEVAR at the specified indices to ROWVALUE. The new value is assigned back to the variable. The resulting value of the variable (which may differ because of traces) is returned as the result of the command.

The standard option -columns may be specified to target specific columns of the table or to match the order of columns to the supplied data.

See the table fill command for more information.

table vinject TABLEVAR ROWVALUES FIRST

Inserts ROWVALUES, a list of rows or a compatible table as the table in variable TABLEVAR, at the position FIRST and stores the result back in TABLEVAR. If FIRST is end, the values are appended to the column. In all cases, the command may extend the array if necessary. The resulting value of the variable (which may differ because of traces) is returned as the result of the command.

The standard option -columns may be specified to match the order of columns to the supplied data. Note that COLUMNS must include all columns in the table as the command would not know what values to use for the unspecified columns.

table vinsert ?-columns COLUMNS? TABLEVAR ROWVALUE FIRST COUNT

Inserts COUNT rows with value ROWVALUE at position FIRST in the table stored in variable TABLEVAR. The new value is assigned back to the variable. The resulting value of the variable (which may differ because of traces) is returned as the result of the command.

The standard option -columns may be specified to match the order of columns to the supplied data. Note that COLUMNS must include all columns in the table as the command would not know what values to use for the unspecified columns.

table vplace ?-columns COLUMNS? TABLEVAR ROWVALUES INDICES

Modifies a table stored in the variable TABLEVAR with the specified values at the corresponding indices. The new value is assigned back to the variable. The resulting value of the variable (which may differ because of traces) is returned as the result of the command.

The standard option -columns may be specified to target specific columns of the table or to match the order of columns to the supplied data.

See the command table place for other details.

table vput ?-columns COLUMNS? TABLEVAR ROWVALUES FIRST

Modifies a variable TABLEVAR containing a typed column. The elements of the column starting at index FIRST are replaced by the corresponding elements of ROWVALUES. If FIRST is not specified the elements are appended to the array. The new value is assigned back to the variable. The resulting value of the variable (which may differ because of traces) is returned as the result of the command.

The standard option -columns may be specified to target specific columns of the table or to match the order of columns to the supplied data.

See the command table put for other details.

table vreverse TABLEVAR

Reverses the order of elements in the table in variable TABLEVAR, stores it back in the variable. The result of the command is the resulting value stored in the variable.

table width TABLE

Returns the number of columns in the table.