B4P Reference

Function Names

table insert selected rows, table insert above selected rows

Description

table insert selected rows inserts rows below the selected rows.
table insert above selected rows inserts rows above the selected rows.

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

2 - 5

Parameters

No.	Type	Description
Opt. 1. input	string	Name of existing table
Opt. 2. code	expression :string	Expression to select rows Specify the conditions or rules to select the rows. See expressions to select rows. The table context for partial table specifications is available for referencing just the columns easily. Example: [Year]>=2022. Attention: Comparison operators = and <> (instead of == and !=) may hijack the next function parameters for its own use as additional comparison operands, e.g. a[]=1,3,5. As long this comparison is not made in the last function parameter, then put parentheses around them, e.g. ... , (a[]=1,3,5), ....
Opt. 3. code	expression :string	Expression to specify number of rows Specify a fixed value or an expression returning a number. This expression will be calculated for all selected rows according to the 2nd function parameter. The table context for partial table specifications is available for referencing just the columns easily. Example: [Year]+1. Default value: 1
Opt. 4. input	table columns	Existing columns to copy See table columns as function parameters for general ruling for this parameter. Specific rules apply for this function: Any number of header names and column numbers may be specified The columns listed must be unique, i.e. not repeated. Default value: (None)
Opt. 5. input	table column	Index column See table columns as function parameters for general ruling for this parameter. Specific rules apply for this function: Max 1 header names or column number may be specified If the column is not existing, then it will created and added after the right-most existing column What will be written into the index column if n rows are inserted below or above: With table insert selected rows, 0 is assigned to the original row. 1...n are assigned to the new rows inserted. With table insert above selected rows, n is assigned to the original row. 0...n-1 are assigned to the rows above.

Return value

Type	Description
numeral	Number of rows identified Only the number of identified rows (and not the number of inserted rows) is returned. -1 is returned if table is empty.

Examples

  table initialize ( table 1,

  { { Animal, leg count }, { Worm,  0}, { Bird, 2 }, { Dog, 4 }, { Fly, 6 }, { Tick, 8 } } );



  table insert selected rows( table 1, ([Animal]=Bird,Dog), [leg count], Animal, Index );



  table list( table 1 ); // Only Dog and Fly are left



  echo(" and above: ");

  table initialize ( table 1,

   { { Animal, leg count }, { Worm,  0}, { Bird, 2 }, { Dog, 4 }, { Fly, 6 }, { Tick, 8 } } );



  table insert above selected rows( table 1, ([Animal]=Bird,Dog), [leg count], Animal, Index );



  table list( table 1 ); // Only Dog and Fly are left

Output

    0 : Animal | leg count | Index
    1 : Worm   | 0         |      
    2 : Bird   | 2         | 0    
    3 : Bird   |           | 1    
    4 : Bird   |           | 2    
    5 : Dog    | 4         | 0    
    6 : Dog    |           | 1    
    7 : Dog    |           | 2    
    8 : Dog    |           | 3    
    9 : Dog    |           | 4    
   10 : Fly    | 6         |      
   11 : Tick   | 8         |      

 and above: 
    0 : Animal | leg count | Index
    1 : Worm   | 0         |      
    2 : Bird   |           | 0    
    3 : Bird   |           | 1    
    4 : Bird   | 2         | 2    
    5 : Dog    |           | 0    
    6 : Dog    |           | 1    
    7 : Dog    |           | 2    
    8 : Dog    |           | 3    
    9 : Dog    | 4         | 4    
   10 : Fly    | 6         |      
   11 : Tick   | 8         |

Try it yourself: Open LIB_Function_table_insert_selected_rows.b4p in B4P_Examples.zip. Decompress before use.

table insert ... selected rows