table check headers ...

Prev Next
Function Library Guide

Function Names

table check headers, table check headers silently

Description

THis function checks the table for column headers in a smart way according to specific rules you can provide. If no further options are specified, then just the existence of the headers will be checked. The function table check headers silently suppresses exceptions in case the header check fails and returns appropriate return values instead.

Call as: function

Restrictions

Indirect parameter passing is disabled

Parameter count

Min 2

Parameters

No.TypeDescription
1
input		 string Name of existing table

2
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

Opt. 3
input		 string Check header option 1

This option affects the header checking rules. See table below for available values. The value n used in the table below stands for number of columns in row 0.

must not exist Specified header names must not exist in the table.
Specified column numbers must like outside range 0..n-1.
All negative numbers are rejected.
may exist Specified headers names may exist, i.e. all header names are accepted.
All positive column numbers are accepted.
Negative numbers from -n..-1 are accepted.
create if missing Create additional headers if the headers do not yet exist. The rows below those new headers will not be initialized!
Positive column numbers from 0 to n are accepted. If n is specified, then an additional blank column will be created.
Negative numbers: -1 refers to next blank column beyond the last existing one. Smaller numbers refer to existing columns further to the left. Values smaller than -(n+1) will be rejected.
must exist or any number The rule desribed below applies if names are provided.
The may exist rule described above applies if positive or negative column numbers are provided.
must exist The specified header names must exist
Specifeid column numbers must be within 0..n-1 or -n..-1.
unique Like must exist, but also checks that the specified column headers are unique in the table, i.e. they exist only once.
full match Like unique, however the table must not contain more (or less) headers than those specified to check. The ordering does not matter. It's like tolerating full number of white pins after a guess in the Master Mind game.
sequence Like unique, but listed parameters are in left-to-right sequence. The checked headers do not need to be adjacent.
strict sequence Like sequence but all headers must be adjacent, being next to each other from left to right
identical Combination of full match and strict sequence. The headers provided and table headers must be identical: Same header names in the same sequence. This corresponds to full number of black pins in the Master Mind game.

Default value: must exist
Opt. 4, 5, etc.
input		 string Additional option(s)

Additional checking options:

no repetition Column specifications must not repeat (i.e. no repeated header names, no repeated column numbers)
no numbers No column numbers allowed in the 2nd parameter. Only header names are allowed
no blanks No blank headers allowed.
ignore blanks Ignore blank headers (supersedes previous option 'no blanks' if specified)
only 1 Exactly 1 column to be specified
max 1 0 or 1 columns to be specified (not more)
min 1 Min. 1 column to be specified (not 0).
Note: Specifying both 'min 1' and 'max 1' means 'only 1'

Return value

TypeDescription
string Feedback

ok (lower case) is returned if no issues have been identified.
In all other cases, if table check headers is specified, exeptions will be asserted. If the function table check headers silently is called instead, following additional values can be returned:

ok All OK (Note: lower case letters)
empty and ok Applicable to option 'may exist': No matches found, but deemed OK.
not found Header name not found, or column number not inside valid range
already existing Header name is alrady existing resp. column number is inside the range of existing headers
duplicate A duplicated header name has been found in the table
no full match Header names in the table not matching.
incorrect sequence Specified headers / column numbers are not in a correct left-to-right sequence.
repeated Repeated reference to same table colummn
forbidden number Encountered forbidden column number in the 2nd function parameter. Only header names are allowed
forbidden blank Encountered forbidden blank header name in the 2nd function parameter.
wrong count Wrong number of columns specified
range error Specified column lies outside the range

Exceptions

Table not found
Various exceptions resulting from issues identified while checking headers

Examples

  table initialize ( table 1,
  { { Name, Street, Town, Country }, { Miller, "..." } } );

  echo("1. Demonstrate 'must not exist':");
  echo( table check headers silently( table 1, {"State", "Province"}, must not exist ) ); // OK
  echo( table check headers silently( table 1, {"Town", "State"} , must not exist ) );    // Not OK
  echo( table check headers silently( table 1, 10,      must not exist ) );   // OK
  echo( table check headers silently( table 1, -1,      must not exist ) );   // Not OK (last column exists)
  echo;

  echo("2. Demonstrate 'may exist':");
  echo( table check headers silently( table 1, {"State", "Province"}, may exist ) );  // Empty and OK
  echo( table check headers silently( table 1, {"Town", "Province"}, may exist ) );   // OK
  echo( table check headers silently( table 1, {"Town", "State"} , may exist ) ); // OK
  echo( table check headers silently( table 1, 10,      must not exist ) );   // OK
  echo( table check headers silently( table 1, -11,      must not exist ) );  // Not OK (range error)
  echo;

  echo("3. Demonstrate 'create if missing':");
  table copy table ( table 1, table 2 );
  echo( table check headers silently( table 2, {"State", "City"}, create if missing ) );  // OK
  echo( "Header row: ", [table 2: .., 0 ] );
  echo;

  echo("4. Demonstrate 'must exist':");
  echo( table check headers silently( table 1, {"Name", "Town"}, must exist ) );  // OK
  echo( table check headers silently( table 1, {"Name", "State"} , must exist ) );    // Not OK
  echo( table check headers silently( table 1, 10,      must exist ) );   // Not OK
  echo( table check headers silently( table 1, -1,      must exist ) ); // OK (last column exists)
  echo( table check headers silently( table 1, {},      must exist ) ); // Empty and oK
  echo;

  echo("5. Demonstrate 'unique':");
  table initialize ( table 2,
  { { Name, Street, Town, Country, Town }, { Miller, "..." } } );
  echo( table check headers silently( table 1, "Town", unique ) );  // OK
  echo( table check headers silently( table 2, "Town", unique ) );  // Not OK
  echo( table check headers silently( table 2, -1, unique ) );        // Not OK (Also "Town")
  echo;

  echo("6. Demonstrate 'full match':");
  echo( table check headers silently( table 1, { Country, Town, Street, Name }, full match ) );   // OK
  echo( table check headers silently( table 1, { 1,3,2,0  }, full match ) );  // OK
  echo( table check headers silently( table 1, { Country, Town, Street, Name, Name }, full match ) ); // Not OK
  echo;

  echo("7. Demonstrate 'sequence':");
  echo( table check headers silently( table 1, { Name, Country }, sequence ) );   // OK
  echo( table check headers silently( table 1, { Country, Name }, sequence ) );   // Not OK
  echo( table check headers silently( table 1, { 0,2,3  }, sequence ) );  // OK
  echo( table check headers silently( table 1, { 0,3,2  }, sequence ) );  // Not OK
  echo;

  echo("8.Demonstrate 'strict sequence':");
  echo( table check headers silently( table 1, { Name, Country }, strict sequence ) );    // Not OK
  echo( table check headers silently( table 1, { Town, Country }, strict sequence ) );    // OK
  echo( table check headers silently( table 1, { 0,1,2  }, strict sequence ) );   // OK
  echo( table check headers silently( table 1, { 0,3,3  }, strict sequence ) );   // Not OK
  echo;

  echo("9. Demonstrate 'identical':");
  echo( table check headers silently( table 1, { Name, Street, Town, Country }, identical ) );    // OK
  echo( table check headers silently( table 1, { Street, Name, Town, Country }, identical ) );    // Not OK
  echo( table check headers silently( table 1, { 0,1,2,3  }, identical) );    // OK
  echo( table check headers silently( table 1, { -4,-3,-2,-1  }, identical ) );   // Also OK
  echo;

  echo("10. Demonstrate 'no repetition':");
  echo( table check headers silently( table 1, { Name, Town, Town }, must exist ) );  // OK
  echo( table check headers silently( table 1, { Name, Town, Town }, must exist, no repetition ) );   // Not OK
  echo;

  echo("11. Demonstrate 'no numbers':");
  echo( table check headers silently( table 1, { Name, Town }, must exist, no numbers ) );    // OK
  echo( table check headers silently( table 1, { Name, 2 }, must exist, no numbers ) );   // Not OK
  echo;

  echo("12. Demonstrate 'no blanks':");
  echo( table check headers silently( table 1, { Name, Town, "" }, must exist, no blanks ) );   // Not OK
  echo;

  echo("13. Demonstrate 'ignore blanks':");
  echo( table check headers silently( table 1, { Name, Town, "" }, must exist, ignore blanks ) );   // OK
  echo;

  echo("14. Demonstrate 'max 1':");
  echo( table check headers silently( table 1, { Name, Town }, must exist, max 1 ) ); // Not OK
  echo( table check headers silently( table 1, { Name  }, must exist, max 1 ) );  //  OK
  echo( table check headers silently( table 1, {  }, must exist, max 1 ) );   //  OK

Output

1. Demonstrate 'must not exist':
ok
already existing
ok
already existing

2. Demonstrate 'may exist':
empty and ok
ok
ok
ok
range error

3. Demonstrate 'create if missing':
ok
Header row: {'Name','Street','Town','Country','State','City'}

4. Demonstrate 'must exist':
ok
not found
range error
ok
empty and ok

5. Demonstrate 'unique':
ok
duplicate
duplicate

6. Demonstrate 'full match':
ok
ok
no full match

7. Demonstrate 'sequence':
ok
incorrect sequence
ok
incorrect sequence

8.Demonstrate 'strict sequence':
incorrect sequence
ok
ok
incorrect sequence

9. Demonstrate 'identical':
ok
incorrect sequence
ok
ok

10. Demonstrate 'no repetition':
ok
repeated

11. Demonstrate 'no numbers':
ok
forbidden number

12. Demonstrate 'no blanks':
forbidden blank

13. Demonstrate 'ignore blanks':
ok

14. Demonstrate 'max 1':
wrong count
ok
empty and ok
Try it yourself: Open LIB_Function_table_check_headers.b4p in B4P_Examples.zip. Decompress before use.

See also

table check header
table insert missing columns

Copyright (C) 2007 - 2024 Georg A. zur Bonsen, All Rights Reserved