B4P Reference

Function Names

table read cells, table read cells seleted rows, table read cells in columns, table read cells selected rows in columns

Description

This function looks for cells using the right-hand comparison expression across all or selected columns and across all or selected rows, read the contents into a set which is then returned as return value.

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

1.
input

string

target table name

The target table must exist.

Opt. 2.
code

expression
:string

Expression to select rows

Applicable to table read cells selected rows and table read cells selected rows in columns:
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 2. / 3.
input

table columns

Header names and/or column numbers

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

2 / 3 / 4
input

string
set

values to compare

Provide one string or multiple strings in a set to compare with the table contents. wildcards are supported if the strings are of type softquoted string.

Opt. 3 / 4 / 5
input

string
set

options

One or multiple options may be applied.

Keyword	Notes	Description
above	See 1	Coordinates of 1 row above will be returned. Note: Combination of 'above' and 'below' will cancel each other. But OK to combine with 'left' or 'right'.
below	"	Coordinates of 1 row below will be returned. Note: See above
left	"	Coordinates of 1 columne to the left will be returned. Note: Combination of 'left' and 'right' will cancel each other. But OK to combine with 'above' or 'below.
right	"	Coordinates of 1 columne to the right will be returned. See above
once	See 2	Find at most 1 cell
once each	"	Find at most 1 cell for every comparison value
ignore case		Search process ignores case, e.g. comparing 'ABC' with 'abc' yields true.
ignore blanks		Search process ignores blanks, e.g. comparing 'can not' and 'cannot' yields true.

Notes:
1. Combination of multiple terms are allowed as usage of every turn displaces the position. Example: Combining 'above' and 'left' points to the cell 1 row above and 1 column to the left. Combining 'left' and 'right', as well as 'above' and 'below' cancel each other out. Mulitple use of a term is also allowed, e.g. 'left', 'left' indicates 2 fields to the left. No coordinates are returned if the final location lies beyond the first column, or on or above the header row.
2. 'once' and 'once each' cannot be combined.

Return value

Type	Description
set	Contents read A set containing all values read. e.g. { Content 1, Content 2, ... }. Empty set is returned in case of no matches.

Examples

table initialize( t,

               { { City,        State, Country },

                 { Tuscon,      AZ,    United States },

                 { Toronto,     ON,    Canada },

                 { Missisauga,  ON,    Canada },

                 { Zürich,      ZH,    Switzerland },

                 { Lake Zurich, MI,    United States } } );



table list(t);





c[] = table read cells( t, {} );

echo ("Nothing to look for: ", c[]);



c[] = table read cells( t, { canada, 'swit*' }, ignore case );

echo ("All countries except USA: ", c[]);



c[] = table read cells in columns( t, City, '*Z*rich*' );

echo ("All Cities sounding 'swiss', point on countries: ",c[]);



c[] = table read cells selected rows in columns( t, [Country]==Canada, State, ON, {once,left} );

echo ("1st Ontario match, point on city: ", c[]);



c[] = table read cells( t, Tuscon, left);

echo ("Empty set, as attempting to return coordinates beyond left side of table: ", c[]);

Output

    0 : City        | State | Country      
    1 : Tuscon      | AZ    | United States
    2 : Toronto     | ON    | Canada       
    3 : Missisauga  | ON    | Canada       
    4 : Zürich      | ZH    | Switzerland  
    5 : Lake Zurich | MI    | United States

Nothing to look for: {}
All countries except USA: {'Canada','Canada','Switzerland'}
All Cities sounding 'swiss', point on countries: {'Zürich','Lake Zurich'}
1st Ontario match, point on city: {'Toronto'}
Empty set, as attempting to return coordinates beyond left side of table: {}

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

table read cells ...

Function Names

Description

Call as: procedure or function

Restrictions

Parameter count

Parameters

Return value

Examples

Output

See also