Programmer Guide/Shell Items/Table/Introducing Table Items

Table Item
INTRODUCTION	NEW	SET	ATTRIBUTES

The STx table item is designed to store string or numerical data in rows and columns. The table item provides search and comparison functions.

Kinds of Tables

Simple Table

Simple tables store every entry as a string. There are no columns or fields. Case-sensitive character searching is supported as well as entry tagging. The display formats (show and write format) have no relevance for simple tables.

Simple Table Example

This example demonstrates basic use of a simple table item.

[macro simple_table_example]
        //
        // create a simple table item
        //
        #t := new table *
        if '$#t[?]' != 'table' em $RC ; $EMSG
        //
        // add some data
        //
        $#t * 'the first entry'
        $#t * 'the second entry with some numbers - 0, 1, 2, 3'
        $#t * 'the third entry'
        //
        // remove some data
        //
        $#t 0 /Delete // remove the first line
        //
        // display the table contents
        //
        showitem $#t
        //
        // clean up
        //
        delete $#t
exit

Extended Table

Extended tables are able to store data of mixed types (integers, floating-point numbers, strings, and STx names) in one or more columns, each column being also known as a field. Fields may be assigned names which, in turn, may be used for accessing the content of the respective field. Regardless of a field being assigned a name, its content may always be referred to by its zero-based index.

#value := set $#table[$#entryIndex,$#fieldName]

or

#value := set $#table[$#index,$#fieldIndex]

In other words, you can access any value in a table with the following syntax:

#value := set $#table[$#row,$#col]

The extended table makes use of the show and write format to format the data for the screen and for reading and writing the data to file.

Note the use of the keyword set, safeguarding against the possibility that the value being returned is an STx keyword. Should that be the case, omitting set would cause the respective command to be executed - most likely not the desired effect.

Extended Table Example

This example demonstrates basic use of an extended table item.

[macro extended_table_example]
    //
    // create an extended table item
    //
    #t := new table * * /Extended string:str integer:int number:num
    if '$#t[?]' != 'table' em $RC ; $EMSG
    //
    // add some data
    //
    $#t * str 'first' int 1 num 2.3
    $#t * str 'second' int 2 num 4.7
    $#t $#t[] str 'third' int 3 num 5.9
    $#t $#t[!nrow] 'fourth'
    $#t 5 str 'sixth' int 6 num 9.9 // 5th entry is left empty
    //
    // remove some data
    //
    $#t 0 /Delete // remove the first line
    //
    // display the table contents
    //
    showitem $#t
    //
    // format data and redisplay
    //
    $#t config str 1 0 1 '%.5s  ' * * * 'string' 8
    if '$rc' > 0 em $rc ; $EMSG
    $#t config int 0 // hide 'int' column
    if '$rc' > 0 em $rc ; $EMSG
    $#t config num 1 1 2 '%f' 1 -1 * 'number' 8
    if '$rc' > 0 em $rc ; $EMSG
    //
    // display the table contents
    //
    showitem $#t
    //
    // clean up
    //
    delete $#t
exit

Parameter Table

Parameter tables are an optimized variant of the extended table restricted to storing numerical data only (integer and floating-point). Otherwise, they behave exactly like the normal extended table.

Parameter Table Example

This example demonstrates basic use of a parameter table item.

[macro parameter_table_example]
    //
    // create an extended table item
    //
    #t := new table * 10 /P
    if '$#t[?]' != 'table' em $RC ; $EMSG
    //
    // add some data
    //
    //  initialize 10x10 matrix
    $#t := eval init($#t[!ncol],$#t[!ncol],0)
    //  replace first line
    $#t[0,*] := eval fill(10,0,1)
    //  replace fifth column
    $#t[*,4] := eval fill(10,$#t[0,4],1)
    //  transpose the matrix
    $#t := eval trn($#t)
    //
    // display the table contents
    //
    showitem $#t
    //
    // clean up
    //
    delete $#t
exit

Soundfile Directory Table

A table designed to be used to manage sound file information. On creation, fields for the sound file name, beginning and length of the sound file are automatically created. This type of table can be used with the LOAD SOUNDFILE command.

Display Formats

The Show Format

A table can be configured to display it's data using a c-style format string. This format is called the 'show' format and is used by the listbox and listview dialog controls when displaying table data. See Configuring a table field for details.

The Write Format

In addition to the show format, a table also has a configurable format for reading from and writing to file; this is called the 'write' format. See Formatting table fields for configuration details.

Note that the show format can also be used to read from and write to file, if so configured (see the MODE command).

Tagged and untagged table entries

Entries in a table can be either tagged or untagged. By default every entry is untagged. A table can be configured to display tagged entries only (see showing and hiding table entries). If so configured, untagged entries cannot be accessed, deleted or displayed (e.g. in a dialog listbox).

You can tag or untag individual entries with the command $#table $#index /Tag or $#table $#index /Untag.

You can switch between table modes displaying all entries ($#table /All) and only tagged entries ($#table /T).

Selected Entries

When a table is used in conjunction with a dialog control (e.g. a listbox), tagged entries are displayed as selected entries. You can retrieve the number of selected entries with $#table[!TAGGED]. If you would like to retrieve the selected entries, you must hide non-selected entries ($#table /tagged) and then you can loop through the visible rows.

Counting Table Entries

There are two ways to retrieve the number of table entries:

$#table[!nrow]

or the special syntax

$#table[]

Assigning table entries

You can assign values to table entries by using the SET table command or by using the assignment operator.

Here are some examples:

// assign a string to the second entry, using the assignment operator
$#table[1] := set 'a string value'

// assign a string to the fifth entry, using the SET command
SET $#table 1 'another string value'

// assigning a string to the eleventh entry, using the implicit SET command
$#table 1 'yet another string!'

// remove all entries and assign this number to
// the first entry
$#table := 1000

// append this number to the table
$#table[$#table[]] := 1001