XLL+ Class Library (7.0)

Argument Details - Matrix Tab

The controls on the Matrix tab of the Argument Details window are divided into groups:

Constraints

This group defines the constraints that will be applied to the size of the matrix argument.

Height is equal to

Use this combo-box to constrain the height of the argument (i.e. the number of rows it contains).

If you type in an integer, then the matrix must contain exactly that number of rows or the input will be rejected by the add-in function, with a message such as "Expected 3 rows for X".

If the property contains a name, then a variable of that name will be instantiated in the add-in functions, and the validation code will set it to the height of the array. If the variable has already been set, then it will be tested. If the size is different from the value of the variable, then the input will rejected, with a message such as "Expected 3 rows for X".

By using the same bounding variable for two arrays, you can constrain multiple inputs to have the same size, width or height.

By using the same bounding variable for the hight and the width of a matrix, you can constrain a matrix input to be square.

If your function has other inputs that are vectors or matrices, then the drop-down list will contain a list of their bounds, so that you can immediately bind the size of this vector to the size of another vector or matrix.

See also Constraining the size of an argument in the User Guide.

If the combo-box is left empty (the default) then there are no constraints on the height of the array.

Width is equal to

Use this combo-box to constrain the width of the argument (i.e. the number of columns it contains).

If you type in an integer, then the matrix must contain exactly that number of columns or the input will be rejected by the add-in function, with a message such as "Expected 3 columns for X".

If the property contains a name, then a variable of that name will be instantiated in the add-in functions, and the validation code will set it to the width of the array. If the variable has already been set, then it will be tested. If the size is different from the value of the variable, then the input will rejected, with a message such as "Expected 3 columns for X".

By using the same bounding variable for two arrays, you can constrain multiple inputs to have the same size, width or height.

By using the same bounding variable for the height and the width of a matrix, you can constrain a matrix input to be square.

If your function has other inputs that are vectors or matrices, then the drop-down list will contain a list of their bounds, so that you can immediately bind the size of this vector to the size of another vector or matrix.

See also Constraining the size of an argument in the User Guide.

If the combo-box is left empty (the default) then there are no constraints on the width of the array.

Reject empty matrix

Check this box if your function should reject matrices that contain zero values.

If the user supplies an empty range as the input, then the function will return an error message such as Expected at least one cell for X.

Truncate

This group controls how the validation code will detect the edges of the vector within the input range.

The behavior of this group of flags is also dependent on the Fill settings.

If Fill is set to "Do not fill" then truncation occurs at the first empty/blank/zero cell and all cells after the empty cell are ignored, even if they are not empty

If Fill is set to "Fill used area", then the array is truncated after the cell that is not empty/blank/zero. Empty cells before the last empty/blank/zero cell are filled with the Fill value.

Truncate at empty cell

If Fill is set to "Do not fill", the array is truncated at the first empty cell. All cells after the empty cell are ignored, even if they are not empty.

If Fill is set to "Fill used area", then the array is truncated after the last non-empty cell. Empty cells before the last empty cell are filled with the Fill value.

Truncate at blank cell

If Fill is set to "Do not fill", the array is truncated at the first blank cell. All cells after the blank cell are ignored, even if they are not blank.

If Fill is set to "Fill used area", then the array is truncated after the last non-blank cell. Blank cells before the last blank cell are filled with the Fill value.

A formula such as ="" will produce a blank cell.

Truncate at zero cell

If Fill is set to "Do not fill", the array is truncated at the first zero cell. All cells after the zero cell are ignored, even if they are not zero.

If Fill is set to "Fill used area", then the array is truncated after the last non-zero cell. Zero cells before the last zero cell are filled with the Fill value.

Container

Container class combo-box

This control allows you to specify the C++ container class into which the argument's values will be copied.

If you leave it blank, then the default container class (as defined by the DefaultMatrixContainer setting) will be used.

For details of the notation to be used for the container class, see Argument.ContainerClass.

Fill

The controls in this group control how the validation code deals with empty cells.

Fill type

This control allows you to control what will be done with input cells that are considered to be empty.

The following values are supported:

Do not fill
Do not fill empty cells
Fill used area
The used area is the continuous area that includes the start (top or left) of the vector and also the last non-empty cell. Empty cells inside that area will be filled. The definition of an empty cell for calculating the used area depends on the Truncate settings.
Fill all cells
Empty cells anywhere in the input range will be filled.

Fill value

This is the value which will be used to fill empty cells if the Fill Type is not set to "Do not fill". It should be a valid C++ expression that can be used to set the target type.

Fill empty cells

If the Fill Type is not "Do not fill", then empty cells will be set to the fill value.

Fill blank cells

If the Fill Type is not "Do not fill", then blank cells will be set to the fill value.

Fill zero cells

If the Fill Type is not "Do not fill", then cells containing the value zero will be set to the fill value.

Bounds

The controls in this group control how the size of the array is measured.

1-based rows

If this box is checked then the target matrix will have an empty row at its start. This is useful if you are passing values to code written for 1-based matrices, such as some Basic, Fortran or Lisp compilers.

1-based columns

If this box is checked then the target matrix will have an empty column at its start.

Upper bound value

If a constraint has been set on the size of the vector then this control modifies how the size is calculated. This size is compared to the value of the upper bound specified in the Size control.

Layout

Transpose drop-down

This drop-down can be set to one of two values:

  1. Store as [row,column] (the default)
  2. Store as [column,row]

This will define how the data is stored in the target container. Code may address the data for an argumnt x as x[row][column] or x.at(row, column) in the first case, or as x[column][row] or x.at(column, row) in the second case.