NEW TABLE

From STX Wiki
Jump to navigation Jump to search
Table Item
INTRODUCTION NEW SET ATTRIBUTES

You can create a new shell table item with the NEW TABLE command.

Normal Creation

NEW TABLE id [ /Extended|Directory|Parameter ] 
             [ nFields|* 
             [ field0|* field1|* … ]] [ /1 /I /N ] [ /G /L ]

Create a new table. This command can be used to create a simple table, an extended table, a directory table or a parameter table. The fields must be defined and configured before the table can be used (see Defining a table field and Configuring a table field). If the parameters fieldX are used, the table can be defined on creation (saving you the SET table DEFINE command).

id
The id to use for the new table item. If an asterisk is used, the id is automatically generated and stored in the local variable #new.
nFields
The number of fields. If nFields is not specified and no table type option (/E|P|D) specified either, then a simple table is created. If a table type option is specified but nFields is not, 1 field is defined. If nFields is an asterisk and the fieldX parameter is not specified, then the default number of fields is 1. If fieldX field definitions are specified and nFields is an asterisk, then the number of fields is calculated.
fieldX
Syntax: {typeX:}nameX or typeX:nameX:countX
typeX - The data-type (see SET table DEFINE for details). typeX is optional; if it is used, it must be separated from nameX by a colon ':'. The default type for parameter tables (option /Parameter) is NUMBER, otherwise the default is STRING.
nameX: The field name
countX: repeat nameX countX times (i.e. nameX will be used to define multiple fields: nameX0 nameX1 nameX2 …).
If fieldX is an asterisk, this field is not defined.
/Extended
If specified, an extended table is created.
/Directory
If specified, a soundfile directory table is created. Three fields are added automatically to the specified number of fields:
0=NAME (Name)
1=BEGIN (Integer)
2=LENGTH (Integer)
/Parameter
If specified, a table which can only store numbers (Integer, Number) is created. Memory usage and access is optimized.
/1
This version of NEW TABLE automatically changes the table mode to 'data' if all fields are defined in the NEW TABLE command. If you would like to automatically change to 'data' mode even though not all field definitions have taken place in the NEW TABLE command, please use this /1 option. Note that at least one field must have been defined in this command.
/Initial=n
If specified, memory for n entries is allocated when the first entry is created. This can improve performance immensely, if you know roughly how many entries you are going to use, since memory is allocated once, rather than being incremented regularly (and copied from the old to the new location). Note that this is particularly useful for parameter tables, since the size of the entry is known and therefore all the memory can be accurately allocated.
/N=n
Memory for table entries is allocated in blocks. When the allocated memory runs out, a new block is allocated. You can specify how big the block is in entries (n). The minimum and default value is 50.
/G
Garbage collection. If specified, the item is automatically deleted when exiting the macro.
/L
If specified, errors will generate warning messages rather than error messages. See The Silent Flag for details.

The table mode is automatically set to 'data', if

  1. all fields are defined in the NEW TABLE command; or
  2. at least one field is defined in the NEW TABLE command and the flag /1 is specified.

Current Soundfile

NEW TABLE id /Soundfiledirectory [ /G ]

Attach a (temporary) table to the directory table of the current soundfile. To set the current soundfile, use the command BSF SELECT.

/G
Garbage collection. If specified, the item is automatically deleted when exiting the macro
/L
If specified, errors will generate warning messages rather than error messages. See The Silent Flag for details.

Creating a Table as the Copy of an existing Table

NEW TABLE id baseTableItem|baseValueItem [ fieldName ] /Copy [ /All|Tagged [ /tRanspose ]] [ /I /N ]

Create a new table with the same field definitions and configuration settings as the table baseTableItem. You can copy the contents with the flags /All (copy all entries) or /Tagged (copy tagged entries). The tagged state is copied in both cases. The table is transposed if the /R flag is specified. If you want to transpose the base table, all fields must be numeric. Alternatively, you can create a new table and fill it with the values in the value item baseValueItem.

baseTableItem
A table item id.
baseValueItem
A value item id.
fieldName
The base name for field name creation if the option /R is used (e.g. if the base table has two entries and fieldName is fn, the fields fn0 and fn1 are created).
/Copy
Copy the contents of the base item to the new table. This option is mandatory.
/tRanspose
Copy a transposed version of the base item data (i.e. make the rows the columns and the columns the rows). All fields must be numeric. If the /tRanspose option proves too slow for your use-case, the faster EVAL trn should be used instead.
/All|Tagged
Copy either all the entries in baseTableItem (/A) or just the tagged entries (/T). Note that if neither option is specified, only the field definitions are copied. These options are only applicable when copying from a table item.
/Initial=n
If specified, memory for n entries is allocated when the first entry is created. This can improve performance immensely, if you know roughly how many entries you are going to use, since memory is allocated once, rather than being incremented regularly (and copied from the old to the new location). Note that this is particularly useful for parameter tables, since the size of the entry is known and therefore all the memory can be accurately allocated.
/N=n
Memory for table entries is allocated in blocks. When the allocated memory runs out, a new block is allocated. You can specify how big the block is in entries (n). The minimum and default value is 50.