Introduction
This is the opposite direction where member contents of structures or arrays are transferred into tables. As long the transaction operator has no assignment operator (described in the next sections further below), then the contents in the destination row will be cleared entirely before writing. Generally, only one nesting level (direct members of specified variables) will be used for the data transfer. Following rules apply:
- Only simple and horizontal table accesses are allowed. Vertical table accesses and matrix table accesses will be rejected and cause exceptions.
- Use '..' or keep blank to specify all column entries in the specified row, e.g. [t:..,1] or [t:,1]. Otherwise only the specified columns will be written.
- Partial table specifications are allowed, provided the context information for the table and row number is available (e.g. inside the function parameters of the table process() call)
- Only one level of array members or structure members will be transferred to the table.
- Further nested members will not be considered and transferred.
- The base variable will also not be considered and transferred (i.e. the name of the table will not be altered).
- During the transaction, the values will be converted to strings automatically because tables maintain all contents as strings.
- Transactions of variables without members (e.g. simple variables, zero members variables) result in no data transfers. Only row in the destination table will be cleared.
- Structure members with blank member names (so called default members) correspond with blank headers
- Open-ended ranges: Additional table columns with header names are only added if open-ended ranges are specified for the table row. Open-ended ranges apply in following cases:
- [t:..,1] - All columns under existing headers selected. Further columns may be added
- [t:,1] - All columns in the current row are selected. Further columns may be added
- [t:3..,1] - All columns beginning with column 3 (example value) till end of row.
Structures to tables:
The member names will be matched with the existing column header names, provided they are part of the table specification
(where whole row, a set of columns, a range or just one column is defined). If a member name cannot be matched with any column header, then an additional
header with that name will be added to the table and the data will be written into the designated field below.
Arrays to tables:
The array members will be written into the table fields as defined in the table specification (whole row, set of columns, a range or just one column).
Normally, the members are written to the table from left to right except if a set of columns is specified. In this case, the sequence inside the set will apply.
If the array contains more elements than the number of columns (header names) provided, then the remaining elements will not be written into the table unless
open-ended ranges have been specified, for example: [t:5..,1], [t:..,1], [t:,1].
The following table applies to transactions from a table row (example: table name 't', row 1, all columns) to a variable.
| Transaction | Symbol | Explanation | Description |
|---|---|---|---|
| Copy | <== | [t:..,1] <== a[]; | Step 1: Checks that exactly one table row and one or more or all columns are specified. Step 2: Clears all contents in the specified table row Step 3: Data transfer from variable to table as described above. Note: The base variable will not be copied. |
| Copy Members | <==^ | [t:..,1] <==^ a[]; | Same mas copy-transaction. |
| Move | <<= | [t:..,1] <<= a[]; | Steps 1-3: Like the copy-transaction Step 4: Deletes variable b[] entirely including its members. If a member variable is specified on the right-hand side, then that member variable with its sub-members will be deleted. |
| Move Members | <<=^ | [t:..,1] <<=^ a[]; | Steps 1-3: Like the copy-members-transaction Step 4: Deletes all members and sub-members of variable b[], but the base variable remains unaffected. If a member variable is specified on the right-hand side, then those sub-members will be deleted. |
| Swap | <=> | [t:..,1] <=> a[]; | The contents in the member variable and the table row will be exchanged. Void value will be assigned to the base variable. |
| Swap Members | <=>^ | [t:..,1] <=>^ a[]; | The contents in the member variable and the table row will be exchanged. The base variable will be preserved. |
Copy Transaction Example
table initialize( animals,
{ { Name, Leg count, Special ability },
{ Owl, 2, Night vision },
{ Dog, 4, Sensitive nose },
{ Ape, 2 or 4, Relatively smart } } );
structure( animal1[], { Name, Leg count, Weapon }, { Snake, 0, poison } );
structure( animals1[Weapon], { venom, muscles }, { rattle snake, boa constrictor } ); // Nested, not copied into table
structure( animal2[], { Name, Leg count, Weapon, Special ability, size }, { Tick, 6, diseases, tricky to remove, tiny} );
[ animals : Name, Owl, .. ] <== animal1[]; // All columsns are written, plus new ones
[ animals : Name, Ape, {Name, Leg count} ] <==^ animal2[]; // Only name and leg count are written
table list ( animals ); 0 : Name | Leg count | Special ability | Weapon
1 : Snake | 0 | | poison
2 : Dog | 4 | Sensitive nose |
3 : Tick | 6 | |
Copy Transaction Example from an array
table initialize( animals,
{ { Name, Leg count, Special ability },
{ Owl, 2, Night vision },
{ Dog, 4, Sensitive nose },
{ Ape, 2 or 4, Relatively smart } } );
array( animal1[], { Boa, 0, Kills by constricting, Likes rats, and mice } ); // Addt'l colum without header added
[ animals : .., 1 ] <== animal1[]; // All columsns are written, plus new ones
table list ( animals ); 0 : Name | Leg count | Special ability | |
1 : Boa | 0 | Kills by constricting | Likes rats | and mice
2 : Dog | 4 | Sensitive nose | |
3 : Ape | 2 or 4 | Relatively smart | |
Move Transaction Example
table initialize( animals,
{ { Name, Leg count, Special ability },
{ Owl, 2, Night vision },
{ Dog, 4, Sensitive nose },
{ Ape, 2 or 4, Relatively smart } } );
structure( animal1[], { Name, Leg count, Weapon }, { Snake, 0, poison } );
structure( animal1[Weapon], { venom, muscles }, { rattle snake, boa constrictor } ); // Nested, not copied into table
structure( animal2[], { Name, Leg count, Weapon, Special ability, size }, { Tick, 6, diseases, tricky to remove, tiny} );
animal2[] = Pets;
[ animals : Name, Owl, .. ] <<= animal1[]; // All columns are written, plus new ones
[ animals : Name, Ape, {Name, Leg count} ] <<=^ animal2[]; // Only name and leg count are written
table list ( animals );
echo("animal1[] existing? ", existing(animal1[]) );
see(animal2[]); 0 : Name | Leg count | Special ability | Weapon
1 : Snake | 0 | | poison
2 : Dog | 4 | Sensitive nose |
3 : Tick | 6 | |
animal1[] existing? false
animal2[] Pets (softquoted string,full access)
Swap Transaction Example
table initialize( animals,
{ { Name, Leg count, Special ability },
{ Owl, 2, Night vision },
{ Dog, 4, Sensitive nose },
{ Ape, 2 or 4, Relatively smart } } );
structure( animal1[], { Name, Leg count, Weapon }, { Snake, 0, poison } );
structure( animal2[], { Name, Leg count, Weapon, Special ability }, { Wolf, 4, teeth, teamwork } );
animal1[] = "Was a snake";
animal2[] = "Was a wolf";
[ animals: Name, Dog, .. ] <=> animal1[]; // Pick up entire row
[ animals: Name, Owl, {Name,Special ability} ] <=>^ animal2[]; // E.g. leg count not included
see( animal1[] );
see( animal2[] );
table list( animals ); // Snake, Wolf, Ape. Additional column included (weapon)
animal1[] animals (quoted string,full access)
Leg count 4 "4" (numeral,full access)
Name Dog (quoted string,full access)
Special ability Sensitive nose (quoted string,full access)
animal2[] Was a wolf (quoted string,full access)
Name Owl (quoted string,full access)
Special ability Night vision (quoted string,full access)
0 : Name | Leg count | Special ability | Weapon
1 : Wolf | | teamwork |
2 : Snake | 0 | | poison
3 : Ape | 2 or 4 | Relatively smart |