The following data types are available[1]:
Fields are defined by the data type followed by the field name, for example...
double longitude
...to define a double-precision field named longitude.
Field definitions can followed by one or more key-value pairs that define additional attributes about the field. Supported attributes include
If indexed is specified with a true (nonzero) value, the code generated for the speed table will include support for generating, maintaining, and using a skip list index on the field being defined.
Indexed traversal can be performed in conjunction with the speed table's search functions to accelerate searches and avoid sorts. Defaults to "indexed 0" aka the field is not generated with index support.
Indexed support is not provided for boolean fields.
If notnull is specified with a true (nonzero) value, the code generated for the speed table will have code for maintaining an out-of-band null/not-null status suppressed, resulting in a substantial performance increase for fields for which out-of-band null support is not needed. Defaults to "notnull 0" aka null values are supported.
If default is specified, the following value is defined as the default value and will be set into rows that are created when the field does not have a value assigned.
There is no default default value, however if no default value is defined and the field is declared as notnull, strings will default to empty and numbers will default to zero.
Currently only valid for fixedstring fields, length specifies the length of the field in bytes. There is no default length; length must be specified for fixedstring fields.
If unique is specified with a true value, the field is defined as indexed ,and an index has been created and is in existence for this field for the current table, a unique check will be performed on this field upon insertion into the speed table.
There are additional special fields that all tables may have:
If the key is not given an explicit alias in the table, then there is an additional field named _key automatically created.
This is a boolean, set to 1 when any record in the field is modified. It may be manually cleared.
Bug: Unique checks are not currently being performed as of 12/31/06.
Bug: String search matching functions don't yet work for fixedstrings and fixedstrings have not had a lot of use as of 12/31/06.
In addition, "C Filters" can be created that can be used to speed up searching ctables with fragments of native code. They look much like field definitions, for a "field type" of "cfilter", but will not show up in the ctable as a field and only have the one parameter, a code fragment.
cfilter distance args {type name type name} code { ... c code goes here ... }
This code fragment is not guaranteed to be a separate c function, but it can be conceptually thought of as one with the following declaration:
int table_filter_name(TCL_Interp *interp, struct ctableTable *ctable, struct ${ctable_name} *row, Tcl_Obj *filter, int sequence);
If arguments are provided, then code is transparently generated to extract the arguments from the Tcl Object. If only one argument is provided, the filter parameter will be used as a whole. If more than one argument is provided, the filter parameter will be treated as a list. The types of the arguments are Tcl types, the actual C variable will be a "char *", a "double", an "int", or a "long" depending on the type provided.
As a special case, "args {list argc argv}" will extract an integer argc (or whatever name is provided) and a list of TclObjs argv.
The filter can examine any fields in the CTable by name, as "row->fieldname". It can also look at "row->_fieldname_IsNull" to see if the field is null (has never been assigned a value, or has been assigned the table's null value string). It should return TCL_OK for a matched row, TCL_CONTINUE for a missed match, TCL_BREAK to terminate the search at this point (here there be dragons), and TCL_ERROR for an error.
To speed up filters, a non-zero sequence number is provided. This ID is unique to each search operation: if it hasn't changed, then the filter object hasn't changed, and any calculations based on the filter object (such as parsing a list of parameters) can be re-used.
Helper functions can be added in "ccode" blocks defined before any speedtables.
[1] Additional data types can be added, although over Speed Tables' evolution it has become an increasingly complicated undertaking.