BEE Script:   group var [delim=char] [matrix=class] [result=class]

            [inverse=bool];

BEE Tag:     <beegroup var [delim=char] [matrix=class] [result=class]

            [inverse=bool]>

The "group" command creates out of a one-dimensional array a two-dimensional array, which is called a "matrix".  The command generates under the "matrix" class a new variable for each element in the subject variable (var), then group the new variables by a common suffix which is separated from the variable name by a delimiter (the "delim" parameter, default to be '_'.)

After the operation, result%keys will hold all distinct variable names created, and result%fields will hold all distinct element names created.  (The class name "result" can be overwritten by the result parameter.)

Examples:

// If we got the followings:

// cart:product_15 = "Orange"

// cart:qty_15 = "4"

// cart:unit_15 = "kg"

// cart:product_23 = "Spinach"

// cart:qty_23 = "1"

// cart:unit_23 = "bunch"

group cart;

// Now we have:

// matrix%15:product = "Orange"

// matrix%15:qty = "4"

// matrix%15:unit = "kg"

// matrix%23:product = "Spinach"

// matrix%23:qty = "1"

// matrix%23:unit = "bunch"

// result%fields = product, qty, unit

// result%keys = 15, 23

Here is a schematic illustration of the example:

group cart;

In fact, the "group" command creates a matrix out of an array variable.  This is useful in a spreadsheet-like input where the columns are the fields and the row numbers are the keys.  In such case, each form input tag should be named as columnName_rowNumber.  If the spreadsheet is to be used in a database operation, the rowNumber should be replaced by the value of the read-only key.  Please see "dbobj%keyfield" in the "database" command.

Parameters

delim is the delimiter character that splits the original element name into the element name part (before the delimiter) and the variable name part (after the delimiter) of the new variable. The default of "delim" is underscore: '_'.

If there no the delimiter characters are not found in the original element name, one is assumed in front of the name.  That is the element name part of the new variable is blank.  On the other hand, if multiple delimiter characters are found in the original element name, only the last one will be used as the delimiter.

matrix specifies the class under which the variables are created.  Existing variables in the matrix class will not be cleared but may be overwritten by newly created variable of the same name if any.  To avoid "polluting the environment", please make sure the matrix class is clean before using it for the "group" command.  The default of "matrix" is "matrix".

result specifies the class for the %fields and %keys variables.  (Please see parameter "matrix".)  The default value of "result" is "result".

inverse indicates the inverse-format of the original element names.  If inverse is true, the original element name is taken as n_e, where n is the variable name part and e is the element name part of the new variable.  The default is false, which means the original element name is in the format of e_n, which is the usual case described above.

There are some points to make about the "matrix" and "result" parameters.  If the matrix created is later on used in a database operation, please remember to specify the same matrix class in the "database" command as in the "group" command that created the matrix.  Also, please use the database object name as the "result" parameter so that the "database" command will pick up the %fields and %keys variables properly.

Also, if the "group" command and the "database" command are in two different Contexts, please make sure you link the matrix and result classes properly using either the "global" or the "parent" command where necessary.

After the "group" command is executed, the following BEE Variables are made available (in additional to the matrix variables created):