Programmer Guide/Shell Items/Table/Introducing Table Items

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

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 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', which safeguards against the possibility that the value being returned is an STx keyword and will be interpreted as a command!

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 (as opposed to simple tables, extended tables and directory tables) are an optimized variant of the extended table restricted to storing numerical data only. Otherwise, they behave exactly like the normal extended table.

For a thorough introduction into the matter of table items, see Introducing Table Items.

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

Sound file Directory Table

Directory tables (as opposed to simple tables, extended tables and parameter tables) store and manage sound file information. On creation of a directory table, fields for the name of the soundfile and for its beginning and length are automatically created. This type of table can be used with the LOAD SOUNDFILE command.

For a thorough introduction into the matter of table items, see Introducing Table Items.

Show Format

Programmer Guide/Shell Items/Table/Show Format

Write Format

Programmer Guide/Shell Items/Table/Write Format

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.

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 using the assignment operator:

// assign a string to the second entry
$#table[1] := set 'a string value'
// remove all entries and assign this number to
// the first entry
$#table := 1000
// append this number to the table
$#table[$#table[]] := 1001