B4P Reference

Function Names

table keep selected rows

Description

This function keeps all rows where the expression to select rows applies. The header row will be protected from getting affected.

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 - 4

Parameters

No.	Type	Description
1. input	string	Name of existing table
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. input	numeral	Number of rows to keep -2 or smaller: All remaining rows except for the last n-1 will be kept. E.g. for -2, the last row will be deleted. For -3, the last two rows will be deleted. -1: All remaining rows will be kept. Checking the remaining rows to delete will be skipped as this is no longer necessaryu 0: No rows will be kept 1: Affected row will be kept 2 or bigger: the specified number of rows below will be kept. Default value: 1
Opt. 4. input	numeral	Row offset value 0: Start keeping on the current row 1: Start keeping on the next row below 2 or bigger: Start keeping on the further rows below -1: Start keeping on the previous row above. If 3rd function parameter is negative, then the specified number of rows above will be kept. -2 or smaller: Start keeping 2 or further rows above. If 3rd function parameter is negative, then the specified number of rows above will be kept. Default value: 0

Return value

Type	Description
numeral	Number of rows kept Number of rows kept. -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 copy table( table 1, t1 );

       echo("Keep 2 rows: Bird and Tick:");

       table keep selected rows( t1, ([Animal]='*i*') ); // Bird, Tick kept

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



       echo("Dog will also be kept:");

       table copy table( table 1, t1 );

       table keep selected rows( t1, ([Animal]='*i*'), 2 ); // Bird, Tick, Dog kept

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



       echo("Keep animal above Dog and Worm:");

       table copy table( table 1, t1 );

       table keep selected rows( t1, ([Animal]='*o*'), 1, -2 ); // Rows above Worm, Dog. Worm is header. Ignore.

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





       echo(new line, "Example with negative row numbers to delete remaining rows");

       table initialize( t, {Values} );



       echo("Delete from matching row (5) to end of table");

       [t:Values,..] = {1..12};

       table delete selected rows( t, [Values]==5, -1 );

       table list( t );



       echo("Delete from row belpow matching row (5) to 1 line avoe end of table");

       [t:Values,..] = {1..12};

       table delete selected rows( t, [Values]==5, -2, 1 );

       table list( t );

Output

Keep 2 rows: Bird and Tick:
    0 : Animal | leg count
    1 : Bird   | 2        
    2 : Tick   | 8        

Dog will also be kept:
    0 : Animal | leg count
    1 : Bird   | 2        
    2 : Dog    | 4        
    3 : Tick   | 8        

Keep animal above Dog and Worm:
    0 : Animal | leg count
    1 : Bird   | 2        


Example with negative row numbers to delete remaining rows
Delete from matching row (5) to end of table
    0 : Values
    1 : 1     
    2 : 2     
    3 : 3     
    4 : 4     

Delete from row belpow matching row (5) to 1 line avoe end of table
    0 : Values
    1 : 1     
    2 : 2     
    3 : 3     
    4 : 4     
    5 : 5     
    6 : 12

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

table keep selected rows