B4P Reference

Function Names

table keep selected rows

Description

This function keeps all rows where the expression to select rows applies.

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 If ≤0: No rows will be kept If 1: Affected row will be kept If ≥2: Neighboing rows are kept once. Example: Rows 5 and 6 apply, so rows 5, 6, and 7 will be kept. Default value: 1
Opt. 4. input	numeral	Row offset value If 0: Deletes selected rows (and further down if number of rows to delete is >1). If 1: Deletes next row below selected rows (and further down) If ≥2: First row to delete is n rows below selected row. If -1: Deletes selected rows (and further up if number of rows to delete is >1) If -2: Deletes next row above selected row (and further up) If ≤-3; First row to delete is abs(n)-1 above selected row If offset is negative and reach into the header row, the header rows are protected from getting 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

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

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

table keep selected rows