View source for Programmer Guide/Shell Items/Table/NEW TABLE

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
{{Table Item}}
You can create a new shell table item with the <code>NEW TABLE</code> command.

=== Normal Creation ===

 NEW TABLE <var>id</var> [ /Extended|Directory|Parameter ] 
              [ <var>nFields</var>|* 
              [ <var>field0</var>|* <var>field<sub>1</sub></var>|* &hellip; ]] [ /1 /I /N ] [ /G /L ]

Create a new table. This command can be used to create a [[Programmer_Guide/Concepts/Simple_table|simple table]], an [[Programmer_Guide/Concepts/Extended_table|extended table]], a [[Programmer Guide/Concepts/Directory table|directory table]] or a [[Programmer_Guide/Concepts/Parameter_table|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 <var>field<sub>X</sub></var> are used, the table can be defined on creation (saving you the <code>[[Programmer_Guide/Shell_Items/Table/SET_TABLE#DEFINE|SET table DEFINE]]</code> command).

;<var>id</var>: 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 <var>#new</var>.
;<var>nFields</var>: The number of fields. If <var>nFields</var> is not specified and no table type option (/E|P|D) specified either, then a [[Programmer_Guide/Concepts/Simple_table|simple table]] is created. If a table type option is specified but <var>nFields</var> is not, 1 field is defined. If <var>nFields</var> is an asterisk and the <var>field<sub>X</sub></var> parameter is not specified, then the default number of fields is 1. If <var>field<sub>X</sub></var> field definitions are specified and <var>nFields</var> is an asterisk, then the number of fields is calculated.
;<var>field<sub>X</sub></var>:Syntax: {<var>type<sub>X</sub></var><code>:</code>}<var>name<sub>X</sub></var> or <var>type<sub>X</sub></var>:<var>name<sub>X</sub></var>:<var>count<sub>X</sub></var>
:<var>type<sub>X</sub></var> - The data-type (see <code>[[Programmer_Guide/Shell_Items/Table/SET_TABLE#DEFINE|SET table DEFINE]]</code> for details). <var>type<sub>X</sub></var> is optional; if it is used, it must be separated from name<sub>X</sub> by a colon ':'. The default type for [[Programmer_Guide/Concepts/Parameter_table|parameter tables]] (option <code>/Parameter</code>) is <code>NUMBER</code>, otherwise the default is <code>STRING</code>.
::<var>name<sub>X</sub></var>: The field name
::<var>count<sub>X</sub></var>: repeat <var>name<sub>X</sub></var> <var>count<sub>X</sub></var> times (i.e. <var>name<sub>X</sub></var> will be used to define multiple fields: <var>name<sub>X0</sub></var> <var>name<sub>X1</sub></var> <var>name<sub>X2</sub></var> &hellip;).
::If <var>field<sub>X</sub></var> is an asterisk, this field is not defined.
;<var>/Extended</var>: If specified, an [[Programmer_Guide/Concepts/Extended_table|extended]] table is created.
;<var>/Directory</var>: If specified, a [[Programmer Guide/Concepts/Directory table|soundfile directory table]] is created. Three fields are added automatically to the specified number of fields:
{| style="margin-left:1.5em;"
 |-
 || 0=NAME || (Name)
 |-
 || 1=BEGIN || (Integer)
 |-
 || 2=LENGTH || (Integer)
 |}
;<var>/Parameter</var>: If specified, a table which can only store numbers (Integer, Number) is created. Memory usage and access is optimized.
;<var>/1</var>: This version of <code>NEW TABLE</code> automatically changes the table mode to 'data' if all fields are defined in the <code>NEW TABLE</code> command. If you would like to automatically change to 'data' mode even though not all field definitions have taken place in the <code>NEW TABLE</code> command, please use this /1 option. Note that at least one field must have been defined in this command.
;<var>/Initial=n</var>: If specified, memory for <code>n</code> 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 [[Programmer_Guide/Concepts/Parameter_table|parameter tables]], since the size of the entry is known and therefore all the memory can be accurately allocated.
;<var>/N=n</var>: 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 (<code>n</code>). The minimum and default value is <code>50</code>.
;<var>/G</var>: Garbage collection. If specified, the item is automatically deleted when exiting the macro.
;<var>/L</var>: If specified, errors will generate warning messages rather than error messages. See [[Programmer_Guide/Command_Reference_Options/Silent|The Silent Flag]] for details.

The table mode is automatically set to 'data', if
# all fields are defined in the <code>NEW TABLE</code> command; or
# at least one field is defined in the <code>NEW TABLE</code> command ''and'' the flag <code>/1</code> is specified.

=== Current Soundfile ===

 NEW TABLE <var>id</var> /Soundfiledirectory [ /G ]

Attach a (temporary) table to the [[Programmer Guide/Concepts/Directory table|directory table]] of the current soundfile. To set the current soundfile, use the command [[Programmer_Guide/Macro_Library/BSF#Select|<code>BSF SELECT</code>]].

;<var>/G</var>: Garbage collection. If specified, the item is automatically deleted when exiting the macro
;<var>/L</var>: If specified, errors will generate warning messages rather than error messages. See [[Programmer_Guide/Command_Reference_Options/Silent|The Silent Flag]] for details.

=== Creating a Table as the Copy of an existing Table ===

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

Create a new table with the same field definitions and configuration settings as the table <var>baseTableItem</var>. 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 <var>baseValueItem</var>.

;<var>baseTableItem</var>: A table item id.
;<var>baseValueItem</var>: A value item id.
;<var>fieldName</var>: The base name for field name creation if the option /R is used (e.g. if the base table has two entries and <var>fieldName</var> is <code>fn</code>, the fields <code>fn0</code> and <code>fn1</code> are created).
;<code>/Copy</code>: Copy the contents of the base item to the new table. This option is mandatory.
;<code>/tRanspose</code>: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 <code>/tRanspose</code> option proves too slow for your use-case, the faster <code>[[Programmer_Guide/Command_Reference/EVAL/trn|EVAL trn]]</code> should be used instead.
;<code>/All|Tagged</code>:Copy either all the entries in <var>baseTableItem</var> (/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.
;<code>/Initial=<var>n</var></code>:If specified, memory for <var>n</var> 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 [[Programmer_Guide/Concepts/Parameter_table|parameter tables]], since the size of the entry is known and therefore all the memory can be accurately allocated.
;<code>/N=<var>n</var></code>: 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 (<var>n</var>). The minimum and default value is <code>50</code>.