Function Names
table write cells, table write cells seleted rowsDescription
This function writes the contents into a specific location in the table. The contents may be one of the following:
- Scalar value (number, string, date, boolean, etc.)
- set containing values. The values will be written into the table below each other.
- 2-level nested sets: Values in nested sets are written into the table next to the right of each other.
- Use the horizontal() function to force a set of values to be written horizontally to the right and not downard.
This function provides some options which can be specified in the last function parameter to make write accesses even smarter than accessing tables directly:
| Keyword | Notes | Description |
|---|---|---|
| overwrite if blank | See 1 | Overwrite individual cells if the contents inside are blank |
| overwrite nonblanks | " | Overwrite individual cells if the data to be written are not blank |
| refuse overwriting | Refuse overwriting if any of the cells would need to be overwritten | |
| stay inside | See 2 | The write access of individual values will only happen if the cells are inside the table |
| strictly stay inside | " | The write access of all values will only happen if all celles to be written are inside the table |
| append | See 3 | The new value is appended to the existing value |
| strip | " | The new value is 'subtracted' from the existing value. Only the first matching string will be stripped. |
1. Combination of both keywords 'overwrite if blank' and 'overwrite nonblanks' will be refused.
2. Combination of both keywords 'stay inside' and 'strictly stay inside' will be refused.
2. Combination of both keywords 'append' and 'trip' will be refused.
If multiple rows and/or multiple columns are specified, then the write procedure will be repeated at every row + column number combination provided.
Call as: procedure or function
Restrictions
Indirect parameter passing is disabled
This function provides a table context for partial table specifications with table name and row number for selected function parameters
Parameter count
1-3
Parameters
| No. | Type | Description |
|---|---|---|
| 1. input |
string | target table name The target table must exist. |
| 2. input |
expression | Row number Applicable to table write cells |
| Alt. 2 code |
expression :string |
Expression to select rows Applicable to table write cells selected rows: |
| 3. input |
table columns | Header names and/or column numbers See table columns as function parameters for general ruling for this parameter.
|
| 4. input |
all types set |
Values to write Scalar values (not sets) will be written directly into the destination. 1-level paramter sets will be written from the specified location downard. 2-level sets: Multiple rows with multple columns will be written. |
| Opt. 5. input |
string set |
options See the table described in the function body. |
Return value
| Type | Description |
|---|---|
| numeral | Number cells written. 0 is returned if no cell has been overwritten or write access has been refused. Every successful write access (including partial ones) will be counted. |
Examples
table initialize( a,
{ { Col 0, Col 1, Col 2, Col 3, Col 4, Col 5, Col 6 },
{ Dog, '', Hog, '', '', Pig },
{ '', '', '', '', '', '' },
{ Cat, '', '', Gnu, Ape, '' },
{ '', '', '', '', '', '' },
{ Bee, '', '', '', '', Fly },
{ '', '', '', '', '', '' },
} );
more animals[] = {{ Rat, Olm }, Emu };
table list (a);
echo("Writing: 'Rat' to row 1 col 5 and further animals below");
table copy table (a,t);
table write cells( t, 1, 5, Rat );
table write cells selected rows( t, ([Col 0]=Cat,Bee), {Col 1, Col 4}, more animals[], overwrite if blank );
table list (t);
echo("Write the animals but refuse overwriting if any destination cell is occupied:");
table copy table (a,t);
table write cells selected rows( t, ([Col 0]=Cat,Bee), {Col 1, Col 4}, more animals[], refuse overwriting );
table list (t);
echo("Write beyond end of table");
table copy table (a,t);
table write cells( t, 1, 5, more animals[] ); // Writes all animals
table write cells( t, 3, 5, more animals[], strictly stay inside ); // Writes no animals
table write cells( t, 5, 5, more animals[], stay inside ); // Write 2 animals
table list (t);
Output
0 : Col 0 | Col 1 | Col 2 | Col 3 | Col 4 | Col 5 | Col 6
1 : Dog | | Hog | | | Pig |
2 : | | | | | |
3 : Cat | | | Gnu | Ape | |
4 : | | | | | |
5 : Bee | | | | | Fly |
6 : | | | | | |
Writing: 'Rat' to row 1 col 5 and further animals below
0 : Col 0 | Col 1 | Col 2 | Col 3 | Col 4 | Col 5 | Col 6
1 : Dog | | Hog | | | Rat |
2 : | | | | | |
3 : Cat | Rat | Olm | Gnu | Ape | Olm |
4 : | Emu | | | Emu | |
5 : Bee | Rat | Olm | | Rat | Fly |
6 : | Emu | | | Emu | |
Write the animals but refuse overwriting if any destination cell is occupied:
0 : Col 0 | Col 1 | Col 2 | Col 3 | Col 4 | Col 5 | Col 6
1 : Dog | | Hog | | | Pig |
2 : | | | | | |
3 : Cat | Rat | Olm | Gnu | Ape | |
4 : | Emu | | | | |
5 : Bee | Rat | Olm | | | Fly |
6 : | Emu | | | | |
Write beyond end of table
0 : Col 0 | Col 1 | Col 2 | Col 3 | Col 4 | Col 5 | Col 6
1 : Dog | | Hog | | | Rat | Olm
2 : | | | | | Emu |
3 : Cat | | | Gnu | Ape | |
4 : | | | | | |
5 : Bee | | | | | Rat |
6 : | | | | | Emu |